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:

```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)