Namespace IntentSharp.Catalog

Classes

CatalogProblem: A problem found while loading definitions. Loading never throws for content errors; it reports them here and keeps the last good snapshot.

Registers the intent catalog and runtime:

services.AddIntentSharp(configuration);
services.AddIntentCatalog("intents");
services.AddIntentRuntime();
services.AddIntentValidator("KnownSku", value => ...);
services.AddIntentType<Invoice>();

Every registration is a singleton. The validator and type registries start empty and are filled from the AddIntentValidator and AddIntentType calls (in any order relative to AddIntentRuntime) when first resolved.

FileIntentCatalog: A catalog loaded from a folder of .intent.json, .intent.yaml and *.intent.yml files (subfolders included by default), reloaded while the application runs. A FileSystemWatcher notices edits, waits until the folder has been quiet for DebounceInterval (250 ms by default), reads every file again, swaps in a new IntentCatalogSnapshot atomically and fires the change token. Callers never poll: IntentRuntime reads Current on every call, so the next call uses the new definitions.

FileIntentCatalogOptions: Settings for FileIntentCatalog.

InMemoryIntentCatalog: A catalog held in memory, for tests and for intents defined in code. Definitions are checked with the same rules as files (an invalid one throws ArgumentException listing every problem) and copied, so changing the object afterwards does not change the catalog. Every Add(IntentDefinition), Replace(IntentDefinition) and successful Remove(string) publishes a new snapshot and fires the change token. Thread-safe.

IntentCatalogSnapshot: A view of the catalog at one moment: a fixed set of definitions, replaced atomically on reload and never changed in place, so callers that hold a snapshot see consistent definitions. The IntentDefinition objects are the catalog's own, not copies; treat them as read-only. IntentRuntime runs a checked private copy of each, so changing one in place after it has run changes nothing (use Describe(string) for a copy to edit).

IntentDefinition: One piece of behaviour as data: a named intent with its text, result shape, rules, limits and examples. Loaded from JSON or YAML files (or any other IIntentCatalog source) and executed by IntentRuntime. Edit the file, not the program, to change what the intent does.

IntentDisabledException: The definition exists but has enabled: false, so it refuses to run. No model is called.

IntentExtensions: Runs a catalog intent on any value: value.RunIntentAsync<T>(runtime, "Name"), or value.RunIntentAsync<T>("Name") inside runtime.AsAmbient(). The code names the behaviour; the file defines it.

IntentNotFoundException: The catalog has no definition with the requested name. The message lists close names and any load problem that mentions the name.

IntentRules: Declarative checks evaluated on the result rendered as JSON (typed results are serialized first, so the same rules work for compiled and runtime shapes). Every violated rule becomes a validator issue fed back to the model.

IntentRuntime: Runs catalog intents by name. Each call reads the definition from Current, so a reload takes effect on the next call, and turns it into one IntentClient request: the shape picks the call (text, a primitive, a registered .NET type, or a JSON schema defined at run time), and the definition supplies the attempts, judge, provider, model, timeout, output limit, examples, output requirements, system instructions, memory opt-out, rules, schema checks and named validators. Every request is tagged intent.name, intent.version and intent.source (plus the definition's own tags), so logs and memory entries say which version decided.

IntentScope

Makes an IntentRuntime ambient for the current async flow, so values can run catalog intents by name without passing the runtime:

using var scope = runtime.AsAmbient();
var urgency = await email.RunIntentAsync<int>("Orders.ClassifyUrgency");

Like IntentClientScope, this is AsyncLocal<T> state: it flows with awaits and tasks started inside it, is invisible to other requests and threads, nests (the inner scope wins until it is disposed) and ends when disposed. A task started inside the scope that is still running after the scope was disposed no longer sees the runtime. There is no process-wide default runtime.

IntentShape: How a result is shaped: text, a primitive, a compiled .NET type, or a JSON schema defined at run time.

IntentShapeMismatchException: RunAsync<T> was called with a T the intent's shape cannot produce. The message names the shape and the requested type. No model is called.

IntentTypeRegistry: The .NET types intent files may name in shape.clrType. Only registered types resolve, so a file can never make the runtime load or instantiate an arbitrary type. Add<T>() registers a type under its simple name, its full name and its assembly-qualified name (with or without version details); Add(string, Type) adds an alias, which always wins over a simple name. When two registered types share a simple name, that simple name stops resolving and the full names must be used. Names ignore case. Safe to use from several threads.

IntentValidatorRegistry: Code validators that definitions reference by name in validators, for checks rules cannot express (a lookup, a checksum, a cross-field invariant). A validator receives the parsed result (the .NET value, or a JsonNode for schema shapes) and returns one message per problem; the messages are fed back to the model. Names ignore case. Safe to use from several threads; validators added later apply to the next run.

Interfaces

IIntentCatalog: A source of intent definitions. Implementations load from files, databases or anything else, expose the current snapshot, and signal changes through a change token so hot reload needs no polling by callers.

IIntentTypeRegistry: Resolves the clrType names that intent files use to .NET types. Only registered types are allowed, so a file cannot name arbitrary types.

IIntentValidatorRegistry: Code validators that intent files may reference by name (for checks that cannot be expressed as rules).

Enums

IntentShapeKind: The kinds of result an intent can return, written in files as text, primitive, clr or schema (any case).

Table of Contents

Namespace IntentSharp.Catalog

Classes

Interfaces

Enums