title: Configuration fields description: Every chat.Config and chat.Settings field: what it is, what it defaults to when you leave it alone, and what happens when the value cannot be applied. tags: [reference, configuration, defaults, config]

Configuration fields¶

Every field of chat.Config and chat.Settings, what it defaults to when left alone, and what happens when the value cannot be applied. chat.Config is the whole of the module's configuration surface: the module reads no config file and has no flags of its own, because a host application owns config schema and maps it into these fields.

Only Provider is meaningful on its own, and even that defaults. Every other field has a working zero value.

How to read the "if it cannot be applied" column¶

chat.New classifies a problem into one of three outcomes, and the tables below name which one each field produces:

A dropped setting is never clamped or approximated. Temperature: 3.0 samples at the provider's default, not at 2.0. The split between dropped and fatal is ownership, not severity: a parameter the module forwards to a vendor degrades, and a feature the module implements itself is fatal. See Handle a partially-applied configuration for the code that tells the three apart.

Provider and model fields¶

ProviderOpenAICompatible is the one provider with two required fields: BaseURL (no default endpoint exists) and Model (model names are backend-specific, so the module has no default to offer).

Credential fields¶

The five sources are tried in order and the first non-empty one wins: Token → Credentials.Env → Credentials.Keychain → Credentials.Key → the provider's well-known variable. Every value is whitespace-trimmed, so a half-configured source cannot mask a working one below it. ProviderClaudeLocal uses none of this, because the claude binary carries its own authentication.

Structured-output fields¶

Build a schema with chat.GenerateSchema[T](), which returns *jsonschema.Schema directly (assignable to both Config.ResponseSchema and Tool.Parameters with no type assertion. It returned any before v0.8.0; code carrying a .(*jsonschema.Schema) assertion no longer compiles.

Generation-control fields¶

The 0–2 bound on Temperature is the module's outer limit, wider than any one provider, because provider ranges differ (Claude 0–1, OpenAI and Gemini 0–2) and the adapters narrow it further. A value inside 0–2 but outside the selected provider's range is refused by the adapter, not here.

Tool-loop fields¶

Parallel execution engages only when a single step returns more than one call. A lone call always takes the sequential path.

Transport and timeout fields¶

Nothing bounds a retry sequence as a whole. RequestTimeout bounds one request, so a high MaxRetries against a provider returning long Retry-After hints can run for a while, so cancel the context to bound it.

Caching fields¶

Setting CacheTTL does not cache anything on its own. Content is cached only when it is added through CachingChatClient.AddCached, and every provider silently declines to cache blocks below a per-model minimum. Confirm with Usage().CachedTokens.

Conversation-mode fields¶

Stateless and HistoryPolicy answer different problems and are not alternatives. Stateless is for calls that were never a conversation (batch classification, extraction, judging) and sends no history at all. HistoryPolicy is for a conversation that genuinely accumulates and needs bounding. chat.TruncateOldest drops the oldest turns, chat.CompactOldest summarises them instead. See Bound a long conversation.

Observability fields¶

ChatClient.History() is the other half of this, and needs no configuration: it reports the turns a client will re-send and the provider's own input-token count for the last call it made. See Bound a long conversation.

Test-only fields¶

AllowInsecureBaseURL is excluded from every decoder (json:"-", mapstructure:"-" and yaml:"-"), so a host decoding chat.Config wholesale from its own config file cannot relax the HTTPS requirement from input it does not control. Every other field tagged json:"-" carries the same three exclusions, and a test enforces that pairing so the next one cannot drift.

client, err := chat.NewClaudeLocal(ctx, settings,
    chat.WithClaudeBinaryLookup(fakeLookPath),
    chat.WithClaudeCommand(fakeCommand),
)

chat.Settings: the construction dependencies¶

Settings is what chat.New takes. It carries the Config above plus the one dependency that is not configuration:

Host-config shapes and their mapstructure keys¶

The module owns typed shapes so a host can decode its own config into them without the module depending on a config library. The mapstructure tags are the key names a decoder will look for:

These are shapes, not a config system. Nothing in this module reads a file, watches for changes, or applies precedence between sources. A host does that and passes the result in. go-tool-base ships such an adapter, and it lives there rather than here.

The order chat.New checks things in¶

The order matters because it determines which problems you learn about together. Config-only checks all run before anything is built, so a caller with three mistakes learns all three from one call:

1. Default the provider from AI_PROVIDER, then to ProviderClaude.
2. Validate BaseURL, and require it for ProviderOpenAICompatible, which is fatal.
3. Validate Effort, Temperature and TopP values, which is dropped.
4. Check the selected model's known capabilities, which is dropped.
5. Stop here if anything so far was fatal, returning no client.
6. Remove every dropped setting from the config, so the provider never sees a value the module has already reported as unapplied, and log each one at WARN.
7. Look up the provider factory, which is fatal if it is unregistered.
8. Call the factory, which is fatal if it errors.
9. Assert the built client implements the marker interface for every capability the config asked for, which is fatal if it cannot.
10. Log the endpoint host at INFO and return the client, plus an error listing anything that was not applied.

Related¶

• Defaults and limits: the constant values, and the caps that are not configurable.
• Errors: every sentinel these failures carry.
• Environment variables: the four variables the module and its providers read.
• Handle a partially-applied configuration: reading the error chat.New returns.