53 lines
2.8 KiB
Markdown
53 lines
2.8 KiB
Markdown
# Subprocess Integration
|
|
|
|
This guide explains how a parent process can invoke Audita and consume its results.
|
|
The [CLI reference](../cli.md) owns command syntax, streams, and exit semantics;
|
|
[configuration](../config.md) owns discovery and precedence.
|
|
|
|
## Invocation
|
|
|
|
Use an argument array with the transcript path and required glossary argument,
|
|
following the [process examples](../cli.md#commands-and-help). For machine workflows,
|
|
select an explicit transcript file destination and a configuration path. Reports
|
|
go beside the transcript unless an explicit `--report-dir` selects another
|
|
directory. For stdout output, reports use the effective `reporting.stdout_dir`
|
|
(defaulting to the invocation working directory), including a `--report-dir`
|
|
override. A config-file or overlay value for `reporting.stdout_dir` alone does
|
|
not redirect file-output reports. `--work-dir` selects a debug root, while
|
|
configuration or `--debug` enables capture; the path flag alone does not.
|
|
Supplying a configuration path also makes file selection predictable; only
|
|
explicitly referenced credential variables are read from the environment.
|
|
|
|
Resolve the executable deliberately and set the child's working directory so
|
|
relative input/output paths and reported artifact paths have a known base.
|
|
Read stdout and stderr concurrently to avoid pipe blocking, and impose timeout
|
|
or cancellation in the parent process when needed.
|
|
|
|
## Result Handling
|
|
|
|
Interpret the exit result according to the
|
|
[CLI output and exit contract](../cli.md#streams-and-exit-status).
|
|
Consume transcript/report data through the
|
|
[output-file contract](output-files.md), and treat stderr as human-readable detail.
|
|
The three reports may be absent after early configuration or destination
|
|
failures. After initialization, failed reports can describe invalid input or
|
|
partial processing and use the same selected report directory as successful
|
|
runs. Exit `0` can include recoverable model errors and applied
|
|
corrections; inspect `errors.yml` and `recoveries.yml` for those outcomes. A
|
|
transcript may have been written before a later required report failure, so
|
|
the file alone does not prove completion.
|
|
|
|
If processing fails, preserve available evidence and follow
|
|
[operations recovery](../operations.md#failure-inspection-and-recovery).
|
|
Ordinary reports are independent of optional retained debug evidence. Parent
|
|
cancellation reaches the child through its context; Audita joins workers and
|
|
attempts failed-status report finalization before exiting. Uncatchable
|
|
termination can leave `in_progress` reports. Neither the existence of an output
|
|
file nor a debug directory alone establishes successful completion.
|
|
|
|
## Related Contracts
|
|
|
|
- [Transcript and glossary inputs](transcript-glossary-files.md)
|
|
- [LLM endpoint compatibility](openai-compatible-llm.md)
|
|
- [Configuration inspection commands](../cli.md#commands-and-help)
|