audita/docs/config.md

Audita Configuration

Audita uses version 3 application configuration. See the migration guide and examples for complete projects. Command syntax is owned by the CLI reference.

Loading and composition

An explicit --config selects one main YAML file. Without it, ConfigKit searches the working directory, user configuration directory, and Unix system directories for audita configuration. If no file is found, built-in defaults apply. An explicit invalid selection or failure of a selected file is an error; search does not continue after a selected file fails. An omitted version uses the v3 schema; a supplied version must be 3.

Operator sources may use ConfigKit imports. The selected main file provides the base for an optional overlays/<name>.yml, optional glossary.yml, and recursive glossary/ YAML files. Without a main source, automatic companion files are not loaded from the working directory. ConfigKit composes sources, resolves native inheritance, applies explicit overrides, records derived defaults, and validates the result. Its configuration reference owns native composition and provenance semantics.

PromptKit profiles and operator prompts

PromptKit loads its default catalog and Audita's embedded prompts, followed by optional prompts.yml and recursive prompts/ YAML files beside the application main. Native imports, resource collections, inheritance, and replacement apply. Profiles, backends, models, credentials, admission, and provider parameters belong to PromptKit configuration; see its format reference. The engine captures its sources for an invocation. Edit files and run a new invocation to pick up changes. Inspection does not require model credentials.

Pipeline and glossary selections

glossary_collections maps names to collections with an ordered entries list. Each entry has an id, name, and category; description, aliases, and plural provide optional context. Entries are identified within their collection by id. Root glossaries and protected_terms select collection names. If root protection is omitted, it derives from the root glossary selection.

pipeline.stages is an ordered list of module records; supported modules are glossary, homophones, spoken_word, and grammar. The default sequence is glossary, homophones, glossary, spoken_word, grammar. Repeated modules run separately; [] runs normalization without model processing. An optional nonempty, unique id identifies a record in evidence. Each record may override glossaries, protected_terms, confidence_threshold, and fields under llm, validation, and context. Omitted fields inherit their resolved root values. Explicit empty lists and null list selections clear a selection.

Each entry receives its selected context and independent protection. Glossary correction exempts active recognized spellings from protection for that entry. A longer exempt name still takes precedence over a shorter protected spelling inside it. A glossary correction must have at least one selected entry at processing preflight. Empty definitions and empty protection remain valid configuration.

Settings

Setting	Default	Meaning
llm.proposal_profile	unset	PromptKit profile for proposals; required for processing entries.
llm.validation_profile	effective proposal profile	Profile for model validation; null clears a selection before fallback.
llm.correction_repair_profile	effective proposal profile	Profile for correction repair; null clears an inherited selection before fallback.
llm.correction_repair_attempts	1	Nonnegative repair attempts per correction; zero disables correction repair.
llm.transient_retries	2	Additional transient attempts per generation.
llm.repair_attempts	2	Structural repairs, from zero through three.
llm.operation_timeout	15m	Positive duration per logical operation.
validation.max_prompt_tokens	2048	Positive validation batching budget.
thresholds.<module>	0.8	Root confidence threshold for each module, in [0, 1].
context.description	empty	Prompt context; at most 500 bytes after trimming.
chunking.target_sections	unset	Optional positive target.
chunking.max_section_tokens, chunking.min_section_tokens	8192, 2048	Positive section bounds; minimum must not exceed maximum.
normalization.max_segment_gap, normalization.ellipsis_gap	4, 3.5	Nonnegative seconds.
normalization.max_segment_duration, normalization.max_segment_tokens	60, 2048	Positive seconds and token estimate.
output.schema	bare-segments	Output format; see output contracts.
reporting.enabled, reporting.stdout_dir	true, .	Ordinary report capture and default directory for stdout output.
diagnostics.work_dir	/tmp/audita	Parent directory for optional debug capture.

For example, an entry can disable correction repair or select another profile:

llm:
  proposal_profile: local
  correction_repair_attempts: 2
pipeline:
  stages:
    - module: grammar
      llm:
        correction_repair_profile: review
    - module: spoken_word
      llm:
        correction_repair_attempts: 0

Processing profiles are selected explicitly; no profile or glossary is selected automatically. The validation selection falls back after root and per-entry settings are combined. An explicit root correction repair profile is inherited by each entry unless overridden or cleared with null; otherwise the entry uses its effective proposal profile. The repair profile is checked only when its attempt budget is positive. Each correction repair attempt is a logical call that can also use the configured transient retries and structural repairs. Null does not disable validation. Numeric zero and false retain their field meaning, subject to validation. Inspect recorded origins and default dependencies using the native commands.