130 lines
4.3 KiB
Markdown
130 lines
4.3 KiB
Markdown
# Operations Guide
|
|
|
|
## Scope
|
|
|
|
This document covers day-to-day operation of the CLI and HTTP service for currently implemented behavior.
|
|
|
|
For command syntax, see [CLI reference](cli.md). For file formats and defaults, see [Configuration reference](config.md).
|
|
|
|
## Operational Model
|
|
|
|
Scriptorium executes one request at a time per CLI invocation or HTTP request.
|
|
|
|
Important boundaries:
|
|
|
|
- No durable run state is stored.
|
|
- No built-in resume, checkpoint, archive, or backup workflow exists.
|
|
- Recovery is rerun-based: fix inputs/config, then rerun.
|
|
|
|
## Filesystem Layout And Config
|
|
|
|
Scriptorium depends on:
|
|
|
|
- prompt definition files (`prompt_dir`)
|
|
- execution profile files (`profile_dir`)
|
|
- optional JSON schemas (`schema_dir`)
|
|
|
|
Config discovery order when `--config` is omitted:
|
|
|
|
1. `/usr/local/etc/scriptorium/config.yml`
|
|
2. `/etc/scriptorium/config.yml`
|
|
|
|
If neither exists, built-in defaults are used. If `--config <path>` is provided, that file must exist and parse successfully.
|
|
|
|
Built-in defaults relevant to operations:
|
|
|
|
- `schema_dir: .`
|
|
- `server.addr: :8080`
|
|
- `server.artifact_root`: unset; HTTP `file` input references are rejected until configured
|
|
- `defaults.render_format: text`
|
|
|
|
## Normal CLI Workflow
|
|
|
|
Use `render` first when you need to verify prompt resolution and runtime settings without calling a model.
|
|
|
|
Use `run` for generation.
|
|
|
|
Typical sequence:
|
|
|
|
1. Confirm prompt/profile directories resolve through config or flags.
|
|
2. Confirm required input files exist and map to prompt input names.
|
|
3. Confirm required API-key environment variables are set.
|
|
4. Confirm the selected profile's model endpoint is reachable from the process environment.
|
|
5. Run `render` for preflight when changing prompt/profile/input wiring.
|
|
6. Run `run` for actual generation.
|
|
|
|
## Secrets Handling
|
|
|
|
Raw API keys are not accepted in config files, profile files as `api_key`, CLI flags, or HTTP request bodies.
|
|
|
|
Operational pattern:
|
|
|
|
- Set environment variables that hold secret values.
|
|
- Set profile `api_key_env` (or runtime override `api_key_env`) to the environment variable name.
|
|
- Keep process environments scoped to only required variables.
|
|
|
|
## HTTP Service Operation
|
|
|
|
Start service with:
|
|
|
|
```bash
|
|
go run ./cmd/scriptorium serve --config ./examples/config.yml
|
|
```
|
|
|
|
Current inbound API behavior:
|
|
|
|
- Route: `POST /v1/runs`
|
|
- JSON request parsing rejects unknown fields.
|
|
- Validation content failures still return `200 OK` with `validation.status: "failed"`.
|
|
- `inline` input references work without filesystem configuration.
|
|
- `file` input references require `server.artifact_root` or `serve --artifact-root`; relative paths resolve inside that root and paths outside it are rejected.
|
|
|
|
Security caveat:
|
|
|
|
- `serve` has no built-in authentication or authorization.
|
|
- Deploy only behind trusted controls (private network boundary, authenticated reverse proxy, API gateway, or equivalent).
|
|
- Keep the HTTP artifact root as narrow as practical and do not make it writable by untrusted users.
|
|
|
|
## Output, Logs, And Exit Codes
|
|
|
|
`run` command:
|
|
|
|
- Generated artifact body goes to stdout by default.
|
|
- `--out` writes generated artifact to a file.
|
|
- Summary metadata line is written to stderr on success.
|
|
- Exit code `2` means generation completed but validation failed.
|
|
|
|
`render` command:
|
|
|
|
- Prepared-run output goes to stdout by default.
|
|
- `--out` writes prepared-run output to a file.
|
|
- Exit code is `0` on success and `1` on failure.
|
|
|
|
`serve` command:
|
|
|
|
- Startup and server errors are written to stderr.
|
|
|
|
## Validation Behavior In Operations
|
|
|
|
Validation modes (`none`, `basic`, `json`, `json_schema`) are defined by prompt output contract.
|
|
|
|
Operational interpretation:
|
|
|
|
- Validation runtime errors are hard failures (`run` exit `1`; HTTP error response).
|
|
- Validation content failures are soft failures (`run` exit `2`; HTTP `200` with failed status).
|
|
|
|
A failed validation run can still produce output. Decide whether to keep or discard that output in your surrounding workflow.
|
|
|
|
## Safe Recovery Steps
|
|
|
|
For failed runs or requests:
|
|
|
|
1. Capture stderr output or HTTP error code/message.
|
|
2. Confirm config path and directory settings.
|
|
3. Verify prompt/profile IDs and input mappings.
|
|
4. Verify API-key environment-variable presence when required.
|
|
5. Reproduce with `render --format json` when prompt/profile/input resolution is uncertain.
|
|
6. Rerun after correction.
|
|
|
|
Because Scriptorium does not persist run state, rerun is the canonical recovery path.
|