eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Cleanup pass to remove refactoring-related artifacts and references

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-12 15:19:50 -05:00
parent af84249da0
commit 390daa8b84
24 changed files with 138 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
README.md
View File

@@ -1,28 +1,27 @@
# Audita (Go)
# Audita
Audita is a transcript polishing CLI.
The Go implementation in this repository is the active implementation. It runs a full default correction pipeline over transcript JSON using glossary context, LLM-backed proposal generation, validator chains, deterministic proposal application, and structured reports/diagnostics.
`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
## What Audita Does
`audita process` performs:
- transcript/glossary schema validation;
- deterministic normalization and chunking;
- default module sequence:
- `glossary`
- `homophones`
- `glossary`
- `spoken_word`
- `grammar`
- glossary-backed domain/acoustic corrections;
- conservative homophone and likely mistranscription corrections;
- conservative spoken-word cleanup (dysfluencies/fillers) with semantic guardrails;
- grammar/punctuation/capitalization/formatting cleanup;
- machine-readable process and module reports;
- per-run diagnostics artifacts with secret redaction.
Default module sequence:
- `glossary`
- `homophones`
- `glossary`
- `spoken_word`
- `grammar`
## Build and install
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:
@@ -36,7 +35,7 @@ Install into your Go bin directory:
go install ./cmd/audita
```
Run help:
CLI help:
```sh
audita --help
@@ -45,21 +44,19 @@ audita process --help
## Test
Run the full test suite:
Run all tests:
```sh
go test ./...
```
Normal tests are deterministic and do not require real LLM credentials or Python dependencies.
## Basic usage
## Basic Usage
Required inputs:
- transcript JSON path (positional argument)
- `--glossary <glossary.yaml>`
Default full pipeline (recommended local example):
Recommended run:
```sh
audita process transcript.json \
@@ -78,13 +75,13 @@ audita process transcript.json \
--report-json report.json
```
Emit transcript JSON to stdout (no `--output`):
Write transcript JSON to stdout (no `--output`):
```sh
audita process transcript.json --glossary glossary.yaml
```
Diagnostics/work-dir control:
Control diagnostics location/retention:
```sh
audita process transcript.json \
@@ -95,17 +92,14 @@ audita process transcript.json \
--report-json report.json
```
## Stdout/stderr and orchestration behavior
## Stdout/Stderr Contract
- With `--output`, stdout should be empty on success.
- With `--output`, stdout is expected to be empty on success.
- Without `--output`, stdout contains transcript JSON only on success.
- `--report-json` writes report JSON to file; report JSON is never printed to stdout.
- stderr is for human-readable warnings/errors.
- `--report-json` writes a file and is never printed to stdout.
- stderr is human-readable diagnostics/errors.
For parent-process integration guidance, see:
- [`docs/subprocess-operations.md`](docs/subprocess-operations.md)
For orchestrated runs, use both `--output` and `--report-json`.
For subprocess orchestration guidance, see [`docs/subprocess-operations.md`](docs/subprocess-operations.md).
## Configuration
@@ -114,13 +108,14 @@ Precedence:
2. environment (`AUDITA_*`)
3. CLI flags
### Module sequence
### Modules
- `AUDITA_MODULES` (CSV, e.g. `glossary,homophones,glossary,spoken_word,grammar`)
- CLI override: `--modules`
- `AUDITA_MODULES` (CSV)
- CLI: `--modules`
### Primary LLM settings
### Primary LLM
Environment:
- `AUDITA_LLM_API_KEY` (or `OPENROUTER_API_KEY` fallback)
- `AUDITA_MODEL`
- `AUDITA_BASE_URL`
@@ -128,15 +123,17 @@ Precedence:
- `AUDITA_MAX_RETRIES`
- `AUDITA_LLM_CONCURRENCY`
CLI overrides:
CLI:
- `--llm-api-key`
- `--model`
- `--base-url`
- `--llm-timeout-seconds`
- `--max-retries`
- `--llm-concurrency`
### Validation LLM settings
### Validation LLM
Environment:
- `AUDITA_VALIDATION_LLM_API_KEY`
- `AUDITA_VALIDATION_MODEL`
- `AUDITA_VALIDATION_BASE_URL`
@@ -145,7 +142,7 @@ CLI overrides:
- `AUDITA_VALIDATION_LLM_CONCURRENCY`
- `AUDITA_VALIDATION_MAX_PROMPT_TOKENS`
CLI overrides:
CLI:
- `--validation-llm-api-key`
- `--validation-model`
- `--validation-base-url`
@@ -154,25 +151,27 @@ CLI overrides:
- `--validation-llm-concurrency`
- `--validation-max-prompt-tokens`
Validation LLM inheritance behavior:
- unset validation fields inherit from primary LLM config;
- set validation fields override primary values for validation calls only.
Validation concurrency behavior:
- when validation concurrency is unset, it inherits primary `llm-concurrency`
- when explicitly set, validation concurrency must be `<= llm-concurrency`
### Confidence thresholds
### Confidence Thresholds
Environment:
- `AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD`
- `AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD`
- `AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD`
- `AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD`
CLI overrides:
CLI:
- `--glossary-confidence-threshold`
- `--homophones-confidence-threshold`
- `--spoken-word-confidence-threshold`
- `--grammar-confidence-threshold`
### Normalization and chunking
### Normalization and Chunking
Environment:
- `AUDITA_NORMALIZE_MAX_SEGMENT_GAP`
- `AUDITA_NORMALIZE_ELLIPSIS_GAP`
- `AUDITA_NORMALIZE_MAX_SEGMENT_DURATION`
@@ -181,7 +180,7 @@ CLI overrides:
- `AUDITA_MIN_SECTION_TOKENS`
- `AUDITA_TARGET_SECTIONS`
CLI overrides:
CLI:
- `--normalize-max-segment-gap`
- `--normalize-ellipsis-gap`
- `--normalize-max-segment-duration`
@@ -190,46 +189,38 @@ CLI overrides:
- `--min-section-tokens`
- `--target-sections`
### Work-dir and retention
### Work Directory
Environment:
- `AUDITA_WORK_DIR`
- `AUDITA_WORK_DIR_RETENTION` (`auto`, `always`, `never`)
CLI overrides:
CLI:
- `--work-dir`
- `--work-dir-retention`
Retention summary:
- `always`: keep all run directories.
- `never`: keep successful run directories.
- `auto`: keep failed runs and successful runs with skipped/rejected corrections.
Retention behavior:
- `always`: keep all run directories
- `never`: keep successful run directories
- `auto`: keep failed runs and successful runs with skipped/rejected corrections
## Report and diagnostics
## Reports and Diagnostics
Per-run diagnostics include:
- source transcript artifacts;
- normalized transcript artifact;
- normalization summary;
- chunking summary;
- invocation metadata;
- redacted effective config;
- prompt/response diagnostics for module and validator LLM interactions;
- `report.json`;
- `error.log` on failure.
- 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>`
## Legacy Python reference
The original Python implementation is preserved in [`python/`](python/) as a legacy/reference implementation for parity history and migration context.
For migration guidance, see [`docs/migration-from-python.md`](docs/migration-from-python.md).
Parity fixture notes and intentional differences:
- [`docs/python-parity.md`](docs/python-parity.md)
## Additional docs
## Documentation
- Architecture: [`docs/architecture.md`](docs/architecture.md)
- Rewrite history and phase notes: [`docs/rewrite-notes.md`](docs/rewrite-notes.md)
- Migration from Python to Go: [`docs/migration-from-python.md`](docs/migration-from-python.md)
- Subprocess operations: [`docs/subprocess-operations.md`](docs/subprocess-operations.md)