# 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
```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: 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:
```sh
audita config validate --config ./audita.yml
```

Print redacted effective config:
```sh
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.