Refresh Scriptorium integration guide
This commit is contained in:
@@ -1,118 +1,91 @@
|
|||||||
# Scriptorium Integration
|
# Scriptorium Integration
|
||||||
|
|
||||||
This document describes the external Scriptorium CLI contract used by
|
`weatherreporter` invokes the Scriptorium executable as a subprocess to
|
||||||
`weatherreporter`.
|
preflight prompt input and produce report artifacts. This is the limited CLI
|
||||||
|
contract Weatherreporter uses, not general Scriptorium documentation.
|
||||||
|
|
||||||
## Purpose
|
## Invocation
|
||||||
|
|
||||||
`weatherreporter` invokes Scriptorium as a subprocess to preflight prompt input
|
The configured `scriptorium.binary` is the executable name or path. When it is
|
||||||
and generate report artifacts. This page documents the CLI surface the adapter
|
empty, the adapter invokes `scriptorium`. Arguments are passed directly to the
|
||||||
uses, not the full Scriptorium product.
|
process, without a shell.
|
||||||
|
|
||||||
## Commands Used
|
For every command, arguments occur in this order:
|
||||||
|
|
||||||
Render preflight:
|
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.
|
||||||
|
|
||||||
```bash
|
The adapter uses these exact command shapes:
|
||||||
scriptorium render \
|
|
||||||
--prompt <prompt_id> \
|
```text
|
||||||
--input data_package=<path> \
|
scriptorium render [--config <path>] [--profile <profile>] \
|
||||||
--format json
|
--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> ...]
|
||||||
```
|
```
|
||||||
|
|
||||||
Report generation:
|
`render` is the preflight command. `run` writes either a Markdown report or a
|
||||||
|
raw generated-text artifact to the supplied `--out` path. The structured
|
||||||
|
generated-text use of `run` has the same argv as Markdown generation; it does
|
||||||
|
not add `--format`, `--schema`, `--schema-path`, or `--json-schema` flags.
|
||||||
|
Prompt configuration selected by `<prompt_id>` controls that output.
|
||||||
|
|
||||||
```bash
|
## Inputs and Outputs
|
||||||
scriptorium run \
|
|
||||||
--prompt <prompt_id> \
|
|
||||||
--input data_package=<path> \
|
|
||||||
--out <artifact_path>
|
|
||||||
```
|
|
||||||
|
|
||||||
Structured generated-text report generation uses the same command shape:
|
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.
|
||||||
|
|
||||||
```bash
|
The application supplies an already-managed output path to every `run` call.
|
||||||
scriptorium run \
|
For direct reports it is the Markdown artifact path. For generated-text
|
||||||
--prompt <prompt_id> \
|
reports it is the raw JSON artifact path; subsequent validation and Markdown
|
||||||
--input data_package=<path> \
|
rendering are owned by [generated-text processing](../internal/generatedtext.md).
|
||||||
--out <generated_text_raw_path>
|
|
||||||
```
|
|
||||||
|
|
||||||
`weatherreporter` always passes prompt input as
|
`render` has no output-path argument. Its JSON-formatted stdout remains
|
||||||
`--input data_package=<path>`. The data package is structured YAML created by
|
captured output: the adapter records it and does not parse it into a separate
|
||||||
`internal/promptinput`; module snapshots remain separate JSON artifacts for
|
CLI result type. Likewise, the adapter records `run` output metadata without
|
||||||
inspection and Recent Changes.
|
decoding the artifact written at `--out`.
|
||||||
|
|
||||||
For generated-text reports, Scriptorium selects the structured output schema
|
## Execution and Results
|
||||||
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
|
`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.
|
||||||
|
|
||||||
The adapter can prepend configured flags before prompt-specific arguments:
|
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.
|
||||||
|
|
||||||
- `--config <path>` from `scriptorium.config_path`
|
The [Scriptorium adapter](../internal/scriptorium-adapter.md) owns process
|
||||||
- `--profile <profile>` from `scriptorium.profile`
|
execution and result capture. [Application orchestration](../internal/app-orchestration.md)
|
||||||
|
owns when preflight output, report artifacts, and generated-text artifacts are
|
||||||
It appends `scriptorium.extra_args` after the built-in arguments. Extra
|
persisted.
|
||||||
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
|
## Failure Behavior
|
||||||
|
|
||||||
The adapter validates required request fields before starting Scriptorium:
|
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.
|
||||||
|
|
||||||
- prompt ID
|
A nonzero process exit returns the captured result and an error that includes
|
||||||
- data package path
|
the exit code and stderr. An output file written before such an exit does not
|
||||||
- output path for `run` and structured generated-text `run`
|
make the request successful. Failures to start the command, context
|
||||||
|
cancellation, and timeout return an error rather than a successful result.
|
||||||
|
|
||||||
Nonzero exits return both the captured result and an error containing the exit
|
## Operational Notes
|
||||||
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
|
- Extra arguments are argv items; they are not shell-interpreted.
|
||||||
without fabricating a successful result.
|
- Prompt input, generated artifacts, stdout, and stderr can contain
|
||||||
|
operationally sensitive weather data.
|
||||||
## Security Notes
|
- Provide API keys through the Scriptorium environment or its configuration,
|
||||||
|
not through Weatherreporter CLI arguments.
|
||||||
- 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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user