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

Replace legacy configuration loading with ConfigKit schema two

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-24 01:33:03 +00:00
parent 1ad2119283
commit 9fb89057ce
18 changed files with 354 additions and 2608 deletions
Download Patch File Download Diff File Expand all files Collapse all files

232
docs/config.md
View File

@@ -1,188 +1,68 @@
# Audita Configuration
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.
This reference describes the version-2 configuration loader in `internal/core/config`.
CLI command parsing and profile inspection are being connected in later work; the
current CLI is not yet a usable entry point for this schema. Complete copyable
examples will be migrated with that integration.
## Loading Model
## Loading and precedence
For processing and effective-config inspection, the first applicable source
selects one YAML file:
The application selects one main YAML file. ConfigKit loads built-in defaults,
the selected file, an optional named overlay from `overlays/<name>.yml` beside the
main file, and only explicitly supplied setting overrides, in that order. Imports
and secret-directory bootstrap are disabled. Unknown fields and missing, null,
or non-integer `version: 2` are errors. Version-1 files require migration; no
compatibility loader or implicit environment configuration remains.
1. Explicit CLI config path.
2. `AUDITA_CONFIG`.
3. `/usr/local/etc/audita/config.yml`, if present.
4. `/etc/audita/config.yml`, if present.
Validation runs after overlays, explicit overrides, and derived settings have
resolved. An override can therefore repair an invalid lower-precedence setting
when that setting can be decoded. ConfigKit retains field origins and derivations
for effective-configuration inspection. Its effective YAML redacts resolved
credentials.
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.
## Settings
## Effective Precedence
| 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 |
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.
## File Schema
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).
### Pipeline and Output
| YAML field | Default | Meaning |
| Field | Default | Rule |
| --- | --- | --- |
| `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). |
| `profiles_dir` | `profiles` | Nonempty; profile files are resolved relative to the selected main file. |
| `backends.<id>.endpoint` | None | Required nonempty endpoint for each backend. At least one backend is required. |
| `backends.<id>.concurrency` | `1` | Positive finite capacity; shared by both roles using that backend. |
| `backends.<id>.queue_capacity` | `1024` | Nonnegative; zero disables waiting admission. |
| `backends.<id>.credential` | Unset | Optional environment-variable secret reference; omission or null means unauthenticated use. |
| `llm.proposal_profile` | None | Required nonempty profile ID. |
| `llm.validation_profile` | Final proposal profile | Omission inherits the final proposal selection; explicit empty or null fails. |
| `llm.transient_retries` | `2` | Nonnegative additional attempts per generation. |
| `llm.repair_attempts` | `2` | Additional structural repair generations, from zero through three. |
| `llm.operation_timeout` | `15m` | Positive Go duration string per logical call. |
| `pipeline.modules` | `[glossary, homophones, glossary, spoken_word, grammar]` | Ordered module keys; repeats are meaningful and an explicit empty list runs no correction modules. |
| `output.schema` | `bare-segments` | `bare-segments` or `audita-v1`. See [output formats](integrations/output-files.md). |
| `validation.max_prompt_tokens` | `2048` | Positive validation batching budget. |
| `chunking.target_sections` | Unset | Optional positive target; omission or null selects automatic chunking. |
| `chunking.max_section_tokens` | `8192` | Positive maximum estimate. |
| `chunking.min_section_tokens` | `2048` | Positive and no greater than maximum. |
| `normalization.max_segment_gap` | `4.0` | Nonnegative numeric seconds. |
| `normalization.ellipsis_gap` | `3.5` | Nonnegative numeric seconds. |
| `normalization.max_segment_duration` | `60.0` | Positive numeric seconds. |
| `normalization.max_segment_tokens` | `2048` | Positive token estimate. |
| `thresholds.glossary`, `.homophones`, `.spoken_word`, `.grammar` | `0.8` each | Confidence thresholds in `[0, 1]`. |
| `context.description` | Empty | Trimmed prompt context, at most 500 bytes. |
| `diagnostics.work_dir` | `/tmp/audita` | Nonempty artifact parent directory. |
| `diagnostics.retention` | `auto` | `auto`, `always`, or `never`; see [operations](operations.md). |
Module keys select correction stages. Validator chains are built into each module;
there is no configuration field for selecting individual validator keys.
Module keys select correction modules; validator chains remain built into them.
The loader preserves module order and repetitions. Normalization time settings
accept numeric seconds only. The operation timeout uses a duration string.
### LLM Settings
## Credentials
The same fields are supported under `llm.proposal` and `llm.validation`.
A backend credential is a ConfigKit secret reference containing an environment
variable name, such as `credential: AUDITA_SERVICE_KEY`. Every reference that
survives overlay and override resolution must name a set, nonempty variable,
including credentials on backends unused by the selected roles. A replacement
reference resolves only the replacement; null removes the reference. General
`AUDITA_*` and `OPENROUTER_API_KEY` variables have no implicit setting effect.
Secret values are available to the runtime through the resolved reference, while
ConfigKit's effective output and provenance contain no resolved secret values.
| 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). |
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.
### Concurrency
| 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. |
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.
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.
### Chunking and Normalization
| 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. |
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.
### Thresholds, Context, and Diagnostics
| 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
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.
| 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 |
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
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.
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 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.
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.
The CLI reference will be updated as the shared input parser and profile inspection
commands are connected. Current invocation syntax belongs in [CLI](cli.md).

2
docs/development.md
View File

@@ -20,7 +20,7 @@ ownership. Commit discipline and agent Git restrictions are in the
## Baseline Validation
Use Go 1.24 or newer. From the repository root:
Use Go 1.25.5 or newer. From the repository root:
```sh
go build -o ./bin/audita ./cmd/audita

8
docs/roadmap/implementation.md
View File

@@ -108,7 +108,13 @@ user-facing policy belong to the feature roadmaps.
## Stage 1: Replace the Configuration Model and Loader
**Status:** Pending. **Depends on:** the completed prototype only.
**Status:** Complete (2026-09-24). Replaced the version-1 loader with the ConfigKit
schema-2 model, selected overlays, typed secret references, final role inheritance,
and retained domain validation. Pinned both libraries and Go 1.25.5, and aligned
the release build image. `go test ./internal/core/config` and `git diff --check`
passed. `go test ./...` currently fails in old CLI, validator, and diagnostic
callers of removed fields; those connections are assigned to later stages.
**Depends on:** the completed prototype only.
**Owns:** root `go.mod`/`go.sum`, `internal/core/config`, and config tests.
1. Pin both modules and the Go minimum above. Align build/CI toolchain declarations