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.entitiesallows no entity, where rc.3's nullAllowedTablesallowed every discovered table. One line restores the old reach:allow: ["@described"]ondata.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.allowWritestoo. 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.Currentis anIntentCatalogSnapshot: the intents that loaded (Definitions), the problems of the latest load (Problems), aGenerationthat rises with every load, andLoadedAt.- 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.versionandintent.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
.intentsharpfolder inside it (the history,state.jsonand 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 aFolderDocumentStorewithFolderDocumentStoreOptions.StateRootand aDocumentIntentCatalogover 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
FileIntentCatalogover 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
$refto 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
$refto a JSON Schema meta-schema the library ships, such ashttps://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 settingsschemas.metaSchemaRefsandproviders.strictSchemaFallbackchoose what such a call does, for an intent's schema and for a schema given toTransformAsyncalike (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
$schemaof a dialect the schema library does not build in, such ashttp://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.DefaultTimeoutwas 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 aConstraintissue until you raise it:o.DefaultTimeout = TimeSpan.FromMinutes(15),AIRequestOptions.Timeoutfor one call, orclient.timeoutin a settings file, which beats code.o.DefaultTimeout = nullkeeps rc.3's behavior.IntentClient.EmbedAsyncruns under the same budget and throwsAITimeoutExceptionwhen 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'sendpointat the address that serves it, and turn redirects off on a handler of your own (HttpClientHandler.AllowAutoRedirect = false). - A supplied
HttpClient'sBaseAddressis not used. Every request goes to the entry'sendpoint, with aWarningonce for a client that has an address of its own. To reach a proxy, put its address in the entry'sendpoint. WithHttpClientFactoryis 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-21from the address; theopenaiandanthropickinds now add it to every request. - A reply over 16 MB from the
openaioranthropickind 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 atDebug. Code that read the body fromMessagereadsDetail. - 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
JudgeStrictnesssays. 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.
InMemoryRequestCacheremoves it. A cache of your own (IRequestCache) is handedSetAsyncwith a refusal that has no text (AIResponse.IsRefusaltrue) 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.