85 lines
3.3 KiB
Markdown
85 lines
3.3 KiB
Markdown
# Migrating from Python Audita to Go Audita
|
|
|
|
This guide describes the operational migration from the legacy Python Audita implementation to the Go Audita implementation in this repository.
|
|
|
|
## Status summary
|
|
|
|
- The Go CLI is now the primary Audita implementation.
|
|
- The Go `audita process` command is intended to replace the Python CLI for normal operation.
|
|
- The Python implementation under [`python/`](../python/) is preserved as a legacy/reference implementation for parity history and troubleshooting context.
|
|
|
|
## What changes for operators
|
|
|
|
Use the Go binary as the integration target in orchestrators and parent processes.
|
|
|
|
Default Go runtime behavior executes the full module sequence:
|
|
1. `glossary`
|
|
2. `homophones`
|
|
3. `glossary`
|
|
4. `spoken_word`
|
|
5. `grammar`
|
|
|
|
Repeated stages are resolved deterministically in reports (for example `glossary_1`, `glossary_2`).
|
|
|
|
## Recommended invocation pattern
|
|
|
|
For orchestrated runs, use explicit output files:
|
|
|
|
```sh
|
|
audita process <transcript.json> \
|
|
--glossary <glossary.yaml> \
|
|
--output <corrected-transcript.json> \
|
|
--report-json <report.json>
|
|
```
|
|
|
|
Why:
|
|
- `--output` keeps stdout empty on success, simplifying subprocess integration.
|
|
- `--report-json` provides machine-readable run metadata independent of stderr.
|
|
|
|
Without `--output`, stdout contains transcript JSON only on successful runs.
|
|
|
|
## Diagnostics and retention behavior
|
|
|
|
- Each run creates a diagnostics run directory when initialization succeeds.
|
|
- Failed runs retain diagnostics and include `error.log`.
|
|
- Retention mode is controlled by `AUDITA_WORK_DIR_RETENTION` / `--work-dir-retention`:
|
|
- `always`: keep all run directories.
|
|
- `never`: keep successful run directories.
|
|
- `auto`: keep failed runs and successful runs with skipped/rejected corrections.
|
|
|
|
For subprocess behavior and pipe-handling guidance, see:
|
|
- [`docs/subprocess-operations.md`](subprocess-operations.md)
|
|
|
|
## Parity notes and known differences
|
|
|
|
Python-vs-Go parity fixtures and intentional differences are documented in:
|
|
- [`docs/python-parity.md`](python-parity.md)
|
|
|
|
Known open parity gaps are tracked there and should be treated as real gaps, not intentional differences. Current documented gaps include:
|
|
- broader direct import/use of Python fixture corpus;
|
|
- a repository-standard Python+Go side-by-side runner command;
|
|
- wider transcript/glossary corpus coverage.
|
|
|
|
## Testing expectations
|
|
|
|
- Normal `go test ./...` does not require real LLM credentials.
|
|
- Normal `go test ./...` does not require Python dependencies.
|
|
- Deterministic fake-LLM fixtures are used for routine CI-friendly testing.
|
|
|
|
## Legacy Python status
|
|
|
|
The Python implementation remains in-repo as a legacy/reference baseline. It is not the primary operational path.
|
|
|
|
Do not route new production orchestration to Python unless you are doing explicit parity/debug work.
|
|
|
|
## Rollout checklist
|
|
|
|
Use this checklist when switching an environment from Python invocation to Go invocation:
|
|
|
|
1. Run `go test ./...`.
|
|
2. Build the Go binary (`go build -o ./bin/audita ./cmd/audita`).
|
|
3. Run one representative fixture through `audita process`.
|
|
4. Verify `--report-json` output is written and machine-readable.
|
|
5. Verify failure runs print diagnostics path to stderr and retain diagnostics with `error.log`.
|
|
6. Update orchestrator configuration to call the Go binary and pass `--output` and `--report-json`.
|