141 lines
5.2 KiB
Markdown
141 lines
5.2 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
|
|
- `server.max_request_bytes: 16777216`
|
|
- `server.max_artifact_bytes: 16777216`
|
|
- `server.max_response_bytes: 16777216`
|
|
- `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 traversal and absolute paths that are lexically outside that root are rejected.
|
|
- Request bodies, HTTP file input artifacts, and encoded JSON responses are limited by `server.max_request_bytes`, `server.max_artifact_bytes`, and `server.max_response_bytes`.
|
|
|
|
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. Symlinks inside the root are followed by the operating system, including symlinks that point outside the root.
|
|
|
|
Sizing guidance:
|
|
|
|
- Keep limits at the defaults unless a deployment has a measured need for larger prompt inputs or outputs.
|
|
- Prefer `inline` inputs for small payloads and HTTP `file` inputs for larger local artifacts inside a controlled artifact root.
|
|
- Increase the response limit when prompts intentionally return large generated artifacts or when clients request `include_raw_output`.
|
|
- Set a limit to `0` only for trusted deployments where another layer enforces request and response size.
|
|
|
|
## 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.
|