eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Refresh documentation and policies and simplify releases

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-23 15:03:20 +00:00
parent 588ca36dfc
commit e8b8fbd509
36 changed files with 2143 additions and 2261 deletions
Download Patch File Download Diff File Expand all files Collapse all files

342
docs/config.md
View File

@@ -1,238 +1,188 @@
# Audita Configuration
## Scope
This is the canonical configuration reference for Audita.
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.
For CLI command syntax, see [`docs/cli.md`](cli.md).
For OpenAI-compatible endpoint behavior, see [`docs/integrations/openai-compatible-llm.md`](integrations/openai-compatible-llm.md).
For transcript/glossary input file contracts, see [`docs/integrations/transcript-glossary-files.md`](integrations/transcript-glossary-files.md).
This is the canonical reference for discovery, settings, defaults, environment
mapping, and validation. [CLI syntax](cli.md), [artifact lifecycle](operations.md),
and [file formats](integrations/output-files.md) have separate owners.
## Loading Model
Path resolution for `audita process` and `audita config print-effective`:
1. `--config <path>`
2. `AUDITA_CONFIG`
3. `/usr/local/etc/audita/config.yml` (if present)
4. `/etc/audita/config.yml` (if present)
For processing and effective-config inspection, the first applicable source
selects one YAML file:
Missing explicit path behavior:
- missing `--config` target is an error;
- missing `AUDITA_CONFIG` target is an error.
1. Explicit CLI config path.
2. `AUDITA_CONFIG`.
3. `/usr/local/etc/audita/config.yml`, if present.
4. `/etc/audita/config.yml`, if present.
Missing default-path files are non-fatal.
These files are alternatives, not layers merged together. Missing system files
are skipped. An empty or missing explicitly selected path is an error, as is an
inaccessible selected file. Without a selected file, built-in defaults apply.
The validation command requires an explicit file and does not use discovery.
## Effective Precedence
`audita process`:
1. defaults
2. file config
3. environment overrides
4. CLI overrides
| Operation | Applied sources, lowest to highest precedence |
| --- | --- |
| Process | Built-in defaults, selected file, environment overrides, explicit CLI overrides |
| Print effective configuration | Built-in defaults, selected file, environment overrides |
| Validate configuration file | Built-in defaults, explicit file |
`audita config print-effective`:
1. defaults
2. file config
3. environment overrides
File validation does not apply configuration environment overrides, but it still
resolves environment variables named by `api_key_env` fields. Each configuration
layer is validated as it is applied: a later override cannot repair an invalid
earlier layer. [Config commands](cli.md#configuration-commands) provide inspection
and validation without processing a transcript or contacting an LLM.
`audita config validate`:
1. defaults
2. file config
## File Schema
`config validate` is intentionally file-only (no environment overrides).
The file is YAML with required `version: 1`. Unknown fields are rejected.
The remaining sections and fields below are optional. Omitted values preserve
lower-precedence settings, except for the documented inheritance rules.
Complete copyable files are in [examples](#examples).
## Defaults
### Pipeline and Output
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 field | Default | Meaning |
| --- | --- | --- |
| `pipeline.modules` | `[glossary, homophones, glossary, spoken_word, grammar]` | Ordered module sequence. Supported keys are `glossary`, `homophones`, `spoken_word`, and `grammar`; repeated keys are allowed. An omitted or empty YAML list leaves the sequence unchanged. |
| `output.schema` | `bare-segments` | Output encoder selection: `bare-segments` or `audita-v1`. See [output formats](integrations/output-files.md#corrected-transcript). |
## YAML Schema (`version: 1`)
Module keys select correction stages. Validator chains are built into each module;
there is no configuration field for selecting individual validator keys.
Supported file version:
- `version: 1` (required)
### LLM Settings
Unknown YAML fields are rejected.
The same fields are supported under `llm.proposal` and `llm.validation`.
```yaml
version: 1
| Field suffix | Proposal default | Meaning |
| --- | --- | --- |
| `base_url` | `https://openrouter.ai/api/v1` | Endpoint base URL; the [LLM contract](integrations/openai-compatible-llm.md#endpoint-and-authentication) defines how it is used. |
| `model` | `openrouter/google/gemma-4-31b-it` | Model identifier sent to the endpoint. Availability is determined by that endpoint. |
| `api_key_env` | Unset | Name of an environment variable containing the API key; see [secrets](#secrets). |
| `timeout` | `600` seconds | Positive integer seconds or a duration string resolving to whole seconds, such as `120s`. |
| `max_retries` | `3` | Non-negative retry count after the initial attempt; retry conditions belong to the [LLM contract](integrations/openai-compatible-llm.md#retries-and-timeouts). |
pipeline:
modules: [glossary, homophones, glossary, spoken_word, grammar]
Validation settings inherit the effective proposal settings individually. Empty
validation model, base URL, or API key values inherit the proposal value; omitted
validation timeout and retry count inherit, while an explicit retry count of zero
is retained in configuration. The current HTTP adapter interprets a retry count
of zero as its default of three retries, so zero does not disable retries.
No API key is required by local config validation. Model and base-URL
usability are checked during client setup/requests, not by an online config check.
output:
schema: bare-segments
### Concurrency
llm:
proposal:
base_url: https://openrouter.ai/api/v1
model: openrouter/google/gemma-4-31b-it
api_key_env: AUDITA_LLM_API_KEY
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: 600
max_retries: 3
| YAML field | Default | Meaning |
| --- | --- | --- |
| `concurrency.total_llm` | `1` | Positive total concurrent LLM-call limit. |
| `concurrency.proposal_llm` | `1` | Positive proposal-call limit, no greater than total. |
| `concurrency.validation_llm` | Inherits total | Positive validation-call limit, no greater than total. |
concurrency:
total_llm: 1
proposal_llm: 1
validation_llm: 1
In a YAML file, setting total alone does not change proposal concurrency. At the
environment or CLI layer, setting total without setting proposal at that same
layer also sets proposal to that total, even if a lower layer supplied a proposal
value. Unset validation concurrency inherits the final total. The canonical total
setting wins over its legacy alias when both appear at the same layer.
chunking:
target_sections: 8
max_section_tokens: 8192
min_section_tokens: 2048
Validation prompt budgeting is available through environment or CLI only:
`AUDITA_VALIDATION_MAX_PROMPT_TOKENS` has default `2048` and must be positive.
There is no YAML field for it.
normalization:
max_segment_gap: 4s
ellipsis_gap: 3.5s
max_segment_duration: 60s
max_segment_tokens: 2048
### Chunking and Normalization
thresholds:
glossary: 0.8
homophones: 0.8
spoken_word: 0.8
grammar: 0.8
| YAML field | Default | Meaning and validation |
| --- | --- | --- |
| `chunking.target_sections` | Unset | Optional positive target count. Processing rejects targets impossible for the normalized transcript and token constraints. |
| `chunking.max_section_tokens` | `8192` | Positive maximum section token estimate. |
| `chunking.min_section_tokens` | `2048` | Positive minimum used in chunk balancing; no greater than maximum. |
| `normalization.max_segment_gap` | `4.0` seconds | Non-negative gap limit for same-speaker merging. |
| `normalization.ellipsis_gap` | `3.5` seconds | Non-negative gap threshold for inserting an ellipsis during merging. |
| `normalization.max_segment_duration` | `60.0` seconds | Positive merged-segment duration limit. |
| `normalization.max_segment_tokens` | `2048` | Positive merged-segment token estimate limit. |
context:
description: optional background context
The three normalization time fields accept numeric seconds or YAML duration
strings. Their environment and CLI overrides use numeric seconds. Section token
counts are estimates; config validation does not test whether a particular input
can satisfy the selected chunking target.
diagnostics:
work_dir: /tmp/audita
retention: auto
```
### Thresholds, Context, and Diagnostics
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.
| YAML field | Default | Meaning and validation |
| --- | --- | --- |
| `thresholds.glossary` | `0.8` | Glossary correction confidence threshold, in `[0, 1]`. |
| `thresholds.homophones` | `0.8` | Homophone correction confidence threshold, in `[0, 1]`. |
| `thresholds.spoken_word` | `0.8` | Spoken-word correction confidence threshold, in `[0, 1]`. |
| `thresholds.grammar` | `0.8` | Grammar correction confidence threshold, in `[0, 1]`. |
| `context.description` | Empty | Trimmed background context for prompts; limited to 500 bytes of UTF-8 text after trimming. It does not replace transcript content. |
| `diagnostics.work_dir` | `/tmp/audita` | Non-empty parent directory for run artifacts. |
| `diagnostics.retention` | `auto` | Accepted values: `auto`, `always`, `never`. Exact lifecycle behavior, including the current behavior of `never`, belongs to [operations](operations.md#retention-behavior). |
## Environment Overrides
Modules:
- `AUDITA_MODULES`
Values are read when the variable is set. Empty values are not generally equivalent
to unset values: numeric overrides must parse, and empty strings may clear a
setting or fail validation. Numeric environment values use integers or floating
point seconds as indicated above, not duration strings.
Config path:
- `AUDITA_CONFIG`
| Environment variable | Setting |
| --- | --- |
| `AUDITA_CONFIG` | Config file selection |
| `AUDITA_MODULES` | Module sequence as comma-separated keys |
| `AUDITA_LLM_API_KEY` | Direct proposal API key |
| `OPENROUTER_API_KEY` | Proposal API key fallback when `AUDITA_LLM_API_KEY` is unset |
| `AUDITA_MODEL` | Proposal model |
| `AUDITA_BASE_URL` | Proposal endpoint |
| `AUDITA_LLM_TIMEOUT_SECONDS` | Proposal timeout |
| `AUDITA_MAX_RETRIES` | Proposal retries |
| `AUDITA_VALIDATION_LLM_API_KEY` | Direct validation API key |
| `AUDITA_VALIDATION_MODEL` | Validation model |
| `AUDITA_VALIDATION_BASE_URL` | Validation endpoint |
| `AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS` | Validation timeout |
| `AUDITA_VALIDATION_MAX_RETRIES` | Validation retries |
| `AUDITA_TOTAL_LLM_CONCURRENCY` | Total concurrency |
| `AUDITA_LLM_CONCURRENCY` | Legacy total-concurrency alias |
| `AUDITA_PROPOSAL_LLM_CONCURRENCY` | Proposal concurrency |
| `AUDITA_VALIDATION_LLM_CONCURRENCY` | Validation concurrency |
| `AUDITA_VALIDATION_MAX_PROMPT_TOKENS` | Validation prompt budget |
| `AUDITA_TARGET_SECTIONS` | Section target |
| `AUDITA_MAX_SECTION_TOKENS` | Section maximum |
| `AUDITA_MIN_SECTION_TOKENS` | Section minimum |
| `AUDITA_NORMALIZE_MAX_SEGMENT_GAP` | Merge gap |
| `AUDITA_NORMALIZE_ELLIPSIS_GAP` | Ellipsis gap |
| `AUDITA_NORMALIZE_MAX_SEGMENT_DURATION` | Merged duration limit |
| `AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS` | Merged token estimate limit |
| `AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD` | Glossary threshold |
| `AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD` | Homophone threshold |
| `AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD` | Spoken-word threshold |
| `AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD` | Grammar threshold |
| `AUDITA_WORK_DIR` | Diagnostics directory |
| `AUDITA_WORK_DIR_RETENTION` | Retention selection |
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`
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`
Concurrency:
- `AUDITA_TOTAL_LLM_CONCURRENCY`
- `AUDITA_PROPOSAL_LLM_CONCURRENCY`
- `AUDITA_VALIDATION_LLM_CONCURRENCY`
- `AUDITA_LLM_CONCURRENCY` (legacy alias for total)
Chunking:
- `AUDITA_MAX_SECTION_TOKENS`
- `AUDITA_MIN_SECTION_TOKENS`
- `AUDITA_TARGET_SECTIONS`
Thresholds:
- `AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD`
- `AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD`
- `AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD`
- `AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD`
Normalization:
- `AUDITA_NORMALIZE_MAX_SEGMENT_GAP`
- `AUDITA_NORMALIZE_ELLIPSIS_GAP`
- `AUDITA_NORMALIZE_MAX_SEGMENT_DURATION`
- `AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS`
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`.
There is no environment override for output schema or transcript description.
Use file configuration or the corresponding [CLI flags](cli.md#process-flag-reference).
## 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.
File config accepts environment variable names through `api_key_env`, not literal
API-key fields. Names must be non-empty and match an environment-variable
identifier; an unset named variable resolves to an empty value. Runtime environment
key overrides take precedence over keys resolved from a file. CLI key flags supply
direct values and take precedence over environment settings.
`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.
Effective-config inspection redacts API keys. Configured LLM secrets are also
redacted by the runtime's error and diagnostic handling, but transcript content
is still sensitive: see [artifact handling](operations.md#artifact-handling).
## 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)
- [Minimal configuration](../examples/minimal-config.yml): starts from defaults
and obtains the proposal key from the environment.
- [Production-oriented configuration](../examples/production-config.yml): illustrates
both LLM targets, concurrency, chunking, normalization, thresholds, and diagnostics.
Its explicit section target is intended for larger inputs, not the tiny sample.
- [Tiny transcript](../examples/tiny-transcript.json) and
[tiny glossary](../examples/tiny-glossary.yaml): inputs for the README quickstart.
Validate the config examples:
```sh
audita config validate --config examples/minimal-config.yml
audita config validate --config examples/production-config.yml
```
Use the [CLI configuration commands](cli.md#configuration-commands) to validate
files and inspect effective settings. Validation checks local structure and
constraints; it does not verify credentials, model availability, or endpoint access.