Settings reference

A setting is a named value that bounds or chooses what IntentSharp does, such as client.maxAttempts or data.allowWrites. A setting can be written in a rule file, in the settings document or in code, and a file wins over code. This page lists every setting the library declares. The IntentSharp section of your configuration is not a settings file: it configures the client, and its values are code values here (Configuration and DI).

Where a value comes from

Each setting takes the first value it finds, in this order:

1. The settings block of a rule set the operation is checked against, in the order the sets are named (Guardrails). When several sets give a security setting a value, the narrowest applies: the smaller number or time, or false; for a text setting, its fail-closed value when one set gives it.
2. The settings document, a settings file named intentsharp.settings.json in the client's document store: the store WithDocumentStore gives the builder, or the one AddDocumentStore registers. With a YAML format added, as WithGuardrailFiles adds one, it can be intentsharp.settings.yaml or .yml instead.
3. Code: the operation's own value (a request's AIRequestOptions, a target runtime's TargetSettings), else the client's code settings (GuardrailOptions.CodeSettings, or the CodeSettings of the options WithGuardrailFiles takes), else, for the client.* settings, the IntentClientOptions value.
4. The library default, or, for a security setting, its fail-closed value.

Code is the application's default, never a ceiling: a file may raise a limit that code sets, or remove it with unlimited, and a file's value beats a request's own AIRequestOptions value too. A model that can edit your files can do the same, so the edits that widen are flagged (below). The settings document applies to every check and request of the client; a rule set's block applies only to the operations checked against that set.

The settings document holds a value for any declared setting:

{
  "intentsharp": "settings/1",
  "settings": {
    "client.timeout": "00:10:00",
    "client.maxModelCalls": 8,
    "data.maxResults": 500
  }
}

A rule set's block holds any declared setting but rules.ambiguousSet, which decides which rule file serves a set name: a rule file that sets it does not load. This set lowers client.maxModelCalls for the requests checked against it:

intentsharp: rules/1
set: requests
checkpoint: request
rules:
  - id: known-providers
    subject: request.provider
    allow: [main, backup]
    message: Call only the providers this application names.
settings:
  client.maxModelCalls: 4

A client over both files, with two client options in code:

// "policy" holds the provider file, the settings document intentsharp.settings.json, the manifest
// intentsharp.guardrails.json and the rule files it lists.
using var store = new FolderDocumentStore("policy");
using var client = new IntentClientBuilder()
    .UseProviderOptions(store)
    .WithDocumentStore(store)                 // the settings document is read from the client's store
    .WithGuardrailFiles(store, "requests")    // the rule files, and the settings blocks of their sets
    .Configure(o =>
    {
        o.MaxAttempts = 3;                            // client.maxAttempts, in code
        o.DefaultTimeout = TimeSpan.FromMinutes(2);   // client.timeout, in code
    })
    .Build();

A call reads its client.* settings once, when it starts, and a saved edit of a file applies to the next call. Under the set requests, its result carries the decision of its Request checkpoint, with every setting that check ran under and where each value came from:

AIResult<string> summary = await client.TransformAsync(email, "Summarize this support email in one sentence.");

// The settings the call's Request checkpoint ran under, and where each value came from.
foreach (var name in new[] { "client.maxAttempts", "client.maxModelCalls", "client.timeout", "rules.patternTimeout", "data.allowWrites" })
{
    SettingValue value = summary.Guardrails!.Settings[name];
    Console.WriteLine($"{name} = {value.Value?.ToJsonString()} ({value.Source})");
}

On a scripted reply it prints:

client.maxAttempts = 3 (Code)
client.maxModelCalls = 4 (File)
client.timeout = "00:10:00" (File)
rules.patternTimeout = "00:00:00.250" (LibraryDefault)
data.allowWrites = false (FailClosed)

client.maxAttempts comes from code; client.maxModelCalls from the rule set's block, ahead of the settings document's 8; client.timeout from the settings document, ahead of code's 2 minutes; rules.patternTimeout is the library default; and data.allowWrites, a security setting nothing sets, is false. A SettingValue has the Value, IsUnlimited and Source: File (a rule set's block or the settings document), Code, LibraryDefault, FailClosed, or None for a setting of your own with no default that nothing sets. A target command's settings are in CommandCheck.Settings, and client.CheckAsync returns the decision of a check of your own.

Values

• A number is a whole number, written as a JSON number.
• A time is text: hh:mm:ss, with optional days and fractions (1.00:00:00, 00:00:00.250), or ISO 8601 such as PT30S. A bare number is refused.
• unlimited, written exactly so, removes a number or time limit where the table lists it, in a file or in the code settings.
• Text is one of the values the table lists.

Zero is refused for a number or a time unless the table says "from 0", a negative value is always refused, and zero never means no limit. A value a setting cannot take never removes a limit: a rule file or a settings document that holds one does not load, and the version before it keeps running. In code, such a value is an error: the builder or the call throws, and a check given one is refused.

Security settings

Six settings guard access or bound what an operation may do. When nothing sets one, it takes its fail-closed value, never a permissive default: data.allowWrites is false, data.timeout is 30 seconds, data.maxResults is 1,000, rules.ambiguousSet is serveNeither, environment.pendingHold is allOperations and mapping.replyCheck is check. A file may still remove data.timeout or data.maxResults with unlimited.

environment.pendingHold and mapping.replyCheck decide whether a check runs. While a rule set or the settings document cannot be read, each takes its fail-closed value whatever code says, and a check that cannot read the settings document is refused.

What a target command may touch is not a setting: the rules on data.entities and data.operations decide it, and with no rule nothing is allowed (Targets).

Edits that are flagged

An edit of the settings document or of a rule file is applied by default. It is flagged, with EditImpact.WidensSecurity true and the setting named in WidenedSubjects, when it writes the value the Flagged column names:

• a security setting widened: a higher number or time, unlimited, true for data.allowWrites, or the other value of a text setting (for mapping.replyCheck, skip; recompileOnce still checks every value);
• one of seven ordinary limits on time and spend raised or made unlimited: client.maxAttempts, client.maxModelCalls, client.maxInputChars, client.timeout, rules.patternTimeout, environment.handlerTimeout and environment.maxRecompilesPerHour.

The new value is compared with the running version's value, else with the value that applies without the file: for a security setting its fail-closed value, for a limit the code value, else the library default. A lower value is not flagged. Removing a setting from a file is not flagged either, even when the value that then applies, from code, allows more; an edit of the settings document lists every setting it changes, a removal included, in EditImpact.Changes. To hold flagged edits for a person to review, wrap the edit writer (Guardrails).

The settings

Each table lists one area. Unset is the value when no file and no code sets the setting. The table is checked against the library when the site is built.

Requests

Read once when a request starts, for every attempt, fallback and judge call of it. The code values are the IntentClientOptions properties MaxAttempts, MaxModelCalls, MaxOutputTokens, MaxInputChars, CacheTtl, DefaultTimeout and JudgeStrictness, and for one request AIRequestOptions.MaxAttempts, MaxModelCalls, MaxOutputTokens and Timeout (How it works).

Setting	Values	Unset	Security	Flagged	What it decides
client.maxAttempts	a number above 0, or unlimited	2	No	higher, or unlimited	How many attempts a request may make.
client.maxModelCalls	a number above 0, or unlimited	6	No	higher, or unlimited	How many model calls a request may make, judge calls included.
client.maxOutputTokens	a number above 0	4096	No	No	The most output tokens a model call may ask for.
client.maxInputChars	a number above 0, or unlimited	200000	No	higher, or unlimited	The longest serialized input a request may send, in characters. A longer one is refused before any model call, never cut.
client.cacheTtl	a time above 0, or unlimited	01:00:00 (one hour)	No	No	How long a cached reply is served.
client.timeout	a time above 0, or unlimited	00:05:00 (5 minutes)	No	higher, or unlimited	How long one request may run, every attempt, retry wait, fallback provider and judge call included.
client.judgeStrictness	failOpen or failClosed	failOpen	No	No	Whether a judge reply that cannot be read as a verdict accepts the attempt (failOpen) or fails it (failClosed).

A request whose other limits are removed still ends at its time budget, a refusal or the provider's own limits. One whose attempts, model calls and time budget are all unlimited ends only at a reply that passes, a refusal, a provider error or your cancellation token, so a request whose replies keep failing their checks never ends.

Target commands

Read for each command a target runtime plans, checks and runs. The code values are the TargetSettings of TargetRuntimeOptions.Settings (Target limits).

Setting	Values	Unset	Security	Flagged	What it decides
data.dryRun	true or false	false	No	No	With true, commands are planned and checked, and none runs.
data.allowWrites	true or false	false	Yes	true	Whether a command may change data. With false, every operation but read is refused.
data.timeout	a time above 0, or unlimited	00:00:30 (30 seconds)	Yes	higher, or unlimited	How long one execution may run before it is cancelled.
data.maxResults	a number above 0, or unlimited	1000	Yes	higher, or unlimited	The most records one command returns; the rest are cut off, and Truncated is true.

Rule files

Setting	Values	Unset	Security	Flagged	What it decides
rules.patternTimeout	a time above 0, or unlimited	00:00:00.250 (250 ms)	No	higher, or unlimited	How long one pattern rule may take to match one value; a match that runs longer is a violation.
rules.ambiguousSet	serveNeither or firstWins	serveNeither	Yes	firstWins	What serves a set name that two rule files of the manifest define: neither file, so every check that names the set is refused until one definition is removed (serveNeither), or the file listed first (firstWins). Set it in the settings document or in code.

Change detection

Read when a change is found and while rule sets wait to be compiled again (Change detection).

Setting	Values	Unset	Security	Flagged	What it decides
environment.handlerTimeout	a time above 0, or unlimited	00:01:00 (one minute)	No	higher, or unlimited	How long the handlers of one change may run.
environment.maxRecompilesPerHour	a number from 0, or unlimited	3	No	higher, or unlimited	How many automatic recompiles a rule set may have per hour for one target; 0 never recompiles automatically.
environment.pendingHold	allOperations or changedOperation	allOperations	Yes	changedOperation	While a rule set waits to be compiled again, whether every operation that names it is checked with environment.pendingRecompile (allOperations) or only the operation that found the change (changedOperation).
environment.recompileRetry	laterOperations, nextChange or off	laterOperations	No	No	When a waiting rule set is tried again: on later operations of its target, within environment.maxRecompilesPerHour, and on the next change or start (laterOperations); only on the next change of its target or intent, or the next start (nextChange); or never by the library (off).

Compiled mappings

Read for each call that a compiled mapping answers (Compiled mappings).

Setting	Values	Unset	Security	Flagged	What it decides
mapping.driftWarnings	everyCall or oncePerRevision	everyCall	No	No	Whether a mapping's drift adds a warning to every call it is measured on (everyCall), or once per client, mapping revision and drift (oncePerRevision).
mapping.replyCheck	check, skip or recompileOnce	check	Yes	skip	Whether every value a mapping returns goes through the Reply checkpoint (check), is returned unchecked (skip), or, when enforced rules do not allow one, has the mapping compiled again once, unless OnReuseFailure is Fail (recompileOnce). A new mapping replaces the previous revision only when the checkpoint allows its values.

Schemas and providers

Read for each call with a run-time JSON schema: a schema given to TransformAsync, or an intent's schema shape.

Setting	Values	Unset	Security	Flagged	What it decides
schemas.metaSchemaRefs	allow or refuse	allow	No	No	Whether such a schema may name a built-in JSON Schema meta-schema by $ref: the provider gets an open object in its place (allow), or the call fails before any model call (refuse).
providers.strictSchemaFallback	jsonMode or refuse	jsonMode	No	No	What a call does when its schema holds that open object and its provider is in strict schema mode: it is sent in JSON-object mode, with the schema in the prompt (jsonMode), or it is not sent (refuse).

Settings of your own

A setting of your own is a SettingDescriptor: its Name, its Kind (Count, Duration, Boolean, Text or Other), its LibraryDefault, or, with Security true, its FailClosedValue, and AllowsZero, AllowsUnlimited and AllowedValues. Declare it with AddSetting on the builder or in GuardrailOptions.Settings for the settings document and code, and in the Settings of the options WithGuardrailFiles takes when rule files set it. A name the library declares cannot be declared again. A kind of your own reads the value from GuardrailKindContext.Settings.