Glossary

Allowlist. DatabaseOptions.AllowedTables: the tables the model may see and reference.

Ambient scope. An IntentClientScope (from client.AsAmbient()) or an IntentScope (from runtime.AsAmbient()): AsyncLocal state that makes a client or an intent runtime available to the ambient extension methods for one async flow. It nests and ends when disposed. It is not a process-wide default. See intent-catalog.md.

Attempt. One model call plus its verification. Recorded as an AttemptRecord. Attempt 2 and later carry the previous output and its issues. Limited by MaxAttempts.

Audit tags. The tags IntentRuntime puts on every run: intent.name, intent.version and intent.source, plus the definition's own tags. They reach AIRequest.Tags and, when the run is recorded, MemoryEntry.Tags.

Cache key. RequestCacheKey.For: a SHA-256 of everything that shapes a provider reply.

Catalog. An IIntentCatalog: a source of intent definitions with a current snapshot and a change token. FileIntentCatalog reads a folder of *.intent.json, *.intent.yaml and *.intent.yml files; InMemoryIntentCatalog holds definitions added in code.

Catalog problem. A CatalogProblem: one thing wrong with a definition file, with its source, its line when known, and a message. Loading reports problems instead of throwing.

Change token. The IChangeToken from IIntentCatalog.GetChangeToken(). It fires once when the catalog's snapshot is replaced; callers fetch a new token after it fires.

Chat client. Microsoft.Extensions.AI's IChatClient, the abstraction Agent Framework and many backends use. ChatClientProvider adapts one to IAIProvider. See extensions-ai.md.

Client. An IntentClient instance. There is no static or process-wide default; code passes it explicitly or makes it ambient for one async flow with client.AsAmbient().

Dry run. DatabaseOptions.DryRun: plan and check a statement but do not execute it.

Envelope. The JSON object {"value": ...} that wraps every non-string result, so primitives and arrays fit providers that require an object at the root.

Example. An IntentExample: an input rendered as text and the exact output expected for it. Examples in AIRequestOptions.Examples (or an intent file's examples) are rendered in the prompt's examples section. They steer the model; they never replace verification.

Fallback. The secondary provider, used only when the primary fails with a transient error (HTTP 429, 5xx, transport) or an HTTP timeout. See request-pipeline.md.

Finding. Informal name for an issue's message when it is fed back to the model.

Generation. IntentCatalogSnapshot.Generation: a number that increases with every new snapshot: every load of a FileIntentCatalog, whether or not it reported problems, and every change to an InMemoryIntentCatalog. A higher generation does not mean an edit took effect; check Problems for that. See intent-catalog.md.

Guardrail. A hard limit that stops a request: the model-call ceiling or the time budget. Also the [AIGuardrail] attribute, which sets request options for ExecuteIntentAsync.

Hot reload. FileIntentCatalog watching its folder and swapping in a new snapshot when files change, so the next run of an intent uses the edited definition without a restart. A file that fails to load keeps its previous definitions.

Input. The value an intent is applied to. Always serialized into the prompt; never truncated.

Intent. The natural-language instruction, for example "Extract the invoice total". In the catalog, the intent property of a definition holds this text.

Intent definition. An IntentDefinition: one named intent as data, with its version, owner, shape, rules, validators, examples and guardrails. Loaded from JSON or YAML.

Intent runtime. IntentRuntime: runs a named intent from a catalog through an IntentClient, resolving the definition on every call.

Intent tool. An AIFunction made from a catalog intent by AsAIFunction or AsAIFunctions, for agents to call. It returns verified JSON or a failure with success: false, and never throws into the agent loop.

Issue. A ResultIssue: one concrete problem with a source (IssueSource), a message and an attempt number.

Judge. An optional model call that reviews a candidate output against the intent and input (IResultJudge, ModelJudge). Its verdict is JudgeVerdict.

Lint warning. Advice from IntentLint about the intent text. Never affects success.

Memory. An ISemanticMemory that records completed requests and recalls similar ones.

Model-call ceiling. MaxModelCalls: attempts plus judge calls allowed per request (default 6).

Named validator. A code validator the application registers under a name (IntentValidatorRegistry, services.AddIntentValidator) so that intent files can refer to it. Files can name validators but cannot carry code.

Plan. Two meanings. PromptPlan is everything the pipeline knows before calling a provider. QueryPlan is the model's SQL statement, parameters and explanation in the database runtime.

Provider. An IAIProvider: OpenAI, Anthropic, ChatClientProvider over any IChatClient, ScriptedProvider, or your own.

Refusal. A provider reply that declines the request (AIResponse.IsRefusal). Ends the attempt loop.

Rule. A declarative check in IntentRules (for example minimum, pattern, enum, required), evaluated by IntentRuleEngine on the result as JSON. Each violation is a validator issue that names the path.

Runtime shape. A result shape given as a JSON schema at run time instead of a .NET type: TransformAsync(input, intent, JsonNode outputSchema), which returns AIResult<JsonNode>. In an intent file, shape.kind: schema.

Safety report. SqlSafetyReport: the checker's verdict, statement kind, tables and parameter names.

Scripted provider. ScriptedProvider, the in-process provider every test uses.

Shape. An IntentShape: what an intent returns. text, primitive, clr (a registered .NET type) or schema (a runtime shape).

Snapshot. An IntentCatalogSnapshot: a catalog's definitions and load problems at one moment, never changed in place (its definitions are the catalog's own objects; treat them as read-only), replaced atomically on reload.

Strict schema. A JSON schema where every object closes additionalProperties and requires every property, with unsupported keywords removed. Built by JsonSchemaBuilder.

Target type. The T in TransformAsync<T>.

Time budget. AIRequestOptions.Timeout or IntentClientOptions.DefaultTimeout; the whole request, all attempts included.

Truncation. A reply cut off by the output token limit (AIResponse.IsTruncated). Always fails the attempt.

Validator. A function that returns problem strings for a parsed value (AIRequestOptions.Validators, Validate<T>, Require<T>, IGuardrailValidator). The catalog adds three kinds per run: the rule validator, the JSON schema validator for schema shapes, and named validators.

Verification. DeterministicVerifier.Verify<T>: the checks that need no model call.