119 lines
3.6 KiB
Markdown
119 lines
3.6 KiB
Markdown
# Scriptorium Integration
|
|
|
|
This document describes the external Scriptorium CLI contract used by
|
|
`weatherreporter`.
|
|
|
|
## Purpose
|
|
|
|
`weatherreporter` invokes Scriptorium as a subprocess to preflight prompt input
|
|
and generate report artifacts. This page documents the CLI surface the adapter
|
|
uses, not the full Scriptorium product.
|
|
|
|
## Commands Used
|
|
|
|
Render preflight:
|
|
|
|
```bash
|
|
scriptorium render \
|
|
--prompt <prompt_id> \
|
|
--input data_package=<path> \
|
|
--format json
|
|
```
|
|
|
|
Report generation:
|
|
|
|
```bash
|
|
scriptorium run \
|
|
--prompt <prompt_id> \
|
|
--input data_package=<path> \
|
|
--out <artifact_path>
|
|
```
|
|
|
|
Structured generated-text report generation uses the same command shape:
|
|
|
|
```bash
|
|
scriptorium run \
|
|
--prompt <prompt_id> \
|
|
--input data_package=<path> \
|
|
--out <generated_text_raw_path>
|
|
```
|
|
|
|
`weatherreporter` always passes prompt input as
|
|
`--input data_package=<path>`. The data package is structured YAML created by
|
|
`internal/promptinput`; module snapshots remain separate JSON artifacts for
|
|
inspection and Recent Changes.
|
|
|
|
For generated-text reports, Scriptorium selects the structured output schema
|
|
from the prompt configuration associated with the prompt ID. `weatherreporter`
|
|
does not pass `--format`, schema path, or JSON Schema flags for structured
|
|
generation.
|
|
|
|
## Configured Arguments
|
|
|
|
The adapter can prepend configured flags before prompt-specific arguments:
|
|
|
|
- `--config <path>` from `scriptorium.config_path`
|
|
- `--profile <profile>` from `scriptorium.profile`
|
|
|
|
It appends `scriptorium.extra_args` after the built-in arguments. Extra
|
|
arguments are passed directly as argv items.
|
|
|
|
`scriptorium.binary` selects the executable name or path. If unset inside the
|
|
adapter, it falls back to `scriptorium`.
|
|
|
|
## Execution Behavior
|
|
|
|
The adapter runs Scriptorium without shell interpolation. Arguments are passed
|
|
through `exec.CommandContext`.
|
|
|
|
`scriptorium.timeout` limits each subprocess call when configured. Context
|
|
cancellation or timeout returns an execution error.
|
|
|
|
Stdout and stderr are captured separately. Each stream is capped at 1 MiB and
|
|
the result records whether truncation occurred.
|
|
|
|
## Results
|
|
|
|
Render results include:
|
|
|
|
- full argv recorded as `command`
|
|
- stdout
|
|
- stderr
|
|
- exit code
|
|
- truncation flags when applicable
|
|
|
|
Run results include the same fields plus the requested output path. Structured
|
|
generated-text run results use the same captured fields and output-path
|
|
recording, with the output path pointing at the raw generated-text JSON
|
|
artifact.
|
|
|
|
`weatherreporter` persists render preflight JSON when orchestration reaches the
|
|
preflight save point. For direct Markdown reports, Scriptorium writes the
|
|
managed Markdown artifact to the `--out` path. For generated-text-template
|
|
reports, Scriptorium writes raw JSON to the `--out` path; later
|
|
weatherreporter workflow steps validate those bytes and render Markdown from an
|
|
embedded template.
|
|
|
|
## Failure Behavior
|
|
|
|
The adapter validates required request fields before starting Scriptorium:
|
|
|
|
- prompt ID
|
|
- data package path
|
|
- output path for `run` and structured generated-text `run`
|
|
|
|
Nonzero exits return both the captured result and an error containing the exit
|
|
code and stderr. A `run` exit code such as `2` is still treated as an error by
|
|
the adapter, even if Scriptorium wrote output to the requested artifact path.
|
|
|
|
Subprocess start failures, context cancellation, and timeouts return errors
|
|
without fabricating a successful result.
|
|
|
|
## Security Notes
|
|
|
|
- The adapter does not invoke a shell.
|
|
- Generated artifacts, rendered prompt context, stdout, and stderr can contain
|
|
operationally sensitive data.
|
|
- API keys should be provided through the Scriptorium environment or
|
|
Scriptorium configuration, not through `weatherreporter` CLI arguments.
|