audita/docs/migration-from-python.md

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/ 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:

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

Parity notes and known differences

Python-vs-Go parity fixtures and intentional differences are documented in:

• docs/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.