Update documentation for PromptKit adoption
This commit is contained in:
44
docs/api.md
44
docs/api.md
@@ -43,7 +43,6 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
|
||||
| Field | Required | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `prompt_id` | yes | Non-blank prompt ID. |
|
||||
| `prompt_version` | no | Prompt version filter. |
|
||||
| `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
|
||||
| `session_id` | no | Optional direct, non-secret session identifier. |
|
||||
| `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. |
|
||||
@@ -52,7 +51,7 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
|
||||
| `include_raw_output` | no | Include `raw_model_output` when true. |
|
||||
| `include_execution_report` | no | Include a terminal `execution` report when true and Promptkit supplies a terminal observation. Omitted, `null`, or false leaves reporting off. |
|
||||
| `transient_retries` | no | Nonnegative additional transient attempt count for this run. Omitted or `null` inherits the configured engine value and then Promptkit's default; `0` disables additional attempts. |
|
||||
| `run_timeout_seconds` | no | Optional signed 64-bit whole-second limit for engine execution. Omitted, `null`, or `0` adds no deadline; positive values shorten the caller context deadline. |
|
||||
| `run_timeout_seconds` | no | Optional signed 64-bit whole-second engine operation budget. Omitted, `null`, or `0` adds no deadline. |
|
||||
|
||||
An input reference has a required `type` of `file` or `inline`. A `file`
|
||||
reference requires `uri`; an `inline` reference requires `body`.
|
||||
@@ -68,16 +67,17 @@ The optional `model` object accepts `endpoint`, `model`, `temperature`,
|
||||
`max_tokens`, `top_p`, `timeout_seconds`, `service_tier`,
|
||||
`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and
|
||||
framework credential semantics are defined by the
|
||||
[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
|
||||
[PromptKit v0.23.2 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md).
|
||||
Explicit zero values for the numeric fields are overrides; zero
|
||||
`timeout_seconds` disables the per-attempt generation deadline only, retaining the
|
||||
request context and configured transport cap. The timeout layers are defined in
|
||||
the [Promptkit v0.12.0 outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
||||
the [PromptKit v0.23.2 outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
||||
Each built-in transient retry gets a fresh generation timeout; the caller's
|
||||
request context remains the outer cancellation boundary.
|
||||
|
||||
Raw API-key values are not accepted. `api_key` and any other unknown model
|
||||
field cause `400 invalid_json`.
|
||||
Raw API-key values are not accepted. `api_key`, the removed `prompt_version`,
|
||||
and any other unknown field cause `400 invalid_json`. Prompt and profile IDs
|
||||
are passed unchanged, including qualified collection IDs.
|
||||
|
||||
`model.reasoning_effort` is an optional JSON string with three states: omission
|
||||
inherits the selected profile, a non-empty string replaces its value, and an
|
||||
@@ -116,14 +116,14 @@ validation contract. The response contains:
|
||||
optional `uri`;
|
||||
- `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus
|
||||
optional `errors` and `schema_path`;
|
||||
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity, model, input-hash, usage,
|
||||
timing, validation, and repair-attempt metadata; and
|
||||
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity,
|
||||
model parameters, input hashes, usage, and timing; and
|
||||
- optional `raw_model_output` when requested.
|
||||
- optional `execution` when requested and a terminal observation exists.
|
||||
|
||||
`metadata.model_params` has `endpoint`, `model`, `temperature`,
|
||||
`max_tokens`, `top_p`, and `timeout_seconds`, plus optional
|
||||
`backend_id`, `service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`.
|
||||
`service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`.
|
||||
`metadata.usage` always includes `prompt_tokens`, `completion_tokens`,
|
||||
`total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
|
||||
cache usage is reported as zero.
|
||||
@@ -132,10 +132,11 @@ When Promptkit resolves a direct or definition-rendered session ID,
|
||||
`metadata.session_id` contains that effective result value. It is omitted when
|
||||
no effective session ID exists.
|
||||
|
||||
`metadata.selected_backend_id` and `metadata.model_params.backend_id` report
|
||||
the corresponding Promptkit result fields independently when present. Both are
|
||||
omitted for an endpoint-only profile; Scriptorium does not infer backend
|
||||
identity from an endpoint.
|
||||
`metadata.selected_backend_id` is omitted for an endpoint-only profile;
|
||||
Scriptorium does not infer backend identity from an endpoint. The redundant
|
||||
`prompt_version`, `model_name`, `endpoint`, `validation_mode`,
|
||||
`validation_status`, `repair_attempts_used`, and `model_params.backend_id`
|
||||
metadata members are not returned: use `model_params` and `validation`.
|
||||
|
||||
A validation failure has `validation.status: "failed"`, `is_valid: false`,
|
||||
and any available diagnostic errors, while still returning the artifact and
|
||||
@@ -150,7 +151,7 @@ call was dispatched; if there is no terminal event, `execution` is omitted.
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `run_id`, `prompt_id`, `prompt_version`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. |
|
||||
| `run_id`, `prompt_id`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. |
|
||||
| `outcome` | `success`, `invalid_output`, `error`, or `other` for an unrecognized upstream value. |
|
||||
| `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. |
|
||||
| `status_code` | Provider status, omitted when unavailable. |
|
||||
@@ -201,7 +202,7 @@ exceed it, the response is the compact `413 response_too_large` error without
|
||||
| `400` | `prompt_render_failed` | Prompt template rendering failed. |
|
||||
| `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. |
|
||||
| `404` | `not_found` | Route does not exist. |
|
||||
| `404` | `prompt_not_found` | Prompt ID or version does not exist. |
|
||||
| `404` | `prompt_not_found` | Prompt ID does not exist. |
|
||||
| `404` | `profile_not_found` | Profile ID does not exist. |
|
||||
| `405` | `method_not_allowed` | The route does not accept the method. |
|
||||
| `408` | `request_canceled` | The caller context was canceled during a failed run. |
|
||||
@@ -212,13 +213,20 @@ exceed it, the response is the compact `413 response_too_large` error without
|
||||
| `500` | `internal_error` | Unclassified server failure. |
|
||||
| `502` | `llm_failed` | Outbound model request failed. |
|
||||
| `503` | `capacity_exceeded` | The selected model backend has no admission capacity. No retry timing is supplied. |
|
||||
| `504` | `deadline_exceeded` | The execution context's deadline expired during a failed run. |
|
||||
| `504` | `deadline_exceeded` | PromptKit reports an operation timeout, or the parent deadline expired and the failed run wraps that deadline. |
|
||||
|
||||
These context outcomes require the execution context to have ended. A provider
|
||||
attempt timeout while it remains live retains `502 llm_failed`. A successful
|
||||
An operation timeout is checked before parent cancellation; a failed run
|
||||
wrapping cancellation returns `408` when the parent is canceled. A provider
|
||||
attempt timeout while the parent remains live retains `502 llm_failed`. A successful
|
||||
run remains successful even if cancellation races with response formatting;
|
||||
delivery after a client disconnect cannot be guaranteed.
|
||||
|
||||
With the selected PromptKit release and Go 1.27.4, an operation budget that
|
||||
expires during an in-flight built-in HTTP request can currently surface as
|
||||
`502 llm_failed` instead of the intended `504`: the transport may return the
|
||||
operation's cancellation cause without the typed timeout. Retry and capacity
|
||||
waits are attributed correctly. Treat this as a known upstream limitation.
|
||||
|
||||
## Retry And Idempotency
|
||||
|
||||
Scriptorium provides no idempotency keys, pagination, caching headers, or rate
|
||||
|
||||
Reference in New Issue
Block a user