prompt_builder 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e762383ea51918fa77b5962f0137775551a37da1c228a37d24364011c8d21f73
-  data.tar.gz: 64e2a4e22feb0a8e0e5752f4807b79452c3cb700dd8b5740500f11cbe0b4217e
+  metadata.gz: a6a857e2a0958425d04263986bca11967fb575af1c1e40ada5bee63556447fe0
+  data.tar.gz: 9840a2750ac27e265aea1e25d9290ee3aecb56cd24889d5903b481891a2925db
 SHA512:
-  metadata.gz: b7eb3a4806f9cd7a24e00652659b7a5d641ae5877187bd714afd0e4eaa86c7a7901eebcfdf11202497d0b98cce03f9a0fec10f1840883f91b4b87be3a9f2c387
-  data.tar.gz: 2b731def4d25b2233b208d3fb3d8867ee17cce9356cb84b3d57d3d3043116af5eb55ca7888de00c329c3637b209bbc70ea11dada040bc5f97f9701c85a0fa8ee
+  metadata.gz: 70fe6418fdd6865e12ec8babb5d5a7542ff31e93b44e0dfb389c1e0853955d5657bbf3482462e1ec091fca8031ac988bfc70222195a8ad2fd50833eb2542c4a1
+  data.tar.gz: bd0d9abb2cbb42d10d70c8f1d15322cc58a4c88c6401f937a45844fbde2dcf8013b183cf19d206b1e4c0e48cf9c0a03fb3ad5b35c17ed083b12d7c73f00224c6

data/CHANGELOG.md

@@ -4,6 +4,51 @@ 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.3.0
+
+### Added
+
+- Response parsers now recognize API error payloads (OpenAI/Gemini `error` envelopes, Anthropic `type: "error"` responses, Bedrock exception bodies) and raise a `PromptBuilder::ErrorResponseError` (a subclass of `UnexpectedPayloadError`) containing the error message reported by the API.
+- `Session.new` accepts a `system:` shorthand that adds a system message, mirroring the existing `input:` shorthand.
+- `Session#clear` resets the conversation — items, `instructions`, and `previous_response_id` — while preserving model configuration and registered tools.
+- `Session#remove_tool` removes a registered tool by name (string or symbol); `Session#clear_tools` removes them all. Both return the removed definitions.
+- `Session#extra=` sets or clears provider-specific extra data after the session has been constructed. Keys are normalized to strings; assigning `nil` clears the data.
+- Message content hashes with a `text` key no longer require a `type` key; the type defaults to `input_text` (or `output_text` on assistant messages).
+- `Items::Message#system?`, `#user?`, and `#assistant?` role predicates.
+- The Converse serializer emits `cachePoint` markers from the `cache_point` extra on tool definitions and `FunctionCallOutput` items, in addition to content blocks.
+- `Session#to_h`/`Session.from_h` now round-trip the response boundary (`response_boundary_index`), and a `response_boundary_index=` setter is available for reconstructing session state.
+- `Session::INITIALIZE_OPTIONS` is now public API: the frozen Array of all keyword options accepted by the constructor, for code that needs to validate or partition an options hash before creating a session.
+
+### Changed
+
+- `Session#extra` always returns a Hash (previously `nil` when unset). The returned Hash is a copy; assign a modified copy back through `Session#extra=` to change it.
+- `Session#to_h` omits `extra` when it is empty.
+- `instructions` is now serialized after system/developer messages instead of before them, matching the Open Responses semantics of `instructions` applying to the current request.
+
+### Fixed
+
+- Serializers silently dropped `Content::Text` content (hashes with `type: "text"`) from messages, system prompts, and tool results; it is now serialized as text everywhere `InputText`/`OutputText` are, including cache markers from content extras. The Messages and Gemini serializers also dropped `OutputText` content from system messages.
+- Tool names are normalized to strings on registration, so registering the same tool by symbol and by string no longer creates duplicate definitions.
+
+## 0.2.0
+
+### Added
+
+- `Session#use_tools` copies tool definitions from a `ToolRegistry` (the global registry by default) onto the session by name, raising a `ToolNotFoundError` for unknown names.
+- `Session#json_output` configures JSON Schema structured output without writing the raw `text.format` wire hash by hand.
+- `Session#think` configures reasoning portably across serializers via `effort:` or `budget_tokens:`; `think(false)` clears the configuration.
+- `Response#parsed_json` parses the response text as JSON (stripping fenced ```json wrappers), returning `nil` when it cannot be parsed; `Response#parsed_json!` raises a `ParseError` including the raw text instead.
+- `Response.from_text` synthesizes a completed assistant text response for canned answers, cached responses, and tests.
+- `PromptBuilder::ParseError` error class.
+
+### Changed
+
+- `Session.new` raises an `ArgumentError` when passed an unsupported keyword option instead of silently ignoring it.
+- The Messages serializer raises an `UnsupportedFormatError` when `session.max_output_tokens` is not set, since the Messages API requires the `max_tokens` parameter.
+- Serializers now raise an `UnsupportedFormatError` for missing fields their target API requires instead of emitting an invalid payload: Chat Completions, Converse, and Open Responses require `session.model`; Chat Completions requires at least one message; Gemini requires a non-empty `contents` array.
+- The Messages serializer raises an `UnsupportedFormatError` when thinking is enabled with a `budget_tokens` that is not less than `max_output_tokens`, matching the Anthropic API requirement that `max_tokens` be greater than the thinking budget.
+- The Converse serializer warns once per process when `session.reasoning` is set instead of silently dropping it (the Converse endpoint has no reasoning parameter).
+
 ## 0.1.2
 
 ### Fixed

data/README.md

@@ -48,15 +48,29 @@ session = PromptBuilder::Session.new(
 session.user("What is the capital of France?")
 ```
 
-You can also pass an `input` shorthand to create a user message in one step:
+You can also pass `system` and `input` shorthands to create a system message and a user message in one step (equivalent to calling `session.system(...)` and `session.user(...)`):
 
 ```ruby
 session = PromptBuilder::Session.new(
   model: "gpt-5.4",
+  system: "You are a helpful assistant.",
   input: "What is the capital of France?"
 )
 ```
 
+Passing an option the constructor doesn't recognize raises an `ArgumentError`. The full list of supported constructor options is available as `PromptBuilder::Session::INITIALIZE_OPTIONS`.
+
+#### `instructions` vs. system and developer messages
+
+Although both can be used to steer the model's behavior, `instructions` and system/developer messages are not interchangeable in the Open Responses API:
+
+- `instructions` is a top-level request parameter, not part of the conversation. It is sent with every request, and in the Open Responses API it applies only to the request it accompanies — it is *not* carried over when chaining responses with `previous_response_id`. That makes it safe to change `session.instructions` at any point in a conversation; the new value simply applies from the next request onward.
+- `session.system(...)` and `session.developer(...)` create messages inside the conversation history (the `input` array). They occupy a position in the transcript like any other message, and once the session is chained with `previous_response_id` they become part of the server-stored history and are not re-sent on subsequent requests.
+
+As a rule of thumb, use `instructions` for standing behavior you may want to adjust from request to request, and use system or developer messages when the directive should be a durable part of the conversation record.
+
+When serializing to the other formats this distinction collapses: `instructions` and any system/developer messages are merged together into the target format's single system field (see [Serializer Compatibility](#serializer-compatibility)).
+
 ### Conversation History
 
 Build up a multi-turn conversation by adding messages:
@@ -69,7 +83,13 @@ session.assistant("Hi there! How can I help you today?")
 session.user("What's the weather like?")
 ```
 
-Messages support the roles `user`, `assistant`, `system`, and `developer`.
+Messages support the roles `user`, `assistant`, `system`, and `developer`. A `Message` exposes `system?`, `user?`, and `assistant?` predicates for checking its role.
+
+Call `session.clear` to reset the conversation: it removes all items and the `instructions`, drops any `previous_response_id`, and returns the session to a fresh local-state start. Model configuration and registered tools are preserved, so the session can be reused for a new conversation.
+
+```ruby
+session.clear   # items and instructions removed; model/config/tools kept
+```
 
 ### Serializing Requests
 
@@ -160,6 +180,59 @@ response.has_tool_calls? # => false
 response.usage           # => #<PromptBuilder::Usage input_tokens=25 output_tokens=12 ...>
 ```
 
+If the payload is an error returned by the API rather than a completion (e.g. an authentication failure, a validation error, or an AWS Coral service envelope), `Response.parse` raises a `PromptBuilder::ErrorResponseError` whose message contains the error reported by the API. Payloads that are neither a completion nor a recognizable error envelope raise a `PromptBuilder::UnexpectedPayloadError` (which `ErrorResponseError` subclasses) including the offending body.
+
+```ruby
+PromptBuilder::Response.parse({"error" => {"type" => "invalid_request_error", "message" => "Incorrect API key provided"}}, :chat_completion)
+# => raises PromptBuilder::ErrorResponseError: the API returned an error: invalid_request_error: Incorrect API key provided
+```
+
+You can also synthesize a plain-text response without calling an API — useful for canned answers (e.g. halting an agent loop), cached responses, and tests:
+
+```ruby
+response = PromptBuilder::Response.from_text("Authentication failed.",
+  model: llm_response.model, usage: llm_response.usage)
+response.text        # => "Authentication failed."
+response.completed?  # => true
+```
+
+### Structured Output
+
+Use `json_output` to request JSON Schema structured output and `parsed_json` to read it back:
+
+```ruby
+schema = {
+  "type" => "object",
+  "properties" => {"answer" => {"type" => "string"}},
+  "required" => ["answer"]
+}
+
+session.json_output(schema, name: "response", strict: true)
+payload = session.request_payload(:messages)  # works with all five serializers
+
+# After parsing the API response:
+data = response.parsed_json    # => {"answer" => "..."} or nil if the text isn't valid JSON
+data = response.parsed_json!   # raises PromptBuilder::ParseError (including the raw text) instead
+```
+
+`parsed_json` strips fenced ```` ```json ```` wrappers, a common provider quirk. `json_output` is sugar for setting `session.text` to the canonical `format` wire hash, so direct `session.text = {...}` assignment keeps working.
+
+### Reasoning / Extended Thinking
+
+Use `think` to configure reasoning portably; each serializer maps it to its native parameter:
+
+```ruby
+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
+```
+
+- `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.
+
+Direct `session.reasoning = {...}` assignment keeps working for provider-specific keys (e.g. Anthropic's `display`, Gemini's `summary`).
+
 ### Agentic Tool Loops
 
 You can register tool definitions on a session, add API responses to the conversation, and manually append tool outputs to build an agentic loop:
@@ -240,6 +313,23 @@ end
 session.register_tools(PromptBuilder.tool_registry)
 ```
 
+Use `use_tools` to attach a subset of registry tools by name without copying schemas by hand. Unknown names raise a `ToolNotFoundError`, so a typo fails fast instead of producing a silently absent tool:
+
+```ruby
+session.use_tools("weather", "traffic_conditions")   # from PromptBuilder.tool_registry
+session.use_tools                                     # all tools in the registry
+session.use_tools(:weather, registry: my_registry)    # explicit registry
+```
+
+Tool definitions are *copied* onto the session in all cases, so later registry changes don't affect the session and the tools survive `to_h`/`from_h` round-trips.
+
+Remove tools from a session with `remove_tool` (by name; accepts a string or symbol) or `clear_tools` (all at once). `remove_tool` returns the removed `Tools::Definition`, or `nil` if no tool by that name was registered; `clear_tools` returns the removed definitions.
+
+```ruby
+session.remove_tool("weather")   # => removed Tools::Definition, or nil
+session.clear_tools              # => [<removed definitions>]
+```
+
 ### Content Types
 
 Message content can be a plain string or an array of structured content objects for multi-modal input. Content can be provided as raw Hashes or as `PromptBuilder::Content` objects.
@@ -360,6 +450,8 @@ session = PromptBuilder::Session.new(
 
 The `extra` attribute on sessions, content blocks, and tool definitions lets you pass provider-specific parameters that are not part of the Open Responses canonical format. Each serializer recognizes a defined set of `extra` keys and maps them to the appropriate location in the target format. Unrecognized keys are silently ignored.
 
+On a session, `extra` is a read/write attribute that can be set at any point in the session's life. On content blocks and tool definitions it is set with keyword arguments at construction time.
+
 #### Session Extra
 
 Pass provider-specific top-level request parameters via `session.extra`:
@@ -413,6 +505,26 @@ session = PromptBuilder::Session.new(
 )
 ```
 
+The same data can be set after the session has been created by assigning to `session.extra`. Keys are normalized to strings, so symbol keys work too.
+
+```ruby
+session = PromptBuilder::Session.new(model: "anthropic.claude-v2")
+
+session.extra # => {}
+
+# Assign the whole hash.
+session.extra = {guardrail_config: {"guardrailIdentifier" => "my-guardrail", "guardrailVersion" => "1"}}
+
+# `extra` returns a copy, so read, modify, and assign it back to change one key.
+session.extra = session.extra.merge("stop_sequences" => ["\n\nHuman:"])
+session.extra = session.extra.except("stop_sequences")
+
+session.extra = nil # clears it
+```
+
+> [!IMPORTANT]
+> `session.extra` never returns `nil` and its keys are always strings. Because the reader returns a copy, mutating it in place has no effect on the session — `session.extra["seed"] = 42` is silently discarded. Assign the modified hash back as shown above.
+
 #### Content Extra
 
 Content blocks support provider-specific attributes via keyword arguments that are captured in the `extra` hash:
@@ -442,6 +554,21 @@ session.user([
     cache_point: true
   )
 ])
+
+# Bedrock Converse: cache_point on tool definitions and tool results
+session.register_tool(
+  "search",
+  description: "Search the knowledge base.",
+  parameters: {"type" => "object", "properties" => {"query" => {"type" => "string"}}},
+  cache_point: true
+)
+session.add_item(
+  PromptBuilder::Items::FunctionCallOutput.new(
+    call_id: "call_1",
+    output: "Search results...",
+    cache_point: true
+  )
+)
 ```
 
 #### Tool Definition Extra
@@ -460,12 +587,14 @@ session.register_tool(
 
 #### Recognized Extra Keys by Serializer
 
+Session extra keys can be supplied to the constructor or assigned later with `session.extra=`.
+
 | Serializer | Session Extra Keys | Content Extra Keys | Tool Extra Keys |
 |:---|:---|:---|:---|
 | **Chat Completions** | `stop`, `seed`, `logit_bias`, `n`, `prediction`, `web_search_options`, `modalities`, `audio` | `file_id`, `media_type` | — |
 | **Messages** | `top_k`, `stop_sequences`, `cache_control` | `cache_control`, `citations`, `file_id`, `media_type` | `cache_control` |
 | **Gemini** | `safety_settings`, `cached_content`, `stop_sequences`, `top_k`, `seed`, `candidate_count`, `response_modalities`, `media_resolution` | `file_id`, `media_type`, `thought_signature` | — |
-| **Converse** | `stop_sequences`, `guardrail_config`, `additional_model_request_fields`, `additional_model_response_field_paths`, `performance_config`, `prompt_variables` | `media_type`, `cache_point` | — |
+| **Converse** | `stop_sequences`, `guardrail_config`, `additional_model_request_fields`, `additional_model_response_field_paths`, `performance_config`, `prompt_variables` | `media_type`, `cache_point` | `cache_point` |
 
 ### Serialization and Persistence
 
@@ -481,6 +610,9 @@ restored_session = PromptBuilder::Session.from_h(hash)
 
 This makes it straightforward to persist conversation state in a database or cache between requests.
 
+> [!WARNING]
+> `to_h` is the persistence format, not a request payload. It retains provider-specific `extra` data and non-replayable items that APIs reject. Send the output of `request_payload(serializer)` to APIs, and use `to_h`/`from_h` only for storage.
+
 ## Serializer Compatibility
 
 The Open Responses format is the canonical data model for this gem. When serializing to other formats, some features may not be available because either the target API does not support them or because the Open Responses format does not expose parameters unique to the target API. If you attempt to use a feature that is not supported by a particular serializer, it will be silently omitted from the serialized output.
@@ -601,6 +733,8 @@ For Messages specifically:
 
 ### Chat Completions-specific notes
 
+Serializing a session without `model` set, or one that produces no messages at all, raises a `PromptBuilder::UnsupportedFormatError`.
+
 Request-side mappings worth calling out:
 
 | Canonical field / value | Chat Completions mapping |
@@ -631,6 +765,8 @@ Response-side behavior and limitations:
 
 ### Anthropic Messages-specific mappings
 
+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`.
+
 A few features map between the canonical Open Responses format and the Messages API in non-obvious ways:
 
 | Canonical field / value | Messages mapping |
@@ -654,6 +790,8 @@ Built-in tool response content blocks (`server_tool_use`, `web_search_tool_resul
 
 ### Gemini-specific notes
 
+Serializing a session without `model` set (the model belongs in the request URL, but it is validated at serialization time), or one that produces an empty `contents` array, raises a `PromptBuilder::UnsupportedFormatError`.
+
 Request-side mappings worth calling out:
 
 | Canonical field / value | Gemini mapping |
@@ -697,6 +835,8 @@ Response-side limitations:
 
 ### Converse-specific notes
 
+Serializing a session without `model` set (populates the required `modelId` parameter) raises a `PromptBuilder::UnsupportedFormatError`.
+
 Request-side restrictions worth calling out:
 
 | Canonical field / value | Converse mapping |
@@ -725,7 +865,7 @@ Content and message restrictions:
 - `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.
 - `tool_choice: "none"` and `tool_choice` without registered tools are both omitted.
-- Converse API request features with no canonical Open Responses field are available through `session.extra` (`stop_sequences`, `guardrail_config`, `additional_model_request_fields`, `additional_model_response_field_paths`, `performance_config`, `prompt_variables`) and content `extra` (`cache_point`). Features not exposed at all include `guardContent`, audio blocks, and `searchResult` blocks.
+- Converse API request features with no canonical Open Responses field are available through `session.extra` (`stop_sequences`, `guardrail_config`, `additional_model_request_fields`, `additional_model_response_field_paths`, `performance_config`, `prompt_variables`) and content `extra` (`cache_point`). `cache_point` is also recognized on tool definitions (the marker is appended to the `toolConfig.tools` array) and on `FunctionCallOutput` items (the marker is appended after the `toolResult` content block). Features not exposed at all include `guardContent`, audio blocks, and `searchResult` blocks.
 - The serialized payload includes `modelId` as a convenience; the Converse REST endpoint takes the model id in the URL path (`/model/{modelId}/converse`), and AWS REST-JSON services ignore unrecognized body members. Remove it from the body if you prefer a strictly minimal payload.
 
 Response-side limitations:
@@ -733,7 +873,7 @@ Response-side limitations:
 - Unknown content block keys (e.g. `citationsContent`, `guardContent`) are silently skipped.
 - `metrics.latencyMs`, `trace` (guardrail and prompt-router trace events), `additionalModelResponseFields`, `performanceConfig`, and the raw `serviceTier` object are exposed on `response.provider_data`. `response.service_tier` is also populated from `serviceTier.type`.
 - `stopReason` mappings: `end_turn` / `tool_use` / `stop_sequence` → `completed`, `max_tokens` / `model_context_window_exceeded` → `incomplete`, `guardrail_intervened` / `content_filtered` / `malformed_model_output` / `malformed_tool_use` → `failed`. Unlike the Messages serializer, the matched stop sequence text is not surfaced separately because Converse does not echo it back unless you request provider-specific fields through `additionalModelResponseFieldPaths` (available via the `additional_model_response_field_paths` session extra; the requested fields appear on `response.provider_data`).
-- `usage.cacheReadInputTokens` and `usage.cacheWriteInputTokens` populate `response.usage.input_tokens_details["cached_tokens"]` and `["cache_creation_input_tokens"]`. Cache writes require `cachePoint` markers in the request, which are emitted via the `cache_point` content extra.
+- `usage.cacheReadInputTokens` and `usage.cacheWriteInputTokens` populate `response.usage.input_tokens_details["cached_tokens"]` and `["cache_creation_input_tokens"]`. Cache writes require `cachePoint` markers in the request, which are emitted via the `cache_point` extra on content, tool definitions, and `FunctionCallOutput` items.
 
 ## Installation
 

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.3.0

data/lib/prompt_builder/errors.rb

@@ -18,4 +18,12 @@ module PromptBuilder
 
   # Raised when a response payload does not match the expected shape.
   class UnexpectedPayloadError < Error; end
+
+  # Raised when a response payload is an error returned by the API rather
+  # than a completion (e.g. an authentication, validation, or throttling
+  # 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.
+  class ParseError < Error; end
 end

data/lib/prompt_builder/items/message.rb

@@ -23,6 +23,24 @@ module PromptBuilder
       # @return [Hash, nil] provider-specific extra data
       attr_reader :extra
 
+      class << self
+        # Deserialize a Message from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [Message]
+        def from_h(hash)
+          content = (hash["content"] || []).map { |c| Content::Base.from_h(c) }
+          new(
+            id: hash["id"],
+            role: hash["role"],
+            status: hash["status"],
+            phase: hash["phase"],
+            content: content,
+            **hash.except("type", "id", "role", "status", "phase", "content").transform_keys(&:to_sym)
+          )
+        end
+      end
+
       # Create a new Message item.
       #
       # @param id [String, nil] the message identifier
@@ -40,22 +58,25 @@ module PromptBuilder
         @extra = extra.transform_keys(&:to_s)
       end
 
-      class << self
-        # Deserialize a Message from a Hash.
-        #
-        # @param hash [Hash] a Hash with string keys
-        # @return [Message]
-        def from_h(hash)
-          content = (hash["content"] || []).map { |c| Content::Base.from_h(c) }
-          new(
-            id: hash["id"],
-            role: hash["role"],
-            status: hash["status"],
-            phase: hash["phase"],
-            content: content,
-            **hash.except("type", "id", "role", "status", "phase", "content").transform_keys(&:to_sym)
-          )
-        end
+      # Check if the message is a system message.
+      #
+      # @return [Boolean]
+      def system?
+        role == "system"
+      end
+
+      # Check if the message is a user message.
+      #
+      # @return [Boolean]
+      def user?
+        role == "user"
+      end
+
+      # Check if the message is an assistant message.
+      #
+      # @return [Boolean]
+      def assistant?
+        role == "assistant"
       end
 
       # Serialize to a Hash with string keys.
@@ -102,6 +123,9 @@ module PromptBuilder
 
       def normalize_hash_content(hash)
         hash = hash.transform_keys(&:to_s)
+        if hash["type"].nil? && hash.key?("text")
+          hash = hash.merge("type" => (assistant? ? "output_text" : "input_text"))
+        end
         unless hash["type"]
           raise InvalidItemError,
             "Content hash is missing required \"type\" key: #{hash.inspect}"

data/lib/prompt_builder/response.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module PromptBuilder
   # Represents a parsed API response from the Open Responses API.
   # All fields are optional and will be nil if not present in the response.
@@ -173,6 +175,23 @@ module PromptBuilder
         attrs = FIELDS.each_with_object({}) { |f, acc| acc[f] = hash[f.to_s] }
         new(**attrs, text_config: hash["text"], output: output, usage: usage, extra: hash["extra"])
       end
+
+      # Synthesize a Response containing a single assistant text message.
+      # Useful for canned answers (halt messages, cached responses) and tests
+      # without assembling Items::Message and Content::OutputText by hand.
+      #
+      # @param text [String] the assistant message text
+      # @param status [String] the response status
+      # @param attributes [Hash] any other Response attributes (e.g. +model+,
+      #   +usage+, +id+)
+      # @return [Response]
+      # @example
+      #   PromptBuilder::Response.from_text("Authentication failed.",
+      #     model: llm_response.model, usage: llm_response.usage)
+      def from_text(text, status: "completed", **attributes)
+        message = Items::Message.new(role: "assistant", content: [Content::OutputText.new(text: text)])
+        new(status: status, output: [message], **attributes)
+      end
     end
 
     # Check if the response completed successfully.
@@ -224,6 +243,40 @@ module PromptBuilder
       nil
     end
 
+    # Parse the response text as JSON, for use with structured output
+    # (see +Session#json_output+). Strips a fenced ```json wrapper when
+    # present — a common provider quirk. Returns nil when the response has
+    # no text or the text is not valid JSON; use +parsed_json!+ to raise
+    # instead.
+    #
+    # @return [Hash, Array, Object, nil] the parsed JSON value, or nil
+    def parsed_json
+      raw = text
+      return nil unless raw
+
+      begin
+        JSON.parse(strip_json_fences(raw))
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    # Parse the response text as JSON, raising when it cannot be parsed.
+    #
+    # @return [Hash, Array, Object] the parsed JSON value
+    # @raise [ParseError] if the response has no text or the text is not
+    #   valid JSON; the error message includes the raw text
+    def parsed_json!
+      raw = text
+      raise ParseError, "Response has no text output to parse as JSON" unless raw
+
+      begin
+        JSON.parse(strip_json_fences(raw))
+      rescue JSON::ParserError => e
+        raise ParseError, "Response text is not valid JSON (#{e.message}); raw text: #{raw}"
+      end
+    end
+
     # Serialize to a Hash with string keys. Nil values are omitted.
     #
     # @return [Hash]
@@ -246,6 +299,12 @@ module PromptBuilder
 
     private
 
+    def strip_json_fences(raw)
+      stripped = raw.strip
+      match = stripped.match(/\A```(?:json)?\s*\n(.*?)\n?```\z/m)
+      match ? match[1] : stripped
+    end
+
     def coerce_field(field, value)
       return value if value.nil?
 

data/lib/prompt_builder/serializers/base.rb

@@ -18,7 +18,9 @@ module PromptBuilder
         #
         # @param hash [Hash] the response hash in the target format
         # @return [Response] the parsed response
+        # @raise [ErrorResponseError] if the payload is an API error envelope
         def parse_response(hash)
+          check_error_response!(hash)
           deserialize_response(hash)
         end
 
@@ -32,6 +34,32 @@ module PromptBuilder
           raise NotImplementedError
         end
 
+        # Detect API error envelopes before parsing so errors surface with the
+        # message reported by the API instead of the generic missing-key error
+        # from require_response_key!. Serializer response classes override
+        # error_response_message to recognize their format's error envelope.
+        #
+        # @param hash [Object] the raw response payload
+        # @return [void]
+        # @raise [ErrorResponseError] if the payload is an API error envelope
+        def check_error_response!(hash)
+          return unless hash.is_a?(Hash)
+
+          message = error_response_message(hash)
+          return if message.nil? || message.empty?
+
+          raise ErrorResponseError, "the API returned an error: #{message}"
+        end
+
+        # Extract a human-readable message from an API error envelope.
+        #
+        # @param _hash [Hash] the raw response payload
+        # @return [String, nil] nil when the payload is not recognized as an
+        #   error envelope
+        def error_response_message(_hash)
+          nil
+        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

@@ -5,6 +5,11 @@ module PromptBuilder
     class ChatCompletion < Base
       # Request serializer for the OpenAI Chat Completions API format.
       #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+
+      # - at least one message (+instructions+ or a conversation item that
+      #   serializes to a message)
+      #
       # === Unsupported Open Responses features
       #
       # These session fields are not supported and are silently omitted from the
@@ -22,6 +27,10 @@ module PromptBuilder
       #   supported, and only when +stream+ is set (otherwise it is omitted)
       #
       # Input content restrictions:
+      # - +instructions+ is serialized as a system message inserted after the
+      #   last system/developer message, or first when there are none
+      #   (instructions apply to the current request, matching Open Responses
+      #   semantics)
       # - +InputVideo+ content is not supported in any message (omitted)
       # - +Reasoning+ items are not supported (skipped)
       # - +RefusalContent+ is dropped silently (a parsed Chat Completions
@@ -62,8 +71,14 @@ module PromptBuilder
 
           def serialize_request(session)
             h = {}
-            h["model"] = session.model if session.model
-            h["messages"] = build_messages(session)
+            raise UnsupportedFormatError, "Chat Completions format requires session.model" unless session.model
+
+            h["model"] = session.model
+            messages = build_messages(session)
+            if messages.empty?
+              raise UnsupportedFormatError, "Chat Completions format requires at least one message"
+            end
+            h["messages"] = messages
             h["temperature"] = session.temperature if session.temperature
             h["top_p"] = session.top_p if session.top_p
             h["presence_penalty"] = session.presence_penalty if session.presence_penalty
@@ -108,7 +123,8 @@ module PromptBuilder
             end
 
             # Session extra: recognized keys for Chat Completions API
-            apply_session_extra!(h, session.extra) if session.extra
+            extra = session.extra
+            apply_session_extra!(h, extra) unless extra.empty?
 
             h
           end
@@ -127,10 +143,6 @@ module PromptBuilder
           def build_messages(session)
             messages = []
 
-            if session.instructions
-              messages << {"role" => "system", "content" => session.instructions}
-            end
-
             pending_tool_calls = []
             last_assistant_msg = nil
 
@@ -160,9 +172,18 @@ module PromptBuilder
             end
 
             flush_tool_calls!(messages, pending_tool_calls, last_assistant_msg)
+            insert_instructions!(messages, session.instructions) if session.instructions
             messages
           end
 
+          # Instructions apply to the current request (matching Open Responses
+          # semantics), so they are inserted after the last system/developer
+          # message rather than before any of them.
+          def insert_instructions!(messages, instructions)
+            index = messages.rindex { |msg| msg["role"] == "system" || msg["role"] == "developer" }
+            messages.insert(index ? index + 1 : 0, {"role" => "system", "content" => instructions})
+          end
+
           def serialize_message(item)
             # Messages with an unsupported role are silently skipped.
             return nil unless SUPPORTED_MESSAGE_ROLES.include?(item.role)
@@ -187,7 +208,7 @@ module PromptBuilder
 
           def serialize_content(role, content)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               serialize_text_content(content)
             when Content::InputImage
               # Image content is only supported in user messages; omit otherwise.
@@ -230,7 +251,7 @@ module PromptBuilder
             # are silently omitted.
             content = output.filter_map do |content|
               case content
-              when Content::InputText, Content::OutputText
+              when Content::InputText, Content::OutputText, Content::Text
                 serialize_text_content(content)
               end
             end