ruby_llm-responses_api 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daf5eec383489e81c577b2f04965ca156b976ca30a708a39a6ab8dce39863ff7
-  data.tar.gz: df8e9a6f230724e40f479679229d20c1b2faeee8e186400f37367e059badea8a
+  metadata.gz: 6b169a57a059b3f091ea37d5f46dea3f253acb25f3544ad5f98ddec9f81e0185
+  data.tar.gz: f5251e33d031cfb749454c344d4e88e0edd83940dced27770d0a29d2de0b71cf
 SHA512:
-  metadata.gz: 7b6ae940cd27e283b2fd06edcb9122fb25328f39d786f3c011073954a4e5574a63f4272b17e11816e499c3064343407181a044768ebaa7f4f9d1844ea3afae3b
-  data.tar.gz: e2f971bfe9d6d874e6b368775485dab455ce16a0291c11d1806adf279273c3b6e762fac015ab86d376d84c3d31e0e1de26475ec5230c912d7352ad0b29c0a7f1
+  metadata.gz: b53e038d5e2c6d022c827a674ae5c14c7fb346922ce6b63d38d0b11755ac291ab3d4515ab66214a9fb65e34b18c544b26ea5031bffac41957e0d04e2c43a37db
+  data.tar.gz: 5974b3b5934dbf0fd9f7d4a5caddc6ec265b8cf3b899a65fdcaf372c3962daad092ca71ad6a8ae2bbda238b062ac0f9559e53151c7be6fcf0f73ba4e1d592c2e

data/CHANGELOG.md

@@ -5,6 +5,43 @@ 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).
 
+## [1.0.0] - 2026-10-31
+
+### Changed
+
+- Migrate to RubyLLM 2.1.1's native provider/protocol architecture; require Ruby 4.x and RubyLLM 2.1.x.
+- Keep `:openai_responses` as an opt-in OpenAI provider with a scoped native Responses protocol. Native `:openai` and other providers are unchanged.
+- Delegate message rendering, attachments, function tools, reasoning, citations, server tool records, batches and usage accounting to RubyLLM; reuse its OpenAI model catalog instead of maintaining snapshots.
+- Move raw-input batch factories to `RubyLLM::ResponsesAPI.batch` / `.batches`, preserving native `RubyLLM.batch(chats)`.
+- Use RubyLLM 2.x's `with_provider_options`, `before_tool_call`, `after_tool_result`, `Message#tokens` and `Message#model` APIs. See MIGRATION.md.
+- Extend native ActiveRecord serialization and message attributes without replacing persistence of usage, tool records, reasoning or attachments.
+
+### Added
+
+- Completed streams expose the final Responses object at `message.raw.body`, including built-in tool output, matching sync calls (issue #4).
+- Explicit stateless mode with `store: false`, without automatic chaining or discarded local history.
+- Native server tool records and usage accounting for WebSocket chat requests.
+
+### Fixed
+
+- Fail on a WebSocket disconnect before completion instead of returning a partial answer as a successful response.
+- Preserve an existing in-flight WebSocket request when a concurrent call is rejected.
+- Use native instrumented DELETE transport for response and container lifecycle operations.
+
+- `StreamAccumulator` now forwards `response_id` from the completed chunk to the assembled message, matching the existing `built_in_tool_events` handling. Previously every streamed chat lost `response_id`, so `previous_response_id` chaining never engaged and each turn resent the full message history instead of just the new items.
+
+## [0.6.1] - 2026-06-11
+
+### Added
+
+- RubyLLM 1.16 compatibility for request instrumentation, including `request.ruby_llm` events for manual Responses API DELETE requests while preserving RubyLLM 1.15 compatibility
+- Explicit provider `configuration_options` for OpenAI API key, base URL, organization, and project settings
+- Explicit `supports_tool_parallel_control?` capability so RubyLLM can discover Responses API support for `calls: :many` / `calls: :one`
+
+### Fixed
+
+- Streamed function-call argument accumulation with RubyLLM 1.16's indexed `StreamAccumulator`, including Responses API `item_id` deltas
+
 ## [0.6.0] - 2026-05-26
 
 ### Added

data/MIGRATION.md

@@ -0,0 +1,276 @@
+# Migrating from 0.x to 1.0
+
+Version 1.0 uses RubyLLM's native OpenAI Responses protocol and adds server-side conversation state, WebSocket transport, containers and response lifecycle helpers. Keep `provider: :openai_responses` to retain this gem's behavior.
+
+This guide covers application changes from `ruby_llm-responses_api` 0.x to 1.0.
+
+## 1. Upgrade the runtime and dependencies
+
+The supported versions are:
+
+| Dependency | Requirement |
+| --- | --- |
+| Ruby | 4.x only: `>= 4.0, < 5.0` |
+| RubyLLM | `>= 2.1.1, < 2.2` |
+| ruby_llm-responses_api | 1.0.x |
+| websocket-client-simple | Optional; required for WebSocket transport |
+
+For Rails applications still on RubyLLM 1.x, first follow the upstream [1.x to 2.0 guide](https://github.com/crmne/ruby_llm/blob/v2.0.0/docs/_reference/upgrading.md), then the [2.0 to 2.1 guide](https://rubyllm.com/upgrading/). Complete the database migration and cleanup steps for each release before moving to the next. The upstream 2.1 upgrade generator does not include the earlier upgrade helpers. This gem's 0.x implementation cannot be loaded alongside RubyLLM 2.x; account for that in the intermediate upgrade environment.
+
+Set Ruby 4 in your runtime configuration, container image and CI. For mise:
+
+```toml
+[tools]
+ruby = "4.0"
+```
+
+Use these final dependency constraints in your application's `Gemfile`:
+
+```ruby
+ruby '>= 4.0', '< 5.0'
+
+gem 'ruby_llm', '~> 2.1.1'
+gem 'ruby_llm-responses_api', '~> 1.0.0'
+
+# Add when using WebSocket transport:
+gem 'websocket-client-simple', '~> 0.8'
+```
+
+Then resolve the new bundle:
+
+```sh
+bundle update ruby_llm ruby_llm-responses_api
+```
+
+## 2. Keep the provider and configuration
+
+The require path, OpenAI credentials and provider name stay the same:
+
+```ruby
+require 'ruby_llm-responses_api'
+
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
+end
+
+chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
+response = chat.ask('Hello!')
+puts response.content
+```
+
+Keep existing `openai_responses` provider values in persisted chats and model records. Switching to `provider: :openai` selects RubyLLM's native stateless behavior and does not enable this gem's automatic chaining or transport helpers.
+
+Model capabilities, limits and pricing now come from the native OpenAI catalog. For a model absent from that catalog, pass `assume_model_exists: true` with an explicit provider. Remove application code that calls the old `ModelRegistry.register_all!`.
+
+## 3. Update chat and message APIs
+
+| Before | After |
+| --- | --- |
+| `chat.with_params(...)` | `chat.with_provider_options(...)` |
+| `chat.with_tool(MyTool)` | `chat.with_tools(MyTool)` |
+| `chat.on_tool_call { ... }` | `chat.before_tool_call { ... }` |
+| `chat.on_tool_result { ... }` | `chat.after_tool_result { ... }` |
+| `response.input_tokens` | `response.tokens.input` |
+| `response.output_tokens` | `response.tokens.output` |
+| `response.cached_tokens` | `response.tokens.cache_read` |
+| `response.cache_creation_tokens` | `response.tokens.cache_write` |
+| `response.model_id` | `response.model` |
+| Structured `response.content` | `response.parsed` |
+| `RubyLLM::Content` attachments | `chat.ask('Describe', with: files_or_urls)` |
+| `Chat.create!(model_id: ..., provider: ...)` | `Chat.create!(model: ..., provider: ...)` |
+
+`response.content` is a string even when a schema is configured. Read structured data through `response.parsed`:
+
+```ruby
+chat.with_schema(
+  type: 'object',
+  properties: { answer: { type: 'string' } },
+  required: ['answer'],
+  additionalProperties: false
+)
+response = chat.ask('Give a short answer.')
+puts response.parsed.fetch('answer')
+```
+
+Pass attachments directly to `ask`:
+
+```ruby
+chat.ask('Summarize this document.', with: ['report.pdf'])
+chat.ask('Describe this image.', with: ['photo.png'])
+```
+
+`with_provider_options` replaces the current options hash. Preserve other options when changing one:
+
+```ruby
+chat.with_provider_options(chat.provider_options.merge(store: false))
+```
+
+## 4. Check conversation state
+
+Automatic chaining remains the default for `:openai_responses`. Requests use `store: true`; the next request sends only messages after the last stored assistant response, with its ID in `previous_response_id`. Current system instructions are sent again on each request. This applies to sync HTTP, HTTP streaming and WebSocket calls.
+
+```ruby
+chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
+first = chat.ask('My name is Alice.')
+puts first.response_id
+chat.ask('What is my name?')
+```
+
+Remove workarounds that manually trim history or patch `format_input` for issue #10. History filtering is handled by the new protocol. Keep complete local conversation history so stateless replay remains possible.
+
+To disable automatic chaining and replay the local history:
+
+```ruby
+chat.with_provider_options(store: false)
+response = chat.ask('Continue using the local history.')
+```
+
+In this mode, returned messages have no automatic chaining `response_id`. The native protocol preserves reasoning data for replay. If needed for diagnostics, the API's returned ID is available at `response.raw.body['id']`.
+
+To start a fresh stored chain from the full local history, explicitly set `previous_response_id: nil` for that request. Remove the override before the next request:
+
+```ruby
+options = chat.provider_options.except(:previous_response_id).merge(store: true)
+chat.with_provider_options(options.merge(previous_response_id: nil))
+chat.ask('Start a fresh chain using this history.')
+chat.with_provider_options(options)
+```
+
+An explicit external `previous_response_id` can resume a stored response in a new chat. Supply only the new local input for that parent; do not also import its entire old history.
+
+## 5. Update tools and callbacks
+
+Custom function tools use RubyLLM's native declarations:
+
+```ruby
+class Weather < RubyLLM::Tool
+  description 'Get the weather for a city'
+  parameter :city, type: 'string', description: 'City name'
+
+  def execute(city:)
+    "Sunny in #{city}"
+  end
+end
+
+chat.with_tools(Weather)
+```
+
+Replace the old `param` declaration with `parameter`, and `desc:` with `description:`. Native function definitions default to non-strict mode. To retain strict definitions, add `provider_options strict: true` to the tool class.
+
+Built-in tool hash builders remain available:
+
+```ruby
+tool = RubyLLM::ResponsesAPI::BuiltInTools.shell
+chat.with_provider_options(tools: [tool])
+```
+
+For tools supported by RubyLLM's native helpers, you can also use:
+
+```ruby
+chat.with_provider_tools(:web_search, :code_execution)
+```
+
+Rename the callbacks:
+
+```ruby
+chat.before_tool_call { |call| puts "#{call.name}: #{call.id}" }
+chat.after_tool_result { |result| puts result.inspect }
+```
+
+For built-in server tools, callbacks run when the final assistant message is added. They report completed work, not live progress, and retain this gem's result hash format. Local function tools keep RubyLLM's own callback arguments.
+
+Use `response.server_tool_calls` for native server tool records. Each record's `raw` retains its provider-specific fields. Existing parsers such as `BuiltInTools.parse_shell_call_results(response.raw.body['output'])` remain available.
+
+For this provider, `response.raw.body` contains the final Responses object in all three transports. For streaming, this is a reconstructed body from the final response event, rather than the SSE wire body. Remove old patches that reconstruct built-in tool metadata or forward `response_id` through the global accumulator.
+
+## 6. Move raw-input batch calls to ResponsesAPI
+
+The gem no longer overrides `RubyLLM.batch`. Rename the factories used by the existing raw-input workflow:
+
+| Before | After |
+| --- | --- |
+| `RubyLLM.batch(model: ..., provider: ...)` | `RubyLLM::ResponsesAPI.batch(model: ..., provider: ...)` |
+| `RubyLLM.batch(id: ...)` | `RubyLLM::ResponsesAPI.batch(id: ...)` |
+| `RubyLLM.batches(...)` | `RubyLLM::ResponsesAPI.batches(...)` |
+
+```ruby
+batch = RubyLLM::ResponsesAPI.batch(model: 'gpt-4o')
+batch.add('What is Ruby?', id: 'ruby')
+batch.create!
+batch.wait!
+puts batch.results.fetch('ruby').content
+
+# Resume or list existing batches:
+RubyLLM::ResponsesAPI.batch(id: 'batch_existing')
+RubyLLM::ResponsesAPI.batches
+```
+
+The helper defaults to `provider: :openai_responses`. RubyLLM's separate native `RubyLLM.batch(chats)` API remains available for its persisted-chat batch workflow.
+
+## 7. Retain Rails response IDs
+
+Complete RubyLLM's own schema upgrades first. Keep the string `response_id` column on your application message table. If it is already present, this gem needs no additional schema change. If it is absent:
+
+```sh
+bin/rails generate migration AddResponseIdToMessages response_id:string
+bin/rails db:migrate
+```
+
+Substitute your actual message table name when using a custom model. The column is optional, but automatic chaining cannot resume across a database reload without it.
+
+Update chat creation to use `model:`:
+
+```ruby
+chat = Chat.create!(model: 'gpt-4o', provider: :openai_responses)
+chat.ask('My name is Alice.')
+
+# After a restart:
+Chat.find(chat.id).ask('What is my name?')
+```
+
+The extension preserves native persistence of usage, reasoning, citations, attachments and tool records, while adding `response_id`. If using ActiveRecord outside Rails, apply the extension after loading ActiveRecord:
+
+```ruby
+require 'active_record'
+RubyLLM::Providers::OpenAIResponses.apply_active_record_extensions!
+```
+
+## 8. Update WebSocket options and error handling
+
+Add `websocket-client-simple` to your application's bundle, then rename `with_params`:
+
+```ruby
+chat.with_provider_options(transport: :websocket)
+chat.ask('Hello') { |chunk| print chunk.content }
+```
+
+Additional chat headers are sent in the handshake. Changing them reconnects the transport. A disconnect before completion now raises `RubyLLM::ResponsesAPI::WebSocket::ConnectionError` instead of returning a partial answer as a successful response. Handle that exception in the application's transport failure path.
+
+Standalone `RubyLLM::ResponsesAPI::WebSocket` remains available. Its `tools:` argument accepts raw Responses API tool hashes; use `BuiltInTools` to build those hashes.
+
+## 9. Remove patches against retired internals
+
+These helpers remain available under `RubyLLM::ResponsesAPI`: `Batch`, `Batches`, `BuiltInTools`, `State`, `Background`, `Compaction`, `Containers` and `WebSocket`.
+
+The old provider `Chat`, `Streaming`, `Media`, `Models`, `Tools` and `Capabilities` modules have been removed. Update direct requires and monkey patches against those modules. Rendering and parsing now use the native RubyLLM protocol; this gem's accumulator is scoped to its own provider.
+
+## Verify the application upgrade
+
+Before deploying, check the application paths you use:
+
+- A sync and a streamed two-turn chat retain `response_id` and send only new input on the second turn.
+- A tool call executes and its result reaches the follow-up request.
+- Structured output uses `response.parsed`; token displays use `response.tokens`.
+- A persisted chat can resume after a fresh database load.
+- Raw-input batch calls use `RubyLLM::ResponsesAPI`.
+- WebSocket disconnects reach the application's failure handler.
+
+For contributors, `bundle exec rake` runs this repository's tests and RuboCop on Ruby 4. Historic VCR recordings remain unchanged and use a compatibility matcher for equivalent 0.x request shapes. Separate WebMock tests assert the new payload, state, persistence and WebSocket behavior.
+
+The optional live WebSocket check sends real requests using the configured OpenAI account:
+
+```sh
+bundle exec rspec spec/integration/websocket_spec.rb --tag live_ws
+```
+
+Set `OPENAI_API_KEY` before running that check.

data/README.md

@@ -1,6 +1,10 @@
 # RubyLLM Responses API
 
-A [RubyLLM](https://github.com/crmne/ruby_llm) provider for OpenAI's [Responses API](https://platform.openai.com/docs/api-reference/responses).
+Stateful conversations, WebSocket transport, containers and response lifecycle helpers on top of [RubyLLM](https://github.com/crmne/ruby_llm)'s native OpenAI Responses protocol.
+
+Version 1.0 requires Ruby 4.x and RubyLLM 2.1.1 (2.1.x). Upgrading from 0.x? See [MIGRATION.md](MIGRATION.md).
+
+`provider: :openai_responses` opts into these extensions. RubyLLM's `provider: :openai`, other providers, and native `RubyLLM.batch(chats)` keep their normal behavior. Standard rendering, parsing, model metadata, reasoning, citations, tool execution and usage accounting come from RubyLLM.
 
 ## Installation
 
@@ -26,7 +30,7 @@ All standard RubyLLM features work as expected (streaming, tools, vision, struct
 
 ## Stateful Conversations
 
-Conversations automatically chain via `previous_response_id`:
+Conversations automatically chain via `previous_response_id`, with `store: true`. Only messages after the last stored assistant response are sent; current system instructions are sent on every turn. This works with HTTP, streaming and WebSocket transport:
 
 ```ruby
 chat = RubyLLM.chat(model: 'gpt-5.5', provider: :openai_responses)
@@ -34,9 +38,11 @@ chat.ask("My name is Alice.")
 chat.ask("What's my name?")  # => "Your name is Alice."
 ```
 
+To use stateless replay instead, set `chat.with_provider_options(store: false)`. The full history (including native reasoning data) is sent and no response ID is retained for automatic chaining. To start a fresh chain from the local history while still storing the new response, set `previous_response_id: nil`; remove that override before resuming automatic chaining.
+
 ## Rails Persistence
 
-For conversations that survive app restarts, add a migration:
+First complete RubyLLM's own 2.x database migration. For conversations that survive app restarts, retain or add a `response_id` column on your application message model:
 
 ```ruby
 class AddResponseIdToMessages < ActiveRecord::Migration[7.0]
@@ -50,7 +56,7 @@ Then use normally:
 
 ```ruby
 # Day 1
-chat = Chat.create!(model_id: 'gpt-5.5', provider: :openai_responses)
+chat = Chat.create!(model: 'gpt-5.5', provider: :openai_responses)
 chat.ask("My name is Alice.")
 
 # Day 2 (after restart)
@@ -60,17 +66,17 @@ chat.ask("What's my name?")  # => "Alice"
 
 ## Built-in Tools
 
-The Responses API provides built-in tools that don't require custom implementation. Pass them as hashes via `with_params`, or use the `BuiltInTools` helper module.
+The Responses API provides built-in tools that don't require custom implementation. Pass them as hashes via `with_provider_options`, or use the `BuiltInTools` helper module.
 
 ### Web Search
 
 ```ruby
-chat.with_params(tools: [{ type: 'web_search' }])
+chat.with_provider_options(tools: [{ type: 'web_search' }])
 chat.ask("Latest news about Ruby 3.4?")
 
 # Or with helper
 tool = RubyLLM::ResponsesAPI::BuiltInTools.web_search(search_context_size: 'high')
-chat.with_params(tools: [tool])
+chat.with_provider_options(tools: [tool])
 
 # Legacy preview type is still available when needed
 tool = RubyLLM::ResponsesAPI::BuiltInTools.web_search_preview
@@ -81,7 +87,7 @@ tool = RubyLLM::ResponsesAPI::BuiltInTools.web_search_preview
 Execute Python code in a sandbox:
 
 ```ruby
-chat.with_params(tools: [{ type: 'code_interpreter' }])
+chat.with_provider_tools(:code_execution)
 chat.ask("Calculate the first 20 Fibonacci numbers and plot them")
 ```
 
@@ -90,7 +96,7 @@ chat.ask("Calculate the first 20 Fibonacci numbers and plot them")
 Search through uploaded files (requires vector store setup):
 
 ```ruby
-chat.with_params(tools: [{ type: 'file_search', vector_store_ids: ['vs_abc123'] }])
+chat.with_provider_options(tools: [{ type: 'file_search', vector_store_ids: ['vs_abc123'] }])
 chat.ask("What does the documentation say about authentication?")
 ```
 
@@ -101,12 +107,12 @@ Execute commands in hosted containers or local terminal environments. Requires G
 ```ruby
 # Auto-provisioned container (default)
 chat = RubyLLM.chat(model: 'gpt-5.5', provider: :openai_responses)
-chat.with_params(tools: [{ type: 'shell', environment: { type: 'container_auto' } }])
+chat.with_provider_options(tools: [{ type: 'shell', environment: { type: 'container_auto' } }])
 chat.ask("List all Python files in the project")
 
 # Using helper
 tool = RubyLLM::ResponsesAPI::BuiltInTools.shell
-chat.with_params(tools: [tool])
+chat.with_provider_options(tools: [tool])
 
 # Reuse an existing container
 tool = RubyLLM::ResponsesAPI::BuiltInTools.shell(container_id: 'cntr_abc123')
@@ -135,18 +141,18 @@ Structured diff-based file editing. Requires GPT-5 family models.
 
 ```ruby
 chat = RubyLLM.chat(model: 'gpt-5.5', provider: :openai_responses)
-chat.with_params(tools: [{ type: 'apply_patch' }])
+chat.with_provider_options(tools: [{ type: 'apply_patch' }])
 chat.ask("Add error handling to the User#save method")
 
 # Using helper
 tool = RubyLLM::ResponsesAPI::BuiltInTools.apply_patch
-chat.with_params(tools: [tool])
+chat.with_provider_options(tools: [tool])
 ```
 
 ### Image Generation
 
 ```ruby
-chat.with_params(tools: [{ type: 'image_generation' }])
+chat.with_provider_options(tools: [{ type: 'image_generation' }])
 chat.ask("Generate an image of a sunset over mountains")
 ```
 
@@ -158,13 +164,13 @@ tool = RubyLLM::ResponsesAPI::BuiltInTools.mcp(
   server_url: 'https://api.github.com/mcp',
   require_approval: 'never'
 )
-chat.with_params(tools: [tool])
+chat.with_provider_options(tools: [tool])
 ```
 
 ### Combining Tools
 
 ```ruby
-chat.with_params(tools: [
+chat.with_provider_options(tools: [
   { type: 'web_search' },
   { type: 'code_interpreter' },
   { type: 'shell', environment: { type: 'container_auto' } }
@@ -180,12 +186,12 @@ For multi-hour agent runs, enable server-side compaction to automatically compre
 chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
 
 # Pass directly
-chat.with_params(
+chat.with_provider_options(
   context_management: [{ type: 'compaction', compact_threshold: 200_000 }]
 )
 
 # Or use the helper
-chat.with_params(
+chat.with_provider_options(
   **RubyLLM::ResponsesAPI::Compaction.compaction_params(compact_threshold: 150_000)
 )
 
@@ -201,7 +207,7 @@ When the token count crosses the threshold, the server automatically compacts th
 You can also run an explicit compaction pass or count request input tokens before creating a response:
 
 ```ruby
-provider = chat.instance_variable_get(:@provider)
+provider = chat.provider
 
 compacted = provider.compact_response(
   model: 'gpt-5.5',
@@ -221,7 +227,7 @@ Manage persistent execution environments for the shell tool and code interpreter
 
 ```ruby
 chat = RubyLLM.chat(model: 'gpt-5.5', provider: :openai_responses)
-provider = chat.instance_variable_get(:@provider)
+provider = chat.provider
 
 # Create a container
 container = provider.create_container(
@@ -232,7 +238,7 @@ container = provider.create_container(
 
 # Use it with the shell tool
 tool = RubyLLM::ResponsesAPI::BuiltInTools.shell(container_id: container['id'])
-chat.with_params(tools: [tool])
+chat.with_provider_options(tools: [tool])
 chat.ask("Install pandas and run my analysis script")
 
 # List files created in the container
@@ -251,11 +257,11 @@ For long-running tasks:
 
 ```ruby
 chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
-chat.with_params(background: true)
+chat.with_provider_options(background: true)
 response = chat.ask("Analyze this large dataset...")
 
 # Poll for completion
-provider = chat.instance_variable_get(:@provider)
+provider = chat.provider
 result = provider.poll_response(response.response_id, interval: 2.0) do |status|
   puts "Status: #{status['status']}"
 end
@@ -263,21 +269,21 @@ end
 
 ## Observing Built-in Tool Activity
 
-Server-side built-in tools (web search, code interpreter, file search, shell, apply patch, image generation, MCP, computer use, local shell) fire through the same `on_tool_call` / `on_tool_result` callbacks as locally executed function tools:
+Server-side built-in tools (web search, code interpreter, file search, shell, apply patch, image generation, MCP, computer use, local shell) fire through the same `before_tool_call` / `after_tool_result` callbacks as locally executed function tools:
 
 ```ruby
 chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
-chat.with_params(tools: [{ type: 'web_search' }])
+chat.with_provider_options(tools: [{ type: 'web_search' }])
 
-chat.on_tool_call  { |tc| puts "#{tc.name} called (id=#{tc.id})" }
-chat.on_tool_result { |r|  puts "  -> status=#{r[:status]}" }
+chat.before_tool_call  { |tc| puts "#{tc.name} called (id=#{tc.id})" }
+chat.after_tool_result { |r|  puts "  -> status=#{r[:status]}" }
 
 chat.ask("What's the latest Ruby release?")
 # web_search called (id=ws_...)
 #   -> status=completed
 ```
 
-The newer `before_tool_call` / `after_tool_result` API (ruby_llm 1.13+) is supported too. Each `ToolCall` carries a normalized name (`web_search`, `code_interpreter`, `file_search`, `image_generation`, `shell`, `apply_patch`, `mcp`, `computer`, `local_shell`) and best-effort arguments extracted from the response item.
+Each `ToolCall` carries a normalized name (`web_search`, `code_interpreter`, `file_search`, `image_generation`, `shell`, `apply_patch`, `mcp`, `computer`, `local_shell`) and best-effort arguments extracted from the response item.
 
 ## Parsing Built-in Tool Results
 
@@ -297,13 +303,17 @@ image_results  = RubyLLM::ResponsesAPI::BuiltInTools.parse_image_generation_resu
 citations      = RubyLLM::ResponsesAPI::BuiltInTools.extract_citations(message_content)
 ```
 
+Completed built-in tool records are also available through native `response.server_tool_calls` (`call.raw` keeps the provider item). For this provider, completed HTTP streams and WebSocket calls expose the final Responses object at `response.raw.body`, matching sync responses. This streamed body is reconstructed from the final response event; it is not the SSE wire body.
+
 ## Batch API
 
+RubyLLM 2.x has its own `RubyLLM.batch(chats)` API. The raw-input batch helper from this gem lives under `RubyLLM::ResponsesAPI` and does not override the native API.
+
 Process many requests asynchronously at 50% lower cost with a 24-hour completion window:
 
 ```ruby
 # Create a batch
-batch = RubyLLM.batch(model: 'gpt-4o', provider: :openai_responses)
+batch = RubyLLM::ResponsesAPI.batch(model: 'gpt-4o', provider: :openai_responses)
 
 # Add requests (auto-generates IDs or use your own)
 batch.add("What is Ruby?")
@@ -323,14 +333,14 @@ results["request_0"].content  # => "Ruby is a dynamic..."
 results["translate_1"].content  # => "Hola"
 
 # Resume from a previous session
-batch = RubyLLM.batch(id: "batch_abc123", provider: :openai_responses)
+batch = RubyLLM::ResponsesAPI.batch(id: "batch_abc123", provider: :openai_responses)
 batch.results
 
 # Cancel a running batch
 batch.cancel!
 
 # List existing batches
-RubyLLM.batches(provider: :openai_responses)
+RubyLLM::ResponsesAPI.batches(provider: :openai_responses)
 ```
 
 **Constraints**: No `web_search`/`code_interpreter` tools, no `previous_response_id` chaining, max 50k requests per batch, 200MB file limit.
@@ -351,7 +361,7 @@ Just add `transport: :websocket` to your params -- the standard `chat.ask` API w
 
 ```ruby
 chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
-chat.with_params(transport: :websocket)
+chat.with_provider_options(transport: :websocket)
 
 chat.ask("Hello!")
 chat.ask("What's 2+2?")  # reuses the same WebSocket connection