ask-core 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f85f689da590da523c0fcf5ead1b02469865eaf957720c8965084d439f69f74
-  data.tar.gz: dec0a975ed1b82346e98a9d84820e8cad192db0f0e308d97a1dcbdc5303ebee9
+  metadata.gz: 384e1b71886280e9db2a3a6d737bc8e272522543715a3b307518eb71ab735957
+  data.tar.gz: 8c66d39ca24f2b7fb8aec39aa5855f3862e2f3f7456c619b11c04903cafb4398
 SHA512:
-  metadata.gz: 4cb0d8b10f05b778fd66717cb54571d486d21cc93ba95334d5ecd3517d8aa4ccacd92b78fa7dfdc26893d89f5871d18593584cf204967f34d64d1545add1efc0
-  data.tar.gz: f00616ed87027aedb9eeadc69445078dd203dee9910dcd014c1c89f6461544241bd1b0e08f6a39c30d60c40452b38f529424c09775e098ed6900aad4b9988279
+  metadata.gz: 10ada0c35161dabb17005329f643a7514df4e67922b8b086728b88207afa670eb7d35e4bc5d10378431d8ff732ed4f44ce24806c5872ae43e8f0e5275c5f52b8
+  data.tar.gz: be4235f9c942e894c83e14859835a43b4017815fc68f5dd11edffe60f46c717fa563fe9fdd3c8160d73d485571f3190fa4c18e8c0d862db6e62bf4b197677a41

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [0.4.0] — 2026-07-21
+
+### Added
+
+- **Provider-executed tools** — `Ask::ProviderTool` value objects for configuring built-in tools that run on the LLM provider's infrastructure (web search, file search, code execution). Supports factory methods for OpenAI's built-in tools.
+
+  ```ruby
+  Ask::ProviderTool.web_search(search_context_size: "high")
+  Ask::ProviderTool.file_search(vector_store_ids: ["vs_abc"], max_num_results: 10)
+  Ask::ProviderTool.code_interpreter(file_ids: ["file_1"])
+  ```
+
+  Provider tools are identified by a fully qualified `id` (e.g. `"openai.web_search"`) and carry provider-specific `args`. They are `frozen` value objects with equality based on `id` + `args`.
+
+### Changed
+
+- **ask-llm-providers OpenAI** — `chat` now splits provider tools from regular tools. When provider tools are present, the Responses API is used instead of Chat Completions. Regular function tools continue to use the existing Chat Completions path.
+- **ask-agent Loop** — `ResponseMessage` now carries `tool_results` for pre-computed provider-executed results. The loop adds them directly to the conversation without local execution, then continues with any remaining user tool calls.
+- **ResponseMessage** — `tool_results` field added with default `{}`. All existing call sites are backward compatible via the custom `initialize` with keyword defaults.
+
+### Tested
+
+- 13 new tests for `Ask::ProviderTool`: creation, factory methods, args, frozen, equality, flags.
+- 13 new integration tests for provider-executed tools: loop handling with mixed tools, only provider tools, tool splitting in OpenAI provider, Responses API tool formatting.
+- Full test suite: 248 ask-core tests, 329 ask-agent tests — 0 failures.
+
 ## [0.3.0] — 2026-07-21
 
 ### Added

data/lib/ask/provider_tool.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Ask
+  # Configuration for a provider-defined or provider-executed tool.
+  #
+  # Provider tools are built-in capabilities that the LLM provider offers
+  # natively — web search, file search, code execution, image generation,
+  # and so on. They are not implemented by user code but by the provider
+  # itself.
+  #
+  # @example Configuring a provider-executed web search
+  #   Ask::ProviderTool.new(
+  #     id: "openai.web_search",
+  #     name: "web_search",
+  #     description: "Search the internet",
+  #     args: { search_context_size: "medium" }
+  #   )
+  #
+  # @example Using shorthand factory methods
+  #   Ask::ProviderTool.web_search(search_context_size: "high")
+  #   Ask::ProviderTool.file_search(max_num_results: 10)
+  class ProviderTool
+    # @return [String] fully qualified tool identifier (e.g. "openai.web_search")
+    attr_reader :id
+
+    # @return [String] short tool name
+    attr_reader :name
+
+    # @return [String] human-readable description
+    attr_reader :description
+
+    # @return [Hash] provider-specific configuration arguments
+    attr_reader :args
+
+    # @return [Boolean] true if the provider handles execution on its side
+    def provider_executed?
+      true
+    end
+
+    # @return [Boolean] true — marks this as a provider tool for routing
+    def provider_tool?
+      true
+    end
+
+    def initialize(id:, name:, description: "", args: {})
+      @id = id
+      @name = name
+      @description = description
+      @args = args.dup.freeze
+      freeze
+    end
+
+    class << self
+      # OpenAI web search tool.
+      # @param search_context_size [String, nil] "low", "medium", or "high"
+      # @param user_location [Hash, nil] approximate location { type: "approximate", country: "US", ... }
+      def web_search(search_context_size: nil, user_location: nil, allowed_domains: nil)
+        args = {}.tap do |h|
+          h[:search_context_size] = search_context_size if search_context_size
+          h[:user_location] = user_location if user_location
+          h[:allowed_domains] = allowed_domains if allowed_domains
+        end
+        new(id: "openai.web_search", name: "web_search", description: "Search the internet for current information", args: args)
+      end
+
+      # OpenAI file search tool. Requires a vector store.
+      # @param vector_store_ids [Array<String>] IDs of vector stores to search
+      # @param max_num_results [Integer, nil] maximum number of results
+      def file_search(vector_store_ids:, max_num_results: nil)
+        args = { vector_store_ids: vector_store_ids }.tap do |h|
+          h[:max_num_results] = max_num_results if max_num_results
+        end
+        new(id: "openai.file_search", name: "file_search", description: "Search through uploaded files", args: args)
+      end
+
+      # OpenAI code interpreter tool.
+      # @param file_ids [Array<String>, nil] IDs of files to make available
+      def code_interpreter(file_ids: nil)
+        args = file_ids ? { file_ids: file_ids } : {}
+        new(id: "openai.code_interpreter", name: "code_interpreter", description: "Execute Python code in a sandboxed environment", args: args)
+      end
+    end
+
+    # Equality based on id + args.
+    def ==(other)
+      return false unless other.is_a?(ProviderTool)
+      id == other.id && args == other.args
+    end
+    alias eql? ==
+
+    def hash
+      [id, args].hash
+    end
+  end
+end

data/lib/ask/state.rb

@@ -65,6 +65,11 @@ module Ask
         raise NotImplementedError
       end
 
+      # Remove all keys from the store.
+      def clear
+        raise NotImplementedError
+      end
+
       # Atomically set a value only if the key does not already exist.
       # @param key [String] the key
       # @param value [Object] the value
@@ -203,6 +208,12 @@ module Ask
         end
       end
 
+      def clear
+        @mutex.synchronize do
+          @data.clear
+        end
+      end
+
       # -- locking --
 
       def acquire_lock(key, ttl: 10)

data/lib/ask/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ask
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/ask.rb

@@ -22,3 +22,4 @@ require_relative "ask/conversation"
 require_relative "ask/provider"
 require_relative "ask/models"
 require_relative "ask/state"
+require_relative "ask/provider_tool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-core
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -68,6 +68,7 @@ files:
 - lib/ask/errors.rb
 - lib/ask/models.rb
 - lib/ask/provider.rb
+- lib/ask/provider_tool.rb
 - lib/ask/result.rb
 - lib/ask/state.rb
 - lib/ask/stream.rb