eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Document Promptkit report generation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-31 05:03:02 +00:00
parent 2c68d0a85f
commit b96f40e5ca
39 changed files with 256 additions and 1741 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/integrations/promptkit.md Normal file
View File

@@ -0,0 +1,22 @@
# Promptkit Integration
Weatherreporter uses Promptkit for all generated-text reports. The four logical prompts are
`weather.daily_generated_text`, `weather.today_generated_text`,
`weather.tomorrow_generated_text`, and `weather.hourly_generated_text`, each at version
`1.0.0`. Their prompt assets and generated-text JSON Schemas are embedded by
`internal/promptassets`.
Before collection, Weatherreporter inspects the exact prompt version, requires one required
`data_package` input with content type `application/yaml`, and requires the report's JSON
Schema output contract. It selects `promptkit.profile` when configured, otherwise the
prompt's declared default profile. Profiles that require a direct API key are unsupported; a
profile that reports `APIKeyEnv` requires a nonblank value in that environment variable.
Execution receives the already-persisted YAML package, prepares it once, and returns structured
JSON that Weatherreporter validates before rendering its own Markdown template. Preparation and
execution receipts are project-owned, safe provenance records. Content-rich diagnostics are
opt-in through `--llm-debug-dir`; see [operations](../operations.md) for retention and permissions.
Prompt/profile configuration is owned by the [configuration reference](../config.md). Adapter
construction and mapping are documented in the [Promptkit adapter internals](../internal/promptkit-adapter.md).
Durable metadata compatibility is described in [state internals](../internal/state.md).

90
docs/integrations/scriptorium.md
View File

@@ -1,90 +0,0 @@
# 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.