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 PromptKit profiles and optional testing overlay. 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.

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.

Profile files are resolved against the selected main file's directory, or may use an absolute profiles_dir. Both selected profiles must exist and select a registered backend. Their effective endpoints must match that backend's endpoint after surrounding whitespace and trailing slashes are removed. Profiles cannot supply a competing api_key_env lookup. The backend credential supplies the runtime key when required; inspection makes no provider call. The CLI inspection views show selected controls and field provenance separately from ConfigKit's redacted settings YAML.

Settings

Field	Default	Rule
profiles_dir	profiles	Nonempty; profile files are resolved relative to the selected main file.
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.