187 lines
4.1 KiB
Markdown
187 lines
4.1 KiB
Markdown
# 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 `/etc/audita/config.yml` if present
|
|
|
|
Missing-file behavior:
|
|
|
|
- missing `--config` path: hard failure;
|
|
- missing `AUDITA_CONFIG` path: hard failure;
|
|
- missing `/etc/audita/config.yml`: 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
|
|
```
|
|
|
|
`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.
|