audita/docs/config.md

Audita Configuration

This reference describes the version-2 configuration loader in internal/core/config. Use the maintained local and service examples with their separately selected local profiles and service profiles, plus the optional testing overlay. The ConfigKit inheritance example shows a local child backend reusing and overriding sibling settings. Choose real models for your endpoint; a testing profile makes no cost or quality guarantee. See the migration guide for retired inputs.

Loading and precedence

The application selects one main YAML file: an explicit --config, then /usr/local/etc/audita/config.yml if present, then /etc/audita/config.yml if present. Missing system candidates are skipped; an explicit missing or empty path, inaccessible selected file, or absence of any selected file is an error. config validate requires an explicit file. ConfigKit loads built-in defaults, the selected file, an optional named overlay from overlays/<name>.yml beside the main file, and only explicitly supplied setting overrides, in that order. Imports and secret-directory bootstrap are disabled. Unknown fields and missing, null, or non-integer version: 2 are errors. Version-1 files require migration; no compatibility loader or implicit environment configuration remains.

After overlay and explicit CLI override precedence is applied, ConfigKit resolves native sibling inheritance before typed decoding. Any input mapping may use extends: <sibling-name>; the child keeps its key, inherits parent settings, and overrides them with its own settings. Selected overlay and CLI values therefore participate in inheritance at their normal precedence. The generic syntax and resolution rules are defined by ConfigKit v0.5.0's sibling inheritance contract.

extends is reserved structural input in base files, imports, overlays, and other application input mappings, including mapping values supplied by explicit CLI setting overrides. ConfigKit consumes it before typed decoding. A previously valid backend whose ID is literally extends cannot be represented under this rule. Rename that backend to a non-conflicting ID and update every PromptKit profile that selects it. This compatibility impact means the upgrade does not promise that every previously valid configuration remains valid.

Inherited values count as explicit input, including zero, false, empty, and null. Existing field rules still apply: for example, inherited backend concurrency must be positive, while an inherited queue capacity of zero is valid. Parent backends undergo the same decoding and application validation as other backends, whether or not a selected profile uses them. A child credential: null removes the child's inherited credential; it does not remove the parent's credential reference, which remains subject to ordinary secret resolution.

Validation runs after overlays, explicit overrides, and derived settings have resolved. An override can therefore repair an invalid lower-precedence setting when that setting can be decoded. ConfigKit retains field origins and derivations for effective-configuration inspection. Its effective YAML redacts resolved credentials.

PromptKit profiles and operator prompts

profiles_dir selects a PromptKit configuration root, resolved against the selected main file's directory unless it is absolute. The root may contain keyed profiles, backends, and prompts definitions; it is not limited to profile-only files. IDs come from literal YAML mapping keys, never filenames. Multiple definitions may share a document, and a document may contribute to any of the supported mappings. Directory discovery is recursive, but discovery order does not establish field precedence. Contributions within each source group must compose without conflicting values.

PromptKit assembles sources in this order: its selected catalogs and owned defaults, Audita's embedded prompt/schema inputs, operator documents under profiles_dir, then the application backend mapping. The application mapping owns each configured endpoint, concurrency limit, queue capacity, and credential environment lookup. Other supported provider fields can be contributed by the operator documents. Imports remain disabled. The current maintained examples select separate roots: local and service, so definitions for one backend do not enter the other example's final configuration.

Both selected roles must resolve to an existing profile, registered backend, nonblank effective model, and nonblank endpoint. The normalized effective endpoint must match the application backend endpoint. A selected profile cannot introduce a competing api_key_env lookup; the application backend credential supplies the runtime key when required. Other unselected profiles may be partial, but every final backend, profile, and prompt definition is validated when the engine is constructed. A malformed or conflicting unused definition can therefore make the selected root invalid. A missing selected root is an operator configuration error; an empty root may contribute no definitions.

Profile IDs and parent IDs are exact, literal keys. PromptKit profiles can use native extends inheritance; child fields override inherited fields, while unmentioned controls survive changes to model or backend. For example:

profiles:
  "shared~base":
    backend: service
    model: example-model
    temperature: 0.4
    top_p: 0.8
  "proposal fast":
    extends: "shared~base"
    model: faster-model
    temperature: 0

Presence matters. Explicit temperature: 0 is sent as zero; omission leaves it unspecified; null suppresses an inherited temperature. Other fields have their own native null and omission rules. Provider extra_params maps merge recursively, and a null provider value is sent as JSON null. See the pinned PromptKit format reference for the complete field semantics.

Operator documents can also override an embedded prompt/version, including its messages and definition-level output settings. Shared variables supplied by the adapter are rendered only when an effective message references them; Audita does not append omitted shared text. Audita's per-call schemas, structural repair budget, and downstream domain validators remain in force. The engine captures effective definitions and message-file contents when constructed, so edits are observed only by a newly constructed runtime.

Migrating PromptKit profile documents

For the PromptKit v0.11 format, wrap each profile's fields under profiles: {<literal-id>: ...}, remove inner id, and replace base_profile with extends. Profile and prompt IDs are mapping keys, so they need not match source filenames. Review zeros, omitted values, and nulls against the native presence rules before deploying. Select a root whose final definitions have valid backend references; eager validation applies even to unselected definitions. See the complete maintained local and service examples and the pinned consumer migration guide. This incompatible profile-format migration is intended for an Audita major release; no automatic file conversion is provided.

The CLI inspection views show selected controls and field provenance separately from ConfigKit's redacted settings YAML. Inspection resolves both roles without provider calls.

Settings

Field	Default	Rule
profiles_dir	profiles	Nonempty PromptKit document root; resolved relative to the selected main file, or absolute.
backends.<id>.endpoint	None	Required nonempty endpoint for each backend. At least one backend is required.
backends.<id>.concurrency	1	Positive finite capacity; shared by both roles using that backend.
backends.<id>.queue_capacity	1024	Nonnegative; zero disables waiting admission.
backends.<id>.credential	Unset	Optional environment-variable secret reference; omission or null means unauthenticated use.
llm.proposal_profile	None	Required nonempty profile ID.
llm.validation_profile	Final proposal profile	Omission inherits the final proposal selection; explicit empty or null fails.
llm.transient_retries	2	Nonnegative additional attempts per generation.
llm.repair_attempts	2	Additional structural repair generations, from zero through three.
llm.operation_timeout	15m	Positive Go duration string per logical call.
pipeline.modules	[glossary, homophones, glossary, spoken_word, grammar]	Ordered module keys; repeats are meaningful and an explicit empty list runs no correction modules.
output.schema	bare-segments	bare-segments or audita-v1. See output formats.
validation.max_prompt_tokens	2048	Positive validation batching budget.
chunking.target_sections	Unset	Optional positive target; omission or null selects automatic chunking.
chunking.max_section_tokens	8192	Positive maximum estimate.
chunking.min_section_tokens	2048	Positive and no greater than maximum.
normalization.max_segment_gap	4.0	Nonnegative numeric seconds.
normalization.ellipsis_gap	3.5	Nonnegative numeric seconds.
normalization.max_segment_duration	60.0	Positive numeric seconds.
normalization.max_segment_tokens	2048	Positive token estimate.
thresholds.glossary, .homophones, .spoken_word, .grammar	0.8 each	Confidence thresholds in [0, 1].
context.description	Empty	Trimmed prompt context, at most 500 bytes.
reporting.enabled	true	Write the ordinary three-file report bundle when processing.
reporting.stdout_dir	.	Report directory for stdout transcript output; a --report-dir flag can select reports for either transcript destination.
diagnostics.debug	false	Persist detailed debug artifacts when processing.
diagnostics.work_dir	/tmp/audita	Parent of the retained debug run directory; required only when debug is enabled.

Module keys select correction modules; validator chains remain built into them. The loader preserves module order and repetitions. Normalization time settings accept numeric seconds only. The operation timeout uses a duration string. reporting.stdout_dir must be nonblank when it supplies the active report destination: for stdout output, or for file output when --report-dir is explicitly supplied. File output without that flag uses the transcript's parent, so the configured value is inactive. Reporting-disabled runs do not select a report directory. diagnostics.work_dir must be nonblank only with debug enabled. These path requirements are checked when choosing process destinations, not during configuration inspection.

Credentials

A backend credential is a ConfigKit secret reference containing an environment variable name, such as credential: AUDITA_SERVICE_KEY. Every reference that survives overlay and override resolution must name a set, nonempty variable, including credentials on backends unused by the selected roles. A replacement reference resolves only the replacement; null removes the reference. General AUDITA_* and OPENROUTER_API_KEY variables have no implicit setting effect. Secret values are available to the runtime through the resolved reference, while ConfigKit's effective output and provenance contain no resolved secret values.

Current invocation syntax belongs in CLI.