109 lines
3.7 KiB
Markdown
109 lines
3.7 KiB
Markdown
# OpenAI-Compatible Chat Integration
|
|
|
|
This is the outbound wire contract for Scriptorium's OpenAI-compatible
|
|
chat-completions client.
|
|
|
|
## Endpoint And Method
|
|
|
|
Scriptorium uses the request endpoint override when present; otherwise it uses
|
|
the configured client base URL. It removes a trailing slash and sends
|
|
`POST /chat/completions`.
|
|
|
|
For example, `http://localhost:8000/v1` becomes
|
|
`http://localhost:8000/v1/chat/completions`.
|
|
|
|
## Request Payload
|
|
|
|
The payload always contains `model` and rendered `messages`. It additionally
|
|
contains these fields when applicable:
|
|
|
|
| Field | Inclusion |
|
|
| --- | --- |
|
|
| `session_id` | Non-empty rendered prompt session ID. |
|
|
| `temperature` | Non-zero effective value or an explicit zero override. |
|
|
| `max_tokens` | Non-zero effective value or an explicit zero override. |
|
|
| `top_p` | Non-zero effective value or an explicit zero override. |
|
|
| `service_tier` | Any non-empty configured value. |
|
|
| `reasoning_effort` | Any non-empty configured value. |
|
|
| `response_format` | Structured output is requested. |
|
|
| provider-specific fields | Flattened from `extra_params`. |
|
|
|
|
`service_tier` and `reasoning_effort` are forwarded without a provider value
|
|
catalog; the selected backend decides which values it supports.
|
|
|
|
`extra_params` are top-level JSON fields, not a nested object. Keys cannot be
|
|
empty or collide with `model`, `session_id`, `messages`, `temperature`,
|
|
`max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, or
|
|
`response_format`. Values must be JSON-serializable.
|
|
|
|
A rendered `session_id` is sent as a top-level JSON field, not as a header.
|
|
Empty values are omitted. The maximum length is 256 Unicode code points.
|
|
|
|
Messages without cache control use string `content`. A message with cache
|
|
control uses one text block:
|
|
|
|
```json
|
|
{
|
|
"role": "system",
|
|
"content": [{
|
|
"type": "text",
|
|
"text": "rendered text",
|
|
"cache_control": {"type": "ephemeral", "ttl": "1h"}
|
|
}]
|
|
}
|
|
```
|
|
|
|
When the prompt omits cache-control `ttl`, the payload omits `ttl`.
|
|
Structured JSON Schema output is sent as:
|
|
|
|
```json
|
|
{
|
|
"response_format": {
|
|
"type": "json_schema",
|
|
"json_schema": {
|
|
"name": "schema name",
|
|
"strict": true,
|
|
"schema": {"type": "object"}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Authentication And Timeout
|
|
|
|
When a direct request API key is present, Scriptorium sends
|
|
`Authorization: Bearer <key>` and does not read `api_key_env`. Otherwise, it
|
|
resolves the configured non-empty `api_key_env` at request time and sends the
|
|
same header. If neither mechanism supplies a key, it sends no
|
|
`Authorization` header.
|
|
|
|
The configured client timeout applies by default. A positive effective
|
|
`timeout_seconds` replaces it. An explicit request override of zero disables
|
|
the HTTP-client timeout; negative values are rejected before a request is sent.
|
|
|
|
## Response Subset And Failures
|
|
|
|
A successful provider response must supply non-empty
|
|
`choices[0].message.content`. Scriptorium reads these optional or required
|
|
usage fields when present:
|
|
|
|
- `usage.prompt_tokens`
|
|
- `usage.completion_tokens`
|
|
- `usage.total_tokens`
|
|
- `usage.prompt_tokens_details.cached_tokens`
|
|
- `usage.cache_write_tokens`
|
|
|
|
Missing cache usage is reported as zero. Invalid JSON, an empty choices array,
|
|
or empty first-choice content is a malformed provider response. Network and
|
|
request-construction failures, non-2xx responses, and malformed responses fail
|
|
the outbound call. Provider response bodies are not exposed by this client.
|
|
|
|
The client does not implement built-in retries, tool calls, top-level
|
|
`cache_control`, or multi-request payload modes.
|
|
|
|
## Related References
|
|
|
|
Prompt schema preparation and runner orchestration are described in
|
|
[runner internals](../internal/runner.md). Prompt and profile configuration is
|
|
defined by the [configuration reference](../config.md).
|