ruby_llm-responses_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b83e9dbc3e924cceb9a1468e0da1271950bdbeb20d3bc0f3f2f859e3d17da565
+  data.tar.gz: 6ffbb8e1792cc333fb375b35a588f11d4d65d54a74182b95a0a3482ea716f39f
+SHA512:
+  metadata.gz: 1178f162885b3fa9e7f084f183568789a3d08b3be0e27550f2aa8f7e069376a9a2165fc62f5a26ce8a8ec72ba4aebc4a5957ed9f83ab19ba9edc0b29eae0f82e
+  data.tar.gz: 7f922f72564bc21cee14d11e7a6d220a79519eb09906e6e1e17321d6e5db9bf424c9b18b1b8219d6a85eee096be9ec498c4da04d251bf10cfb190b1b5cc25fcb

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+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.1.0] - 2025-01-03
+
+### Added
+
+- Initial release of the RubyLLM Responses API provider
+- Core chat completion support with Responses API format
+- Streaming support with typed event handling
+- Function calling (tool use) support
+- Built-in tools support:
+  - Web Search (`web_search_preview`)
+  - Code Interpreter (`code_interpreter`)
+  - File Search (`file_search`)
+  - Image Generation (`image_generation`)
+  - MCP (Model Context Protocol) (`mcp`)
+  - Computer Use (`computer_use_preview`)
+- Stateful conversation support via `previous_response_id` and `store`
+- Background mode for long-running tasks
+- Response polling and cancellation
+- Message extension to support `response_id`
+- Model capabilities for GPT-4o, GPT-4.1, and O-series models
+- Media handling for images, PDFs, and audio

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Hasinski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# 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).
+
+## Installation
+
+```ruby
+gem 'ruby_llm-responses_api'
+```
+
+## Quick Start
+
+```ruby
+require 'ruby_llm-responses_api'
+
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV['OPENAI_API_KEY']
+end
+
+chat = RubyLLM.chat(model: 'gpt-4o-mini', provider: :openai_responses)
+response = chat.ask("Hello!")
+puts response.content
+```
+
+All standard RubyLLM features work as expected (streaming, tools, vision, structured output).
+
+## Stateful Conversations
+
+Conversations automatically chain via `previous_response_id`:
+
+```ruby
+chat = RubyLLM.chat(model: 'gpt-4o-mini', provider: :openai_responses)
+chat.ask("My name is Alice.")
+chat.ask("What's my name?")  # => "Your name is Alice."
+```
+
+## Rails Persistence
+
+For conversations that survive app restarts, add a migration:
+
+```ruby
+class AddResponseIdToMessages < ActiveRecord::Migration[7.0]
+  def change
+    add_column :messages, :response_id, :string
+  end
+end
+```
+
+Then use normally:
+
+```ruby
+# Day 1
+chat = Chat.create!(model_id: 'gpt-4o-mini', provider: :openai_responses)
+chat.ask("My name is Alice.")
+
+# Day 2 (after restart)
+chat = Chat.find(1)
+chat.ask("What's my name?")  # => "Alice"
+```
+
+## Built-in Tools
+
+The Responses API provides built-in tools that don't require custom implementation.
+
+### Web Search
+
+```ruby
+chat.with_params(tools: [{ type: 'web_search_preview' }])
+chat.ask("Latest news about Ruby 3.4?")
+```
+
+### Code Interpreter
+
+Execute Python code in a sandbox:
+
+```ruby
+chat.with_params(tools: [{ type: 'code_interpreter' }])
+chat.ask("Calculate the first 20 Fibonacci numbers and plot them")
+```
+
+### File Search
+
+Search through uploaded files (requires vector store setup):
+
+```ruby
+chat.with_params(tools: [{ type: 'file_search', vector_store_ids: ['vs_abc123'] }])
+chat.ask("What does the documentation say about authentication?")
+```
+
+### Combining Tools
+
+```ruby
+chat.with_params(tools: [
+  { type: 'web_search_preview' },
+  { type: 'code_interpreter' }
+])
+chat.ask("Find the latest Bitcoin price and plot a chart")
+```
+
+## Why Use the Responses API?
+
+- **Built-in tools** - Web search, code execution, file search without custom implementation
+- **Stateful conversations** - OpenAI stores context server-side via `previous_response_id`
+- **Simpler multi-turn** - No need to send full message history on each request
+
+## License
+
+MIT

data/lib/ruby_llm/providers/openai_responses/active_record_extension.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Extends RubyLLM's ActiveRecord MessageMethods to support response_id persistence
+      # for stateful conversations with the OpenAI Responses API.
+      #
+      # This is automatically applied when Rails loads ActiveRecord.
+      # Just add a migration: add_column :messages, :response_id, :string
+      #
+      module MessageMethodsExtension
+        # Override to_llm to include response_id for Responses API support
+        def to_llm
+          cached = has_attribute?(:cached_tokens) ? self[:cached_tokens] : nil
+          cache_creation = has_attribute?(:cache_creation_tokens) ? self[:cache_creation_tokens] : nil
+          resp_id = has_attribute?(:response_id) ? self[:response_id] : nil
+
+          RubyLLM::Message.new(
+            role: role.to_sym,
+            content: extract_content,
+            tool_calls: extract_tool_calls,
+            tool_call_id: extract_tool_call_id,
+            input_tokens: input_tokens,
+            output_tokens: output_tokens,
+            cached_tokens: cached,
+            cache_creation_tokens: cache_creation,
+            model_id: model_association&.model_id,
+            response_id: resp_id
+          )
+        end
+      end
+
+      # Extends RubyLLM's ActiveRecord ChatMethods to persist response_id
+      module ChatMethodsExtension
+        # Override persist_message_completion to also save response_id
+        def persist_message_completion(message)
+          super
+
+          # After the parent saves, update response_id if the column exists and message has one
+          return unless message
+          return unless message.respond_to?(:response_id) && message.response_id
+          return unless @message.has_attribute?(:response_id)
+
+          @message.update_column(:response_id, message.response_id)
+        end
+      end
+
+      @active_record_extensions_applied = false
+
+      # Apply ActiveRecord extensions for response_id persistence.
+      # Called automatically when ActiveRecord loads, or can be called manually.
+      def self.apply_active_record_extensions!
+        return if @active_record_extensions_applied
+
+        require 'ruby_llm/active_record/message_methods'
+        require 'ruby_llm/active_record/chat_methods'
+
+        RubyLLM::ActiveRecord::MessageMethods.prepend(MessageMethodsExtension)
+        RubyLLM::ActiveRecord::ChatMethods.prepend(ChatMethodsExtension)
+
+        @active_record_extensions_applied = true
+      rescue LoadError, NameError
+        # RubyLLM ActiveRecord support not available, skip silently
+        nil
+      end
+    end
+  end
+end
+
+# Auto-apply extensions when ActiveRecord is loaded in Rails
+if defined?(ActiveSupport.on_load)
+  ActiveSupport.on_load(:active_record) do
+    RubyLLM::Providers::OpenAIResponses.apply_active_record_extensions!
+  end
+end

data/lib/ruby_llm/providers/openai_responses/background.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Background mode support for the OpenAI Responses API.
+      # Handles async responses with polling for long-running tasks.
+      module Background
+        module_function
+
+        # Status constants
+        QUEUED = 'queued'
+        IN_PROGRESS = 'in_progress'
+        COMPLETED = 'completed'
+        FAILED = 'failed'
+        CANCELLED = 'cancelled'
+        INCOMPLETE = 'incomplete'
+
+        TERMINAL_STATUSES = [COMPLETED, FAILED, CANCELLED, INCOMPLETE].freeze
+        PENDING_STATUSES = [QUEUED, IN_PROGRESS].freeze
+
+        # Add background mode to payload
+        # @param payload [Hash] The request payload
+        # @param background [Boolean] Whether to run in background mode
+        # @return [Hash] Updated payload
+        def apply_background_mode(payload, background: false)
+          payload[:background] = background if background
+          payload
+        end
+
+        # Check if response is still pending
+        # @param response [Hash] The API response
+        # @return [Boolean]
+        def pending?(response)
+          status = response['status']
+          PENDING_STATUSES.include?(status)
+        end
+
+        # Check if response is complete (terminal state)
+        # @param response [Hash] The API response
+        # @return [Boolean]
+        def complete?(response)
+          status = response['status']
+          TERMINAL_STATUSES.include?(status)
+        end
+
+        # Check if response was successful
+        # @param response [Hash] The API response
+        # @return [Boolean]
+        def successful?(response)
+          response['status'] == COMPLETED
+        end
+
+        # Check if response failed
+        # @param response [Hash] The API response
+        # @return [Boolean]
+        def failed?(response)
+          response['status'] == FAILED
+        end
+
+        # Get response status
+        # @param response [Hash] The API response
+        # @return [String] The status
+        def status(response)
+          response['status']
+        end
+
+        # Get error information if failed
+        # @param response [Hash] The API response
+        # @return [Hash, nil] Error information
+        def error_info(response)
+          response['error']
+        end
+
+        # URL to retrieve a response by ID
+        # @param response_id [String] The response ID
+        # @return [String] The URL path
+        def retrieve_url(response_id)
+          "responses/#{response_id}"
+        end
+
+        # URL to cancel a response
+        # @param response_id [String] The response ID
+        # @return [String] The URL path
+        def cancel_url(response_id)
+          "responses/#{response_id}/cancel"
+        end
+
+        # URL to list input items for a response
+        # @param response_id [String] The response ID
+        # @return [String] The URL path
+        def input_items_url(response_id)
+          "responses/#{response_id}/input_items"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai_responses/base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # OpenAI Responses API provider for RubyLLM.
+    # Implements the new Responses API which provides built-in tools,
+    # stateful conversations, background mode, and MCP support.
+    #
+    # This base file defines the class structure before modules are loaded
+    # to avoid "superclass mismatch" errors.
+    class OpenAIResponses < Provider
+    end
+  end
+end

data/lib/ruby_llm/providers/openai_responses/built_in_tools.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Built-in tools support for the OpenAI Responses API.
+      # Provides configuration helpers and result parsing for:
+      # - Web Search
+      # - File Search
+      # - Code Interpreter
+      # - Image Generation
+      # - MCP (Model Context Protocol)
+      module BuiltInTools
+        module_function
+
+        # Web Search tool configuration
+        # @param search_context_size [String, nil] 'low', 'medium', or 'high'
+        # @param user_location [Hash, nil] { type: 'approximate', city: '...', country: '...' }
+        def web_search(search_context_size: nil, user_location: nil)
+          tool = { type: 'web_search_preview' }
+          tool[:search_context_size] = search_context_size if search_context_size
+          tool[:user_location] = user_location if user_location
+          tool
+        end
+
+        # File Search tool configuration
+        # @param vector_store_ids [Array<String>] IDs of vector stores to search
+        # @param max_num_results [Integer, nil] Maximum results to return
+        # @param ranking_options [Hash, nil] Ranking configuration
+        def file_search(vector_store_ids:, max_num_results: nil, ranking_options: nil)
+          tool = {
+            type: 'file_search',
+            vector_store_ids: Array(vector_store_ids)
+          }
+          tool[:max_num_results] = max_num_results if max_num_results
+          tool[:ranking_options] = ranking_options if ranking_options
+          tool
+        end
+
+        # Code Interpreter tool configuration
+        # @param container_type [String] 'auto' or specific container type
+        def code_interpreter(container_type: 'auto')
+          {
+            type: 'code_interpreter',
+            container: { type: container_type }
+          }
+        end
+
+        # Image Generation tool configuration
+        # @param partial_images [Integer, nil] Number of partial images during streaming
+        def image_generation(partial_images: nil)
+          tool = { type: 'image_generation' }
+          tool[:partial_images] = partial_images if partial_images
+          tool
+        end
+
+        # MCP (Model Context Protocol) tool configuration
+        # @param server_label [String] Label for the MCP server
+        # @param server_url [String] URL of the MCP server
+        # @param require_approval [String] 'never', 'always', or specific tool patterns
+        # @param allowed_tools [Array<String>, nil] List of allowed tool names
+        # @param headers [Hash, nil] Additional headers for the MCP server
+        def mcp(server_label:, server_url:, require_approval: 'never', allowed_tools: nil, headers: nil)
+          tool = {
+            type: 'mcp',
+            server_label: server_label,
+            server_url: server_url,
+            require_approval: require_approval
+          }
+          tool[:allowed_tools] = allowed_tools if allowed_tools
+          tool[:headers] = headers if headers
+          tool
+        end
+
+        # Computer Use tool configuration (preview)
+        # @param display_width [Integer] Display width in pixels
+        # @param display_height [Integer] Display height in pixels
+        # @param environment [String] 'browser' or 'mac' or 'windows' or 'ubuntu'
+        def computer_use(display_width:, display_height:, environment: 'browser')
+          {
+            type: 'computer_use_preview',
+            display_width: display_width,
+            display_height: display_height,
+            environment: environment
+          }
+        end
+
+        # Parse web search results from output
+        # @param output [Array] Response output array
+        # @return [Array<Hash>] Parsed search results with citations
+        def parse_web_search_results(output)
+          output
+            .select { |item| item['type'] == 'web_search_call' }
+            .map do |item|
+              {
+                id: item['id'],
+                status: item['status'],
+                results: parse_citations(item)
+              }
+            end
+        end
+
+        # Parse file search results from output
+        # @param output [Array] Response output array
+        # @return [Array<Hash>] Parsed file search results
+        def parse_file_search_results(output)
+          output
+            .select { |item| item['type'] == 'file_search_call' }
+            .map do |item|
+              {
+                id: item['id'],
+                status: item['status'],
+                results: item['results'] || []
+              }
+            end
+        end
+
+        # Parse code interpreter results from output
+        # @param output [Array] Response output array
+        # @return [Array<Hash>] Parsed code interpreter results
+        def parse_code_interpreter_results(output)
+          output
+            .select { |item| item['type'] == 'code_interpreter_call' }
+            .map do |item|
+              {
+                id: item['id'],
+                code: item['code'],
+                results: item['results'] || [],
+                container_id: item['container_id']
+              }
+            end
+        end
+
+        # Parse image generation results from output
+        # @param output [Array] Response output array
+        # @return [Array<Hash>] Parsed image generation results
+        def parse_image_generation_results(output)
+          output
+            .select { |item| item['type'] == 'image_generation_call' }
+            .map do |item|
+              {
+                id: item['id'],
+                status: item['status'],
+                result: item['result']
+              }
+            end
+        end
+
+        # Extract all citations from message content
+        # @param content [Array] Message content array
+        # @return [Array<Hash>] All citations/annotations
+        def extract_citations(content)
+          return [] unless content.is_a?(Array)
+
+          content
+            .select { |c| c['type'] == 'output_text' }
+            .flat_map { |c| c['annotations'] || [] }
+            .map do |annotation|
+              {
+                type: annotation['type'],
+                text: annotation['text'],
+                url: annotation['url'],
+                title: annotation['title'],
+                start_index: annotation['start_index'],
+                end_index: annotation['end_index']
+              }.compact
+            end
+        end
+
+        private_class_method def parse_citations(item)
+          return [] unless item['results']
+
+          item['results'].map do |result|
+            {
+              url: result['url'],
+              title: result['title'],
+              snippet: result['snippet']
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end