audita/docs/config.md

Audita Configuration

This is the canonical reference for discovery, settings, defaults, environment mapping, and validation. CLI syntax, artifact lifecycle, and file formats have separate owners.

Loading Model

For processing and effective-config inspection, the first applicable source selects one YAML file:

1. Explicit CLI config path.
2. AUDITA_CONFIG.
3. /usr/local/etc/audita/config.yml, if present.
4. /etc/audita/config.yml, if present.

These files are alternatives, not layers merged together. Missing system files are skipped. An empty or missing explicitly selected path is an error, as is an inaccessible selected file. Without a selected file, built-in defaults apply. The validation command requires an explicit file and does not use discovery.

Effective Precedence

Operation	Applied sources, lowest to highest precedence
Process	Built-in defaults, selected file, environment overrides, explicit CLI overrides
Print effective configuration	Built-in defaults, selected file, environment overrides
Validate configuration file	Built-in defaults, explicit file

File validation does not apply configuration environment overrides, but it still resolves environment variables named by api_key_env fields. Each configuration layer is validated as it is applied: a later override cannot repair an invalid earlier layer. Config commands provide inspection and validation without processing a transcript or contacting an LLM.

File Schema

The file is YAML with required version: 1. Unknown fields are rejected. The remaining sections and fields below are optional. Omitted values preserve lower-precedence settings, except for the documented inheritance rules. Complete copyable files are in examples.

Pipeline and Output

YAML field	Default	Meaning
pipeline.modules	[glossary, homophones, glossary, spoken_word, grammar]	Ordered module sequence. Supported keys are glossary, homophones, spoken_word, and grammar; repeated keys are allowed. An omitted or empty YAML list leaves the sequence unchanged.
output.schema	bare-segments	Output encoder selection: bare-segments or audita-v1. See output formats.

Module keys select correction stages. Validator chains are built into each module; there is no configuration field for selecting individual validator keys.

LLM Settings

The same fields are supported under llm.proposal and llm.validation.

Field suffix	Proposal default	Meaning
base_url	https://openrouter.ai/api/v1	Endpoint base URL; the LLM contract defines how it is used.
model	openrouter/google/gemma-4-31b-it	Model identifier sent to the endpoint. Availability is determined by that endpoint.
api_key_env	Unset	Name of an environment variable containing the API key; see secrets.
timeout	600 seconds	Positive integer seconds or a duration string resolving to whole seconds, such as 120s.
max_retries	3	Non-negative retry count after the initial attempt; retry conditions belong to the LLM contract.

Validation settings inherit the effective proposal settings individually. Empty validation model, base URL, or API key values inherit the proposal value; omitted validation timeout and retry count inherit, while an explicit retry count of zero is retained in configuration. The current HTTP adapter interprets a retry count of zero as its default of three retries, so zero does not disable retries. No API key is required by local config validation. Model and base-URL usability are checked during client setup/requests, not by an online config check.

Concurrency

YAML field	Default	Meaning
concurrency.total_llm	1	Positive total concurrent LLM-call limit.
concurrency.proposal_llm	1	Positive proposal-call limit, no greater than total.
concurrency.validation_llm	Inherits total	Positive validation-call limit, no greater than total.

In a YAML file, setting total alone does not change proposal concurrency. At the environment or CLI layer, setting total without setting proposal at that same layer also sets proposal to that total, even if a lower layer supplied a proposal value. Unset validation concurrency inherits the final total. The canonical total setting wins over its legacy alias when both appear at the same layer.

Validation prompt budgeting is available through environment or CLI only: AUDITA_VALIDATION_MAX_PROMPT_TOKENS has default 2048 and must be positive. There is no YAML field for it.

Chunking and Normalization

YAML field	Default	Meaning and validation
chunking.target_sections	Unset	Optional positive target count. Processing rejects targets impossible for the normalized transcript and token constraints.
chunking.max_section_tokens	8192	Positive maximum section token estimate.
chunking.min_section_tokens	2048	Positive minimum used in chunk balancing; no greater than maximum.
normalization.max_segment_gap	4.0 seconds	Non-negative gap limit for same-speaker merging.
normalization.ellipsis_gap	3.5 seconds	Non-negative gap threshold for inserting an ellipsis during merging.
normalization.max_segment_duration	60.0 seconds	Positive merged-segment duration limit.
normalization.max_segment_tokens	2048	Positive merged-segment token estimate limit.

The three normalization time fields accept numeric seconds or YAML duration strings. Their environment and CLI overrides use numeric seconds. Section token counts are estimates; config validation does not test whether a particular input can satisfy the selected chunking target.

Thresholds, Context, and Diagnostics

YAML field	Default	Meaning and validation
thresholds.glossary	0.8	Glossary correction confidence threshold, in [0, 1].
thresholds.homophones	0.8	Homophone correction confidence threshold, in [0, 1].
thresholds.spoken_word	0.8	Spoken-word correction confidence threshold, in [0, 1].
thresholds.grammar	0.8	Grammar correction confidence threshold, in [0, 1].
context.description	Empty	Trimmed background context for prompts; limited to 500 bytes of UTF-8 text after trimming. It does not replace transcript content.
diagnostics.work_dir	/tmp/audita	Non-empty parent directory for run artifacts.
diagnostics.retention	auto	Accepted values: auto, always, never. Exact lifecycle behavior, including the current behavior of never, belongs to operations.

Environment Overrides

Values are read when the variable is set. Empty values are not generally equivalent to unset values: numeric overrides must parse, and empty strings may clear a setting or fail validation. Numeric environment values use integers or floating point seconds as indicated above, not duration strings.

Environment variable	Setting
AUDITA_CONFIG	Config file selection
AUDITA_MODULES	Module sequence as comma-separated keys
AUDITA_LLM_API_KEY	Direct proposal API key
OPENROUTER_API_KEY	Proposal API key fallback when AUDITA_LLM_API_KEY is unset
AUDITA_MODEL	Proposal model
AUDITA_BASE_URL	Proposal endpoint
AUDITA_LLM_TIMEOUT_SECONDS	Proposal timeout
AUDITA_MAX_RETRIES	Proposal retries
AUDITA_VALIDATION_LLM_API_KEY	Direct validation API key
AUDITA_VALIDATION_MODEL	Validation model
AUDITA_VALIDATION_BASE_URL	Validation endpoint
AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS	Validation timeout
AUDITA_VALIDATION_MAX_RETRIES	Validation retries
AUDITA_TOTAL_LLM_CONCURRENCY	Total concurrency
AUDITA_LLM_CONCURRENCY	Legacy total-concurrency alias
AUDITA_PROPOSAL_LLM_CONCURRENCY	Proposal concurrency
AUDITA_VALIDATION_LLM_CONCURRENCY	Validation concurrency
AUDITA_VALIDATION_MAX_PROMPT_TOKENS	Validation prompt budget
AUDITA_TARGET_SECTIONS	Section target
AUDITA_MAX_SECTION_TOKENS	Section maximum
AUDITA_MIN_SECTION_TOKENS	Section minimum
AUDITA_NORMALIZE_MAX_SEGMENT_GAP	Merge gap
AUDITA_NORMALIZE_ELLIPSIS_GAP	Ellipsis gap
AUDITA_NORMALIZE_MAX_SEGMENT_DURATION	Merged duration limit
AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS	Merged token estimate limit
AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD	Glossary threshold
AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD	Homophone threshold
AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD	Spoken-word threshold
AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD	Grammar threshold
AUDITA_WORK_DIR	Diagnostics directory
AUDITA_WORK_DIR_RETENTION	Retention selection

There is no environment override for output schema or transcript description. Use file configuration or the corresponding CLI flags.

Secrets

File config accepts environment variable names through api_key_env, not literal API-key fields. Names must be non-empty and match an environment-variable identifier; an unset named variable resolves to an empty value. Runtime environment key overrides take precedence over keys resolved from a file. CLI key flags supply direct values and take precedence over environment settings.

Effective-config inspection redacts API keys. Configured LLM secrets are also redacted by the runtime's error and diagnostic handling, but transcript content is still sensitive: see artifact handling.

Examples

• Minimal configuration: starts from defaults and obtains the proposal key from the environment.
• Production-oriented configuration: illustrates both LLM targets, concurrency, chunking, normalization, thresholds, and diagnostics. Its explicit section target is intended for larger inputs, not the tiny sample.
• Tiny transcript and tiny glossary: inputs for the README quickstart.

Use the CLI configuration commands to validate files and inspect effective settings. Validation checks local structure and constraints; it does not verify credentials, model availability, or endpoint access.