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

```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
```

`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:

```sh
audita config validate --config ./audita.yml
```

Print redacted effective config:

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

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

## Example: local OpenAI-compatible endpoint

```yaml
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.