audita/docs/configuration.md

Audita Configuration

Scope

This document defines the supported versioned YAML configuration model and runtime precedence behavior.

Supported file version

Current supported config file version:

• version: 1

Validation rules:

• missing version fails;
• unsupported version fails;
• unknown YAML fields fail (strict decoding).

Config path resolution

For audita process and audita config print-effective, path resolution order is:

1. --config <path>
2. AUDITA_CONFIG
3. /usr/local/etc/audita/config.yml (if present)
4. /etc/audita/config.yml (if present)

Missing-path behavior:

• missing --config path is an error;
• missing AUDITA_CONFIG path is an error;
• missing both default paths is non-fatal.

Effective precedence

audita process effective precedence:

1. defaults
2. file config
3. environment overrides
4. CLI overrides

audita config print-effective uses:

1. defaults
2. file config
3. environment overrides

audita config validate intentionally uses file-only validation:

1. defaults
2. file config

Environment overrides are not applied in config validate.

Supported top-level YAML fields

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: 120s
    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: 120s
    max_retries: 3

concurrency:
  total_llm: 2
  proposal_llm: 2
  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 transcript background context"

diagnostics:
  work_dir: /tmp/audita
  retention: auto

Module and output-schema validation

pipeline.modules keys are validated against the built-in supported module catalog.

Supported module keys:

• glossary
• homophones
• spoken_word
• grammar

Repeated supported module keys are allowed.

output.schema is validated against the built-in output schema catalog.

Supported output schema keys:

• bare-segments
• audita-v1

Unknown module keys and unknown output schema keys fail validation.

Duration field parsing

Duration-like fields support:

• numeric seconds (for example 120, 3.5)
• duration strings (for example 120s, 2m)

LLM timeout duration strings must resolve to whole seconds.

Secret handling

Use api_key_env fields for secrets:

• llm.proposal.api_key_env
• llm.validation.api_key_env

These fields store environment variable names, not secret values.

Resolved secret values are redacted from:

• audita config print-effective output;
• diagnostics effective-config.json;
• report and diagnostics payloads.

Commands

Validate a file config:

audita config validate --config ./audita.yml

Print redacted effective config:

audita config print-effective --config ./audita.yml

Compatibility notes

Legacy compatibility flags and environment aliases remain available where implemented, but the stable configuration surface is the versioned YAML model described above.