ruby_llm-responses_api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba5d18029ff9e07a0577fa0fc92b5946fe0b43768e495b5550dc6e3b396520b5
-  data.tar.gz: 67f47ef8f9ca80c54ad4765f0ade6f84a2dbdc04dfc9c9e42136c5c5aa8d1fe3
+  metadata.gz: '09bb1acfd81c2fac2bfecfbaae9780ca64a3d6e13f1692237df82372f42f9263'
+  data.tar.gz: bcfcbd5d83280b319748b58ae2533f8963d0a4eeb8c829bd645cfe5c08245ff0
 SHA512:
-  metadata.gz: d943d82abf6f1afe6c268fbdbc8b9c0179321f67f188c3c1c25058387591673e91356616b1fafdf868da79ee1084aca90ad0117d0835fcd3dd0a238fb96cb712
-  data.tar.gz: 6b5906f1a604543b7a7cd34e25eb21faf500b2dd14558b174c6165da60cad656576b12af5e72cc49cd6960e9ad5e1210a6836bcc706be92e0b9ac77fea45c3ca
+  metadata.gz: 1f1f210817358d55bb76ad1169e7ffcbb510b54d57111aee18c2aa748a5ad0a1c8b3bb10b0b7e54a4d767234bd388c6936b2ab15c0c1ae8fa7ae8370e91e57b6
+  data.tar.gz: 047b530a9923948c8c25813192566c27a94dad2954ff3fbf26dfa14944a52f6a5df4a6d8839ad94ca9447194f3a1eea7b8ca46fec07e036bf3b9776465d10596

data/CHANGELOG.md

@@ -5,6 +5,31 @@ 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] - 2026-02-11
+
+### Added
+
+- **Shell tool** support for executing commands in hosted or local terminal environments
+  - Auto-provisioned containers (`container_auto`), reusable containers (`container_reference`), and local execution (`local`)
+  - Container networking with domain allowlists and domain-scoped secrets
+  - Configurable memory limits (`1g`, `4g`, `16g`, `64g`)
+  - `BuiltInTools.shell` helper and `parse_shell_call_results` parser
+- **Server-side compaction** for multi-hour agent runs without hitting context limits
+  - `Compaction.compaction_params(compact_threshold:)` helper
+  - Pass via `chat.with_params(context_management: [{ type: 'compaction', compact_threshold: 200_000 }])`
+- **Containers API** for managing persistent execution environments
+  - `create_container`, `retrieve_container`, `delete_container`
+  - `list_container_files`, `retrieve_container_file`, `retrieve_container_file_content`
+- **Apply Patch tool** for structured diff-based file editing
+  - `BuiltInTools.apply_patch` helper and `parse_apply_patch_results` parser
+
+## [0.2.0] - 2026-01-15
+
+### Added
+
+- Legacy ActiveRecord support
+- CI compatibility fixes
+
 ## [0.1.0] - 2025-01-03
 
 ### Added

data/README.md

@@ -60,13 +60,17 @@ chat.ask("What's my name?")  # => "Alice"
 
 ## Built-in Tools
 
-The Responses API provides built-in tools that don't require custom implementation.
+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.
 
 ### Web Search
 
 ```ruby
 chat.with_params(tools: [{ type: 'web_search_preview' }])
 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])
 ```
 
 ### Code Interpreter
@@ -87,21 +91,181 @@ chat.with_params(tools: [{ type: 'file_search', vector_store_ids: ['vs_abc123']
 chat.ask("What does the documentation say about authentication?")
 ```
 
+### Shell
+
+Execute commands in hosted containers or local terminal environments. Requires GPT-5 family models.
+
+```ruby
+# Auto-provisioned container (default)
+chat = RubyLLM.chat(model: 'gpt-5.2', provider: :openai_responses)
+chat.with_params(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])
+
+# Reuse an existing container
+tool = RubyLLM::ResponsesAPI::BuiltInTools.shell(container_id: 'cntr_abc123')
+
+# With networking (allow specific domains)
+tool = RubyLLM::ResponsesAPI::BuiltInTools.shell(
+  network_policy: {
+    type: 'allowlist',
+    allowed_domains: ['pypi.org', 'github.com'],
+    domain_secrets: [
+      { domain: 'github.com', name: 'GITHUB_TOKEN', value: ENV['GITHUB_TOKEN'] }
+    ]
+  }
+)
+
+# With memory limit
+tool = RubyLLM::ResponsesAPI::BuiltInTools.shell(memory_limit: '4g')
+
+# Local execution (you handle running commands yourself)
+tool = RubyLLM::ResponsesAPI::BuiltInTools.shell(environment_type: 'local')
+```
+
+### Apply Patch
+
+Structured diff-based file editing. Requires GPT-5 family models.
+
+```ruby
+chat = RubyLLM.chat(model: 'gpt-5.2', provider: :openai_responses)
+chat.with_params(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])
+```
+
+### Image Generation
+
+```ruby
+chat.with_params(tools: [{ type: 'image_generation' }])
+chat.ask("Generate an image of a sunset over mountains")
+```
+
+### MCP (Model Context Protocol)
+
+```ruby
+tool = RubyLLM::ResponsesAPI::BuiltInTools.mcp(
+  server_label: 'github',
+  server_url: 'https://api.github.com/mcp',
+  require_approval: 'never'
+)
+chat.with_params(tools: [tool])
+```
+
 ### Combining Tools
 
 ```ruby
 chat.with_params(tools: [
   { type: 'web_search_preview' },
-  { type: 'code_interpreter' }
+  { type: 'code_interpreter' },
+  { type: 'shell', environment: { type: 'container_auto' } }
 ])
-chat.ask("Find the latest Bitcoin price and plot a chart")
+chat.ask("Research the latest sorting algorithms and benchmark them")
+```
+
+## Server-Side Compaction
+
+For multi-hour agent runs, enable server-side compaction to automatically compress conversation context when it exceeds a token threshold:
+
+```ruby
+chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
+
+# Pass directly
+chat.with_params(
+  context_management: [{ type: 'compaction', compact_threshold: 200_000 }]
+)
+
+# Or use the helper
+chat.with_params(
+  **RubyLLM::ResponsesAPI::Compaction.compaction_params(compact_threshold: 150_000)
+)
+
+# Now run a long agent loop without worrying about context limits
+loop do
+  response = chat.ask(next_prompt)
+  break if done?(response)
+end
+```
+
+When the token count crosses the threshold, the server automatically compacts the conversation. The compacted state is carried forward transparently via `previous_response_id`.
+
+## Containers API
+
+Manage persistent execution environments for the shell tool and code interpreter:
+
+```ruby
+chat = RubyLLM.chat(model: 'gpt-5.2', provider: :openai_responses)
+provider = chat.instance_variable_get(:@provider)
+
+# Create a container
+container = provider.create_container(
+  name: 'my-analysis-env',
+  expires_after: { anchor: 'last_active_at', minutes: 60 },
+  memory_limit: '4g'
+)
+
+# Use it with the shell tool
+tool = RubyLLM::ResponsesAPI::BuiltInTools.shell(container_id: container['id'])
+chat.with_params(tools: [tool])
+chat.ask("Install pandas and run my analysis script")
+
+# List files created in the container
+files = provider.list_container_files(container['id'])
+
+# Retrieve a specific file
+content = provider.retrieve_container_file_content(container['id'], file_id)
+
+# Clean up
+provider.delete_container(container['id'])
+```
+
+## Background Mode
+
+For long-running tasks:
+
+```ruby
+chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
+chat.with_params(background: true)
+response = chat.ask("Analyze this large dataset...")
+
+# Poll for completion
+provider = chat.instance_variable_get(:@provider)
+result = provider.poll_response(response.response_id, interval: 2.0) do |status|
+  puts "Status: #{status['status']}"
+end
+```
+
+## Parsing Built-in Tool Results
+
+When the API returns results from built-in tools, use the parsers to extract structured data:
+
+```ruby
+# Access raw response output (available via response.raw)
+output = response.raw.body['output']
+
+# Parse results by tool type
+web_results    = RubyLLM::ResponsesAPI::BuiltInTools.parse_web_search_results(output)
+code_results   = RubyLLM::ResponsesAPI::BuiltInTools.parse_code_interpreter_results(output)
+file_results   = RubyLLM::ResponsesAPI::BuiltInTools.parse_file_search_results(output)
+shell_results  = RubyLLM::ResponsesAPI::BuiltInTools.parse_shell_call_results(output)
+patch_results  = RubyLLM::ResponsesAPI::BuiltInTools.parse_apply_patch_results(output)
+image_results  = RubyLLM::ResponsesAPI::BuiltInTools.parse_image_generation_results(output)
+citations      = RubyLLM::ResponsesAPI::BuiltInTools.extract_citations(message_content)
 ```
 
 ## Why Use the Responses API?
 
-- **Built-in tools** - Web search, code execution, file search without custom implementation
+- **Built-in tools** - Web search, code execution, file search, shell, apply patch 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
+- **Server-side compaction** - Run multi-hour agent sessions without hitting context limits
+- **Containers** - Persistent execution environments with networking and file management
 
 ## License
 

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

@@ -85,6 +85,31 @@ module RubyLLM
           }
         end
 
+        # Shell tool configuration
+        # @param environment_type [String] 'container_auto', 'container_reference', or 'local'
+        # @param container_id [String, nil] Container ID for 'container_reference' type
+        # @param network_policy [Hash, nil] Network policy (e.g. { type: 'allowlist', allowed_domains: [...] })
+        # @param memory_limit [String, nil] Memory limit: '1g', '4g', '16g', '64g'
+        def shell(environment_type: 'container_auto', container_id: nil,
+                  network_policy: nil, memory_limit: nil)
+          env = if container_id
+                  { type: 'container_reference', container_id: container_id }
+                else
+                  { type: environment_type }
+                end
+
+          env[:network_policy] = network_policy if network_policy
+          env[:memory_limit] = memory_limit if memory_limit
+
+          { type: 'shell', environment: env }
+        end
+
+        # Apply Patch tool configuration
+        # Enables the model to create, update, and delete files using structured diffs.
+        def apply_patch
+          { type: 'apply_patch' }
+        end
+
         # Parse web search results from output
         # @param output [Array] Response output array
         # @return [Array<Hash>] Parsed search results with citations
@@ -146,6 +171,39 @@ module RubyLLM
             end
         end
 
+        # Parse apply_patch call results from output
+        # @param output [Array] Response output array
+        # @return [Array<Hash>] Parsed apply_patch call results
+        def parse_apply_patch_results(output)
+          output
+            .select { |item| item['type'] == 'apply_patch_call' }
+            .map do |item|
+              {
+                id: item['id'],
+                call_id: item['call_id'],
+                status: item['status'],
+                operation: item['operation']
+              }
+            end
+        end
+
+        # Parse shell call results from output
+        # @param output [Array] Response output array
+        # @return [Array<Hash>] Parsed shell call results
+        def parse_shell_call_results(output)
+          output
+            .select { |item| item['type'] == 'shell_call' }
+            .map do |item|
+              {
+                id: item['id'],
+                call_id: item['call_id'],
+                status: item['status'],
+                action: item['action'],
+                container_id: item['container_id']
+              }
+            end
+        end
+
         # Extract all citations from message content
         # @param content [Array] Message content array
         # @return [Array<Hash>] All citations/annotations

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Server-side compaction support for long-running agent sessions.
+      # Automatically compacts conversation context when token count exceeds threshold.
+      module Compaction
+        module_function
+
+        # Build context_management parameter for compaction
+        # @param compact_threshold [Integer] Token count threshold to trigger compaction (minimum 1000)
+        # @return [Hash] Parameters to merge into request payload via with_params
+        def compaction_params(compact_threshold: 200_000)
+          {
+            context_management: [
+              { type: 'compaction', compact_threshold: compact_threshold }
+            ]
+          }
+        end
+
+        # Apply compaction settings to payload
+        # @param payload [Hash] The request payload
+        # @param params [Hash] Additional parameters that may contain compaction options
+        # @return [Hash] Updated payload with context_management
+        def apply_compaction(payload, params)
+          if params[:compact_threshold]
+            payload[:context_management] = [
+              { type: 'compaction', compact_threshold: params[:compact_threshold] }
+            ]
+          elsif params[:context_management]
+            payload[:context_management] = params[:context_management]
+          end
+
+          payload
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Containers API support for managing persistent execution environments.
+      # Containers can be used with the shell tool and code interpreter.
+      module Containers
+        module_function
+
+        # URL helpers
+        def containers_url
+          'containers'
+        end
+
+        def container_url(container_id)
+          "containers/#{container_id}"
+        end
+
+        def container_files_url(container_id)
+          "containers/#{container_id}/files"
+        end
+
+        def container_file_url(container_id, file_id)
+          "containers/#{container_id}/files/#{file_id}"
+        end
+
+        def container_file_content_url(container_id, file_id)
+          "containers/#{container_id}/files/#{file_id}/content"
+        end
+
+        # Build create container payload
+        # @param name [String, nil] Name for the container
+        # @param expires_after [Hash, nil] Expiry config, e.g. { anchor: 'last_active_at', minutes: 60 }
+        # @param file_ids [Array<String>, nil] Files to copy into the container
+        # @param memory_limit [String, nil] Memory limit: '1g', '4g', '16g', '64g'
+        # @return [Hash] Create container payload
+        def create_payload(name: nil, expires_after: nil, file_ids: nil, memory_limit: nil)
+          payload = {}
+          payload[:name] = name if name
+          payload[:expires_after] = expires_after if expires_after
+          payload[:file_ids] = file_ids if file_ids
+          payload[:memory_limit] = memory_limit if memory_limit
+          payload
+        end
+      end
+    end
+  end
+end

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

@@ -21,7 +21,9 @@ module RubyLLM
           file_search: ->(vector_store_ids) { { type: 'file_search', vector_store_ids: vector_store_ids } },
           code_interpreter: { type: 'code_interpreter', container: { type: 'auto' } },
           image_generation: { type: 'image_generation' },
-          computer_use: ->(opts) { { type: 'computer_use_preview', **opts } }
+          computer_use: ->(opts) { { type: 'computer_use_preview', **opts } },
+          shell: { type: 'shell', environment: { type: 'container_auto' } },
+          apply_patch: { type: 'apply_patch' }
         }.freeze
 
         def tool_for(tool)
@@ -187,6 +189,24 @@ module RubyLLM
           tool[:headers] = headers if headers
           tool
         end
+
+        def shell_tool(environment_type: 'container_auto', container_id: nil,
+                        network_policy: nil, memory_limit: nil)
+          env = if container_id
+                  { type: 'container_reference', container_id: container_id }
+                else
+                  { type: environment_type }
+                end
+
+          env[:network_policy] = network_policy if network_policy
+          env[:memory_limit] = memory_limit if memory_limit
+
+          { type: 'shell', environment: env }
+        end
+
+        def apply_patch_tool
+          { type: 'apply_patch' }
+        end
       end
     end
   end

data/lib/ruby_llm/providers/openai_responses.rb

@@ -44,7 +44,7 @@ module RubyLLM
       # @param response_id [String] The response ID to delete
       # @return [Hash] The deletion result
       def delete_response(response_id)
-        response = @connection.delete(Background.retrieve_url(response_id))
+        response = delete_request(Background.retrieve_url(response_id))
         response.body
       end
 
@@ -76,6 +76,77 @@ module RubyLLM
         end
       end
 
+      # --- Container Management ---
+
+      # Create a new container
+      # @param name [String, nil] Container name
+      # @param expires_after [Hash, nil] Expiry configuration
+      # @param file_ids [Array<String>, nil] File IDs to copy into container
+      # @param memory_limit [String, nil] Memory limit: '1g', '4g', '16g', '64g'
+      # @return [Hash] Created container data
+      def create_container(name: nil, expires_after: nil, file_ids: nil, memory_limit: nil)
+        payload = Containers.create_payload(
+          name: name, expires_after: expires_after,
+          file_ids: file_ids, memory_limit: memory_limit
+        )
+        response = @connection.post(Containers.containers_url, payload)
+        response.body
+      end
+
+      # Retrieve a container by ID
+      # @param container_id [String] The container ID
+      # @return [Hash] Container data
+      def retrieve_container(container_id)
+        response = @connection.get(Containers.container_url(container_id))
+        response.body
+      end
+
+      # Delete a container
+      # @param container_id [String] The container ID
+      # @return [Hash] Deletion result
+      def delete_container(container_id)
+        response = delete_request(Containers.container_url(container_id))
+        response.body
+      end
+
+      # List files in a container
+      # @param container_id [String] The container ID
+      # @return [Hash] File listing
+      def list_container_files(container_id)
+        response = @connection.get(Containers.container_files_url(container_id))
+        response.body
+      end
+
+      # Retrieve a specific file from a container
+      # @param container_id [String] The container ID
+      # @param file_id [String] The file ID
+      # @return [Hash] File metadata
+      def retrieve_container_file(container_id, file_id)
+        response = @connection.get(Containers.container_file_url(container_id, file_id))
+        response.body
+      end
+
+      # Get file content from a container
+      # @param container_id [String] The container ID
+      # @param file_id [String] The file ID
+      # @return [String] File content
+      def retrieve_container_file_content(container_id, file_id)
+        response = @connection.get(Containers.container_file_content_url(container_id, file_id))
+        response.body
+      end
+
+      private
+
+      # DELETE request via the underlying Faraday connection
+      # RubyLLM::Connection only exposes get/post, so we use Faraday directly
+      def delete_request(url)
+        @connection.connection.delete(url) do |req|
+          req.headers.merge!(headers)
+        end
+      end
+
+      public
+
       class << self
         def capabilities
           OpenAIResponses::Capabilities

data/lib/rubyllm_responses_api.rb

@@ -17,6 +17,8 @@ require_relative 'ruby_llm/providers/openai_responses/chat'
 require_relative 'ruby_llm/providers/openai_responses/built_in_tools'
 require_relative 'ruby_llm/providers/openai_responses/state'
 require_relative 'ruby_llm/providers/openai_responses/background'
+require_relative 'ruby_llm/providers/openai_responses/compaction'
+require_relative 'ruby_llm/providers/openai_responses/containers'
 require_relative 'ruby_llm/providers/openai_responses/message_extension'
 require_relative 'ruby_llm/providers/openai_responses/model_registry'
 require_relative 'ruby_llm/providers/openai_responses/active_record_extension'
@@ -34,11 +36,13 @@ RubyLLM::Providers::OpenAIResponses::ModelRegistry.register_all!
 module RubyLLM
   # ResponsesAPI namespace for direct access to helpers and version
   module ResponsesAPI
-    VERSION = '0.1.0'
+    VERSION = '0.3.0'
 
     # Shorthand access to built-in tool helpers
     BuiltInTools = Providers::OpenAIResponses::BuiltInTools
     State = Providers::OpenAIResponses::State
     Background = Providers::OpenAIResponses::Background
+    Compaction = Providers::OpenAIResponses::Compaction
+    Containers = Providers::OpenAIResponses::Containers
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-responses_api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chris Hasinski
@@ -122,8 +122,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 description: A RubyLLM provider that implements OpenAI's Responses API, providing
-  access to built-in tools (web search, code interpreter, file search), stateful conversations,
-  background mode, and MCP support.
+  access to built-in tools (web search, code interpreter, file search, shell, apply
+  patch), stateful conversations, server-side compaction, containers API, background
+  mode, and MCP support.
 email:
 - krzysztof.hasinski@gmail.com
 executables: []
@@ -141,6 +142,8 @@ files:
 - lib/ruby_llm/providers/openai_responses/built_in_tools.rb
 - lib/ruby_llm/providers/openai_responses/capabilities.rb
 - lib/ruby_llm/providers/openai_responses/chat.rb
+- lib/ruby_llm/providers/openai_responses/compaction.rb
+- lib/ruby_llm/providers/openai_responses/containers.rb
 - lib/ruby_llm/providers/openai_responses/media.rb
 - lib/ruby_llm/providers/openai_responses/message_extension.rb
 - lib/ruby_llm/providers/openai_responses/model_registry.rb