audita/docs/configuration.md

Audita Configuration

This document describes Audita's versioned YAML config support and related commands.

Purpose

Audita's config file provides a stable place for pipeline defaults and runtime tuning that would otherwise require many environment variables or CLI flags.

Use config files for baseline settings, then use environment variables and CLI flags for deployment and per-run overrides.

Supported version

Current supported config version:

• version: 1

Rules:

• missing version fails validation;
• unknown versions fail validation;
• unknown fields fail validation (strict decoding).

Config path resolution

For audita process, config path resolution is:

1. --config <path> if provided
2. AUDITA_CONFIG if set and --config is not provided
3. default /usr/local/etc/audita/config.yml if present
4. fallback default /etc/audita/config.yml if present

Missing-file behavior:

• missing --config path: hard failure;
• missing AUDITA_CONFIG path: hard failure;
• missing both default-path files: non-fatal, run continues.

Precedence model

Effective config precedence is:

1. built-in defaults
2. file config
3. environment overrides
4. CLI overrides

Supported 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

context.description provides background-only transcript context for prompts. If both config and CLI provide a description, --transcript-description takes precedence.

output.schema supports the built-in output schema registry values:

• bare-segments (default)
• audita-v1

Unknown schema names fail clearly before transcript output is written.

Duration-like fields accept either:

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

For LLM timeouts, duration strings must resolve to whole seconds.

Secret handling

Use api_key_env for secrets:

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

These fields must contain environment variable names, not secret values.

At runtime, Audita resolves those names from the process environment.

Redaction behavior:

• run diagnostics effective-config.json is redacted;
• audita config print-effective output is redacted;
• API keys are never emitted in plaintext by those outputs.

Config commands

Validate a config file:

audita config validate --config ./audita.yml

Print redacted effective config:

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

print-effective loads defaults, then file config, then environment overrides.

Example: local OpenAI-compatible endpoint

version: 1

llm:
  proposal:
    base_url: http://localhost:8000/v1
    model: local/proposal-model
    api_key_env: AUDITA_LLM_API_KEY
    timeout: 90s
    max_retries: 2

  validation:
    base_url: http://localhost:8000/v1
    model: local/validation-model
    api_key_env: AUDITA_VALIDATION_LLM_API_KEY
    timeout: 90s
    max_retries: 2

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

diagnostics:
  work_dir: /tmp/audita
  retention: auto

Compatibility notes

Existing environment variables and lower-level CLI flags remain available for compatibility.

Current guidance:

• prefer file config for baseline behavior;
• keep environment variables for secrets/deployment-specific overrides;
• use CLI flags for per-run overrides.
• validator chains are built-in and are not user-configurable in config.
• prompt source selection and filesystem prompt overrides are not config options.