eric/audita

Fork 0

Files

Eric Rakestraw 28d5201a69 Add integration documentation for subprocess, LLM, and input files

2026-05-24 01:07:27 +00:00

6.4 KiB

Raw Blame History

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. For OpenAI-compatible endpoint behavior, see docs/integrations/openai-compatible-llm.md. For transcript/glossary input file contracts, see docs/integrations/transcript-glossary-files.md.

Loading Model

Path resolution for audita process and audita config print-effective:

--config <path>
AUDITA_CONFIG
/usr/local/etc/audita/config.yml (if present)
/etc/audita/config.yml (if present)

Missing explicit path behavior:

missing --config target is an error;
missing AUDITA_CONFIG target is an error.

Missing default-path files are non-fatal.

Effective Precedence

audita process:

defaults
file config
environment overrides
CLI overrides

audita config print-effective:

defaults
file config
environment overrides

audita config validate:

defaults
file config

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.

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

concurrency:
  total_llm: 1
  proposal_llm: 1
  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 background context

diagnostics:
  work_dir: /tmp/audita
  retention: auto

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.

Environment Overrides

Modules:

AUDITA_MODULES

Config path:

AUDITA_CONFIG

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.

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
Production-style config: examples/production-config.yml
Tiny transcript input: examples/tiny-transcript.json
Tiny glossary input: examples/tiny-glossary.yaml

Validate the config examples:

audita config validate --config examples/minimal-config.yml
audita config validate --config examples/production-config.yml

6.4 KiB Raw Blame History