100 lines
2.8 KiB
Markdown
100 lines
2.8 KiB
Markdown
# Subprocess Integration
|
|
|
|
## Scope
|
|
|
|
This document describes how a parent process should invoke Audita as a subprocess.
|
|
|
|
It covers:
|
|
- invocation shape;
|
|
- stdout/stderr behavior;
|
|
- output/report file behavior;
|
|
- diagnostics and exit behavior.
|
|
|
|
For full CLI and config references, see [`docs/cli.md`](../cli.md) and [`docs/config.md`](../config.md).
|
|
|
|
## Recommended Invocation
|
|
|
|
Use explicit output and report paths for machine workflows:
|
|
|
|
```sh
|
|
audita process <transcript.json> \
|
|
--glossary <glossary.yaml> \
|
|
--output <output-transcript.json> \
|
|
--report-json <report.json>
|
|
```
|
|
|
|
Optional commonly used flags:
|
|
- `--config <path>`
|
|
- `--output-schema <bare-segments|audita-v1>`
|
|
- `--work-dir <dir>`
|
|
- `--work-dir-retention <always|auto|never>`
|
|
- `--transcript-description <text>`
|
|
|
|
## Stdout Contract
|
|
|
|
On success:
|
|
- with `--output`: stdout is expected to be empty;
|
|
- without `--output`: stdout contains transcript JSON only.
|
|
|
|
`--report-json` output is never written to stdout.
|
|
|
|
## Stderr Contract
|
|
|
|
Stderr is human-readable status/error output.
|
|
|
|
On failures:
|
|
- stderr includes a concise top-level error;
|
|
- when diagnostics are initialized, stderr includes diagnostics directory path.
|
|
|
|
Do not treat stderr as a machine-stable JSON channel.
|
|
|
|
## Output and Report File Contract
|
|
|
|
Transcript output:
|
|
- `--output` writes corrected transcript JSON to the provided path;
|
|
- output write failures return nonzero.
|
|
|
|
Report output:
|
|
- `--report-json` writes machine-readable process report JSON to the provided path;
|
|
- run diagnostics also attempt to write their own `report.json`;
|
|
- report write failures return nonzero;
|
|
- on failure paths, report writing is best-effort and does not mask the primary run error.
|
|
|
|
## Diagnostics Contract
|
|
|
|
When run-directory initialization succeeds, per-run diagnostics artifacts are written under the configured work directory.
|
|
|
|
Typical artifacts include:
|
|
- `source-transcript.json`
|
|
- `source-transcript-parsed.json`
|
|
- `normalized-transcript.json`
|
|
- `normalization-summary.json`
|
|
- `chunking-summary.json`
|
|
- `invocation.json`
|
|
- `effective-config.json`
|
|
- `utilization-diagnostics.json`
|
|
- `correction-ledger.json`
|
|
- `report.json`
|
|
- `error.log` (failure)
|
|
|
|
Retention behavior is controlled by `--work-dir-retention` / config.
|
|
|
|
## Exit Behavior
|
|
|
|
Exit codes:
|
|
- `0`: success;
|
|
- `1`: runtime processing/output/report failure;
|
|
- `2`: CLI usage or configuration input error.
|
|
|
|
Treat any nonzero as subprocess failure.
|
|
|
|
## Parent-Process Guidance
|
|
|
|
For reliable orchestration:
|
|
- read stdout and stderr concurrently to avoid pipe blocking;
|
|
- prefer `--output` and `--report-json` for machine parsing;
|
|
- use timeout/cancellation in the parent process;
|
|
- inspect diagnostics path and `report.json`/`error.log` on failure.
|
|
|
|
For input file contracts, see [`docs/integrations/transcript-glossary-files.md`](transcript-glossary-files.md).
|