87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
# Audita Subprocess Operations
|
|
|
|
This document describes how parent processes should invoke `audita process` safely in production orchestration.
|
|
|
|
## Recommended command form
|
|
|
|
Use explicit file outputs for orchestrated runs:
|
|
|
|
```sh
|
|
audita process <transcript.json> \
|
|
--glossary <glossary.yaml> \
|
|
--output <output-transcript.json> \
|
|
--report-json <report.json>
|
|
```
|
|
|
|
Recommended additions:
|
|
- `--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 explicit LLM throughput controls.
|
|
- `--modules ...` only when intentionally overriding the default full sequence.
|
|
|
|
## Stdout behavior
|
|
|
|
- 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 behavior
|
|
|
|
- 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.
|
|
|
|
## Output file behavior
|
|
|
|
- `--output` writes transcript JSON to the provided path.
|
|
- Output write failures return nonzero and surface actionable errors.
|
|
- The command does not silently ignore output write errors.
|
|
|
|
## Report JSON behavior
|
|
|
|
- `--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.
|
|
|
|
## Diagnostics directory behavior
|
|
|
|
- Each run creates (when possible) a per-run diagnostics directory.
|
|
- Typical artifacts include transcript, normalization, chunking, invocation, effective config, LLM diagnostics, `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.
|
|
|
|
## Exit codes
|
|
|
|
- `0`: success.
|
|
- Nonzero: failure (input/schema/config/module/LLM/runtime/output/report/diagnostics errors).
|
|
|
|
Treat any nonzero as a failed subprocess invocation.
|
|
|
|
## Timeout and cancellation
|
|
|
|
- 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.
|
|
|
|
## Secret redaction expectations
|
|
|
|
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.
|
|
|
|
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.
|