Public API

Every public type in the library packages, grouped by namespace. The core package, IntentSharp, comes first; its files are relative to src/IntentSharp. The two packages beside it, IntentSharp.Catalog and IntentSharp.Extensions.AI, follow at the end.

IntentSharp

Type	File	Purpose
IntentClient	IntentClient.cs	The entry point: TransformAsync<T>, TransformAsync (text), TransformAsync(input, intent, JsonNode outputSchema) (a runtime-defined shape, returning AIResult<JsonNode>), GenerateAsync<T>, ExecuteIntentAsync<T>, EmbedAsync, AsAmbient(); token and call totals; License, the current license status (evaluated at Build(), date-based state refreshed while the client is used). Dispose and DisposeAsync dispose the primary and fallback providers, including ones passed to UseProvider or UseFallbackProvider: the client owns its providers.
IntentClientScope	IntentClientScope.cs	The ambient client for one async flow, returned by IntentClient.AsAmbient(). Static Current (throws with guidance when no scope is open) and CurrentOrNull, both of which skip ended scopes on every flow; Dispose restores the previous client while this scope's client is still ambient, disposing an outer scope ends the scopes opened inside it, and a second Dispose does nothing.
IntentClientBuilder	IntentClientBuilder.cs	Fluent construction: providers, memory, cache, rate limiter, judge, logging, options, license key. A primary and a fallback with the same name (ignoring case) are refused with ArgumentException. Build() evaluates the license key and throws LicenseException for the version gate or under FailWhenUnlicensed.
IntentClientOptions	IntentClientOptions.cs	Client-wide defaults: attempts, tokens, temperature, input limit, timeout, model-call ceiling, judge, memory, cache, fallback, license key, FailWhenUnlicensed, LicenseReminderInterval.
AIRequestOptions	IntentClientOptions.cs	Per-request overrides, validators (Validate<T>, Require<T>), tags, cache and memory opt-outs, Examples, OutputSchema, Clone().
IntentExample	IntentClientOptions.cs	A worked example: Input and the exact Output expected, rendered in the prompt's examples section.
JudgeMode	IntentClientOptions.cs	Never, OnRequest, Always.

A literal null options argument

IntentClient has two non-generic TransformAsync overloads that start with (object? input, string intent, ...): the text overload, whose third parameter is AIRequestOptions? options, and the runtime-shape overload, whose third parameter is JsonNode outputSchema. A literal null converts to both, so client.TransformAsync(input, intent, null) does not compile (CS0121, the call is ambiguous). For text with no options, omit the argument or type the null:

var text = await client.TransformAsync(input, intent);                            // options omitted
var same = await client.TransformAsync(input, intent, (AIRequestOptions?)null);   // typed null
var json = await client.TransformAsync(input, intent, schema);                    // runtime shape

The overloads stay as they are. A call to the runtime-shape overload always passes a schema third, so its options argument, omitted or null, is not ambiguous.

IntentSharp.Results

Type	Purpose
AIResultBase	Shared result fields: Success, Issues, Warnings, Attempts, Intent, Provider, Model, Usage, Elapsed, RawOutput, FromCache, FailureSummary.
AIResult<T>	Typed result: Value, GetValueOrThrow(), GetValueOrDefault(fallback).
ResultIssue	One problem: Source, Message, Attempt.
IssueSource	Provider, Verification, Validator, Judge, Guardrail.
AttemptRecord	One attempt: number, provider, model, usage, elapsed, passed, raw output, issues.

IntentSharp.Providers

Type	Purpose
IAIProvider	Provider contract: Name, DefaultModel, SupportsEmbeddings, CompleteAsync, EmbedAsync.
AIRequest, AIResponse, AIMessage, TokenUsage, ResponseFormat	Provider-neutral request and response shapes.
HttpProviderBase, HttpProviderSettings	Shared HTTP plumbing: retries, backoff, error mapping, timeouts.
OpenAIProvider	Chat Completions and embeddings.
AnthropicProvider	Messages API with output_config structured output.
IntentSharpException	Base exception for the library.
AIProviderException	A provider call failed; ProviderName, HttpStatusCode, IsTransient.
AIRateLimitException	HTTP 429 or the local limiter refused; RetryAfter.
AIAuthenticationException, AIValidationException, AIProviderInternalException	401/403, 400/422, 5xx.
AITimeoutException	An HTTP request exceeded its timeout.
AIGuardrailException	A guardrail stopped the operation; Guardrail names it.
SemanticDatabaseException	The database runtime refused or failed; Reasons.

Every provider exception type (AIProviderException and its subtypes, and AITimeoutException) has a constructor that takes an inner exception, so an adapter such as ChatClientProvider can keep the original failure.

IntentSharp.Prompting

Type	Purpose
PromptBuilder	Plan and Build; SystemPreamble.
PromptPlan	Everything known before a call: intent, target type, serialized input, schema, extra instructions, examples; IsRuntimeShape.
InputSerializer	Input value to prompt text (a JsonNode, JsonElement or JsonDocument as its JSON text); type descriptions.
JsonSchemaBuilder	Envelope and strict schemas (BuildEnvelope from a type, BuildEnvelopeFromSchema from a runtime schema, which hoists the caller's definitions and rewrites root-relative $ref pointers); SerializerOptions; EnvelopeProperty.

IntentSharp.Verification

Type	Purpose
DeterministicVerifier	Verify<T> and StripFences.
VerificationOutcome<T>	Passed, Value, Issues.
IResultJudge	Judge contract.
ModelJudge	Model-as-judge on a provider.
JudgeVerdict	Passes, Problems.

IntentSharp.Intent

Type	Purpose
IntentLint	Advisory intent checks returned as warnings; MaxIntentLength.
IntentTemplates	Convert, Extract, Summarize, Classify, Translate, Sql phrasings.

IntentSharp.Attributes

Type	Purpose
AIIntentAttribute	Declares an intent on a method or class for ExecuteIntentAsync.
AIGuardrailAttribute	Declares a constraint; ApplyTo(AIRequestOptions).
GuardrailType	MaxAttempts, MaxExecutionTimeMs, MaxModelCalls, RequireJudge, OutputRequirement, CustomValidator. The three [Obsolete] version 1 aliases were removed in 1.0.0-rc.1: use MaxAttempts for MaxRecursionDepth, RequireJudge for MinConfidenceScore and OutputRequirement for SchemaValidation.
IGuardrailValidator	Custom output check used by CustomValidator.

IntentSharp.Extensions

Type	Purpose
AIExtensions	AIAsync, AIConvertAsync, AIClassifyAsync, AIMapAsync, AIFilterAsync, AISortAsync, AIGroupAsync, AIReduceAsync, AIMapValuesAsync, Project.
AmbientAIExtensions	The same methods except Project, without the client parameter. They use IntentClientScope.Current and throw InvalidOperationException with guidance when no scope is active.
AIExtensions.IndexedItem<T>, IndexGroup, KeyedEntry<T>	Shapes exchanged with the model by the collection methods.

IntentSharp.Data

Type	Purpose
SemanticDatabase	GetSchemaAsync, PlanAsync, QueryAsync, ExecutePlanAsync, UpsertAsync.
DatabaseOptions	Writes, allowlist, dry run, row cap, timeouts, parameters, transactions.
QueryPlan	The model's statement, parameters, explanation and tables.
QueryResult	Rows or affected count, safety report, planning result; As<T>().
SqlSafetyChecker, SqlSafetyReport	The SQL guard and its verdict.
ISchemaDiscovery, AdoSchemaDiscovery	Schema discovery; DetectDialect.
DatabaseSchema, TableSchema, ColumnSchema	Discovered schema; ToPromptText, FindTable.

IntentSharp.Memory

Type	Purpose
ISemanticMemory	Record, recall, stats, clear.
InMemorySemanticMemory, SqliteSemanticMemory	In-process and SQLite implementations.
MemoryEntry, MemoryMatch, MemoryStats	Stored entry, recall hit, totals.
Similarity	Cosine, TokenOverlap, Tokens.

IntentSharp.Resilience

Type	Purpose
IRequestCache, MemoryRequestCache, CacheStats	Response cache and its stats.
RequestCacheKey	Stable key for a request.
IRateLimiter, TokenBucketRateLimiter, RateLimitSnapshot	Local throttle and its snapshot.

IntentSharp.DependencyInjection

Type	Purpose
ServiceCollectionExtensions	AddIntentSharp(IConfiguration, sectionName) and AddIntentSharp(Action<IntentSharpSettings>); named HTTP clients IntentSharp.OpenAI and IntentSharp.Anthropic.
IntentSharpSettings	Keys, models, primary provider, memory path, cache and rate-limit settings, Options.

IntentSharp.Licensing

Details in licensing.md.

Type	Purpose
LicenseEdition	Evaluation, Developer, Team, Business, Enterprise, Oem.
LicensePayload	The signed content of a key: version, id, licensee, email, edition, seats, issued, expires, maintenance-until, features, notes.
LicenseKeyCodec	The ISK1.<payload>.<signature> wire format: Prefix, JsonOptions, SerializePayload, Encode, TryDecode, base64url helpers.
LicenseKeyStatus	Missing, Malformed, BadSignature, Valid.
LicenseVerification	The verifier's result: Status, Payload, Error.
LicenseVerifier	Checks a key's signature against one or more trusted public keys. Thread-safe.
LicensePublicKeys	The trusted signing public keys; All.
ReleaseInfo	ReleaseDate (the version gate) and Version of this build.
LicenseState	None, Invalid, Evaluation, EvaluationExpired, Licensed, RenewalDue, Lapsed, VersionGated. Read it as client.License.State.
LicenseStatus	The evaluated state: State, Payload, Message, DaysRemaining. Returned by IntentClient.License and LicenseEnforcer.Status.
LicenseEnforcer	Applies the policy for one client: Evaluate, Status, ThrowIfGated, ThrowIfUnlicensed, LogStatus, MaybeRemind (the reminder, which also refreshes the date-based state), ReleaseDate, ReminderInterval, RenewalWindowDays (30), DefaultReminderInterval (one hour).
LicenseException	Thrown by Build() for the version gate (paid keys only), and for no key, an invalid key or an ended evaluation when FailWhenUnlicensed is set. Status and State name the cause.
LicenseInfo	Constants compiled into every build: LicenseName, Licensor ("C2Consultants LLC"), ContactEmail ("licensing@c2consultants.net"), PurchaseUrl ("https://intentsharp.com/pricing"), FreeUseSummary; and the property PurchaseInstructions, built from the contact and the purchase URL.

Licensing members on other types:

Member	Purpose
IntentClient.License	The client's current LicenseStatus: evaluated at Build(), with the date-based state refreshed at most once per LicenseReminderInterval while the client is used.
IntentClientOptions.LicenseKey	The key, ISK1. followed by payload and signature. Set by IntentClientBuilder.WithLicenseKey or IntentSharp:Options:LicenseKey.
IntentClientOptions.FailWhenUnlicensed	Default false. When true, Build() throws LicenseException for no key, an invalid key or an ended evaluation.
IntentClientOptions.LicenseReminderInterval	Minimum time between repeated license notices, and between date refreshes. Default one hour; must be greater than zero.

Every license log line carries EventId 9100, named "IntentSharp.License". The notice text itself is internal and is not part of the public API.

Not in the library: LicenseSigner (namespace IntentSharp.Licensing.Signing) is in src/IntentSharp.Licensing.Signing and is used only by the license tool, the license service and tests.

IntentSharp.Testing

Type	Purpose
ScriptedProvider	In-process provider with queued or computed replies; records requests.

IntentSharp.Catalog

Package IntentSharp.Catalog, folder src/IntentSharp.Catalog. The contract types are in Model/. Details in intent-catalog.md.

Type	Purpose
IntentDefinition	One intent as data: Name, Version, Intent, Description, Shape, Rules, Validators, Examples, OutputRequirements, SystemInstructions, Attempts, Judge, Provider, Model, Timeout, MaxOutputTokens, DoNotRecord, Enabled, Owner, Tags, and Source (set by the loader).
IntentShape, IntentShapeKind	The result shape: Kind (Text, Primitive, Clr, Schema), Primitive, ClrType, Schema; IntentShape.Text.
IntentRules	Declarative checks: Minimum, Maximum, MinLength, MaxLength, Pattern, Enum, MinItems, MaxItems, UniqueItems, NotEmpty, Required, Properties, Items.
IIntentCatalog	A source of definitions: Current, GetChangeToken(), ReloadAsync.
IntentCatalogSnapshot	The catalog at one moment, replaced atomically and never changed in place; its definitions are the catalog's own objects, to be treated as read-only: Generation, Definitions (case-insensitive), Problems, LoadedAt, TryGet, Empty.
CatalogProblem	One load problem: Source, Line, Message; prints as source:line: message.
IIntentValidatorRegistry, IntentValidatorRegistry	Named code validators that files may reference: TryGet, Names; Add(name, Func<object?, IEnumerable<string>>).
IIntentTypeRegistry, IntentTypeRegistry	.NET types that clr shapes may name: TryResolve, Names; Add<T>(), Add(name, Type).
FileIntentCatalog	IIntentCatalog over a folder of *.intent.json, *.intent.yaml and *.intent.yml files, with hot reload; IDisposable.
InMemoryIntentCatalog	IIntentCatalog for tests and code-defined intents: Add, Remove, Replace.
IntentDefinitionParser	Parse(text, source, format): definitions and problems from JSON or YAML.
IntentRuleEngine	Evaluate(IntentRules, JsonNode): one message per violated rule.
IntentRuntime	Runs named intents: RunAsync<T>(name, input), RunAsync(name, input) (any shape, as AIResult<JsonNode>), Describe(name), Catalog, AsAmbient().
IntentScope	The ambient runtime for one async flow, returned by IntentRuntime.AsAmbient(). Current, CurrentOrNull; Dispose behaves as IntentClientScope.Dispose.
IntentExtensions	value.RunIntentAsync<T>(runtime, "Name"), and value.RunIntentAsync<T>("Name") through the ambient IntentScope.
CatalogServiceCollectionExtensions	services.AddIntentCatalog(folder, configure?) and services.AddIntentRuntime(). Validators and types are registered with services.AddIntentValidator(name, fn) and services.AddIntentType<T>().
IntentNotFoundException, IntentDisabledException, IntentShapeMismatchException	Programming errors from IntentRuntime; all derive from IntentSharpException.

IntentSharp.Extensions.AI

Package IntentSharp.Extensions.AI, folder src/IntentSharp.Extensions.AI. Details in extensions-ai.md.

Type	Purpose
ChatClientProvider	An IAIProvider over a Microsoft.Extensions.AI IChatClient, with an optional IEmbeddingGenerator<string, Embedding<float>>. Chat-client failures become IntentSharp provider exceptions with the original as the inner exception; DefaultName.
ChatClientBuilderExtensions	On IntentClientBuilder: UseChatClient(IChatClient, IEmbeddingGenerator? = null, string? name = null, string? model = null, ILogger? logger = null) and UseChatClientAsFallback(...) with the same parameters. The logger sees the chat client's translated failures at Debug.
IntentToolExtensions	On IntentRuntime, and on any IIntentInvoker: AsAIFunction("Name", toolName = null, logger = null), AsAIFunctions(params string[] names), AsAIFunctions(ILogger? logger, params string[] names), AsAIFunctions() and AsAIFunctions(ILogger? logger), Microsoft.Extensions.AI AIFunction tools that agents can call. A tool logs each exception it answers with success: false at Warning to the logger. ToToolName, IntentNameProperty, MaxToolNameLength (64).
IIntentInvoker	What the tools need from an intent runner: RunAsync, Describe, EnabledDefinitions. Implement it to expose another runner as tools; IntentRuntime needs no wrapper.