From 4ff55221a3e5463c9843d997a17f617db9c28484 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 26 May 2026 15:00:06 +0000 Subject: [PATCH] Update internal docs for stable runner error reasons and serialized model fields --- docs/internal/adapters.md | 3 ++- docs/internal/runner.md | 23 ++++++++++++++++------- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/internal/adapters.md b/docs/internal/adapters.md index e153d71..60bf383 100644 --- a/docs/internal/adapters.md +++ b/docs/internal/adapters.md @@ -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`). diff --git a/docs/internal/runner.md b/docs/internal/runner.md index 552e3b7..929ae65 100644 --- a/docs/internal/runner.md +++ b/docs/internal/runner.md @@ -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.