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

Update internal docs for stable runner error reasons and serialized model fields

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-26 15:00:06 +00:00
parent 8d8024099f
commit 4ff55221a3
2 changed files with 18 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/internal/adapters.md
View File

@@ -105,6 +105,7 @@ Validator:
HTTP error mapping:
- maps domain/use-case errors to stable HTTP code + error code/message.
- distinguishes missing profile selection and missing `api_key_env` variable using stable use-case sentinel errors.
- avoids returning internal wrapped-cause details in response payload.
## CLI Adapter Semantics
@@ -140,4 +141,4 @@ Behavior highlights:
- Adapter packages do not own runner decision logic.
- External request/response strictness is part of contract stability.
- Prepared-render output never includes resolved API key values.
- Outbound OpenAI-compatible request includes only currently serialized fields (`model`, `messages`, optional `temperature`, `max_tokens`, `top_p`, optional `response_format`).
- Outbound OpenAI-compatible request includes only currently serialized fields (`model`, `messages`, optional `temperature`, `max_tokens`, `top_p`, optional `service_tier`, optional `response_format`).

23
docs/internal/runner.md
View File

@@ -66,14 +66,21 @@ It receives fully constructed repositories/readers/validators from adapters. Eff
## Failure Behavior
Key error classes surfaced from `Runner`:
Primary runner error classes:
- `ErrInvalidRequest`: invalid prompt/profile/request/runtime/API-key-env prerequisites.
- `ErrProfileLoad`: prompt or profile load failures.
- `ErrInvalidRequest`: invalid run request envelope.
- `ErrProfileRequired`: specific invalid-request reason when neither request `profile_id` nor prompt `default_profile` is available.
- `ErrAPIKeyEnvMissing`: specific invalid-request reason when `api_key_env` is set but the named environment variable is unset/empty.
- `ErrProfileLoad`: prompt/profile repository load failures.
- `ErrArtifactLoad`: artifact read failures.
- `ErrPromptRender`: template render failures.
- `ErrLLMGenerate`: model request failures.
- `ErrValidation`: validation runtime failures (including schema load/compile failures).
- `ErrLLMGenerate`: outbound model request failures.
- `ErrValidation`: validation runtime failures (including structured-output schema load/compile failures).
Reason sentinel behavior:
- `ErrProfileRequired` and `ErrAPIKeyEnvMissing` are wrapped with `ErrInvalidRequest`.
- Adapters can use `errors.Is` for stable reason mapping without matching runner prose.
Validation content failures are not run errors:
@@ -90,13 +97,15 @@ Validation content failures are not run errors:
3. select profile ID:
- explicit request profile ID
- prompt `default_profile`
- otherwise request error
- otherwise return an invalid request with `ErrProfileRequired`
4. load execution profile.
5. merge effective runtime target:
- built-in execution defaults
- selected profile values
- request overrides
6. verify required `api_key_env` environment variable (name only; value is not returned).
6. verify required `api_key_env` environment variable:
- missing/empty env value returns an invalid request with `ErrAPIKeyEnvMissing`
- only the environment-variable name is retained; secret value is never returned
7. resolve output contract and structured-output schema payload when `json_schema` mode is active.
8. read input artifacts.
9. render prompt messages.