prompt_builder 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81ca025b0770c1b045ba525bc7fb6839a25b2d0b760b06ba85698de84c0a36b7
-  data.tar.gz: e8fc9eded433a202f7b2c6e9c79d0a0f8a9325b156cc884d09e1f7af535679a0
+  metadata.gz: aeeec3cd90a84a7b1daf32891039ca8338176ebf4b682a00e02110673eac2d53
+  data.tar.gz: 4db3f0193cd06736840bb06a16101278a9124fcbd3db131eb05dfc7965cdf5b8
 SHA512:
-  metadata.gz: e5eab3ec44e9c2a958b60d6c8c24dd740c8586eef8e5d05b6d0ab67807bc5526c3946b8ddd50439d60a860fdcc96e7372d637c552d15938383ef36ecfa173486
-  data.tar.gz: b0aaf0e28017996c603101d8fbde94fc4c242ffa42d471caa7cb0bbaad55f812962873237cf839d51755a86d844ec4fe7676516d3ed8c87df322a6bcd33b424c
+  metadata.gz: 99dfc3d20c0b1535939832b58bde93c3aec58527b4fa469698d96d03f0f44b316f6819093f48a128b1498d19ae463728fde048dcecdfa3e30d57b9c9157c11af
+  data.tar.gz: f31a14885a75c8a0306237cd62840e87912336db42104438e96111675d2e9eec5868f96b6e23f21e6cdb74c76edb29ac5a43c59cf4045cb9ea216ba223cda466

data/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.5.0
+
+### Added
+
+- `Response.parse_stream(body, serializer, headers: nil)` parses a complete streamed response body into the same `Response` that the non-streaming endpoint would have produced. Every format is supported: Server-Sent Events for Open Responses, Chat Completions, Messages, and Gemini (`alt=sse`), and AWS event-stream frames for Converse. The stream is first rebuilt into the non-streaming response body, so the existing response parsing applies unchanged. `Serializers::<Format>.collapse_stream(body)` returns that rebuilt hash. `Serializers::<Format>.stream_accumulator` returns an incremental accumulator that takes raw chunks split at any point with `<<` and keeps only reassembly state, not the raw body. In-stream error events raise `ErrorResponseError`. A stream that ends before its terminal event raises the new `IncompleteStreamError` (a subclass of `UnexpectedPayloadError`). An event-stream CRC mismatch raises `ParseError`. A JSON body that is not a stream (e.g. a 4xx error envelope) is passed through so it parses as it would without streaming.
+- `Session#think` can be called with no depth control (`session.think`), leaving whether and how much to reason to the target API's defaults. The Messages serializer maps it to adaptive thinking; other serializers send no depth control. Previously it raised an `ArgumentError`.
+- `Session#think` accepts any `effort` level instead of raising an `ArgumentError` for levels outside `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`, since providers add new levels with new models (e.g. OpenAI's `none`). The level is forwarded to the API, which rejects levels the model doesn't support.
+- `Session#think(false)` accepts an `effort` level, storing `{"type" => "disabled", "effort" => ...}`. The Messages serializer sends it as `output_config.effort` alongside `thinking.type: "disabled"`, since effort also limits token spend without thinking; serializers whose only reasoning control is effort ignore it and keep reasoning off. Previously it raised an `ArgumentError`, which `think(false, budget_tokens:)` still does.
+- The Messages serializer supports `reasoning.type: "between_tools"`, the lowest thinking setting on models that offer it. It was previously dropped silently, which sent the request with thinking left to the model — the opposite of what the caller asked for. It cannot be combined with `budget_tokens` or `display`.
+- The Converse serializer maps `session.reasoning` (including `Session#think`) into `additionalModelRequestFields` for Anthropic and OpenAI models, which read their native reasoning fields from it: the Messages API `thinking` and `output_config.effort` for Anthropic models, the `reasoning` object for OpenAI models, and the flat `reasoning_effort` field for the open-weight gpt-oss models. The model family is detected from the model id, allowing cross-region inference prefixes and ARNs. Values are forwarded without validation, and the fields are deep-merged into the `additional_model_request_fields` extra, whose values win on conflicts; a `thinking` object in the extra replaces the inferred one as a whole.
+
+### Changed
+
+- The Chat Completions serializer sends `stream_options: {"include_usage": true}` when `stream` is true and `stream_options` is not set, since streamed responses otherwise report no token usage. Set `stream_options` to opt out (e.g. `{"include_usage" => false}`).
+- `Session#think(false)` turns reasoning off instead of clearing the reasoning configuration. It stores `{"type" => "disabled"}`, which the serializers map to `thinking.type: "disabled"` (Messages, and Anthropic models on Converse), effort `none` (`reasoning_effort` on Chat Completions and gpt-oss models on Converse, `reasoning.effort` on Open Responses and other OpenAI models on Converse), and `thinkingConfig.thinkingBudget: 0` (Gemini). Converse sends nothing for it on other model families rather than raising. Previously `think(false)` set `reasoning` to `nil`, which sends no reasoning parameter and leaves the API's default in place, so models that reason by default (such as Claude models that run adaptive thinking when `thinking` is omitted) kept reasoning. Set `session.reasoning = nil` to get that behavior. The off values are forwarded without checking the model, so models that can't turn reasoning off, or don't accept the parameter, reject the request.
+- The Converse serializer raises an `UnsupportedFormatError` when a non-empty `session.reasoning` is set for a model other than an Anthropic or OpenAI model, instead of warning and omitting it. Set the model's native reasoning fields through the `additional_model_request_fields` extra instead.
+- The Messages serializer now emits a `thinking` parameter for any reasoning configuration that asks for thinking, where it previously only emitted one for `budget_tokens` or an explicit `reasoning.type`. Omitting `thinking` leaves the thinking mode to the model rather than turning thinking on, so `think(effort:)` produced no thinking on models that don't think by default. `thinking.type` defaults to `enabled` when `budget_tokens` is set, so `think(budget_tokens:)` serializes as before, and to `adaptive` for an `effort` level, `display`, or bare `think`. Adaptive thinking is not inferred from `effort` alongside `temperature`, a `top_p` below 0.95, or a forced `tool_choice`, so those sessions still send the effort on its own. Configurations without thinking keys (e.g. only another provider's `summary`) still emit no `thinking`.
+- The Messages serializer forwards any `reasoning.type` to `thinking.type` instead of silently omitting the `thinking` parameter for types outside a fixed list, for the same reason. Which types a model accepts varies by model and changes often, so the API is left to reject types the model doesn't support.
+- The Messages and Gemini serializers forward every `reasoning.effort` level to the API as is (Gemini upcases it) instead of dropping levels outside a fixed list. Which levels a model accepts varies by model and changes often, so the API is left to reject levels the model doesn't support. Previously, levels such as `minimal` on Messages or `xhigh` and `max` on Gemini were dropped silently, leaving the depth at the model's default.
+- The Gemini serializer raises when `reasoning.budget_tokens` and `reasoning.effort` are both set, since the Gemini API rejects `thinkingBudget` and `thinkingLevel` in the same request.
+
+### Removed
+
+- `PromptBuilder::Serializers::Converse::Request.reset_reasoning_warning!`, since the Converse serializer no longer warns about reasoning.
+
+### Fixed
+
+- The Converse serializer replays `Reasoning` items as `reasoningContent` blocks instead of dropping them, so tool loops with thinking enabled work on Anthropic models, which reject a `toolUse` turn without its signed reasoning. Signed `thinking` blocks are sent as `reasoningText` with their `signature` and `redacted_thinking` blocks as `redactedContent`; unsigned reasoning and summaries are still dropped.
+- The Open Responses serializer no longer forwards the `budget_tokens`, `type`, and `display` reasoning keys, which are not part of the Open Responses schema and are rejected by the API. `think(budget_tokens:)` previously produced a payload the API rejects.
+
 ## 0.4.0
 
 ### Added

data/README.md

@@ -203,6 +203,46 @@ response.text        # => "Authentication failed."
 response.completed?  # => true
 ```
 
+### Parsing Streamed Responses
+
+Streaming (`stream: true`, or a streaming endpoint) keeps bytes flowing during long generations. If you only need the final response, `Response.parse_stream` turns a complete streamed body into the same `Response` that the non-streaming endpoint would have produced. It first rebuilds the non-streaming response body from the stream, then parses it with `Response.parse`, so content, tool calls, reasoning, usage, and stop reasons come out exactly as they do for a non-streamed request:
+
+```ruby
+session.stream = true
+# ... send the request and read the whole streamed body ...
+response = PromptBuilder::Response.parse_stream(response_body, :messages)
+```
+
+The body is the raw stream: Server-Sent Events text for Open Responses, Chat Completions, Messages, and Gemini (`streamGenerateContent?alt=sse`), or AWS event-stream bytes for Converse (`ConverseStream`). Gemini and Converse choose streaming by endpoint rather than a request body field. Pass `headers:` the same way you would to `Response.parse`, for example to get the Converse response id from the `x-amzn-requestid` header.
+
+To reassemble the stream as it arrives without keeping the raw body, feed chunks to an accumulator. Chunks can split the stream anywhere, including in the middle of an event, a UTF-8 character, or a binary frame. The accumulator keeps only what it needs to rebuild the response:
+
+```ruby
+accumulator = PromptBuilder::Serializers::Messages.stream_accumulator
+http.request(request) do |http_response|
+  http_response.read_body { |chunk| accumulator << chunk }
+end
+response = PromptBuilder::Response.parse(accumulator.result, :messages)
+```
+
+`Serializers::<Format>.collapse_stream(body)` returns the rebuilt response hash directly. The body can be a String or an enumerable of chunks.
+
+How each format is rebuilt:
+
+- **Open Responses**: the full response object is taken from the terminal `response.completed`, `response.incomplete`, or `response.failed` event.
+- **Chat Completions**: `choices[].delta` objects are merged by choice index, and `tool_calls` fragments by tool call index (`function.arguments` is concatenated). Usage comes from the final chunk, which the API only sends when `stream_options.include_usage` is set. The Chat Completions serializer sets it by default when `stream` is true (see [Session Fields](#session-fields)).
+- **Messages**: content blocks are rebuilt by index from the text, citation, thinking, signature, and tool input deltas. `message_delta` supplies the stop reason, and its cumulative usage is merged into the `message_start` usage.
+- **Gemini**: candidate parts from each chunk are concatenated. A text part that starts a chunk continues the text part that ended the previous chunk if both are the same kind (thought or not), keeping the `thoughtSignature`. Parts within one chunk stay separate. A part that carries only a `thoughtSignature` is attached to the text part before it. The `logprobsResult` token lists are concatenated, and `logProbabilitySum` is recomputed from the chosen tokens. `finishReason`, `usageMetadata`, and other fields come from the last chunk that has them. A JSON array body (`streamGenerateContent` without `alt=sse`) is also accepted, but it is buffered whole.
+- **Converse**: event-stream frames are decoded with both CRC32 checksums verified, then content blocks are rebuilt from the `contentBlockStart` and `contentBlockDelta` events (text, tool use input, reasoning text, signatures, and redacted reasoning). `stopReason` comes from `messageStop`, and `usage` and `metrics` come from `metadata`.
+
+Errors:
+
+- An error event sent mid-stream (with HTTP 200) raises a `PromptBuilder::ErrorResponseError` that includes the error the API reported. Examples are a Messages `error` event such as `overloaded_error`, an Open Responses `error` event, an `error` chunk from Chat Completions or Gemini, and a Converse `exception` frame such as `throttlingException`.
+- A stream that ends before the format's terminal event raises a `PromptBuilder::IncompleteStreamError`, a subclass of `UnexpectedPayloadError`, so a truncated stream is never treated as a complete response. The terminal events are Open Responses `response.completed`/`incomplete`/`failed`, Chat Completions `data: [DONE]`, Messages `message_stop`, a `finishReason` on every Gemini candidate (or a `promptFeedback.blockReason`), and Converse `messageStop`.
+- A malformed stream, such as an event-stream checksum mismatch or invalid JSON in an event, raises a `PromptBuilder::ParseError`.
+- A body that is a JSON object or array, such as an error envelope returned with a 4xx status, is not a stream. It is passed through unchanged, so `Response.parse_stream` raises the same `ErrorResponseError` that `Response.parse` would.
+- Unknown event types are ignored, so new event types the providers add don't break parsing.
+
 ### Structured Output
 
 Use `json_output` to request JSON Schema structured output and `parsed_json` to read it back:
@@ -229,16 +269,22 @@ data = response.parsed_json!   # raises PromptBuilder::ParseError (including the
 Use `think` to configure reasoning portably; each serializer maps it to its native parameter:
 
 ```ruby
+session.think                        # API defaults (adaptive thinking on Messages)
 session.think(effort: :medium)       # portable across serializers
 session.think(budget_tokens: 8_000)  # explicit token budget where supported
-session.think(false)                 # clear the reasoning configuration
+session.think(false)                 # turn reasoning off
+session.think(false, effort: :low)   # off, with an effort level for Messages
+session.reasoning = nil              # no reasoning parameter; the API default applies
 ```
 
-- `effort:` (one of `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) maps to `output_config.effort` (Messages), `reasoning_effort` (Chat Completions), `thinkingConfig.thinkingLevel` (Gemini), and `reasoning.effort` (Open Responses). Levels a target API doesn't accept are omitted.
-- `budget_tokens:` maps to `thinking.budget_tokens` (Messages) and `thinkingConfig.thinkingBudget` (Gemini); effort-based APIs ignore it. The Messages serializer raises an `UnsupportedFormatError` at `request_payload` time when `max_output_tokens` is not greater than the budget, since the Anthropic API requires `max_tokens > budget_tokens`.
-- The Converse API has no reasoning parameter; the serializer warns once per process and omits the configuration.
+- `effort:` (any level, such as `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; `think` doesn't restrict it, since providers add new levels with new models) maps to `output_config.effort` (Messages), `reasoning_effort` (Chat Completions), `thinkingConfig.thinkingLevel` (Gemini), and `reasoning.effort` (Open Responses). Every serializer forwards the level as is (Gemini upcases it) without checking it against the model. Which levels a model accepts varies and changes often, so the target API is left to reject levels the model doesn't support.
+- `budget_tokens:` maps to `thinking.budget_tokens` (Messages) and `thinkingConfig.thinkingBudget` (Gemini); effort-based APIs ignore it (Open Responses omits it from `reasoning`, along with the Anthropic-only `type` and `display` keys). The Gemini serializer raises an `UnsupportedFormatError` when `budget_tokens` and `effort` would both be sent, since the Gemini API rejects `thinkingBudget` and `thinkingLevel` together. A fixed thinking budget is only accepted by some Anthropic models — `effort:` is the portable control. The Messages serializer raises an `UnsupportedFormatError` at `request_payload` time when `max_output_tokens` is not greater than the budget, since the Anthropic API requires `max_tokens > budget_tokens`.
+- Calling `think` with no depth control leaves both whether and how much to reason to the target API's defaults. Only the Messages serializer has a switch for it, which it maps to adaptive thinking (`thinking.type: "adaptive"`); Chat Completions and Gemini send no reasoning parameter and Open Responses sends an empty `reasoning` object, so models that don't reason by default won't reason.
+- `think(false)` turns reasoning off by storing `{"type" => "disabled"}`, which each serializer maps to its API's off switch: `thinking.type: "disabled"` (Messages), `reasoning_effort: "none"` (Chat Completions), `reasoning.effort: "none"` (Open Responses), and `thinkingConfig.thinkingBudget: 0` (Gemini). As with effort levels, the value is forwarded without checking the model, and models that can't turn reasoning off (or don't accept the parameter at all) reject it. This is different from `session.reasoning = nil`, which sends no reasoning parameter and leaves the API's default in place, so models that reason by default (such as Claude models that run adaptive thinking when `thinking` is omitted, or OpenAI models whose default effort isn't `none`) keep reasoning.
+- `think(false, effort:)` stores `{"type" => "disabled", "effort" => ...}`. On the Messages API, effort also limits overall token spend without thinking, so the serializer sends it as `output_config.effort` next to `thinking.type: "disabled"`. Chat Completions, Open Responses, and Gemini have no effort control separate from reasoning, so they ignore the effort and send their off value, keeping reasoning off. `think(false)` still raises an `ArgumentError` with `budget_tokens:`.
+- The Converse API has no reasoning parameter of its own, so the serializer sends the model family's native fields in `additionalModelRequestFields`: the Messages API `thinking` and `output_config.effort` fields for Anthropic models, the Responses API `reasoning` object (e.g. `reasoning.effort`) for OpenAI models, and the flat `reasoning_effort` field for OpenAI gpt-oss models. `think(false)` maps to `thinking.type: "disabled"` for Anthropic models and effort `none` for OpenAI models. Any other model raises an `UnsupportedFormatError` when `reasoning` holds a depth control or other setting (a bare `think` or `think(false)` sends nothing); pass that model's native fields through the `additional_model_request_fields` extra instead. See note ¹⁵.
 
-Direct `session.reasoning = {...}` assignment keeps working for provider-specific keys (e.g. Anthropic's `display`, Gemini's `summary`).
+Direct `session.reasoning = {...}` assignment keeps working for provider-specific keys (e.g. Anthropic's `type` and `display`, Gemini's `summary`).
 
 ### Agentic Tool Loops
 
@@ -639,12 +685,12 @@ The following table shows which session configuration fields are supported by ea
 | `presence_penalty` | ✅ | ❌ | ✅ → `generationConfig.presencePenalty` | ❌ |
 | `prompt_cache_key` | ✅ | ❌ | ❌ | ❌ |
 | `prompt_cache_retention` | ✅ | ❌ | ❌ | ❌ |
-| `reasoning` | `effort` key only | `budget_tokens`/`display`/`effort`/`type` only | `budget_tokens`/`effort`/`summary: "auto"` only | ❌ |
+| `reasoning` | `effort` key only | `budget_tokens`/`display`/`effort`/`type` only¹⁴ | `budget_tokens`/`effort`/`summary: "auto"` only | Anthropic and OpenAI models only → `additionalModelRequestFields`¹⁵ |
 | `safety_identifier` | ✅ | ✅ → `metadata.user_id` | ❌ | ❌ |
 | `service_tier` | ✅ | `auto`/`standard_only` only | `unspecified`/`standard`/`flex`/`priority` only | ✅ → `serviceTier.type` |
 | `store` | ✅ | ❌ | ✅ | ❌ |
-| `stream` | ✅ | ✅ | endpoint-selected⁸ | ❌ |
-| `stream_options` | `include_usage`/`include_obfuscation` only | ❌ | ❌ | ❌ |
+| `stream` | ✅ | ✅ | endpoint-selected⁸ | endpoint-selected⁸ |
+| `stream_options` | `include_usage`/`include_obfuscation` only¹⁶ | ❌ | ❌ | ❌ |
 | `text` | `format`/`verbosity` only | `format.type=json_schema` only | `format` key only | `format.type == json_schema` only |
 | `top_logprobs` | ✅ | ❌ | ✅ → `responseLogprobs`/`logprobs` | ❌ |
 | `truncation` | ❌ | ❌ | ❌ | ❌ |
@@ -659,24 +705,30 @@ The following table shows which session configuration fields are supported by ea
 | `InputVideo` | ❌ | ❌ | URL required (Google-hosted URI only)⁶ | S3 URI only |
 | `OutputText` | ✅ (annotations dropped on request)¹¹ | ✅ (annotations ↔ citations)¹² | ✅ | ✅ |
 | `RefusalContent` | dropped⁹ | dropped⁹ | dropped⁹ | dropped⁹ |
-| `Reasoning` items | ❌ | ✅³ | ✅⁴ | ❌ |
+| `Reasoning` items | ❌ | ✅³ | ✅⁴ | signed only → `reasoningContent`³ |
 | `Compaction` items | ❌ | ❌ | ❌ | ❌ |
 | `ItemReference` items | ❌ | ❌ | ❌ | ❌ |
 
 ¹ Messages format uses the media type from the data URL for base64 sources; set `InputFile.media_type` to override. `file_id` is mapped to a `file` source for the Anthropic Files API beta — set the appropriate `anthropic-beta: files-api-2025-04-14` header in your HTTP client.
 ² Converse format infers the document type from the filename or URL extension.
-³ Messages format only emits `thinking` blocks that include a cryptographic `signature`; unsigned blocks are silently dropped.
+³ Messages and Converse formats only emit `thinking` blocks that include a cryptographic `signature` (Converse sends them as `reasoningContent.reasoningText`, and `redacted_thinking` as `reasoningContent.redactedContent`); unsigned blocks are silently dropped.
 ⁴ Gemini format passes `thoughtSignature` through transparently on reasoning, text, and function-call parts. `redacted_thinking` blocks are silently skipped.
 ⁵ Anthropic does not support a `detail` field on images; it is silently dropped. `file_id` is mapped to a `file` source (Anthropic Files API beta).
 ⁶ Gemini supports inline base64 data or any URL. For files, set `media_type` or use a recognized `filename`/URL extension.
 ⁷ Chat Completions does not accept `InputImage.file_id` — the `image_file` content type is Assistants API only. Use a URL or base64 `data` instead; a `file_id`-only image is omitted.
-⁸ Gemini selects streaming by endpoint (`:streamGenerateContent`), not a request body field, so `session.stream` is silently ignored when serializing to Gemini.
+⁸ Gemini (`:streamGenerateContent`) and Converse (`ConverseStream`) select streaming by endpoint, not a request body field, so `session.stream` is silently ignored when serializing to them. `Response.parse_stream` parses their streamed responses (see [Parsing Streamed Responses](#parsing-streamed-responses)).
 ⁹ `RefusalContent` blocks are dropped silently by all request serializers so a parsed refusal can sit in session history without breaking subsequent `request_payload` calls. A message left empty after stripping is omitted entirely.
 ¹⁰ Chat Completions sends `InputFile` as a `{"type": "file", "file": {...}}` content block. `file_id` (Files API) and base64 data URL (with optional `filename`/`media_type`) are supported. A URL-only `InputFile` (non-data URL) is omitted because Chat Completions has no remote-URL form for files.
 ¹¹ `OutputText.annotations` (e.g. URL citations from `web_search_options`) are parsed onto the assistant message and round-trip through session history, but are dropped silently on Chat Completions and Converse request serialization since those formats have no request-side equivalent. `OutputText.logprobs` is likewise dropped.
 ¹² Messages text-block `citations` are parsed into `OutputText.annotations` and emitted back as `citations` when serializing Messages history. Annotations from other providers (e.g. a Chat Completions `url_citation`) are silently dropped since they are not valid Anthropic citation shapes. Document/tool-result citation opt-ins are still not modeled.
 ¹³ Converse `requestMetadata` only accepts string key/value pairs. This serializer stringifies scalar metadata values and silently omits nested arrays or objects.
 
+¹⁴ A Messages `reasoning` configuration that asks for thinking (`type`, `budget_tokens`, `display`, an `effort` level, or an empty configuration from a bare `think`) emits a `thinking` parameter, since omitting it leaves the thinking mode to the model rather than turning thinking on. Adaptive thinking is not inferred from `effort` alongside `temperature`, a `top_p` below 0.95, or a forced `tool_choice`; the effort is sent on its own. `reasoning.type` is forwarded as is, including types the serializer doesn't know, and the API rejects types the model doesn't support.
+
+¹⁵ The Converse serializer detects the model family from the model id, allowing a cross-region inference prefix (`us.`, `global.`, ...) and an ARN resource path. Anthropic models (`anthropic.*`) get `thinking` (`type`, `budget_tokens`, `display`) and `output_config.effort`, with `thinking.type` inferred as in the Messages serializer (note ¹⁴) but without its validation. OpenAI models (`openai.*`) get `reasoning` without the Anthropic-only `budget_tokens`, `type`, and `display` keys; a bare `think` or `budget_tokens` alone sends nothing. The open-weight gpt-oss models (`openai.gpt-oss-*`) read only a flat `reasoning_effort` field, so they get `effort` as `reasoning_effort` and nothing else. A disabled configuration (`think(false)`) sends effort `none` to both OpenAI families in place of any effort; gpt-oss models can't turn reasoning off and reject it. Models in other families are assumed not to reason without their native fields, so a disabled configuration sends nothing for them. Application inference profile ARNs don't name a model family and raise like other unsupported models. Values are forwarded without validation, and the fields are deep-merged into the `additional_model_request_fields` extra, whose values win on conflicts. A `thinking` object in the extra replaces the inferred one as a whole rather than being merged into it, since which `thinking` keys are valid depends on its `type`.
+
+¹⁶ A streamed Chat Completions response only reports token usage when `stream_options.include_usage` is set, so the serializer sends `stream_options: {"include_usage": true}` whenever `stream` is true and `stream_options` is not set. To opt out, set `stream_options` yourself, for example `{"include_usage" => false}`.
+
 ### Features Not Accessible Through Open Responses
 
 These target API features are not available through the Open Responses canonical format because Open Responses does not expose the equivalent parameters:
@@ -753,6 +805,7 @@ Request-side mappings worth calling out:
 | `text.format` | `response_format` (the OR-canonical flat `json_schema` is reshaped into `{"type": "json_schema", "json_schema": {...}}`) |
 | `text.verbosity` | top-level `verbosity` |
 | `reasoning.effort` | `reasoning_effort` |
+| `reasoning.type: "disabled"` | `reasoning_effort: "none"` (replaces any effort) |
 | `tool_choice: {"type": "function", "name": ...}` | `{"type": "function", "function": {"name": ...}}` |
 | `InputFile.file_id` | `{"type": "file", "file": {"file_id": ...}}` |
 | `InputFile` with data URL (+ optional `filename`/`media_type`) | `{"type": "file", "file": {"filename": ..., "file_data": "data:<media_type>;base64,..."}}` |
@@ -763,7 +816,7 @@ Chat Completions request features with no canonical Open Responses field are ava
 Response-side behavior and limitations:
 
 - Responses with multiple choices (`n > 1`) parse only the first choice; additional candidates are dropped.
-- Streaming chunks (`chat.completion.chunk` deltas) raise `UnsupportedFormatError` — this gem expects a fully assembled non-streaming response body.
+- `Response.parse` raises `UnsupportedFormatError` for a single streaming chunk (a `chat.completion.chunk` delta). Use `Response.parse_stream` to parse a whole streamed body (see [Parsing Streamed Responses](#parsing-streamed-responses)).
 - `system_fingerprint` is exposed on `response.provider_data`.
 - `service_tier` is populated when present on the response.
 - `message.annotations` (URL citations from `web_search_options`) are copied onto `OutputText.annotations`.
@@ -774,6 +827,8 @@ Response-side behavior and limitations:
 
 The Messages API requires the `max_tokens` parameter, which is populated from `session.max_output_tokens`. Serializing a session without `max_output_tokens` set raises a `PromptBuilder::UnsupportedFormatError`.
 
+When thinking is on (any `thinking.type` other than `disabled`), the serializer raises an `UnsupportedFormatError` if `temperature` is set, `top_p` is below `0.95`, `tool_choice` forces tool use, or `max_output_tokens` is not greater than `reasoning.budget_tokens`. Beyond that, which values the Messages API accepts for `temperature`, `top_p`, `reasoning.type`, and forced `tool_choice` depends on the model, and the serialized payload carries no model capability information, so these are forwarded without further validation.
+
 A few features map between the canonical Open Responses format and the Messages API in non-obvious ways:
 
 | Canonical field / value | Messages mapping |
@@ -783,9 +838,10 @@ A few features map between the canonical Open Responses format and the Messages
 | `FunctionCallOutput.status` ∈ `incomplete`, `failed`, `error` | `tool_result.is_error: true` |
 | `safety_identifier` | `metadata.user_id` |
 | `parallel_tool_calls: false` | `tool_choice.disable_parallel_tool_use: true` (forces `tool_choice.type` to `auto` if unset) |
+| `reasoning` asking for thinking | `thinking` (`thinking.type` defaults to `adaptive`; see note ¹⁴) |
 | `reasoning.budget_tokens` | `thinking.budget_tokens` (with `thinking.type` defaulted to `enabled`) |
-| `reasoning.effort` | `output_config.effort` (`low`, `medium`, `high`, `xhigh`, or `max`) |
-| `reasoning.type: "adaptive"` | `thinking.type: "adaptive"` |
+| `reasoning.effort` | `output_config.effort` (forwarded as is) |
+| `reasoning.type` | `thinking.type` (forwarded as is, e.g. `adaptive`, `between_tools`, `disabled`, or `enabled`) |
 | `text.format.type: "json_schema"` | `output_config.format` (`type` and `schema` only; `name`, `description`, and `strict` are ignored) |
 | `Tools::Definition#strict` | tool definition `strict: true` |
 | `tool_choice: "required"` | `{"type": "any"}` |
@@ -811,7 +867,9 @@ Request-side mappings worth calling out:
 | `text.format == "text"` | `generationConfig.responseMimeType = "text/plain"` |
 | `text.format == "json_object"` | `generationConfig.responseMimeType = "application/json"` |
 | `text.format == "json_schema"` | `generationConfig.responseMimeType = "application/json"` + `responseSchema` (read from `format.json_schema.schema` or `format.schema`) |
-| `reasoning.budget_tokens` | `generationConfig.thinkingConfig.thinkingBudget` |
+| `reasoning.budget_tokens` | `generationConfig.thinkingConfig.thinkingBudget` (raises alongside a mapped `reasoning.effort`) |
+| `reasoning.type: "disabled"` | `generationConfig.thinkingConfig.thinkingBudget: 0` (replaces any budget or effort) |
+| `reasoning.effort` | `generationConfig.thinkingConfig.thinkingLevel` (upcased and forwarded as is) |
 | `tool_choice: "auto"` / `"none"` / `"required"` | `toolConfig.functionCallingConfig.mode = AUTO` / `NONE` / `ANY` |
 | `tool_choice: {"type": "function", "name": ...}` | `mode = ANY` + `allowedFunctionNames: [name]` |
 | Tool definitions | single `tools[0].functionDeclarations[]` entry |
@@ -838,7 +896,7 @@ Response-side limitations:
 - `finishReason` mappings: `STOP` → `completed`; `MAX_TOKENS` → `incomplete`; `SAFETY`, `RECITATION`, `OTHER`, `BLOCKLIST`, `PROHIBITED_CONTENT`, `SPII`, `MALFORMED_FUNCTION_CALL`, `IMAGE_SAFETY`, `LANGUAGE`, `UNEXPECTED_TOOL_CALL`, `TOO_MANY_TOOL_CALLS`, `MODEL_ARMOR` → `failed`. `FINISH_REASON_UNSPECIFIED` is treated as nil.
 - An empty `candidates` array combined with `promptFeedback.blockReason` is mapped to `failed`.
 - `usageMetadata.cachedContentTokenCount`, `toolUsePromptTokenCount`, `promptTokensDetails`, `cacheTokensDetails`, and `toolUsePromptTokensDetails` populate `response.usage.input_tokens_details`. `thoughtsTokenCount` and `candidatesTokensDetails` populate `response.usage.output_tokens_details`.
-- Response metadata with no canonical Open Responses slot is exposed on `response.provider_data`: `groundingMetadata`, `citationMetadata`, `urlContextMetadata`, `urlRetrievalMetadata`, `safetyRatings`, `groundingAttributions`, `avgLogprobs`, `logprobsResult`, `finishMessage`, candidate `index`, top-level `createTime`, and full `promptFeedback`. Streaming chunks are not parsed — this gem expects a fully assembled non-streaming response body.
+- Response metadata with no canonical Open Responses slot is exposed on `response.provider_data`: `groundingMetadata`, `citationMetadata`, `urlContextMetadata`, `urlRetrievalMetadata`, `safetyRatings`, `groundingAttributions`, `avgLogprobs`, `logprobsResult`, `finishMessage`, candidate `index`, top-level `createTime`, and full `promptFeedback`. Use `Response.parse_stream` to parse a `streamGenerateContent` response (see [Parsing Streamed Responses](#parsing-streamed-responses)).
 
 ### Converse-specific notes
 
@@ -857,6 +915,10 @@ Request-side restrictions worth calling out:
 | `tool_choice: "auto"` | `{"auto": {}}` |
 | `tool_choice: "required"` | `{"any": {}}` |
 | `tool_choice: {"type": "function", "name": ...}` | `{"tool": {"name": ...}}` |
+| `reasoning` (Anthropic models) | `additionalModelRequestFields.thinking` / `additionalModelRequestFields.output_config.effort` |
+| `reasoning` (OpenAI models) | `additionalModelRequestFields.reasoning` |
+| `reasoning` (OpenAI gpt-oss models) | `additionalModelRequestFields.reasoning_effort` (`effort` only) |
+| `reasoning` (other models) | raises `UnsupportedFormatError` (nothing is sent for a bare `think` or `think(false)`) |
 
 Content and message restrictions:
 
@@ -867,7 +929,7 @@ Content and message restrictions:
 - `InputFile.file_id` is silently ignored because Converse does not accept provider file IDs for documents.
 - `InputVideo` requires an `s3://` URI; a non-S3 URL is omitted, and raw bytes (`source.bytes`) cannot be sent because the canonical `InputVideo` content type does not model byte data.
 - `InputImage`, `InputFile`, and `InputVideo` are only supported in user messages; the same content on an assistant message is omitted. `RefusalContent`, `OutputText.annotations`, and `OutputText.logprobs` are also dropped because Converse has no request-side representation for them.
-- `Reasoning` items are silently skipped on the request side, so multi-turn extended-thinking + tool-use loops are not supported through this serializer (the response parser does decode `reasoningContent` blocks back into `Reasoning` items, but they cannot be sent back).
+- `Reasoning` items are replayed as `reasoningContent` blocks on the assistant turn, so multi-turn extended-thinking + tool-use loops work: Anthropic models require the signed reasoning ahead of a `toolUse` block when thinking is on. Only signed `thinking` blocks and `redacted_thinking` blocks are sent, because Bedrock validates replayed reasoning against its signature; unsigned reasoning and summaries are dropped. Signatures are tied to the model that produced them, so switching a session to a model from another family can make the request fail on the replayed reasoning; start a fresh session or remove the `Reasoning` items when you switch.
 - `Compaction` and `ItemReference` items are silently skipped.
 - `FunctionCall.arguments` must parse to a JSON object; non-object JSON values raise (Bedrock's `toolUse.input` requires an object).
 - `FunctionCallOutput.output` content supports `InputText`/`OutputText`, `InputImage`, `InputFile`, and `InputVideo`, mapping to Converse `text`, `image`, `document`, and `video` tool result blocks. Converse also supports `json` and `searchResult` tool result blocks, but this gem has no canonical content types for them, so unsupported content is omitted. `FunctionCallOutput.status` is mapped: `completed` → `success`, `failed`/`incomplete` → `error`, anything else passes through or is dropped.

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.5.0

data/lib/prompt_builder/errors.rb

@@ -24,6 +24,14 @@ module PromptBuilder
   # error envelope). The message contains the error reported by the API.
   class ErrorResponseError < UnexpectedPayloadError; end
 
-  # Raised by Response#parsed_json! when the response text is not valid JSON.
+  # Raised when a streamed response ends before the format's terminal event
+  # (e.g. a dropped connection), so a truncated stream is never treated as a
+  # complete response.
+  class IncompleteStreamError < UnexpectedPayloadError; end
+
+  # Raised when text or binary data cannot be decoded: by Response#parsed_json!
+  # when the response text is not valid JSON, and by the stream decoders when a
+  # streamed response body is malformed (e.g. an AWS event-stream checksum
+  # mismatch or an unparseable event payload).
   class ParseError < Error; end
 end

data/lib/prompt_builder/response.rb

@@ -172,6 +172,30 @@ module PromptBuilder
         serializer.parse_response(hash, headers: headers)
       end
 
+      # Parse a complete streamed response body (from a request sent with
+      # +stream: true+ or a streaming endpoint) into a Response. The stream is
+      # reassembled into the body the non-streaming endpoint would have
+      # returned and then parsed with #parse, so the result is the same as for
+      # a non-streamed request.
+      #
+      # @param body [String, #each] the raw streamed body (SSE text, or AWS
+      #   event-stream bytes for Converse), or an enumerable of body chunks
+      # @param serializer_class [Class, Symbol] a serializer class or a symbol
+      #   shorthand (see #parse)
+      # @param headers [Hash, #each, nil] the HTTP response headers (see #parse)
+      # @return [Response]
+      # @raise [IncompleteStreamError] if the stream ended before the format's
+      #   terminal event
+      # @raise [ErrorResponseError] if the stream contains an error event or
+      #   the body is an API error envelope
+      # @raise [ParseError] if the stream is malformed
+      # @example
+      #   response = PromptBuilder::Response.parse_stream(sse_body, :messages)
+      def parse_stream(body, serializer_class, headers: nil)
+        serializer = Serializers.resolve(serializer_class)
+        parse(serializer.collapse_stream(body), serializer, headers: headers)
+      end
+
       # Deserialize a Response from a Hash.
       #
       # @param hash [Hash] a Hash with string keys from the API response

data/lib/prompt_builder/serializers/base.rb

@@ -32,6 +32,42 @@ module PromptBuilder
           deserialize_response(hash)
         end
 
+        # Create an incremental accumulator that reassembles a streamed
+        # response body in this format into the Hash the non-streaming
+        # endpoint would have returned. Feed it raw body chunks with +<<+,
+        # then call +result+.
+        #
+        # @return [Streaming::Accumulator] a new accumulator
+        # @raise [UnsupportedFormatError] if the format has no stream accumulator
+        def stream_accumulator
+          unless const_defined?(:StreamAccumulator, false)
+            raise UnsupportedFormatError, "#{name} does not support streamed responses"
+          end
+
+          const_get(:StreamAccumulator, false).new
+        end
+
+        # Reassemble a complete streamed response body into the Hash the
+        # non-streaming endpoint would have returned, ready for
+        # +parse_response+.
+        #
+        # @param body [String, #each] the raw streamed body (SSE text, or AWS
+        #   event-stream bytes for Converse), or an enumerable of body chunks
+        # @return [Hash] the non-streaming equivalent response
+        # @raise [IncompleteStreamError] if the stream ended before the
+        #   format's terminal event
+        # @raise [ErrorResponseError] if the stream contains an error event
+        # @raise [ParseError] if the stream is malformed
+        def collapse_stream(body)
+          accumulator = stream_accumulator
+          if body.is_a?(String)
+            accumulator << body
+          else
+            body.each { |chunk| accumulator << chunk }
+          end
+          accumulator.result
+        end
+
         private
 
         def serialize_request(_session)
@@ -68,6 +104,16 @@ module PromptBuilder
           nil
         end
 
+        # Whether a reasoning configuration turns reasoning off, as stored by
+        # Session#think(false). Distinct from a nil configuration, which leaves
+        # reasoning to the API's default.
+        #
+        # @param reasoning [Hash, nil] the session's reasoning configuration
+        # @return [Boolean]
+        def reasoning_disabled?(reasoning)
+          reasoning.is_a?(Hash) && reasoning["type"] == "disabled"
+        end
+
         # Ensure a response payload is a Hash containing the key that identifies
         # it as a well-formed response for this format. Raised before parsing so
         # malformed bodies (e.g. provider error envelopes) fail loudly with the

data/lib/prompt_builder/serializers/chat_completion/request.rb

@@ -22,9 +22,15 @@ module PromptBuilder
       # Partially supported session fields (unsupported keys are omitted):
       # - +text+ — only +format+ (mapped to +response_format+) and +verbosity+
       #   (mapped to top-level +verbosity+) are supported
-      # - +reasoning+ — only the +effort+ key is mapped to +reasoning_effort+
+      # - +reasoning+ — only the +effort+ key is mapped to +reasoning_effort+;
+      #   +type: "disabled"+ (Session#think(false)) is sent as
+      #   +reasoning_effort: "none"+ in place of any effort, and models that
+      #   cannot turn reasoning off reject it
       # - +stream_options+ — only +include_usage+ and +include_obfuscation+ are
-      #   supported, and only when +stream+ is set (otherwise it is omitted)
+      #   supported, and only when +stream+ is set (otherwise it is omitted).
+      #   When +stream+ is set and +stream_options+ is not, +include_usage: true+
+      #   is sent so the streamed response reports token usage like a
+      #   non-streamed one
       #
       # Input content restrictions:
       # - +instructions+ is serialized as a system message inserted after the
@@ -97,9 +103,14 @@ module PromptBuilder
             h["prompt_cache_retention"] = session.prompt_cache_retention if session.prompt_cache_retention
             h["stream"] = session.stream unless session.stream.nil?
             # stream_options is only valid alongside stream; otherwise it is omitted.
-            # Unsupported stream_options keys are dropped.
-            if session.stream_options && session.stream
-              stream_options = normalize_hash(session.stream_options).slice(*SUPPORTED_STREAM_OPTION_KEYS)
+            # Unsupported stream_options keys are dropped. Streamed responses only
+            # report usage with include_usage, so it is requested by default.
+            if session.stream
+              stream_options = if session.stream_options
+                normalize_hash(session.stream_options).slice(*SUPPORTED_STREAM_OPTION_KEYS)
+              else
+                {"include_usage" => true}
+              end
               h["stream_options"] = stream_options unless stream_options.empty?
             end
 
@@ -110,7 +121,10 @@ module PromptBuilder
             end
 
             if session.reasoning
-              effort = normalize_hash(session.reasoning)["effort"]
+              reasoning = normalize_hash(session.reasoning)
+              # Effort is the only reasoning control, so turning reasoning off
+              # overrides any effort set alongside it.
+              effort = reasoning_disabled?(reasoning) ? "none" : reasoning["effort"]
               h["reasoning_effort"] = effort if effort
             end
 

data/lib/prompt_builder/serializers/chat_completion/response.rb

@@ -10,7 +10,9 @@ module PromptBuilder
       # responses, legacy +function_call+ responses, non-function tool calls,
       # and unknown content block types are silently skipped. Streaming chunks
       # (+chat.completion.chunk+ deltas) raise +UnsupportedFormatError+ — this
-      # parser expects a fully assembled non-streaming response body.
+      # parser expects a fully assembled non-streaming response body; use
+      # ChatCompletion::StreamAccumulator (or Response.parse_stream) to
+      # reassemble a streamed body first.
       # Top-level +system_fingerprint+ is exposed through +extra+.
       class Response < Base
         class << self

data/lib/prompt_builder/serializers/chat_completion/stream_accumulator.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Serializers
+    class ChatCompletion < Base
+      # Reassembles an OpenAI Chat Completions SSE stream of
+      # +chat.completion.chunk+ objects into the +chat.completion+ object the
+      # non-streaming endpoint would have returned.
+      #
+      # Choice deltas are merged by +choices[].index+ into a +message+:
+      # +content+, +refusal+, and other string fields are concatenated, and
+      # +tool_calls+ fragments are merged by their own +index+, with +id+,
+      # +type+, and +function.name+ taken as they appear and
+      # +function.arguments+ concatenated. +finish_reason+ comes from the chunk
+      # that carries it, and +logprobs+ arrays are concatenated. Usage arrives
+      # in a final chunk with empty +choices+, and only when the request set
+      # +stream_options.include_usage+.
+      #
+      # The stream must end with +data: [DONE]+; a chunk with an +error+ raises
+      # an ErrorResponseError.
+      class StreamAccumulator < Streaming::Accumulator
+        DONE = "[DONE]"
+        private_constant :DONE
+
+        def initialize
+          super
+          @response = {}
+          @choices = {}
+          @done = false
+        end
+
+        private
+
+        def handle_event(event)
+          if event.data.strip == DONE
+            @done = true
+            return
+          end
+
+          chunk = parse_json(event.data)
+          return unless chunk.is_a?(Hash)
+
+          if chunk["error"]
+            error = chunk["error"]
+            message = error.is_a?(Hash) ? [error["code"] || error["type"], error["message"]].compact.join(": ") : error.to_s
+            raise_error_event!(message)
+          end
+
+          chunk.each do |key, value|
+            next if value.nil?
+
+            if key == "choices"
+              value.each_with_index { |choice, position| merge_choice(choice, position) if choice.is_a?(Hash) }
+            else
+              @response[key] = value
+            end
+          end
+        end
+
+        def merge_choice(choice, position)
+          index = choice["index"] || position
+          merged = @choices[index] ||= {"index" => index, "message" => {"role" => "assistant", "content" => nil}, "tool_calls" => {}}
+
+          merge_delta(merged, choice["delta"]) if choice["delta"].is_a?(Hash)
+          merge_logprobs(merged, choice["logprobs"]) if choice["logprobs"].is_a?(Hash)
+          merged["finish_reason"] = choice["finish_reason"] if choice["finish_reason"]
+        end
+
+        def merge_delta(merged, delta)
+          message = merged["message"]
+          delta.each do |key, value|
+            next if value.nil?
+
+            case key
+            when "role"
+              message["role"] = value
+            when "tool_calls"
+              value.each_with_index { |call, position| merge_tool_call(merged["tool_calls"], call, position) if call.is_a?(Hash) }
+            when "annotations"
+              (message["annotations"] ||= []).concat(value) if value.is_a?(Array)
+            else
+              if value.is_a?(String)
+                message[key] = message[key] ? +message[key] : +""
+                message[key] << value
+              else
+                message[key] = value
+              end
+            end
+          end
+        end
+
+        def merge_tool_call(tool_calls, delta, position)
+          call = tool_calls[delta["index"] || position] ||= {"function" => {}}
+          call["id"] = delta["id"] if delta["id"]
+          call["type"] = delta["type"] if delta["type"]
+
+          function = delta["function"]
+          return unless function.is_a?(Hash)
+
+          call["function"]["name"] = function["name"] if function["name"]
+          if function["arguments"]
+            arguments = call["function"]["arguments"]
+            call["function"]["arguments"] = arguments ? +arguments : +""
+            call["function"]["arguments"] << function["arguments"]
+          end
+        end
+
+        def merge_logprobs(merged, logprobs)
+          target = merged["logprobs"] ||= {}
+          logprobs.each do |key, value|
+            if value.is_a?(Array)
+              (target[key] ||= []).concat(value)
+            elsif !value.nil?
+              target[key] = value
+            end
+          end
+        end
+
+        def build_result
+          incomplete!("Chat Completions stream ended without data: [DONE]") unless @done
+
+          choices = @choices.sort_by { |index, _| index.to_i }.map { |_, choice| build_choice(choice) }
+          @response.merge("object" => "chat.completion", "choices" => choices)
+        end
+
+        def build_choice(choice)
+          message = choice["message"]
+          tool_calls = choice["tool_calls"].sort_by { |index, _| index.to_i }.map do |_, call|
+            {"type" => "function"}.merge(call)
+          end
+          message = message.merge("tool_calls" => tool_calls) unless tool_calls.empty?
+
+          {
+            "index" => choice["index"],
+            "message" => message,
+            "logprobs" => choice["logprobs"],
+            "finish_reason" => choice["finish_reason"]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/prompt_builder/serializers/chat_completion.rb

@@ -7,6 +7,7 @@ module PromptBuilder
     class ChatCompletion < Base
       autoload :Request, File.expand_path("chat_completion/request", __dir__)
       autoload :Response, File.expand_path("chat_completion/response", __dir__)
+      autoload :StreamAccumulator, File.expand_path("chat_completion/stream_accumulator", __dir__)
 
       class << self
         # Export a session to Chat Completions request payload.