Documentation
Table of Contents

Migrating from 1.0.0-rc.3 to 1.0.0

1.0.0 removes or renames every rc.3 member this page lists, with no compatibility layer: code that names one does not compile until you replace it. Most applications change four things: where the providers come from, how a database is reached, the renamed constraint types, and the namespace of two exceptions. Breaking changes has the short list, and the changelog has everything 1.0.0 adds.

Move the four packages together

The add-ons now depend on one exact version: IntentSharp.Catalog and IntentSharp.Guardrails on IntentSharp [1.0.0], and IntentSharp.Extensions.AI on IntentSharp and IntentSharp.Catalog [1.0.0], where rc.3 accepted 1.0.0-rc.3 or later. Update every IntentSharp package a project references at once. A direct reference to a newer IntentSharp than the add-ons require gets NuGet's warning NU1608 at restore. IntentSharp.Guardrails is new: it reads rule files (Guardrails).

Providers and models

IntentSharp ships no model id and no vendor helper. Providers and their models come from a provider file, intentsharp.providers.json in a document store, from an IProviderOptionsSource of your own, or from providers added in code. Each entry names a kind (openai, anthropic, chat-client or one of your own), its model, and where its key is read from:

{
  "intentsharp": "providers/1",
  "providers": [
    { "name": "main", "kind": "anthropic", "secret": "env:ANTHROPIC_API_KEY", "model": "<model id>" },
    { "name": "backup", "kind": "openai", "secret": "env:OPENAI_API_KEY", "model": "<model id>" }
  ],
  "roles": {
    "answer": ["main", "backup"],
    "judge": "backup"
  }
}

builder.UseProviderOptions(store) reads it (Providers, Provider file).

rc.3 1.0.0
IntentClientBuilder.UseOpenAI(apiKey, model) An entry of kind openai, read with UseProviderOptions(store).
IntentClientBuilder.UseAnthropic(apiKey, model) An entry of kind anthropic.
UseOpenAIAsFallback(apiKey, model), UseAnthropicAsFallback(apiKey, model) The second entry of the role's chain: "answer": ["main", "backup"].
UseProvidersFromEnvironment(openAIModel, anthropicModel) Entries whose secret is "env:OPENAI_API_KEY" or "env:ANTHROPIC_API_KEY". Nothing reads those variables unless an entry names them.
OpenAIProvider and AnthropicProvider as public types: their constructors, CompleteAsync, EmbedAsync, Name, SupportsEmbeddings, Authenticate and OpenAIProvider.EmbeddingModel Internal: the openai and anthropic kinds create them from an entry. An openai entry's endpoint points it at a compatible service, and its embeddingModel names the embedding model.
OpenAIProvider.DefaultModelId, OpenAIProvider.DefaultEmbeddingModel, AnthropicProvider.DefaultModelId None. Write the model in the entry (model, embeddingModel), in the role ("answer": "main@<model id>") or in the call (AIRequestOptions.Model).
AnthropicProvider.SendTemperature The entry's capability: "capabilities": { "temperature": true }.
A model left unset, which sent the vendor's constant ProviderConfigurationException from the call, naming the provider and the role, and nothing is sent.
IAIProvider.DefaultModel Removed. The call, the role or the file names the model, and result.Model says which model answered.
IAIProvider.SupportsEmbeddings, IAIProvider.EmbedAsync(text, cancellationToken) IEmbeddingProvider.EmbedAsync(text, EmbeddingRequest, cancellationToken). A provider of your own that embeds implements both interfaces. The client embeds through the embedding role (client.EmbedAsync(text)) or builder.UseEmbeddingProvider(provider).
A provider of your own that implements IAIProvider Unchanged. RequestHost is new, with a default body that returns null. Return the host your provider calls, in lower case with no port, so that a rule on request.host can allow it; a provider that reports none is refused by such a rule.
HttpProviderBase.EmbedAsync and HttpProviderBase.SupportsEmbeddings (abstract) Removed. A subclass implements IEmbeddingProvider when its service embeds. IsModelUnavailable(status, payload) is new and virtual.
ScriptedProvider.EmbedAsync, ScriptedProvider.SupportsEmbeddings ScriptedProvider.Embeddings, an IEmbeddingProvider when the provider was given an embedder: new ScriptedProvider(request => "...", text => vector).Embeddings.
IntentClientOptions.JudgeModel The judge role: "judge": "main@<model id>". With no judge role, the judge uses the first provider of answer. IntentClientOptions.JudgeStrictness is new, FailOpen by default.

An endpoint is checked more strictly. A plain http address of a host that is not loopback, which HttpProviderSettings.BaseAddress accepted, needs "allowInsecureHttp": true on an entry that has a secret, and an address with user info (https://user:key@host/) does not load: name the key with secret instead (Provider secrets).

Dependency injection

AddIntentSharp takes its providers from the container: the provider file of a registered document store (services.AddDocumentStore("config")), a registered IProviderOptionsSource, and registered providers (Configuration and DI).

rc.3 1.0.0
IntentSharpSettings.OpenAIApiKey, IntentSharpSettings.AnthropicApiKey (the keys IntentSharp:OpenAIApiKey and IntentSharp:AnthropicApiKey) An entry's secret: "env:OPENAI_API_KEY", or "config:Keys:OpenAI" for a configuration value, user secrets included.
IntentSharpSettings.OpenAIModel, IntentSharpSettings.AnthropicModel An entry's model.
IntentSharpSettings.PrimaryProvider The order of the answer role's chain.
IntentSharpSettings.MemoryPath A memory you register (Memory).
ServiceCollectionExtensions.OpenAIHttpClientName, ServiceCollectionExtensions.AnthropicHttpClientName No constants. The named clients are still "IntentSharp.OpenAI" and "IntentSharp.Anthropic".

With no provider file, provider options source or registered provider, resolving the client throws InvalidOperationException, even when OPENAI_API_KEY or ANTHROPIC_API_KEY is set. The other keys of the IntentSharp section (Options, EnableRequestCache, CacheCapacity, RateLimitPerSecond and RateLimitBurst) bind as before. The removed keys are ignored in an existing appsettings.json, so delete them.

Databases: targets replace IntentSharp.Data

The core no longer reads a database, and the IntentSharp.Data namespace is gone. Connect your database, or any other technology, as an ITarget, and run commands through TargetRuntime; your rule files and the data.* settings decide what may run (Targets). The SQLite target the targets guide shows is an example, not part of the packages.

This rule file allows a read of every table the target describes, as rc.3 did with no table list, and sets the limits that DatabaseOptions set:

intentsharp: rules/1
set: reports-read
checkpoint: data
rules:
  - id: described-tables
    subject: data.entities
    allow: ["@described"]
    message: Use only the tables this database describes.
  - id: read-only
    subject: data.operations
    allow: [read]
    message: Only read; this set never changes data.
settings:
  data.maxResults: 500
  data.timeout: "00:00:15"
// "policy" holds the provider file, the manifest intentsharp.guardrails.json and rules/reports.rules.yaml.
using var store = new FolderDocumentStore("policy");
using var client = new IntentClientBuilder()
    .UseProviderOptions(store)
    .WithGuardrailFiles(store)
    .Build();

// target is your ITarget over your database: the connection and the schema reading live there.
var runtime = new TargetRuntime(client, target, new TargetRuntimeOptions { GuardrailSets = ["reports-read"] });
CommandOutcome outcome = await runtime.RunAsync("Customers in California, largest total first");
if (outcome.Executed)
    foreach (var record in outcome.Result!.Records) Console.WriteLine(record.ToJsonString());

Under reports-read, a read of any table the target describes is allowed, and a command that changes data is refused by the rule read-only.

rc.3 1.0.0
SemanticDatabase and its constructor (IntentClient, DbConnection, DatabaseOptions, ISchemaDiscovery) TargetRuntime(client, target, options), over a target of your own.
SemanticDatabase.QueryAsync(intent) TargetRuntime.RunAsync(request), which returns a CommandOutcome.
SemanticDatabase.PlanAsync(intent), which returned (AIResult<QueryPlan>, SqlSafetyReport) TargetRuntime.PlanAsync(request), which returns AIResult<CommandPlan>. Check the plan with CheckAsync(plan), which returns a CommandCheck.
SemanticDatabase.ExecutePlanAsync(plan) TargetRuntime.ExecuteAsync(plan), which inspects and checks the plan again before the target runs it.
SemanticDatabase.GetSchemaAsync(refresh) TargetRuntime.DescribeAsync(refresh), which returns a TargetDescription.
SemanticDatabase.UpsertAsync(tableName, sourceData, intent) TargetRuntime.RunAsync(request, input), such as RunAsync("Insert or update these rows in the customers table.", rows), under a rule set that allows writes.
SemanticDatabase.Options, DatabaseOptions TargetRuntimeOptions.Settings, a TargetSettings, and the data.* settings, which a file sets first (Settings reference).
DatabaseOptions.AllowWrites The setting data.allowWrites, false when unset, and a rule on data.operations such as allow: [read, write].
DatabaseOptions.AllowedTables A rule on data.entities: allow: [customers, orders], or allow: ["@described"] for every entity the target describes.
DatabaseOptions.MaxRows The setting data.maxResults, 1,000 when unset. CommandOutcome.Result.Truncated says when it cut the records.
DatabaseOptions.CommandTimeout The setting data.timeout, 30 seconds when unset.
DatabaseOptions.DryRun The setting data.dryRun, or CheckAsync(plan).
DatabaseOptions.RequireParameters A subject of your target's own, as the example SQLite target's sql.inlineValues with count: { max: 0 }.
DatabaseOptions.SchemaCacheDuration The target's ProbeAsync, which tells the runtime when to describe the target again.
DatabaseOptions.UseTransactionsForWrites Your target decides.
QueryPlan (Sql, Parameters, Explanation, TablesUsed) CommandPlan (Command, Parameters, Explanation, Entities, Language).
QueryResult (Rows, RowsAffected, Truncated, Executed, Plan, Safety, Planning, Elapsed, As<T>()) CommandOutcome (Result.Records, Result.Affected, Result.Truncated, Executed, Plan, Check, Planning, Elapsed, As<T>() and Maintenance).
SqlSafetyReport (IsAllowed, Violations, ReferencedTables, ParameterNames, StatementKind) CommandCheck (Allowed, Violations, Refusals, Inspection, Decision, Settings).
ISchemaDiscovery, AdoSchemaDiscovery (its constructor and DiscoverAsync) ITarget.DescribeAsync.
AdoSchemaDiscovery.DetectDialect TargetDescription.Language, which the target sets.
DatabaseSchema (Tables, Dialect, DiscoveredAt, FindTable) TargetDescription (Entities, Language, SensedAt).
TableSchema (Name, Schema, QualifiedName, Columns) TargetEntity (Path, Name, Kind, Fields, Operations).
ColumnSchema (Name, DataType, IsNullable, IsPrimaryKey) TargetField (Name, Type, Nullable, IsKey, Children).
SemanticDatabaseException (Reasons), in IntentSharp.Providers Not an exception: a refused command has Executed false, and its Check holds the violations and refusals. A target's own failure throws TargetOperationException, in IntentSharp.Targets, with its Kind.

What a command may do is closed until a file opens it:

  • An unset data.entities allows no entity, where rc.3's null AllowedTables allowed every discovered table. One line restores the old reach: allow: ["@described"] on data.entities, as in the file above. List the tables instead when the application needs fewer.
  • No write and no operation runs until a rule allows it, and a write needs data.allowWrites too. A command returns at most 1,000 records and runs at most 30 seconds unless a setting says otherwise.
  • A command whose inspection names no table or other entity is refused, as nothing was checked, unless the target sets TargetInspection.TouchesNoEntity (Targets).

Memory

rc.3 1.0.0
SqliteSemanticMemory (its constructor (path, IAIProvider embeddingProvider, logger), RecordAsync, RecallAsync, GetStatsAsync, ClearAsync and RecallCandidateLimit) Removed from the package. A log that survives a restart is an ISemanticMemory of your own, given with builder.WithMemory(memory); the in-process InMemorySemanticMemory is the default (Memory, cache and rate limiting).
InMemorySemanticMemory(int maxEntries, IAIProvider embeddingProvider, ILogger logger) InMemorySemanticMemory(int maxEntries, IEmbeddingProvider embeddingProvider, ILogger logger): the embedder is an IEmbeddingProvider.
IntentSharpSettings.MemoryPath (a path) Register the memory: services.AddSingleton<ISemanticMemory>(memory).
IntentSharpSettings.MemoryPath = "" (no memory) IntentSharp:Options:RecordInMemory set to false.

Renamed types and the root namespace

Six types are renamed so that each word has one meaning: "guardrail" names only the rule sets checked at checkpoints, an object you configure in code is *Options while "settings" names the settings a file or code sets, and an in-process implementation is InMemory*. There is no alias for an old name, so replace it where your code names it. Members keep their names and signatures unless a row says otherwise.

rc.3 1.0.0
AIGuardrailAttribute, written [AIGuardrail(GuardrailType.MaxAttempts, 3)] AIConstraintAttribute, written [AIConstraint(ConstraintKind.MaxAttempts, 3)], in the same namespace, IntentSharp.Attributes. Its constructor, Type, Value, Description and ApplyTo are unchanged.
GuardrailType (MaxAttempts, MaxExecutionTimeMs, MaxModelCalls, RequireJudge, OutputRequirement, CustomValidator) ConstraintKind, with the same six members and values.
IGuardrailValidator (Validate(object value)) IOutputValidator, with the same member: public sealed class OneToTen : IOutputValidator.
AIGuardrailException in IntentSharp.Providers, its property Guardrail and its constructor parameter guardrail AIConstraintException in IntentSharp, its property Constraint and its constructor parameter constraint: new AIConstraintException("ReviewBudget", "The review budget is spent.").
IntentSharpException in IntentSharp.Providers IntentSharpException in IntentSharp: add using IntentSharp; for catch (IntentSharpException ex). The provider exceptions (AIProviderException and its subtypes, AITimeoutException, ProviderConfigurationException) stay in IntentSharp.Providers.
MemoryRequestCache, in IntentSharp.Resilience InMemoryRequestCache, with the same constructor and members: builder.WithCache(new InMemoryRequestCache(capacity: 1000)).
HttpProviderSettings, in IntentSharp.Providers: the type of HttpProviderBase's constructor parameter settings and of its field Settings HttpProviderOptions, with the same properties and the new MaxResponseBytes (16 MB by default).
HttpProviderBase's protected field Settings and its constructor parameter settings Options and options. A provider derived from HttpProviderBase reads Options.Model where it read Settings.Model, and a call that names the argument writes options:.

A constraint value of the wrong kind throws ArgumentException with "Constraint MaxAttempts expects ...", where rc.3 said "Guardrail MaxAttempts expects ...", and an unknown kind throws ArgumentOutOfRangeException with "Unknown constraint kind.", where rc.3 said "Unknown guardrail type.". A test that compares these messages needs the new text.

Constraint issues

The model-call ceiling, the time budget and a setting that refuses a call before it is sent end the request with an IssueSource.Constraint issue, and so does an AIConstraintException your own code throws, such as a judge of your own. rc.3 reported the ceiling and the time budget as IssueSource.Guardrail, which now names only a rule set's refusal at a checkpoint. Constraint is a new member, after Mapping, with the value 6, so the other members keep their values. Code that tested IssueSource.Guardrail to find a ceiling or a time budget tests IssueSource.Constraint.

IntentSharp.Extensions.AI

rc.3 1.0.0
IntentToolExtensions.MaxToolNameLength, the constant 64 IntentToolOptions.MaxToolNameLength, 64 by default: runtime.AsAIFunctions(new IntentToolOptions { MaxToolNameLength = 128 }).
AsAIFunction(this IntentRuntime runtime, string name, string toolName, ILogger logger) and its IIntentInvoker form The same, with a last optional IntentToolOptions options. Your code compiles as it is; recompile it.
ToToolName(string intentName) ToToolName(string intentName, IntentToolOptions options = null). Your code compiles as it is.
ChatClientProvider(IChatClient chatClient, IEmbeddingGenerator embeddingGenerator, string name, string model, ILogger logger) ChatClientProvider(IChatClient chatClient, string name, string model, ILogger logger), and the generator in new ChatClientEmbeddingProvider(generator, name, logger). UseChatClient(chatClient, embeddingGenerator, ...) still takes both.
ChatClientProvider.EmbedAsync, ChatClientProvider.SupportsEmbeddings ChatClientEmbeddingProvider.EmbedAsync(text, EmbeddingRequest, cancellationToken).

An agent tool's error for an exception is its type and a short reason, such as the provider and the HTTP status, where rc.3 returned the type and the whole message. new IntentToolOptions { IncludeErrorDetail = true } returns the whole message and the provider's reply.

An application that loaded its own instruction files

An rc.3 application could keep its instructions in files of its own: it read each file, watched the folder, and kept copies of each wording to know which one ran. The IntentSharp.Catalog package does this for intent files, and in 1.0.0 it also keeps the versions of each file. Before, the application read its file and passed the text to each call:

// rc.3: the application kept the wording in a file of its own and passed the text to each call.
string intent = await File.ReadAllTextAsync(Path.Combine("instructions", "classify-urgency.txt"));
AIResult<int> urgency = await client.TransformAsync<int>(email, intent);

After, the wording, the result shape, the rules and the examples are one intent file:

name: Orders.ClassifyUrgency
version: 1
owner: order-desk
intent: Rate the urgency of this order email from 1 (routine) to 5 (critical).
shape: int
rules:
  minimum: 1
  maximum: 5
examples:
  - input: "Line 3 is down until the bearings arrive. Ship today."
    output: 5
  - input: "Please restock these when convenient, no rush."
    output: 1

The catalog loads the folder of such files, and the runtime runs an intent by name:

// 1.0.0: the wording, the result shape, the rules and the examples are the intent file
// intents/Orders.ClassifyUrgency.intent.yaml, which the catalog loads, and loads again when it changes.
using var catalog = new FileIntentCatalog("intents");
var runtime = new IntentRuntime(client, catalog);

IntentCatalogSnapshot snapshot = catalog.Current;
foreach (CatalogProblem problem in snapshot.Problems)
    Console.WriteLine($"Not loaded: {problem}");

AIResult<int> urgency = await runtime.RunAsync<int>("Orders.ClassifyUrgency", email);
  • catalog.Current is an IntentCatalogSnapshot: the intents that loaded (Definitions), the problems of the latest load (Problems), a Generation that rises with every load, and LoadedAt.
  • A saved edit applies to the next run. A file that does not load keeps its last good version, and the problem names the file and the line.
  • Each run is tagged with intent.name, intent.version and intent.source, so a recorded call names the intent, its version and its file.
  • Over a writable folder, the catalog keeps up to 100 versions of each file in a .intentsharp folder inside it (the history, state.json and a lock file), with revert and side-by-side runs (Documents and edits). Leave that folder out of source control. To keep the history elsewhere, create a FolderDocumentStore with FolderDocumentStoreOptions.StateRoot and a DocumentIntentCatalog over it.

The catalog checks the rules and the result shape, so checks the application wrote around the text can move into the file (Running intents from files, Intent file reference). TransformAsync still takes intent text from code, for an application that keeps it there.

Intent files and schemas

  • FileIntentCatalog over a read-only folder, such as one baked into an image, works as before, with the history in memory; its first snapshot reports that comparison across restarts is off.
  • The catalog reads its folder by the folder store's rules: an intent file larger than 4 MB is reported and not read; a file whose name is a reserved Windows device name (con.intent.json), ends with a dot or a space, or holds a colon is not read on any platform; and a file behind a folder link, or a file link whose target is outside the folder, is not read. rc.3 had none of these limits.
  • A schema's $ref to an external URI is a load problem that names the file and the reference, where rc.3 loaded the file and then failed every reply.
  • A $ref to a JSON Schema meta-schema the library ships, such as https://json-schema.org/draft/2020-12/schema, still loads, and the reply is still checked against it, but the provider gets an open object in its place. The settings schemas.metaSchemaRefs and providers.strictSchemaFallback choose what such a call does, for an intent's schema and for a schema given to TransformAsync alike (Settings reference).
  • A schema that applies more than 10,000 subschemas at one place in a value, or nests more than 320 subschemas along one path, is a load problem, where rc.3 loaded it. So is a $schema of a dialect the schema library does not build in, such as http://json-schema.org/draft-04/schema#.
  • A YAML file whose aliases repeat more than 4,000,000 characters of text fails to load, with a problem on its line.

Other behavior that changed

  • A request ends at 5 minutes. IntentClientOptions.DefaultTimeout was none in rc.3; it is now 5 minutes, and it covers every attempt, retry wait, fallback and judge call. A call that needs longer fails with a Constraint issue until you raise it: o.DefaultTimeout = TimeSpan.FromMinutes(15), AIRequestOptions.Timeout for one call, or client.timeout in a settings file, which beats code. o.DefaultTimeout = null keeps rc.3's behavior. IntentClient.EmbedAsync runs under the same budget and throws AITimeoutException when it runs out.
  • Redirects are not followed. rc.3's providers followed a 3xx reply. The 1.0.0 kinds, and the named clients of AddIntentSharp, fail the call instead and name both hosts. Point the entry's endpoint at the address that serves it, and turn redirects off on a handler of your own (HttpClientHandler.AllowAutoRedirect = false).
  • A supplied HttpClient's BaseAddress is not used. Every request goes to the entry's endpoint, with a Warning once for a client that has an address of its own. To reach a proxy, put its address in the entry's endpoint.
  • WithHttpClientFactory is asked for the entry's name, where rc.3's providers asked for "OpenAI" and "Anthropic": WithHttpClientFactory(name => name == "main" ? proxied : null).
  • An endpoint's query is sent. rc.3 dropped a query such as ?api-version=2024-10-21 from the address; the openai and anthropic kinds now add it to every request.
  • A reply over 16 MB from the openai or anthropic kind fails the call (IntentClientOptions.MaxResponseBytes), where rc.3 read any reply whole.
  • Provider exception messages carry no reply body. The message names the provider, the status and the provider's error code; the body is on AIProviderException.Detail, and the client logs it at Debug. Code that read the body from Message reads Detail.
  • A judge refusal fails the attempt. When the judge's provider marks its reply as a refusal, such as a content filter, the attempt fails with "The judge refused to review this output, so it was not approved." and a result warning, whatever JudgeStrictness says. rc.3 accepted it as an unreadable reply. A reply that is only unreadable is still accepted under the default, FailOpen.
  • Every request marks its input as data. The request text differs from rc.3, so a test that compares prompt text or recorded request bodies needs the new text, and a reply cached under rc.3 is not served. A judge of your own that sends the answer to a model should mark that answer as data to review, too.
  • A cached reply that fails a request's checks is withdrawn. InMemoryRequestCache removes it. A cache of your own (IRequestCache) is handed SetAsync with a refusal that has no text (AIResponse.IsRefusal true) for the request's cache lifetime, which the client reads back as a miss. Store it like any other response; a cache that drops it keeps the failing reply, to be read and checked again by every identical request.