audita/README.md

Audita

Audita is a transcript polishing CLI.

audita process validates transcript/glossary input, normalizes and chunks transcript segments, runs the default correction pipeline, and emits corrected transcript output plus machine-readable diagnostics and reports.

What Audita Does

Default module sequence:

• glossary
• homophones
• glossary
• spoken_word
• grammar

Pipeline behavior includes:

• glossary-backed domain/acoustic corrections
• conservative homophone and mistranscription corrections
• conservative spoken-word dysfluency cleanup with semantic guardrails
• grammar/punctuation/capitalization/formatting cleanup
• validator-chain enforcement before application
• run reports and diagnostics artifacts with secret redaction

Build and Install

Build a local binary:

go build -o ./bin/audita ./cmd/audita

Install into your Go bin directory:

go install ./cmd/audita

CLI help:

audita --help
audita process --help

Test

Run all tests:

go test ./...

Basic Usage

Required inputs:

• transcript JSON path (positional argument)
• --glossary <glossary.yaml>

Recommended run:

audita process transcript.json \
  --glossary glossary.yaml \
  --output corrected.json \
  --report-json report.json

Explicit module override:

audita process transcript.json \
  --glossary glossary.yaml \
  --modules glossary,homophones,grammar \
  --output corrected.json \
  --report-json report.json

Optional transcript background context:

audita process transcript.json \
  --glossary glossary.yaml \
  --transcript-description "Brief context that may help resolve ambiguous terms." \
  --output corrected.json

The transcript description is background context only and does not override transcript content.

Write transcript JSON to stdout (no --output):

audita process transcript.json --glossary glossary.yaml

Control diagnostics location/retention:

audita process transcript.json \
  --glossary glossary.yaml \
  --work-dir /tmp/audita \
  --work-dir-retention auto \
  --output corrected.json \
  --report-json report.json

Stdout/Stderr Contract

• With --output, stdout is expected to be empty on success.
• Without --output, stdout contains transcript JSON only on success.
• --report-json writes a file and is never printed to stdout.
• stderr is human-readable diagnostics/errors.

For subprocess orchestration guidance, see docs/subprocess-operations.md.

Configuration

Precedence:

1. defaults
2. environment (AUDITA_*)
3. CLI flags

Modules

• AUDITA_MODULES (CSV)
• CLI: --modules

Transcript Description

CLI:

• --transcript-description

Behavior:

• optional background context for proposal and LLM-validator prompts;
• trimmed and length-limited by CLI validation;
• does not override transcript content;
• no AUDITA_* environment variable is currently defined for this setting.

Primary LLM

Environment:

• AUDITA_LLM_API_KEY (or OPENROUTER_API_KEY fallback)
• AUDITA_MODEL
• AUDITA_BASE_URL
• AUDITA_LLM_TIMEOUT_SECONDS
• AUDITA_MAX_RETRIES

CLI:

• --llm-api-key
• --model
• --base-url
• --llm-timeout-seconds
• --max-retries

Validation LLM

Environment:

• AUDITA_VALIDATION_LLM_API_KEY
• AUDITA_VALIDATION_MODEL
• AUDITA_VALIDATION_BASE_URL
• AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS
• AUDITA_VALIDATION_MAX_RETRIES
• AUDITA_VALIDATION_LLM_CONCURRENCY
• AUDITA_VALIDATION_MAX_PROMPT_TOKENS

CLI:

• --validation-llm-api-key
• --validation-model
• --validation-base-url
• --validation-llm-timeout-seconds
• --validation-max-retries
• --validation-llm-concurrency
• --validation-max-prompt-tokens

LLM Concurrency

Environment:

• AUDITA_TOTAL_LLM_CONCURRENCY
• AUDITA_PROPOSAL_LLM_CONCURRENCY
• AUDITA_VALIDATION_LLM_CONCURRENCY
• AUDITA_LLM_CONCURRENCY (legacy alias for AUDITA_TOTAL_LLM_CONCURRENCY)

CLI:

• --total-llm-concurrency
• --proposal-llm-concurrency
• --validation-llm-concurrency
• --llm-concurrency (legacy alias for --total-llm-concurrency)

Behavior:

• all proposal and validation LLM calls are bounded by total LLM concurrency
• proposal LLM calls are additionally bounded by proposal LLM concurrency
• when validation concurrency is unset, it inherits total LLM concurrency
• when explicitly set, proposal and validation concurrency must each be <= total-llm-concurrency
• canonical total settings win when both canonical and legacy alias settings are provided at the same precedence layer

Confidence Thresholds

Environment:

• AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD
• AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD
• AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD
• AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD

CLI:

• --glossary-confidence-threshold
• --homophones-confidence-threshold
• --spoken-word-confidence-threshold
• --grammar-confidence-threshold

Normalization and Chunking

Environment:

• AUDITA_NORMALIZE_MAX_SEGMENT_GAP
• AUDITA_NORMALIZE_ELLIPSIS_GAP
• AUDITA_NORMALIZE_MAX_SEGMENT_DURATION
• AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS
• AUDITA_MAX_SECTION_TOKENS
• AUDITA_MIN_SECTION_TOKENS
• AUDITA_TARGET_SECTIONS

CLI:

• --normalize-max-segment-gap
• --normalize-ellipsis-gap
• --normalize-max-segment-duration
• --normalize-max-segment-tokens
• --max-section-tokens
• --min-section-tokens
• --target-sections

Work Directory

Environment:

• AUDITA_WORK_DIR
• AUDITA_WORK_DIR_RETENTION (auto, always, never)

CLI:

• --work-dir
• --work-dir-retention

Retention behavior:

• always: keep all run directories
• never: keep successful run directories
• auto: keep failed runs and successful runs with skipped/rejected corrections

Reports and Diagnostics

Per-run diagnostics include:

• source transcript artifacts
• normalized transcript artifact
• normalization summary
• chunking summary
• invocation metadata
• redacted effective config
• module/validator prompt-response diagnostics
• report.json
• error.log on failure

Optional external report output:

• --report-json <path>

Documentation

• Architecture: docs/architecture.md
• Structured LLM adapter: docs/structured-llm.md
• Subprocess operations: docs/subprocess-operations.md