Rewrite README and add canonical CLI/config documentation
This commit is contained in:
206
docs/config.md
Normal file
206
docs/config.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# Configuration Reference
|
||||
|
||||
## Config Discovery And Precedence
|
||||
|
||||
Application settings are loaded in this order:
|
||||
|
||||
1. Built-in defaults
|
||||
2. `config.yml` values
|
||||
3. CLI overrides
|
||||
|
||||
When `--config` is not provided, Scriptorium searches for config files in this order:
|
||||
|
||||
1. `/usr/local/etc/scriptorium/config.yml`
|
||||
2. `/etc/scriptorium/config.yml`
|
||||
|
||||
If neither file exists, Scriptorium continues with built-in defaults.
|
||||
|
||||
When `--config <path>` is provided, that file is required.
|
||||
|
||||
## Minimal App Config
|
||||
|
||||
```yaml
|
||||
prompt_dir: ./prompts
|
||||
profile_dir: ./profiles
|
||||
```
|
||||
|
||||
This is enough to use `run` and `render` when prompt/profile files are valid.
|
||||
|
||||
## Production-Oriented App Config
|
||||
|
||||
```yaml
|
||||
prompt_dir: /opt/scriptorium/prompts
|
||||
profile_dir: /opt/scriptorium/profiles
|
||||
schema_dir: /opt/scriptorium/schemas
|
||||
|
||||
server:
|
||||
addr: 127.0.0.1:8080
|
||||
|
||||
defaults:
|
||||
render_format: text
|
||||
```
|
||||
|
||||
## App Config File (`config.yml`)
|
||||
|
||||
Top-level fields:
|
||||
|
||||
- `prompt_dir` (optional): default prompt definition directory.
|
||||
- `profile_dir` (optional): default profile definition directory.
|
||||
- `schema_dir` (optional): base directory for schema files used by `json_schema` validation.
|
||||
- `server.addr` (optional): default listen address for `serve`.
|
||||
- `defaults.render_format` (optional): default `render` output format (`text` or `json`).
|
||||
|
||||
Built-in defaults:
|
||||
|
||||
- `schema_dir`: `.`
|
||||
- `server.addr`: `:8080`
|
||||
- `defaults.render_format`: `text`
|
||||
|
||||
Validation behavior:
|
||||
|
||||
- Config decoding is strict; unknown YAML fields are rejected.
|
||||
- Raw API key fields are not supported in `config.yml`.
|
||||
|
||||
## Prompt Definition Files
|
||||
|
||||
Prompt definitions are YAML files in `prompt_dir`.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
id: generic.structured_events
|
||||
version: "1.0.0"
|
||||
default_profile: local-quality
|
||||
description: Produce structured event JSON from a transcript.
|
||||
|
||||
inputs:
|
||||
- name: transcript
|
||||
required: true
|
||||
content_type: text/markdown
|
||||
description: Source transcript content
|
||||
- name: glossary
|
||||
required: false
|
||||
content_type: text/yaml
|
||||
description: Optional glossary context
|
||||
|
||||
messages:
|
||||
- role: system
|
||||
content_file: ./generic.structured_events.system.md
|
||||
- role: user
|
||||
content_file: ./generic.structured_events.user.md
|
||||
|
||||
output:
|
||||
format: json
|
||||
validation_mode: json_schema
|
||||
schema_path: structured_events.schema.json
|
||||
repair_attempts: 0
|
||||
```
|
||||
|
||||
Field reference:
|
||||
|
||||
- `id` (required): prompt identifier.
|
||||
- `version` (required): prompt version.
|
||||
- `default_profile` (optional): profile ID used when request does not provide `profile_id`.
|
||||
- `description` (optional): prompt description.
|
||||
- `inputs` (optional list): expected named inputs.
|
||||
- `messages` (required list): prompt message templates.
|
||||
- `output` (required object): output contract.
|
||||
|
||||
`inputs[]` fields:
|
||||
|
||||
- `name` (required)
|
||||
- `required` (optional, boolean)
|
||||
- `content_type` (optional metadata)
|
||||
- `description` (optional)
|
||||
|
||||
`messages[]` fields:
|
||||
|
||||
- `role` (required)
|
||||
- `content` or `content_file` (exactly one is required)
|
||||
|
||||
Message rules:
|
||||
|
||||
- Repeated roles are allowed.
|
||||
- `content_file` is resolved relative to the prompt YAML file location.
|
||||
- Prompt decoding is strict; unknown YAML fields are rejected.
|
||||
|
||||
`output` fields:
|
||||
|
||||
- `format` (required): `text`, `markdown`, or `json`.
|
||||
- `validation_mode` (required): `none`, `basic`, `json`, or `json_schema`.
|
||||
- `schema_path` (required when `validation_mode: json_schema`).
|
||||
- `repair_attempts` (required): integer `>= 0`.
|
||||
|
||||
Repair behavior boundary:
|
||||
|
||||
- `repair_attempts` is part of the prompt contract.
|
||||
- CLI and HTTP currently construct the runner without a repairer, so normal `run`/`serve` execution does not perform output repair attempts.
|
||||
|
||||
## Profile Definition Files
|
||||
|
||||
Execution profiles are YAML files in `profile_dir`.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
id: local-fast
|
||||
endpoint: http://localhost:8000/v1
|
||||
model: gpt-4o-mini
|
||||
temperature: 0.2
|
||||
max_tokens: 500
|
||||
top_p: 1.0
|
||||
timeout_seconds: 90
|
||||
api_key_env: SCRIPTORIUM_API_KEY
|
||||
```
|
||||
|
||||
Field reference:
|
||||
|
||||
- `id` (required)
|
||||
- `endpoint` (required)
|
||||
- `model` (required)
|
||||
- `temperature` (optional): range `0..2`
|
||||
- `max_tokens` (optional): `>= 0`
|
||||
- `top_p` (optional): range `0..1`
|
||||
- `timeout_seconds` (optional): `>= 0`
|
||||
- `reasoning_effort` (optional)
|
||||
- `api_key_env` (optional)
|
||||
- `extra_params` (optional map of strings)
|
||||
|
||||
Profile rules:
|
||||
|
||||
- Profile decoding is strict; unknown YAML fields are rejected.
|
||||
- Raw `api_key` is rejected; use `api_key_env`.
|
||||
- If `api_key_env` is set, that environment variable must be set when preparing/running.
|
||||
|
||||
Current outbound request behavior:
|
||||
|
||||
- The OpenAI-compatible client currently serializes: `model`, `messages`, `temperature`, `max_tokens`, `top_p`, and optional `response_format` for `json_schema` prompts.
|
||||
- `reasoning_effort` and `extra_params` are parsed and carried in effective settings, but are not currently serialized into outbound chat-completions requests.
|
||||
|
||||
## Schema Behavior
|
||||
|
||||
Schemas are JSON files, typically in `schema_dir`.
|
||||
|
||||
Rules:
|
||||
|
||||
- `output.validation_mode: json_schema` requires `output.schema_path`.
|
||||
- Relative `schema_path` values resolve from `schema_dir`.
|
||||
- Absolute `schema_path` values are used directly.
|
||||
- Missing or invalid schema documents cause runtime validation errors.
|
||||
- Invalid generated JSON causes validation status `failed` (not a runtime error).
|
||||
|
||||
Supported artifact reference types for request inputs are `file` and `inline`.
|
||||
|
||||
## Secrets Handling
|
||||
|
||||
- Keep secret values in environment variables.
|
||||
- Store only environment-variable names in profile `api_key_env`.
|
||||
- Do not put raw API keys in config, prompts, profiles, CLI flags, or HTTP request bodies.
|
||||
|
||||
## Maintained Examples
|
||||
|
||||
- App config: `examples/config.yml`
|
||||
- Prompt examples: `prompts/`
|
||||
- Profile examples: `profiles/`
|
||||
- Schema examples: `schemas/`
|
||||
- Input fixtures: `examples/fixtures/`
|
||||
Reference in New Issue
Block a user