Clarify HTTP operations documentation
This commit is contained in:
@@ -2,139 +2,154 @@
|
||||
|
||||
## 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).
|
||||
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 request at a time per CLI invocation or HTTP request.
|
||||
Scriptorium executes one prompt request 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.
|
||||
- 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 And Config
|
||||
## Filesystem Layout
|
||||
|
||||
Scriptorium depends on:
|
||||
Operational deployments usually provide:
|
||||
|
||||
- prompt definition files (`prompt_dir`)
|
||||
- execution profile files (`profile_dir`)
|
||||
- optional JSON schemas (`schema_dir`)
|
||||
- `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`.
|
||||
|
||||
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`
|
||||
Keep these directories readable by the Scriptorium process. Keep
|
||||
`server.artifact_root` narrow and not writable by untrusted users.
|
||||
|
||||
## Normal CLI Workflow
|
||||
|
||||
Use `render` first when you need to verify prompt resolution and runtime settings without calling a model.
|
||||
Use `render` before `run` when changing prompt/profile/input wiring:
|
||||
|
||||
Use `run` for generation.
|
||||
```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
|
||||
```
|
||||
|
||||
Typical sequence:
|
||||
Use `run` for generation after preflight:
|
||||
|
||||
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.
|
||||
```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
|
||||
```
|
||||
|
||||
## Secrets Handling
|
||||
Before production runs, confirm:
|
||||
|
||||
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.
|
||||
- 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 service with:
|
||||
Start the service with:
|
||||
|
||||
```bash
|
||||
go run ./cmd/scriptorium serve --config ./examples/config.yml
|
||||
```
|
||||
|
||||
Current inbound API behavior:
|
||||
The implemented HTTP route is `POST /v1/runs`; request and response fields are
|
||||
defined in the [HTTP API reference](api.md).
|
||||
|
||||
- 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`.
|
||||
HTTP service notes:
|
||||
|
||||
Security caveat:
|
||||
- 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.
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
Sizing guidance:
|
||||
## Secrets Handling
|
||||
|
||||
- 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.
|
||||
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` command:
|
||||
`run`:
|
||||
|
||||
- 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.
|
||||
- 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` command:
|
||||
`render`:
|
||||
|
||||
- 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.
|
||||
- stdout: prepared-run output unless `--out` is used.
|
||||
- stderr: errors.
|
||||
- exit `0` on success, `1` on failure.
|
||||
|
||||
`serve` command:
|
||||
`serve`:
|
||||
|
||||
- Startup and server errors are written to stderr.
|
||||
- stderr: startup and server errors.
|
||||
- HTTP response body: JSON success or error envelope.
|
||||
|
||||
## Validation Behavior In Operations
|
||||
## Validation Behavior
|
||||
|
||||
Validation modes (`none`, `basic`, `json`, `json_schema`) are defined by prompt output contract.
|
||||
Prompt `output.validation_mode` controls validation:
|
||||
|
||||
Operational interpretation:
|
||||
- `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.
|
||||
|
||||
- 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).
|
||||
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).
|
||||
|
||||
A failed validation run can still produce output. Decide whether to keep or discard that output in your surrounding workflow.
|
||||
## Size Limits
|
||||
|
||||
## Safe Recovery Steps
|
||||
Defaults are documented in [Configuration reference](config.md). Operationally:
|
||||
|
||||
For failed runs or requests:
|
||||
- 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.
|
||||
|
||||
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.
|
||||
## 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 canonical recovery path.
|
||||
Because Scriptorium does not persist run state, rerun is the supported recovery
|
||||
path.
|
||||
|
||||
Reference in New Issue
Block a user