audita/docs/config.md

# Audita Configuration

This is the canonical reference for discovery, settings, defaults, environment
mapping, and validation. [CLI syntax](cli.md), [artifact lifecycle](operations.md),
and [file formats](integrations/output-files.md) 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](cli.md#configuration-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](#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](integrations/output-files.md#corrected-transcript). |

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](integrations/openai-compatible-llm.md#endpoint-and-authentication) 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](#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](integrations/openai-compatible-llm.md#retries-and-timeouts). |

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](operations.md#retention-behavior). |

## 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](cli.md#process-flag-reference).

## 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](operations.md#artifact-handling).

## Examples

- [Minimal configuration](../examples/minimal-config.yml): starts from defaults
  and obtains the proposal key from the environment.
- [Production-oriented configuration](../examples/production-config.yml): 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](../examples/tiny-transcript.json) and
  [tiny glossary](../examples/tiny-glossary.yaml): inputs for the README quickstart.

Use the [CLI configuration commands](cli.md#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.