Add integration documentation for subprocess, LLM, and input files
This commit is contained in:
@@ -1,96 +1,99 @@
|
||||
# Audita Subprocess Operations
|
||||
# Subprocess Integration
|
||||
|
||||
This document describes how parent processes should invoke `audita process` safely in production orchestration.
|
||||
## Scope
|
||||
|
||||
## Recommended command form
|
||||
This document describes how a parent process should invoke Audita as a subprocess.
|
||||
|
||||
Use explicit file outputs for orchestrated runs:
|
||||
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> \
|
||||
--transcript-description "Brief context that may help resolve ambiguous terms." \
|
||||
--glossary <glossary.yaml> \
|
||||
--output <output-transcript.json> \
|
||||
--report-json <report.json>
|
||||
```
|
||||
|
||||
Additional flags that may be situationally appropriate:
|
||||
- `--config <path>` to select an explicit versioned config file.
|
||||
- `--output-schema <bare-segments|audita-v1>` to select transcript output shape.
|
||||
- `--work-dir <dir>` to control diagnostics location.
|
||||
- `--work-dir-retention <always|auto|never>` to control retained run directories.
|
||||
- `--total-llm-concurrency`, `--proposal-llm-concurrency`, and `--validation-llm-concurrency` when orchestration needs to set explicit LLM throughput controls.
|
||||
- `--modules ...` only when intentionally overriding the default sequence.
|
||||
Optional commonly used flags:
|
||||
- `--config <path>`
|
||||
- `--output-schema <bare-segments|audita-v1>`
|
||||
- `--work-dir <dir>`
|
||||
- `--work-dir-retention <always|auto|never>`
|
||||
- `--transcript-description <text>`
|
||||
|
||||
For config-driven orchestration, validate config files in CI/preflight:
|
||||
## Stdout Contract
|
||||
|
||||
```sh
|
||||
audita config validate --config <path>
|
||||
```
|
||||
On success:
|
||||
- with `--output`: stdout is expected to be empty;
|
||||
- without `--output`: stdout contains transcript JSON only.
|
||||
|
||||
## Stdout behavior
|
||||
`--report-json` output is never written to stdout.
|
||||
|
||||
- With `--output`: stdout is expected to be empty on success.
|
||||
- Without `--output`: stdout contains transcript JSON only on success.
|
||||
- Report JSON is never written to stdout.
|
||||
## Stderr Contract
|
||||
|
||||
## Stderr behavior
|
||||
Stderr is human-readable status/error output.
|
||||
|
||||
- Success path should be quiet or minimal human-readable logs.
|
||||
- Failure path writes concise human-readable errors.
|
||||
- When a diagnostics run directory exists, failure stderr includes its path.
|
||||
- Prompt/response diagnostic payloads are not streamed to stderr.
|
||||
On failures:
|
||||
- stderr includes a concise top-level error;
|
||||
- when diagnostics are initialized, stderr includes diagnostics directory path.
|
||||
|
||||
## Output file behavior
|
||||
Do not treat stderr as a machine-stable JSON channel.
|
||||
|
||||
- `--output` writes transcript JSON in the selected output schema to the provided path.
|
||||
- Output write failures return nonzero and surface actionable errors.
|
||||
- The command does not silently ignore output write errors.
|
||||
## Output and Report File Contract
|
||||
|
||||
## Report JSON behavior
|
||||
Transcript output:
|
||||
- `--output` writes corrected transcript JSON to the provided path;
|
||||
- output write failures return nonzero.
|
||||
|
||||
- `--report-json` writes a machine-readable process report to the requested path.
|
||||
- Run-directory `report.json` is written independently under diagnostics.
|
||||
- Best-effort failure reports are emitted when possible without masking the primary failure.
|
||||
- Report write failures return nonzero with clear stderr messaging.
|
||||
- Report diagnostics metadata references run-directory artifacts including utilization diagnostics and correction ledger paths when available.
|
||||
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 directory behavior
|
||||
## Diagnostics Contract
|
||||
|
||||
- Each run creates (when possible) a per-run diagnostics directory.
|
||||
- Typical artifacts include transcript, normalization, chunking, invocation, effective config, LLM diagnostics, `utilization-diagnostics.json`, `correction-ledger.json`, `report.json`, and `error.log` on failure.
|
||||
- Failed runs retain diagnostics.
|
||||
- Under `auto` retention, successful runs with skipped/rejected corrections are retained; clean successful runs may be removed.
|
||||
When run-directory initialization succeeds, per-run diagnostics artifacts are written under the configured work directory.
|
||||
|
||||
## Exit codes
|
||||
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)
|
||||
|
||||
- `0`: success.
|
||||
- Nonzero: failure (input/schema/config/module/LLM/runtime/output/report/diagnostics errors).
|
||||
Retention behavior is controlled by `--work-dir-retention` / config.
|
||||
|
||||
Treat any nonzero as a failed subprocess invocation.
|
||||
## Exit Behavior
|
||||
|
||||
## Timeout and cancellation
|
||||
Exit codes:
|
||||
- `0`: success;
|
||||
- `1`: runtime processing/output/report failure;
|
||||
- `2`: CLI usage or configuration input error.
|
||||
|
||||
- Runtime operations propagate context cancellation and request timeouts through LLM/scheduler paths.
|
||||
- On cancellation or timeout, the process exits nonzero and should not hang.
|
||||
- If diagnostics were initialized before failure, failure artifacts remain available for debugging.
|
||||
Treat any nonzero as subprocess failure.
|
||||
|
||||
## Secret redaction expectations
|
||||
## Parent-Process Guidance
|
||||
|
||||
API keys and configured secret values are redacted from:
|
||||
- reports (`--report-json` and run-dir `report.json`);
|
||||
- diagnostics artifacts (including effective config and LLM interaction artifacts);
|
||||
- surfaced adapter/runtime errors;
|
||||
- test fixtures and regression outputs.
|
||||
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.
|
||||
|
||||
Parent-process logs should still avoid printing raw environment variables.
|
||||
|
||||
## Parent-process pipe guidance
|
||||
|
||||
To avoid deadlocks in orchestrators:
|
||||
- always read both stdout and stderr concurrently when invoking as a subprocess;
|
||||
- prefer file outputs (`--output`, `--report-json`) for machine workflows;
|
||||
- treat stderr as human-readable diagnostics, not structured data;
|
||||
- parse structured results from output/report files.
|
||||
|
||||
For Go callers, prefer `exec.CommandContext` with explicit timeout/cancellation and buffered/streamed readers for both pipes.
|
||||
For input file contracts, see [`docs/integrations/transcript-glossary-files.md`](transcript-glossary-files.md).
|
||||
|
||||
Reference in New Issue
Block a user