audita/docs/config.md

# Audita Configuration

## Scope

This is the canonical configuration reference for Audita.

It documents:
- config path resolution;
- effective precedence across defaults, file config, environment, and CLI;
- supported `version: 1` YAML schema;
- environment overrides;
- CLI override relationship;
- validation and secrets behavior.

For CLI command syntax, see [`docs/cli.md`](cli.md).
For OpenAI-compatible endpoint behavior, see [`docs/integrations/openai-compatible-llm.md`](integrations/openai-compatible-llm.md).
For transcript/glossary input file contracts, see [`docs/integrations/transcript-glossary-files.md`](integrations/transcript-glossary-files.md).

## Loading Model

Path resolution for `audita process` and `audita config print-effective`:
1. `--config <path>`
2. `AUDITA_CONFIG`
3. `/usr/local/etc/audita/config.yml` (if present)
4. `/etc/audita/config.yml` (if present)

Missing explicit path behavior:
- missing `--config` target is an error;
- missing `AUDITA_CONFIG` target is an error.

Missing default-path files are non-fatal.

## Effective Precedence

`audita process`:
1. defaults
2. file config
3. environment overrides
4. CLI overrides

`audita config print-effective`:
1. defaults
2. file config
3. environment overrides

`audita config validate`:
1. defaults
2. file config

`config validate` is intentionally file-only (no environment overrides).

## Defaults

Current defaults:
- modules: `glossary,homophones,glossary,spoken_word,grammar`
- output schema: `bare-segments`
- primary model: `openrouter/google/gemma-4-31b-it`
- primary base URL: `https://openrouter.ai/api/v1`
- primary timeout: `600` seconds
- max retries: `3`
- total/proposal LLM concurrency: `1`
- validation max prompt tokens: `2048`
- max section tokens: `8192`
- min section tokens: `2048`
- confidence thresholds: `0.8`
- normalization max segment gap: `4.0`
- normalization ellipsis gap: `3.5`
- normalization max segment duration: `60.0`
- normalization max segment tokens: `2048`
- transcript description: empty
- work dir: `/tmp/audita`
- work dir retention: `auto`

## YAML Schema (`version: 1`)

Supported file version:
- `version: 1` (required)

Unknown YAML fields are rejected.

```yaml
version: 1

pipeline:
  modules: [glossary, homophones, glossary, spoken_word, grammar]

output:
  schema: bare-segments

llm:
  proposal:
    base_url: https://openrouter.ai/api/v1
    model: openrouter/google/gemma-4-31b-it
    api_key_env: AUDITA_LLM_API_KEY
    timeout: 600s
    max_retries: 3
  validation:
    base_url: https://openrouter.ai/api/v1
    model: openrouter/google/gemma-4-31b-it
    api_key_env: AUDITA_VALIDATION_LLM_API_KEY
    timeout: 600
    max_retries: 3

concurrency:
  total_llm: 1
  proposal_llm: 1
  validation_llm: 1

chunking:
  target_sections: 8
  max_section_tokens: 8192
  min_section_tokens: 2048

normalization:
  max_segment_gap: 4s
  ellipsis_gap: 3.5s
  max_segment_duration: 60s
  max_segment_tokens: 2048

thresholds:
  glossary: 0.8
  homophones: 0.8
  spoken_word: 0.8
  grammar: 0.8

context:
  description: optional background context

diagnostics:
  work_dir: /tmp/audita
  retention: auto
```

Duration-parsing behavior:
- `llm.*.timeout`: integer seconds or duration string; duration strings must resolve to whole seconds.
- `normalization.*` duration-like fields: numeric seconds or duration string.

## Environment Overrides

Modules:
- `AUDITA_MODULES`

Config path:
- `AUDITA_CONFIG`

Primary LLM:
- `AUDITA_LLM_API_KEY` (falls back to `OPENROUTER_API_KEY` when unset)
- `AUDITA_MODEL`
- `AUDITA_BASE_URL`
- `AUDITA_LLM_TIMEOUT_SECONDS`
- `AUDITA_MAX_RETRIES`

Validation LLM:
- `AUDITA_VALIDATION_LLM_API_KEY`
- `AUDITA_VALIDATION_MODEL`
- `AUDITA_VALIDATION_BASE_URL`
- `AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS`
- `AUDITA_VALIDATION_MAX_RETRIES`
- `AUDITA_VALIDATION_MAX_PROMPT_TOKENS`

Concurrency:
- `AUDITA_TOTAL_LLM_CONCURRENCY`
- `AUDITA_PROPOSAL_LLM_CONCURRENCY`
- `AUDITA_VALIDATION_LLM_CONCURRENCY`
- `AUDITA_LLM_CONCURRENCY` (legacy alias for total)

Chunking:
- `AUDITA_MAX_SECTION_TOKENS`
- `AUDITA_MIN_SECTION_TOKENS`
- `AUDITA_TARGET_SECTIONS`

Thresholds:
- `AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD`
- `AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD`
- `AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD`
- `AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD`

Normalization:
- `AUDITA_NORMALIZE_MAX_SEGMENT_GAP`
- `AUDITA_NORMALIZE_ELLIPSIS_GAP`
- `AUDITA_NORMALIZE_MAX_SEGMENT_DURATION`
- `AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS`

Diagnostics:
- `AUDITA_WORK_DIR`
- `AUDITA_WORK_DIR_RETENTION` (`auto`, `always`, `never`)

Transcript description:
- no `AUDITA_*` environment variable is currently defined.

## CLI Override Relationship

CLI flags override file and environment values for `audita process`.

The CLI supports canonical total concurrency (`--total-llm-concurrency`) and legacy alias (`--llm-concurrency`):
- when both are provided at the same precedence layer, canonical total wins;
- if proposal concurrency is not explicitly set and total is set via environment or CLI, proposal concurrency inherits that total;
- validation concurrency inherits total only when validation concurrency is unset.

For full flag syntax, see [`docs/cli.md`](cli.md).

## Validation Rules

Validation includes:
- supported module keys only;
- supported output schema keys only (`bare-segments`, `audita-v1`);
- positive timeout/concurrency/token constraints;
- `proposal_llm <= total_llm` and `validation_llm <= total_llm` when validation is set;
- confidence thresholds in `[0.0, 1.0]`;
- transcript description length `<= 500` characters;
- non-empty work dir;
- work-dir retention in `auto|always|never`.

## Secrets

Recommended secret handling:
- use `llm.proposal.api_key_env` and `llm.validation.api_key_env` in file config;
- use `AUDITA_*_API_KEY` environment overrides or CLI key flags when needed.

`api_key_env` fields contain environment variable names, not secret values.

Redaction behavior:
- `audita config print-effective` redacts resolved API keys.
- diagnostics and report paths redact configured secret values.

## Examples

- Minimal config: [`examples/minimal-config.yml`](../examples/minimal-config.yml)
- Production-style config: [`examples/production-config.yml`](../examples/production-config.yml)
- Tiny transcript input: [`examples/tiny-transcript.json`](../examples/tiny-transcript.json)
- Tiny glossary input: [`examples/tiny-glossary.yaml`](../examples/tiny-glossary.yaml)

Validate the config examples:

```sh
audita config validate --config examples/minimal-config.yml
audita config validate --config examples/production-config.yml
```