115 lines
3.1 KiB
Markdown
115 lines
3.1 KiB
Markdown
# weatherreporter Subprocess Integration
|
|
|
|
## Purpose
|
|
|
|
This document defines the supported subprocess contract for weatherreporter invoking Scriptorium through the public CLI.
|
|
|
|
This is a CLI contract, not an internal Go package integration.
|
|
|
|
## Supported Commands
|
|
|
|
weatherreporter should invoke:
|
|
|
|
- `scriptorium run`
|
|
- `scriptorium render`
|
|
|
|
Use `run` for generation.
|
|
|
|
Use `render` for preflight/debug output without LLM execution.
|
|
|
|
## Recommended Invocation Shapes
|
|
|
|
Run:
|
|
|
|
```bash
|
|
scriptorium run \
|
|
--prompt <prompt_id> \
|
|
--input data_package=<path> \
|
|
--out <artifact_path>
|
|
```
|
|
|
|
Render:
|
|
|
|
```bash
|
|
scriptorium render \
|
|
--prompt <prompt_id> \
|
|
--input data_package=<path> \
|
|
--format json
|
|
```
|
|
|
|
weatherreporter may add:
|
|
|
|
- `--config <path>`
|
|
- `--profile <profile_id>`
|
|
- repeatable `--input name=path`
|
|
- repeatable `--var name=value`
|
|
- runtime overrides when explicitly needed (`--model`, `--llm-base-url`, `--timeout`, etc.)
|
|
|
|
## Config And Directory Behavior
|
|
|
|
weatherreporter can rely on resolved app config or pass explicit paths.
|
|
|
|
- default config search order:
|
|
1. `/usr/local/etc/scriptorium/config.yml`
|
|
2. `/etc/scriptorium/config.yml`
|
|
- explicit `--config` requires file existence and valid syntax
|
|
- CLI flags override config values
|
|
|
|
## Profile Selection
|
|
|
|
Profile selection follows runner behavior:
|
|
|
|
1. explicit `--profile`
|
|
2. prompt `default_profile`
|
|
3. error if neither is available
|
|
|
|
weatherreporter should treat prompt/profile IDs as deployment configuration, not hardcoded logic.
|
|
|
|
## Input And Variable Contract
|
|
|
|
- Inputs use repeated `--input name=path`.
|
|
- Input names must match prompt definition input names.
|
|
- Variables use repeated `--var name=value` for small metadata values.
|
|
- Prefer file inputs for large content.
|
|
|
|
## Environment Contract
|
|
|
|
- Pass through required API-key environment variables referenced by `api_key_env`.
|
|
- Never pass raw API keys via CLI arguments.
|
|
- Keep subprocess environment scoped to required variables.
|
|
|
|
## Output And Error Handling
|
|
|
|
`run`:
|
|
|
|
- stdout: artifact body unless `--out` is used
|
|
- `--out`: writes artifact to file
|
|
- stderr: success summary and errors
|
|
|
|
`render`:
|
|
|
|
- stdout: prepared-run output unless `--out` is used
|
|
- stderr: errors
|
|
|
|
weatherreporter should capture stdout and stderr separately.
|
|
|
|
## Exit Status Contract
|
|
|
|
- `0`: success
|
|
- `1`: parse/config/load/render/generation/IO/runtime error
|
|
- `2`: run completed but validation failed
|
|
|
|
A `run` exit code `2` can still produce output (stdout or `--out`).
|
|
|
|
## Security Notes
|
|
|
|
- Treat generated artifacts and stderr logs as potentially sensitive.
|
|
- Avoid logging full rendered prompts by default in production contexts.
|
|
- Use controlled output paths and access controls for persisted artifacts.
|
|
|
|
## Canonical References
|
|
|
|
- CLI behavior: [CLI reference](https://gitea.maximumdirect.net/eric/scriptorium/docs/cli.md)
|
|
- Config behavior: [Configuration reference](https://gitea.maximumdirect.net/eric/scriptorium/docs/config.md)
|
|
- Operations and failure handling: [Operations guide](https://gitea.maximumdirect.net/eric/scriptorium/docs/operations.md), [Troubleshooting](https://gitea.maximumdirect.net/eric/scriptorium/docs/troubleshooting.md)
|