From 72fb021453a8981ecc4389f3905fc0ae7db86602 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 24 May 2026 00:51:02 +0000 Subject: [PATCH] Rewrite README and add canonical CLI reference --- README.md | 301 ++++------------------------------------------------ docs/cli.md | 182 +++++++++++++++++++++++++++++++ 2 files changed, 201 insertions(+), 282 deletions(-) create mode 100644 docs/cli.md diff --git a/README.md b/README.md index 2f9b64a..99c3f1c 100644 --- a/README.md +++ b/README.md @@ -1,305 +1,42 @@ # Audita -Audita is a transcript polishing CLI. +Audita is a CLI that polishes transcript JSON using glossary-aware and LLM-backed correction modules. -`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. +## Quickstart -## 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 -- malformed module-stage LLM payloads degrade to warnings/rejections instead of failing the run -- run reports and diagnostics artifacts with secret redaction - -## Build and Install - -Build a local binary: +Build: ```sh go build -o ./bin/audita ./cmd/audita ``` -Install into your Go bin directory: +Run the shortest useful command: ```sh -go install ./cmd/audita +audita process ./transcript.json --glossary ./glossary.yaml --output ./corrected.json ``` -CLI help: - -```sh -audita --help -audita process --help -audita config --help -``` - -## Test - -Run all tests: - -```sh -go test ./... -``` - -## Basic Usage - -Required inputs: -- transcript JSON path (positional argument) -- `--glossary ` - -Recommended run: - -```sh -audita process transcript.json \ - --glossary glossary.yaml \ - --output corrected.json \ - --report-json report.json -``` - -Select an explicit output schema (default is `bare-segments`): - -```sh -audita process transcript.json \ - --glossary glossary.yaml \ - --output-schema audita-v1 \ - --output corrected.json \ - --report-json report.json -``` - -Recommended config-based run: - -```sh -audita process transcript.json \ - --glossary glossary.yaml \ - --config audita.yml \ - --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. -- successful runs remain quiet on stderr even when module warnings are recorded in report/diagnostics artifacts. - -For subprocess orchestration guidance, see [`docs/integrations/subprocess.md`](docs/integrations/subprocess.md). +Notes: +- the transcript JSON path is required as a positional argument; +- `--glossary` is required; +- without `--output`, corrected transcript JSON is written to stdout. ## Configuration -Precedence: -1. defaults -2. config file (`--config`, `AUDITA_CONFIG`, or default search paths when present: `/usr/local/etc/audita/config.yml`, then `/etc/audita/config.yml`) -3. environment (`AUDITA_*`) -4. CLI flags +Audita loads defaults, optional file config, environment overrides, then CLI overrides. -Config commands: +Use these commands to validate and inspect config: ```sh -audita config validate --config audita.yml -audita config print-effective --config audita.yml +audita config validate --config ./audita.yml +audita config print-effective --config ./audita.yml ``` -For full config-file schema and examples, see [`docs/config.md`](docs/config.md). -For output-schema details, see [`docs/architecture/output-schemas.md`](docs/architecture/output-schemas.md). -For built-in validator keys and chain definitions, see [`docs/architecture/validators.md`](docs/architecture/validators.md). -For embedded prompt assets and prompt metadata behavior, see [`docs/architecture/prompts.md`](docs/architecture/prompts.md). -For CLI/process compatibility guarantees, see [`docs/architecture/public-contract.md`](docs/architecture/public-contract.md). - -### 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 -- utilization diagnostics summary -- correction ledger -- invocation metadata -- redacted effective config -- module/validator prompt-response diagnostics -- `report.json` -- `error.log` on failure - -Optional external report output: -- `--report-json ` - ## Documentation -- Architecture: [`docs/architecture.md`](docs/architecture.md) -- Diagnostics: [`docs/architecture/diagnostics.md`](docs/architecture/diagnostics.md) -- Structured LLM adapter: [`docs/architecture/structured-llm.md`](docs/architecture/structured-llm.md) -- Subprocess operations: [`docs/integrations/subprocess.md`](docs/integrations/subprocess.md) -- Release checklist: [`docs/release-checklist.md`](docs/release-checklist.md) +- CLI reference: [`docs/cli.md`](docs/cli.md) +- Configuration reference: [`docs/config.md`](docs/config.md) +- Subprocess integration: [`docs/integrations/subprocess.md`](docs/integrations/subprocess.md) +- Development workflow: [`docs/policy/development.md`](docs/policy/development.md) +- Architecture policy: [`docs/policy/architecture.md`](docs/policy/architecture.md) +- Documentation policy: [`docs/policy/documentation.md`](docs/policy/documentation.md) diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..8fa49c1 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,182 @@ +# Audita CLI Reference + +## Shortest Useful Command + +```sh +audita process --glossary --output +``` + +This command validates input files, runs the configured correction pipeline, and writes corrected transcript JSON. + +## Command Overview + +- `audita process`: process one transcript JSON file. +- `audita config validate`: validate a versioned YAML config file. +- `audita config print-effective`: print redacted effective config JSON. + +General help: + +```sh +audita --help +audita process --help +audita config --help +``` + +## `process` + +Usage: + +```sh +audita process [flags] +``` + +Input requirements: +- exactly one transcript JSON positional argument is required; +- `--glossary ` is required. + +Config path selection for `process`: +1. `--config ` +2. `AUDITA_CONFIG` +3. `/usr/local/etc/audita/config.yml` (if present) +4. `/etc/audita/config.yml` (if present) + +For precedence and full config schema, see [`docs/config.md`](config.md). + +### `process` Flag Reference + +Core I/O flags: +- `--config `: path to versioned YAML config file. +- `--glossary `: glossary YAML input path (required). +- `--output `: corrected transcript JSON output file path. +- `--report-json `: machine-readable report JSON output path. +- `--output-schema `: output schema key (`bare-segments` or `audita-v1`). +- `--modules `: comma-separated module sequence override. + +Primary LLM flags: +- `--llm-api-key `: primary LLM API key. +- `--model `: primary LLM model name. +- `--base-url `: primary OpenAI-compatible base URL. +- `--llm-timeout-seconds `: primary timeout in seconds. +- `--max-retries `: primary structured-output retries. + +Validation LLM flags: +- `--validation-llm-api-key `: validation LLM API key. +- `--validation-model `: validation LLM model name. +- `--validation-base-url `: validation OpenAI-compatible base URL. +- `--validation-llm-timeout-seconds `: validation timeout in seconds. +- `--validation-max-retries `: validation structured-output retries. +- `--validation-max-prompt-tokens `: validation max prompt tokens. + +Concurrency flags: +- `--total-llm-concurrency `: total concurrent proposal+validation LLM calls. +- `--proposal-llm-concurrency `: concurrent proposal-generation LLM calls. +- `--validation-llm-concurrency `: concurrent validation LLM calls. +- `--llm-concurrency `: alias for `--total-llm-concurrency`. + +Chunking and normalization flags: +- `--target-sections `: target number of transcript sections. +- `--max-section-tokens `: maximum section tokens. +- `--min-section-tokens `: minimum section tokens. +- `--normalize-max-segment-gap `: maximum same-speaker merge gap. +- `--normalize-ellipsis-gap `: gap threshold for ellipsis insertion. +- `--normalize-max-segment-duration `: maximum merged segment duration. +- `--normalize-max-segment-tokens `: maximum merged segment token estimate. + +Threshold flags: +- `--glossary-confidence-threshold ` +- `--homophones-confidence-threshold ` +- `--spoken-word-confidence-threshold ` +- `--grammar-confidence-threshold ` + +Context and diagnostics flags: +- `--transcript-description `: background context for prompts; does not override transcript content. +- `--work-dir `: per-run diagnostics work directory. +- `--work-dir-retention `: run-directory retention policy. + +### `process` Output and Exit Behavior + +- 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. +- On failures after diagnostics initialization, stderr includes the diagnostics directory path. + +Exit behavior: +- `0`: success. +- `1`: runtime failure during processing/reporting/output paths. +- `2`: CLI usage or configuration input error. + +### `process` Examples + +Write corrected transcript to a file: + +```sh +audita process transcript.json \ + --glossary glossary.yaml \ + --output corrected.json +``` + +Emit transcript JSON to stdout: + +```sh +audita process transcript.json --glossary glossary.yaml +``` + +Use explicit config and write report JSON: + +```sh +audita process transcript.json \ + --glossary glossary.yaml \ + --config audita.yml \ + --output corrected.json \ + --report-json report.json +``` + +Override the module sequence: + +```sh +audita process transcript.json \ + --glossary glossary.yaml \ + --modules glossary,homophones,grammar \ + --output corrected.json +``` + +## `config validate` + +Usage: + +```sh +audita config validate --config +``` + +Behavior: +- validates defaults merged with file config; +- does not apply environment overrides; +- prints `config is valid` on success. + +Errors: +- `--config` is required; +- positional arguments are rejected; +- validation failures are printed to stderr. + +## `config print-effective` + +Usage: + +```sh +audita config print-effective [--config ] +``` + +Config path selection: +1. `--config ` when provided +2. `AUDITA_CONFIG` +3. `/usr/local/etc/audita/config.yml` (if present) +4. `/etc/audita/config.yml` (if present) + +Behavior: +- merges defaults, optional config file, and environment overrides; +- prints redacted JSON to stdout. + +Errors: +- positional arguments are rejected; +- resolution or parse failures are printed to stderr.