From ac1787d6835590f6b7cc22da50e6d64300a723dd Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 6 May 2026 16:50:11 +0000 Subject: [PATCH] Document application config support --- README.md | 96 ++++++++++++++++++++++++++++++++++++++++----- architecture.md | 25 +++++++++++- examples/config.yml | 9 +++++ 3 files changed, 119 insertions(+), 11 deletions(-) create mode 100644 examples/config.yml diff --git a/README.md b/README.md index 0a52675..86ad3f4 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,25 @@ Callers can explicitly provide a `profile_id` to override the prompt's `default_ ## Precedence -When resolving runtime settings, Scriptorium follows this precedence model (highest to lowest): +Scriptorium uses two precedence layers: + +### Application Configuration Precedence + +For application-level adapter settings (for example prompt/profile/schema directories, server address, and render output default), precedence is: + +1. **CLI Flags** +2. **`config.yml`** +3. **Built-in application defaults** + +Application config loading behavior: +- Default config path: `/etc/scriptorium/config.yml` +- Override path: `--config ` (supported by `run`, `render`, and `serve`) +- If `--config` is provided, the file must exist and be valid. +- If `--config` is omitted, missing `/etc/scriptorium/config.yml` is allowed. + +### Runtime Model Precedence + +When resolving runtime model settings, Scriptorium follows this precedence model (highest to lowest): 1. **Runtime Overrides**: Provided via CLI flags or HTTP request `model` object. 2. **Execution Profile**: Settings defined in the selected profile. @@ -65,17 +83,32 @@ Available CLI commands: - `scriptorium render` - `scriptorium serve` +All commands accept `--config `. + +`prompt_dir` and `profile_dir` may be supplied by CLI flags or `config.yml`: +- `--prompt-dir` or `config.yml` `prompt_dir` +- `--profile-dir` or `config.yml` `profile_dir` + +`schema_dir` and `serve` `addr` may also be supplied by `config.yml` where applicable: +- `--schema-dir` or `config.yml` `schema_dir` +- `--addr` or `config.yml` `server.addr` + ### `scriptorium run` Runs a single prompt execution. **Required Flags:** -- `--prompt-dir`: Directory containing prompt YAML files. -- `--profile-dir`: Directory containing profile YAML files. - `--prompt`: The prompt ID to execute. - `--input`: Input mapping `name=path` (repeatable). +**Required Effective Settings:** +- Prompt directory: `--prompt-dir` or `config.yml` `prompt_dir` +- Profile directory: `--profile-dir` or `config.yml` `profile_dir` + **Optional Flags:** +- `--config`: Application config file path. Default discovery path is `/etc/scriptorium/config.yml`. +- `--prompt-dir`: Override prompt directory from config. +- `--profile-dir`: Override profile directory from config. - `--profile`: Override the prompt's default profile. - `--var`: Template variable `name=value` (repeatable). - `--out`: Write output to a file instead of stdout. @@ -90,7 +123,14 @@ Runs a single prompt execution. **Examples:** -Using the prompt's `default_profile`: +Using `config.yml` for prompt/profile directories: +```bash +scriptorium run \ + --prompt generic.markdown_summary \ + --input transcript=./examples/fixtures/transcript.md +``` + +Overriding config directories explicitly: ```bash scriptorium run \ --prompt-dir ./prompts \ @@ -154,12 +194,17 @@ Prepares and renders a prompt without calling the LLM. It may include `api_key_env` names where relevant. **Required Flags:** -- `--prompt-dir`: Directory containing prompt YAML files. -- `--profile-dir`: Directory containing profile YAML files. - `--prompt`: The prompt ID to render. - `--input`: Input mapping `name=path` (repeatable). +**Required Effective Settings:** +- Prompt directory: `--prompt-dir` or `config.yml` `prompt_dir` +- Profile directory: `--profile-dir` or `config.yml` `profile_dir` + **Optional Flags:** +- `--config`: Application config file path. Default discovery path is `/etc/scriptorium/config.yml`. +- `--prompt-dir`: Override prompt directory from config. +- `--profile-dir`: Override profile directory from config. - `--profile`: Override the prompt's default profile. - `--var`: Template variable `name=value` (repeatable). - `--out`: Write output to a file instead of stdout. @@ -180,7 +225,22 @@ Render formatting is modular; additional output formats can be added later witho **Examples:** -Default text output: +Default text output using `config.yml` directories: +```bash +scriptorium render \ + --prompt generic.markdown_summary \ + --input transcript=./examples/fixtures/transcript.md +``` + +Explicit config path: +```bash +scriptorium render \ + --config ./examples/config.yml \ + --prompt generic.markdown_summary \ + --input transcript=./examples/fixtures/transcript.md +``` + +Explicit directory overrides: ```bash scriptorium render \ --prompt-dir ./prompts \ @@ -248,14 +308,30 @@ scriptorium render \ Starts the HTTP API. -**Required Flags:** -- `--prompt-dir`: Directory containing prompt YAML files. -- `--profile-dir`: Directory containing profile YAML files. +**Required Effective Settings:** +- Prompt directory: `--prompt-dir` or `config.yml` `prompt_dir` +- Profile directory: `--profile-dir` or `config.yml` `profile_dir` **Optional Flags:** +- `--config`: Application config file path. Default discovery path is `/etc/scriptorium/config.yml`. - `--addr`: Listen address (default `:8080`). - `--schema-dir`: Base directory for validation schemas. +**Examples:** + +Using `config.yml`: +```bash +scriptorium serve +``` + +Overriding config for local use: +```bash +scriptorium serve \ + --prompt-dir ./prompts \ + --profile-dir ./profiles \ + --addr :9090 +``` + ## HTTP API ### `POST /v1/runs` diff --git a/architecture.md b/architecture.md index 46cb976..28d9c9b 100644 --- a/architecture.md +++ b/architecture.md @@ -28,6 +28,7 @@ Scriptorium uses a ports-and-adapters architecture to decouple the core executio - `cmd/scriptorium`: Binary entrypoint for CLI and HTTP server. - `internal/domain`: Core domain contracts, including `PromptDefinition`, `ExecutionProfile`, `PreparedRun`, `RunResult`, and related metadata. - `internal/usecase`: `Runner` use case logic, including prompt preparation, profile selection, runtime override resolution, full run execution, validation, and bounded repair. +- `internal/config`: Application-level config model/loader for adapter settings (for example prompt/profile/schema directories, server address, and render format default). - `internal/promptdef`: Repository for loading and validating Prompt Definitions from the filesystem. - `internal/profile`: Repository for loading Execution Profiles from the filesystem. - `internal/artifact`: Input artifact resolution (`inline`, `file`). @@ -40,6 +41,28 @@ Scriptorium uses a ports-and-adapters architecture to decouple the core executio Exact package names may evolve, but the architectural boundaries should remain stable. +### Application Configuration + +`config.yml` is adapter/application setup, not domain logic. + +Application config is intended for application-level settings such as: +- `prompt_dir` +- `profile_dir` +- `schema_dir` +- `server.addr` +- `defaults.render_format` + +Application config precedence is: +1. CLI flags +2. `config.yml` +3. Built-in application defaults + +Runtime model settings are intentionally separate: +- Execution profiles and runtime overrides continue to own endpoint/model/runtime behavior. +- `config.yml` does not replace execution profiles. + +The core use case (`Runner.Prepare`/`Runner.Run`) does not need to know whether adapter-level settings came from CLI flags or `config.yml`; it receives resolved dependencies and requests from adapters. + ## 3. Core Execution Model Scriptorium has two closely related execution paths: @@ -457,4 +480,4 @@ Future work should remain grounded in the current architecture: - **Profiles**: Support more granular profile versioning and environment-specific profiles. - **HTTP**: Add an HTTP prepare/render endpoint if Narratio or another caller needs it. -Future render formats should plug into the formatter layer and should not require changes to the usecase layer. \ No newline at end of file +Future render formats should plug into the formatter layer and should not require changes to the usecase layer. diff --git a/examples/config.yml b/examples/config.yml new file mode 100644 index 0000000..23512c4 --- /dev/null +++ b/examples/config.yml @@ -0,0 +1,9 @@ +prompt_dir: ./prompts +profile_dir: ./profiles +schema_dir: ./schemas + +server: + addr: :8080 + +defaults: + render_format: text