165 lines
5.3 KiB
Markdown
165 lines
5.3 KiB
Markdown
# Operations Guide
|
|
|
|
## Scope
|
|
|
|
This guide covers operating the implemented CLI commands and HTTP service. It
|
|
does not replace the [CLI reference](cli.md), [Configuration reference](config.md),
|
|
or [HTTP API reference](api.md).
|
|
|
|
## Operational Model
|
|
|
|
Scriptorium executes one prompt request per CLI invocation or HTTP request.
|
|
|
|
Important boundaries:
|
|
|
|
- No durable run state is stored.
|
|
- No manifest, archive, checkpoint, or built-in backup workflow is written.
|
|
- No built-in resume behavior exists.
|
|
- Recovery is rerun-based: correct inputs, config, or environment, then run again.
|
|
|
|
## Filesystem Layout
|
|
|
|
Operational deployments usually provide:
|
|
|
|
- `prompt_dir`: prompt definition YAML files and adjacent `content_file` templates.
|
|
- `profile_dir`: optional custom profile YAML files.
|
|
- `schema_dir`: optional JSON Schema files.
|
|
- `server.artifact_root`: optional HTTP file-input root for `serve`.
|
|
|
|
Keep these directories readable by the Scriptorium process. Keep
|
|
`server.artifact_root` narrow and not writable by untrusted users.
|
|
|
|
## Normal CLI Workflow
|
|
|
|
Use `render` before `run` when changing prompt/profile/input wiring:
|
|
|
|
```bash
|
|
go run ./cmd/scriptorium render \
|
|
--config ./examples/config.yml \
|
|
--prompt generic.markdown_summary \
|
|
--input transcript=./examples/fixtures/transcript.md \
|
|
--input glossary=./examples/fixtures/glossary.yml \
|
|
--format json
|
|
```
|
|
|
|
Use `run` for generation after preflight:
|
|
|
|
```bash
|
|
go run ./cmd/scriptorium run \
|
|
--config ./examples/config.yml \
|
|
--prompt generic.markdown_summary \
|
|
--input transcript=./examples/fixtures/transcript.md \
|
|
--input glossary=./examples/fixtures/glossary.yml \
|
|
--out ./summary.md
|
|
```
|
|
|
|
Before production runs, confirm:
|
|
|
|
- the effective config path is the intended one;
|
|
- prompt/profile/schema directories are readable;
|
|
- input file paths exist and match prompt input names;
|
|
- required API-key environment variables are set;
|
|
- the selected model endpoint is reachable from the process environment.
|
|
|
|
## HTTP Service Operation
|
|
|
|
Start the service with:
|
|
|
|
```bash
|
|
go run ./cmd/scriptorium serve --config ./examples/config.yml
|
|
```
|
|
|
|
The implemented HTTP route is `POST /v1/runs`; request and response fields are
|
|
defined in the [HTTP API reference](api.md).
|
|
|
|
The maintained HTTP request-shape example is `examples/http-run.json`.
|
|
|
|
HTTP service notes:
|
|
|
|
- Unknown JSON fields are rejected.
|
|
- `inline` input references work without an artifact root.
|
|
- `file` input references require `server.artifact_root` or `serve --artifact-root`.
|
|
- Request bodies, HTTP file input artifacts, and encoded JSON responses are size-limited.
|
|
- Validation content failures return `200 OK` with `validation.status: "failed"`.
|
|
|
|
Security boundary:
|
|
|
|
- `serve` has no built-in authentication or authorization.
|
|
- Put it behind trusted controls such as a private network, authenticated reverse proxy, or API gateway.
|
|
- Do not expose an artifact root containing unrelated sensitive files.
|
|
- Symlinks inside the artifact root are followed by the operating system.
|
|
|
|
## Secrets Handling
|
|
|
|
Raw API keys are not accepted in app config, profiles, CLI flags, or HTTP
|
|
request bodies.
|
|
|
|
Use this pattern:
|
|
|
|
1. Set an environment variable containing the secret value.
|
|
2. Store only the variable name in profile `api_key_env` or request override `api_key_env`.
|
|
3. Scope the process environment to the minimum required variables.
|
|
|
|
## Output, Logs, And Exit Codes
|
|
|
|
`run`:
|
|
|
|
- stdout: generated artifact body unless `--out` is used.
|
|
- stderr: summary on success, errors on failure.
|
|
- exit `2`: generation completed and output was written, but validation failed.
|
|
|
|
`render`:
|
|
|
|
- stdout: prepared-run output unless `--out` is used.
|
|
- stderr: errors.
|
|
- exit `0` on success, `1` on failure.
|
|
|
|
`serve`:
|
|
|
|
- stderr: startup and server errors.
|
|
- HTTP response body: JSON success or error envelope.
|
|
|
|
## Validation Behavior
|
|
|
|
Prompt `output.validation_mode` controls validation:
|
|
|
|
- `none`: skipped.
|
|
- `basic`: output body must not be empty.
|
|
- `json`: output body must parse as JSON.
|
|
- `json_schema`: output body must parse as JSON and satisfy the configured schema.
|
|
|
|
Runtime/schema failures are hard failures (`run` exit `1`, HTTP error).
|
|
Generated-content validation failures are soft failures (`run` exit `2`, HTTP
|
|
`200 OK` with failed validation status).
|
|
|
|
## Size Limits
|
|
|
|
Defaults are documented in [Configuration reference](config.md). Operationally:
|
|
|
|
- Keep default HTTP limits unless larger payloads are measured and expected.
|
|
- Prefer `inline` HTTP inputs for small payloads.
|
|
- Prefer `file` HTTP inputs for larger local artifacts under a controlled artifact root.
|
|
- Increase `server.max_response_bytes` when generated artifacts or requested raw output are expected to be large.
|
|
- Use `0` only when another trusted layer enforces size limits.
|
|
|
|
## Maintained Examples
|
|
|
|
- `examples/config.yml`
|
|
- `examples/config.full.yml`
|
|
- `examples/render-markdown-summary.sh`
|
|
- `examples/http-run.json`
|
|
|
|
## Safe Recovery
|
|
|
|
For failed CLI commands or HTTP requests:
|
|
|
|
1. Capture stderr or the HTTP error `code` and `message`.
|
|
2. Confirm config path and effective directory settings.
|
|
3. Verify prompt ID, profile ID, schema path, and input mappings.
|
|
4. Verify required API-key environment variables.
|
|
5. Reproduce with `render --format json` when pre-LLM resolution is uncertain.
|
|
6. Rerun after correction.
|
|
|
|
Because Scriptorium does not persist run state, rerun is the supported recovery
|
|
path.
|