diff --git a/docs/config.md b/docs/config.md index f70d20d..4202935 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,48 +1,81 @@ # 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` +This is the canonical configuration reference for Audita. -Validation rules: -- missing `version` fails; -- unsupported version fails; -- unknown YAML fields fail (strict decoding). +It documents: +- config path resolution; +- effective precedence across defaults, file config, environment, and CLI; +- supported `version: 1` YAML schema; +- environment overrides; +- CLI override relationship; +- validation and secrets behavior. -## Config path resolution -For `audita process` and `audita config print-effective`, path resolution order is: +For CLI command syntax, see [`docs/cli.md`](cli.md). + +## Loading Model + +Path resolution for `audita process` and `audita config print-effective`: 1. `--config ` 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. +Missing explicit path behavior: +- missing `--config` target is an error; +- missing `AUDITA_CONFIG` target is an error. -## Effective precedence -`audita process` effective precedence: +Missing default-path files are non-fatal. + +## Effective Precedence + +`audita process`: 1. defaults 2. file config 3. environment overrides 4. CLI overrides -`audita config print-effective` uses: +`audita config print-effective`: 1. defaults 2. file config 3. environment overrides -`audita config validate` intentionally uses file-only validation: +`audita config validate`: 1. defaults 2. file config -Environment overrides are not applied in `config validate`. +`config validate` is intentionally file-only (no environment overrides). + +## Defaults + +Current defaults: +- modules: `glossary,homophones,glossary,spoken_word,grammar` +- output schema: `bare-segments` +- primary model: `openrouter/google/gemma-4-31b-it` +- primary base URL: `https://openrouter.ai/api/v1` +- primary timeout: `600` seconds +- max retries: `3` +- total/proposal LLM concurrency: `1` +- validation max prompt tokens: `2048` +- max section tokens: `8192` +- min section tokens: `2048` +- confidence thresholds: `0.8` +- normalization max segment gap: `4.0` +- normalization ellipsis gap: `3.5` +- normalization max segment duration: `60.0` +- normalization max segment tokens: `2048` +- transcript description: empty +- work dir: `/tmp/audita` +- work dir retention: `auto` + +## YAML Schema (`version: 1`) + +Supported file version: +- `version: 1` (required) + +Unknown YAML fields are rejected. -## Supported top-level YAML fields ```yaml version: 1 @@ -57,18 +90,18 @@ llm: base_url: https://openrouter.ai/api/v1 model: openrouter/google/gemma-4-31b-it api_key_env: AUDITA_LLM_API_KEY - timeout: 120s + timeout: 600s 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 + timeout: 600 max_retries: 3 concurrency: - total_llm: 2 - proposal_llm: 2 + total_llm: 1 + proposal_llm: 1 validation_llm: 1 chunking: @@ -89,61 +122,115 @@ thresholds: grammar: 0.8 context: - description: "optional transcript background context" + description: optional 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. +Duration-parsing behavior: +- `llm.*.timeout`: integer seconds or duration string; duration strings must resolve to whole seconds. +- `normalization.*` duration-like fields: numeric seconds or duration string. -Supported module keys: -- `glossary` -- `homophones` -- `spoken_word` -- `grammar` +## Environment Overrides -Repeated supported module keys are allowed. +Modules: +- `AUDITA_MODULES` -`output.schema` is validated against the built-in output schema catalog. +Config path: +- `AUDITA_CONFIG` -Supported output schema keys: -- `bare-segments` -- `audita-v1` +Primary LLM: +- `AUDITA_LLM_API_KEY` (falls back to `OPENROUTER_API_KEY` when unset) +- `AUDITA_MODEL` +- `AUDITA_BASE_URL` +- `AUDITA_LLM_TIMEOUT_SECONDS` +- `AUDITA_MAX_RETRIES` -Unknown module keys and unknown output schema keys fail validation. +Validation LLM: +- `AUDITA_VALIDATION_LLM_API_KEY` +- `AUDITA_VALIDATION_MODEL` +- `AUDITA_VALIDATION_BASE_URL` +- `AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS` +- `AUDITA_VALIDATION_MAX_RETRIES` +- `AUDITA_VALIDATION_MAX_PROMPT_TOKENS` -## Duration field parsing -Duration-like fields support: -- numeric seconds (for example `120`, `3.5`) -- duration strings (for example `120s`, `2m`) +Concurrency: +- `AUDITA_TOTAL_LLM_CONCURRENCY` +- `AUDITA_PROPOSAL_LLM_CONCURRENCY` +- `AUDITA_VALIDATION_LLM_CONCURRENCY` +- `AUDITA_LLM_CONCURRENCY` (legacy alias for total) -LLM timeout duration strings must resolve to whole seconds. +Chunking: +- `AUDITA_MAX_SECTION_TOKENS` +- `AUDITA_MIN_SECTION_TOKENS` +- `AUDITA_TARGET_SECTIONS` -## Secret handling -Use `api_key_env` fields for secrets: -- `llm.proposal.api_key_env` -- `llm.validation.api_key_env` +Thresholds: +- `AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD` +- `AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD` +- `AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD` +- `AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD` -These fields store environment variable names, not secret values. +Normalization: +- `AUDITA_NORMALIZE_MAX_SEGMENT_GAP` +- `AUDITA_NORMALIZE_ELLIPSIS_GAP` +- `AUDITA_NORMALIZE_MAX_SEGMENT_DURATION` +- `AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS` -Resolved secret values are redacted from: -- `audita config print-effective` output; -- diagnostics `effective-config.json`; -- report and diagnostics payloads. +Diagnostics: +- `AUDITA_WORK_DIR` +- `AUDITA_WORK_DIR_RETENTION` (`auto`, `always`, `never`) + +Transcript description: +- no `AUDITA_*` environment variable is currently defined. + +## CLI Override Relationship + +CLI flags override file and environment values for `audita process`. + +The CLI supports canonical total concurrency (`--total-llm-concurrency`) and legacy alias (`--llm-concurrency`): +- when both are provided at the same precedence layer, canonical total wins; +- if proposal concurrency is not explicitly set and total is set via environment or CLI, proposal concurrency inherits that total; +- validation concurrency inherits total only when validation concurrency is unset. + +For full flag syntax, see [`docs/cli.md`](cli.md). + +## Validation Rules + +Validation includes: +- supported module keys only; +- supported output schema keys only (`bare-segments`, `audita-v1`); +- positive timeout/concurrency/token constraints; +- `proposal_llm <= total_llm` and `validation_llm <= total_llm` when validation is set; +- confidence thresholds in `[0.0, 1.0]`; +- transcript description length `<= 500` characters; +- non-empty work dir; +- work-dir retention in `auto|always|never`. + +## Secrets + +Recommended secret handling: +- use `llm.proposal.api_key_env` and `llm.validation.api_key_env` in file config; +- use `AUDITA_*_API_KEY` environment overrides or CLI key flags when needed. + +`api_key_env` fields contain environment variable names, not secret values. + +Redaction behavior: +- `audita config print-effective` redacts resolved API keys. +- diagnostics and report paths redact configured secret values. + +## Examples + +- Minimal config: [`examples/minimal-config.yml`](../examples/minimal-config.yml) +- Production-style config: [`examples/production-config.yml`](../examples/production-config.yml) +- Tiny transcript input: [`examples/tiny-transcript.json`](../examples/tiny-transcript.json) +- Tiny glossary input: [`examples/tiny-glossary.yaml`](../examples/tiny-glossary.yaml) + +Validate the config examples: -## Commands -Validate a file config: ```sh -audita config validate --config ./audita.yml +audita config validate --config examples/minimal-config.yml +audita config validate --config examples/production-config.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. diff --git a/docs/configuration.md b/docs/configuration.md deleted file mode 100644 index 8d50bc9..0000000 --- a/docs/configuration.md +++ /dev/null @@ -1,5 +0,0 @@ -# Moved: Configuration Reference - -The canonical configuration reference now lives at [`docs/config.md`](config.md). - -This file is retained temporarily as a migration shim for older links. diff --git a/examples/minimal-config.yml b/examples/minimal-config.yml new file mode 100644 index 0000000..35adc72 --- /dev/null +++ b/examples/minimal-config.yml @@ -0,0 +1,6 @@ +version: 1 +output: + schema: bare-segments +llm: + proposal: + api_key_env: AUDITA_LLM_API_KEY diff --git a/examples/production-config.yml b/examples/production-config.yml new file mode 100644 index 0000000..2f39ab4 --- /dev/null +++ b/examples/production-config.yml @@ -0,0 +1,41 @@ +version: 1 +pipeline: + modules: [glossary, homophones, glossary, spoken_word, grammar] +output: + schema: audita-v1 +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: 120 + 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: "General context for domain vocabulary and speaker names." +diagnostics: + work_dir: /tmp/audita + retention: auto diff --git a/examples/tiny-glossary.yaml b/examples/tiny-glossary.yaml new file mode 100644 index 0000000..c660b40 --- /dev/null +++ b/examples/tiny-glossary.yaml @@ -0,0 +1,6 @@ +glossary: + - name: Audita + aliases: + - audita + category: product + summary: The Audita transcript correction CLI. diff --git a/examples/tiny-transcript.json b/examples/tiny-transcript.json new file mode 100644 index 0000000..6ea9bea --- /dev/null +++ b/examples/tiny-transcript.json @@ -0,0 +1,9 @@ +[ + { + "id": 1, + "speaker": "A", + "start": 0.0, + "end": 1.2, + "text": "hello world" + } +]