265 lines
6.3 KiB
Markdown
265 lines
6.3 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
go build -o ./bin/audita ./cmd/audita
|
|
```
|
|
|
|
Install into your Go bin directory:
|
|
|
|
```sh
|
|
go install ./cmd/audita
|
|
```
|
|
|
|
CLI help:
|
|
|
|
```sh
|
|
audita --help
|
|
audita process --help
|
|
```
|
|
|
|
## Test
|
|
|
|
Run all tests:
|
|
|
|
```sh
|
|
go test ./...
|
|
```
|
|
|
|
## Basic Usage
|
|
|
|
Required inputs:
|
|
- transcript JSON path (positional argument)
|
|
- `--glossary <glossary.yaml>`
|
|
|
|
Recommended run:
|
|
|
|
```sh
|
|
audita process transcript.json \
|
|
--glossary glossary.yaml \
|
|
--output corrected.json \
|
|
--report-json report.json
|
|
```
|
|
|
|
Explicit module override:
|
|
|
|
```sh
|
|
audita process transcript.json \
|
|
--glossary glossary.yaml \
|
|
--modules glossary,homophones,grammar \
|
|
--output corrected.json \
|
|
--report-json report.json
|
|
```
|
|
|
|
Optional transcript background context:
|
|
|
|
```sh
|
|
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`):
|
|
|
|
```sh
|
|
audita process transcript.json --glossary glossary.yaml
|
|
```
|
|
|
|
Control diagnostics location/retention:
|
|
|
|
```sh
|
|
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`](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`](docs/architecture.md)
|
|
- Structured LLM adapter: [`docs/structured-llm.md`](docs/structured-llm.md)
|
|
- Subprocess operations: [`docs/subprocess-operations.md`](docs/subprocess-operations.md)
|