91 lines
3.8 KiB
Markdown
91 lines
3.8 KiB
Markdown
# Scriptorium Integration
|
|
|
|
`weatherreporter` invokes the Scriptorium executable as a subprocess to
|
|
preflight prompt input and produce report artifacts. This is the limited CLI
|
|
contract Weatherreporter uses, not general Scriptorium documentation.
|
|
|
|
## Invocation
|
|
|
|
The configured `scriptorium.binary` is the executable name or path. When it is
|
|
empty, the adapter invokes `scriptorium`. Arguments are passed directly to the
|
|
process, without a shell.
|
|
|
|
For every command, arguments occur in this order:
|
|
|
|
1. The subcommand.
|
|
2. `--config <path>` when `scriptorium.config_path` is set.
|
|
3. `--profile <profile>` when `scriptorium.profile` is set.
|
|
4. The command-specific arguments below.
|
|
5. Each configured `scriptorium.extra_args` item.
|
|
|
|
The adapter uses these exact command shapes:
|
|
|
|
```text
|
|
scriptorium render [--config <path>] [--profile <profile>] \
|
|
--prompt <prompt_id> --input data_package=<data_package_path> --format json \
|
|
[<extra_arg> ...]
|
|
|
|
scriptorium run [--config <path>] [--profile <profile>] \
|
|
--prompt <prompt_id> --input data_package=<data_package_path> --out <output_path> \
|
|
[<extra_arg> ...]
|
|
```
|
|
|
|
`render` is the preflight command. `run` writes a structured generated-text
|
|
artifact to the supplied `--out` path. It does not add `--format`, `--schema`,
|
|
`--schema-path`, or `--json-schema` flags. Prompt configuration selected by
|
|
`<prompt_id>` controls that output.
|
|
|
|
## Inputs and Outputs
|
|
|
|
Weatherreporter always supplies exactly one prompt input:
|
|
`--input data_package=<data_package_path>`. The path identifies the YAML data
|
|
package produced by the [prompt-input builder](../internal/prompt-input.md).
|
|
Its schema and the separate JSON module snapshots are internal artifacts, not
|
|
part of this CLI contract.
|
|
|
|
The application supplies an already-managed output path to every `run` call.
|
|
For direct reports it is the Markdown artifact path. For generated-text
|
|
reports it is the raw JSON artifact path; subsequent validation and Markdown
|
|
rendering are owned by [generated-text processing](../internal/generatedtext.md).
|
|
|
|
`render` has no output-path argument. Its JSON-formatted stdout remains
|
|
captured output: the adapter records it and does not parse it into a separate
|
|
CLI result type. Likewise, the adapter records `run` output metadata without
|
|
decoding the artifact written at `--out`.
|
|
|
|
## Execution and Results
|
|
|
|
`scriptorium.timeout`, when greater than zero, creates a timeout for each
|
|
subprocess invocation. Parent-context cancellation and that timeout stop the
|
|
command through the process context.
|
|
|
|
Stdout and stderr are captured independently, each up to 1 MiB. Every returned
|
|
result records the complete argv as `command`, the captured `stdout` and
|
|
`stderr`, `exitCode`, and `stdoutTruncated` and `stderrTruncated` when a stream
|
|
was capped. Results from both forms of `run` also record `outputPath`, the
|
|
requested `--out` value.
|
|
|
|
The [Scriptorium adapter](../internal/scriptorium-adapter.md) owns process
|
|
execution and result capture. [Application orchestration](../internal/app-orchestration.md)
|
|
owns when preflight output, report artifacts, and generated-text artifacts are
|
|
persisted.
|
|
|
|
## Failure Behavior
|
|
|
|
Before starting Scriptorium, the adapter requires a prompt ID and data-package
|
|
path for every command, plus an output path for `run`. Missing fields fail
|
|
without executing a subprocess.
|
|
|
|
A nonzero process exit returns the captured result and an error that includes
|
|
the exit code and stderr. An output file written before such an exit does not
|
|
make the request successful. Failures to start the command, context
|
|
cancellation, and timeout return an error rather than a successful result.
|
|
|
|
## Operational Notes
|
|
|
|
- Extra arguments are argv items; they are not shell-interpreted.
|
|
- Prompt input, generated artifacts, stdout, and stderr can contain
|
|
operationally sensitive weather data.
|
|
- Provide API keys through the Scriptorium environment or its configuration,
|
|
not through Weatherreporter CLI arguments.
|