eric/scriptorium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Document Scriptorium as a Promptkit application

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-28 14:21:19 +00:00
parent fb0b21c51d
commit 7bb4cf35b9
18 changed files with 327 additions and 1031 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
docs/config.md
View File

@@ -1,15 +1,17 @@
# Configuration Reference
This is the canonical reference for Scriptorium application settings and the
prompt, profile, and schema files those settings select. For command syntax,
see the [CLI reference](cli.md); for HTTP request shapes, limits, and outcomes,
see the [HTTP API reference](api.md).
This is the canonical reference for Scriptorium application settings. Prompt,
profile, schema, execution-setting, built-in profile, and framework credential
semantics are defined by the
[Promptkit v0.1.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/formats.md).
For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and
outcomes, see the [HTTP API reference](api.md).
## Discovery And Precedence
Application settings are resolved in this order:
1. built-in defaults;
1. built-in Scriptorium defaults;
2. a configuration file; then
3. CLI overrides.
@@ -19,7 +21,7 @@ If neither exists, it uses built-in defaults. An explicit `--config` path must
exist and decode successfully.
The maintained [minimal configuration](../examples/config.yml) and
[full configuration](../examples/config.full.yml) are copyable examples.
[complete configuration](../examples/config.full.yml) are copyable examples.
## Application Configuration File
@@ -28,146 +30,57 @@ do not override a prior value. Raw API-key fields are not accepted.
| Field | Default | Meaning |
| --- | --- | --- |
| `prompt_dir` | unset | Directory containing prompt-definition YAML. `run`, `render`, and `serve` require an effective value. |
| `profile_dir` | unset | Directory containing custom profile YAML. Built-in profiles remain available. |
| `schema_dir` | `.` | Base directory for relative JSON Schema paths. |
| `prompt_dir` | unset | Promptkit prompt-definition source directory. `run`, `render`, and `serve` require an effective value. |
| `profile_dir` | unset | Optional custom Promptkit profile source directory overlaid on Promptkit built-ins. |
| `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. |
| `server.addr` | `:8080` | Address used by `serve`. |
| `server.artifact_root` | unset | Root that enables HTTP `file` input references. |
| `server.max_request_bytes` | `16777216` | Maximum encoded HTTP request body bytes; `0` disables the limit. |
| `server.max_request_bytes` | `16777216` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
| `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. |
| `defaults.render_format` | `text` | Default `render` output format: `text` or `json`. |
| `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. |
The three size fields must be zero or greater. The HTTP contract defines how
each limit is enforced and reported. `server.artifact_root` configures the
deployment boundary; see the [HTTP API reference](api.md) for request-path and
containment behavior, and [operations](operations.md) for deployment handling.
The size fields must be zero or greater. The [HTTP API](api.md) defines how
each limit is enforced and reported. `server.artifact_root` configures an HTTP
deployment boundary; see [operations](operations.md) for deployment handling.
## Prompt Definition Files
## Framework Source Mapping
Prompt definitions are strict YAML files anywhere below `prompt_dir`. A prompt
is selected by its YAML `id`, not by file path; nested directories are only for
organization. See [maintained prompt examples](../examples/prompts/).
Scriptorium passes `prompt_dir`, `profile_dir`, and `schema_dir` to Promptkit
when constructing its engine. Scriptorium does not redefine or independently
parse those framework file formats.
| Field | Required | Meaning |
| --- | --- | --- |
| `id` | yes | Prompt identifier. |
| `version` | yes | Prompt version. |
| `default_profile` | no | Profile used when a request omits a profile ID. |
| `description` | no | Human-readable description. |
| `session_id` | no | Go-template string rendered from request variables and sent to a compatible provider when non-empty. |
| `inputs` | no | Declared input metadata. |
| `messages` | yes | Chat-message templates. |
| `output` | yes | Output format and validation contract. |
- Prompt selection, versions, message templates, inputs, output contracts, and
session IDs are Promptkit contracts.
- Profile fields, numeric ranges, execution defaults, overlay precedence,
built-in profiles, and credential rules are Promptkit contracts.
- Schema path behavior and generated-content validation are Promptkit
contracts.
### Inputs And Messages
See the
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/formats.md)
for all of those definitions. The files under
[`examples/prompts`](../examples/prompts/),
[`examples/profiles`](../examples/profiles/), and
[`examples/schemas`](../examples/schemas/) are maintained Scriptorium
application inputs using that tagged format.
Each `inputs` item has a required `name` and optional `required`,
`content_type`, and `description` fields. Input names must be unique.
## Credentials And Outbound Behavior
Each message has a required `role`, exactly one of `content` or `content_file`,
and optional `cache_control`. A `content_file` path is relative to the prompt
file. `cache_control.type` must be `ephemeral`; its optional `ttl` is `1h`.
Scriptorium maps `--api-key-env` and HTTP `model.api_key_env` into Promptkit
request overrides. Keep secret values in environment variables and store only
their names in configuration or framework source files. Do not place raw keys
in configuration, prompts, profiles, CLI arguments, examples, or HTTP
payloads.
`session_id` uses the same template variables as messages. Empty rendered
values are omitted. A rendered value may contain at most 256 Unicode code
points.
### Output Contract
| Field | Required | Values or behavior |
| --- | --- | --- |
| `format` | yes | `text`, `markdown`, or `json`. |
| `validation_mode` | yes | `none`, `basic`, `json`, or `json_schema`. |
| `schema_path` | for `json_schema` | Schema path, relative to `schema_dir` unless absolute. |
| `repair_attempts` | no | Integer greater than or equal to `0`; omitted means `0`. |
## Profile Definition Files
Profiles are strict YAML files anywhere below `profile_dir`. A profile is
selected by YAML `id`; nested directories are organizational. See the
[maintained profile examples](../examples/profiles/).
| Field | Required | Meaning |
| --- | --- | --- |
| `id` | yes | Profile identifier. |
| `endpoint` | yes | OpenAI-compatible base URL, including its API version path when needed. |
| `model` | yes | Provider model name. |
| `temperature` | no | Number from `0` through `2`. |
| `max_tokens` | no | Integer zero or greater. |
| `top_p` | no | Number from `0` through `1`. |
| `timeout_seconds` | no | Per-generation-call deadline in whole seconds; integer zero or greater. |
| `service_tier` | no | Non-empty provider-specific request tier. |
| `reasoning_effort` | no | Non-empty provider-specific reasoning setting. |
| `api_key_env` | no | Environment-variable name containing the API key. |
| `extra_params` | no | JSON-compatible provider-specific outbound request fields. |
Execution defaults before profile and request overrides are `temperature: 0`,
`max_tokens: 0`, `top_p: 1`, and `timeout_seconds: 600`. Profile numeric values
merge by non-zero value. Request overrides preserve presence, so an explicit
zero can override a profile value. For `timeout_seconds`, explicit request zero
disables the generation deadline while retaining the caller context and the
built-in client's transport cap. See the
[OpenAI-compatible integration contract](integrations/openai-compatible-chat.md#authentication-and-timeout)
for the complete timeout interaction.
Custom profiles take precedence over built-ins with the same ID. Invalid custom
profiles are errors; they do not fall back to a built-in profile. Raw `api_key`
is rejected. Use `api_key_env`, or the public Go package's request-scoped key
mechanism described in the [package contract](consumers/pkg-scriptorium.md).
`extra_params` keys must be non-empty and cannot be `model`, `session_id`,
`messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`,
`reasoning_effort`, or `response_format`.
### Built-In Profile Catalog
Each embedded profile uses `OPENROUTER_API_KEY`.
| Provider | ID | Model |
| --- | --- | --- |
| aion-labs | `aion-2` | `aion-labs/aion-2.0` |
| anthropic | `claude-fable-latest` | `~anthropic/claude-fable-latest` |
| anthropic | `claude-haiku-latest` | `~anthropic/claude-haiku-latest` |
| anthropic | `claude-opus-latest` | `~anthropic/claude-opus-latest` |
| anthropic | `claude-sonnet-latest` | `~anthropic/claude-sonnet-latest` |
| deepseek | `deepseek-3-2` | `deepseek/deepseek-v3.2` |
| deepseek | `deepseek-4-flash` | `deepseek/deepseek-v4-flash` |
| deepseek | `deepseek-4-pro` | `deepseek/deepseek-v4-pro` |
| google | `gemini-2-flash` | `google/gemini-2.5-flash` |
| google | `gemini-2-flash-lite` | `google/gemini-2.5-flash-lite` |
| google | `gemini-2-pro` | `google/gemini-2.5-pro` |
| google | `gemini-3-flash-lite` | `google/gemini-3.1-flash-lite` |
| google | `gemini-flash-latest` | `~google/gemini-flash-latest` |
| google | `gemini-pro-latest` | `~google/gemini-pro-latest` |
| google | `gemma-4-31b` | `google/gemma-4-31b-it:exacto` |
| minimax | `minimax-m2` | `minimax/minimax-m2.5` |
| minimax | `minimax-m3` | `minimax/minimax-m3` |
| mistral | `mistral-large-2512` | `mistralai/mistral-large-2512` |
| mistral | `mistral-medium-3-5` | `mistralai/mistral-medium-3-5` |
| mistral | `mistral-small-3` | `mistralai/mistral-small-3.2-24b-instruct` |
| mistral | `mistral-small-4` | `mistralai/mistral-small-2603` |
| nvidia | `nemotron-3-ultra` | `nvidia/nemotron-3-ultra-550b-a55b` |
| openai | `gpt-5-mini` | `openai/gpt-5.4-mini` |
| openai | `gpt-5-nano` | `openai/gpt-5.4-nano` |
## Schemas
Schemas are JSON files, normally below `schema_dir`. `json_schema` output
requires a `schema_path`. Relative paths resolve from `schema_dir`; absolute
paths are used directly. Referenced nested schemas use relative paths and are
not discovered by basename. An unreadable or invalid schema is a runtime
validation error; generated content that fails JSON or schema validation is a
validation result.
## Credentials
Keep secrets in environment variables. Store only an environment-variable name
in `api_key_env`; do not place raw keys in configuration, prompt or profile
files, CLI arguments, examples, or HTTP payloads.
Promptkit's
[OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/integrations/openai-compatible-chat.md)
defines outbound authentication, provider request mapping, transport limits,
and timeout layering.
## Related References
- [CLI reference](cli.md)
- [HTTP API reference](api.md)
- [OpenAI-compatible outbound contract](integrations/openai-compatible-chat.md)
- [Operations guide](operations.md)
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/formats.md)