ask-core 0.2.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27b1acea84966d56137426aa88ddc1cda8f61dd277a37c9c9961f79540c156f2
-  data.tar.gz: 5096b62044dd0110ba21e59642a2af4d2ce149cf7a3e24bf6235cbe025f9412d
+  metadata.gz: 76460c5c6e631cb59ed89bb8fabb48cd52dca8d6930c99e43ec34b8f4b9a0912
+  data.tar.gz: cbd34d8e2dec789316f4b7e7f1aead500dc80983c003fd6a8ef657dfa9c7a299
 SHA512:
-  metadata.gz: 5d92e48754c546c5904f3fec07d398569dadf4c8d70ba8068a098e3e9d2ee363133f5466c08e50402325054241df2b815cf4d53435bca121f6941a92eb20a6d7
-  data.tar.gz: 00752dace3a9a4d017e0af32c8caaf0cbbd2e57af89b9cd797e54a275458ef6e30be7c255c5bc3d39eef7bb0089b67243e40ae0327cce1cfa981034827e3470d
+  metadata.gz: bea59c9b587c6c3f00a2aa4ce4b9052e00af5d4f924eccc395fce73560a99cf7fafa586e813d7b11efbdd74a39e20dc85ca2c6627c49be63256e8485fdf5be16
+  data.tar.gz: feb067f7cc3f11bda5f942614df3717da8e06ceada1a4ad2c92fe07a8c05b613fd240cab929217bb7cebc4f273e7e5e5d7d338ecaefd579b92d3ac3bb61c6b3f

data/CHANGELOG.md

@@ -1,3 +1,68 @@
+## [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
+
+- **Pluggable state abstraction** — `Ask::State::Adapter` defines a unified interface for key-value storage, distributed locking, message queues, and ordered lists. `Ask::State::Memory` provides an in-process, thread-safe implementation backed by Hash.
+
+  ```ruby
+  store = Ask::State::Memory.new
+
+  # Key-value with optional TTL
+  store.set("key", "value", ttl: 60)
+  store.get("key")
+
+  # Distributed locking
+  lock = store.acquire_lock("resource", ttl: 10)
+  store.release_lock("resource", lock)
+
+  # Message queues
+  store.enqueue("queue", { task: "check" })
+  store.dequeue("queue")
+
+  # Ordered lists
+  store.list_append("list", "item", max_length: 100)
+  store.list_range("list", 0, -1)
+  store.list_remove("list", "item")
+  ```
+
+  The adapter pattern mirrors `Ask::Provider` — define the contract in ask-core, provide implementations in separate gems. Production backends (Redis, PostgreSQL) can be added by any gem without modifying ask-core.
+
+  Data types: `Ask::State::Lock` (with `#expired?`), `Ask::State::QueueEntry`.
+
+### Changed
+
+- **ask-agent's `Persistence::Base` now wraps `Ask::State::Adapter`** — session persistence is backed by the unified state interface instead of a standalone abstract class. `Persistence::InMemory` delegates to `Ask::State::Memory`. Backward compatible — no API changes for users.
+
+### Tested
+
+- 34 new tests for `Ask::State::Adapter` + `Ask::State::Memory`: key-value operations, TTL expiry, thread safety, locking semantics, queue FIFO order, list management, adapter subclassing, and the base class contract.
+
 ## [0.2.4] — 2026-07-17
 
 ### 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

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "forwardable"
+
+module Ask
+  # Pluggable state backend for agent sessions, channel providers, and
+  # any other ask-rb component that needs durable key-value storage,
+  # distributed locking, message queues, or ordered lists.
+  #
+  # The {State::Adapter} abstract base defines the contract.
+  # {State::Memory} provides an in-process implementation backed by Hash.
+  # Production apps can provide Redis, PostgreSQL, or other backends by
+  # subclassing {State::Adapter}.
+  #
+  # @example Using the in-memory adapter
+  #   store = Ask::State::Memory.new
+  #   store.set("key", "value")
+  #   store.get("key")     # => "value"
+  #   store.delete("key")
+  #
+  # @example Acquiring a distributed lock
+  #   lock = store.acquire_lock("resource-1", ttl: 10)
+  #   if lock
+  #     begin
+  #       # critical section
+  #     ensure
+  #       store.release_lock("resource-1", lock)
+  #     end
+  #   end
+  #
+  # @example Using a message queue
+  #   store.enqueue("queue-name", { task: "check_health" })
+  #   entry = store.dequeue("queue-name")
+  #   # => { id: "uuid", value: { task: "check_health" }, enqueued_at: timestamp }
+  module State
+    Lock = Data.define(:id, :token, :expires_at) do
+      def expired?(now = Time.now)
+        expires_at && now >= expires_at
+      end
+    end
+
+    QueueEntry = Data.define(:id, :value, :enqueued_at)
+
+    # Abstract base class for state backends.
+    # Subclasses must implement all methods.
+    class Adapter
+      # Key-value storage
+
+      # @param key [String] the key
+      # @return [Object, nil] the stored value, or nil if not found
+      def get(key)
+        raise NotImplementedError
+      end
+
+      # @param key [String] the key
+      # @param value [Object] the value (must be JSON-serializable)
+      # @param ttl [Integer, nil] time-to-live in seconds (nil = no expiry)
+      def set(key, value, ttl: nil)
+        raise NotImplementedError
+      end
+
+      # @param key [String] the key
+      def delete(key)
+        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
+      # @return [Boolean] true if the value was set, false if the key already exists
+      def set_if_not_exists(key, value, ttl: nil)
+        raise NotImplementedError
+      end
+
+      # Distributed locking
+
+      # Acquire a lock for a key. Returns nil if the lock is held by another owner.
+      # @param key [String] the resource to lock
+      # @param ttl [Integer] lock time-to-live in seconds (default 10)
+      # @return [Lock, nil] the lock if acquired, nil if already held
+      def acquire_lock(key, ttl: 10)
+        raise NotImplementedError
+      end
+
+      # Release a lock. Only the lock owner can release it.
+      # @param key [String] the resource to unlock
+      # @param lock [Lock] the lock returned by {#acquire_lock}
+      # @return [Boolean] true if released, false if lock was already expired or not held
+      def release_lock(key, lock)
+        raise NotImplementedError
+      end
+
+      # Message queues
+
+      # Push an item onto a named queue.
+      # @param queue [String] the queue name
+      # @param value [Object] the value to enqueue
+      # @return [QueueEntry] the enqueued entry
+      def enqueue(queue, value)
+        raise NotImplementedError
+      end
+
+      # Pop the next item from a named queue.
+      # @param queue [String] the queue name
+      # @return [QueueEntry, nil] the next entry, or nil if the queue is empty
+      def dequeue(queue)
+        raise NotImplementedError
+      end
+
+      # @param queue [String] the queue name
+      # @return [Integer] the number of items in the queue
+      def queue_depth(queue)
+        raise NotImplementedError
+      end
+
+      # Ordered lists
+
+      # Append a value to an ordered list. Trims to max_length (keeps newest).
+      # @param key [String] the list key
+      # @param value [Object] the value to append
+      # @param max_length [Integer, nil] maximum list length (nil = no limit)
+      def list_append(key, value, max_length: nil)
+        raise NotImplementedError
+      end
+
+      # Return a slice of the list.
+      # @param key [String] the list key
+      # @param start [Integer] starting index (0-based)
+      # @param stop [Integer] ending index (inclusive, -1 for all)
+      # @return [Array<Object>] the list slice
+      def list_range(key, start = 0, stop = -1)
+        raise NotImplementedError
+      end
+
+      # Remove all occurrences of a value from a list.
+      # @param key [String] the list key
+      # @param value [Object] the value to remove
+      # @return [Integer] number of removed elements
+      def list_remove(key, value)
+        raise NotImplementedError
+      end
+
+      # Lifecycle
+
+      # Optional: called when the adapter is no longer needed.
+      def close
+        # no-op by default
+      end
+    end
+
+    # In-process state backend backed by a Hash.
+    # All operations are thread-safe via a Mutex.
+    # Data is not persisted — lost on process exit.
+    class Memory < Adapter
+      def initialize
+        @data = {}
+        @locks = {}
+        @queues = {}
+        @lists = {}
+        @mutex = Mutex.new
+      end
+
+      # -- key-value --
+
+      def get(key)
+        @mutex.synchronize do
+          expiry = @data[key]&.dig(:expires_at)
+          return nil if expiry && Time.now >= expiry
+
+          @data[key]&.dig(:value)
+        end
+      end
+
+      def set(key, value, ttl: nil)
+        @mutex.synchronize do
+          @data[key] = {
+            value: value,
+            expires_at: ttl ? Time.now + ttl : nil
+          }
+        end
+      end
+
+      def delete(key)
+        @mutex.synchronize { @data.delete(key) }
+      end
+
+      def set_if_not_exists(key, value, ttl: nil)
+        @mutex.synchronize do
+          if @data.key?(key)
+            expiry = @data[key][:expires_at]
+            return false if expiry.nil? || Time.now < expiry
+
+            # Key expired — treat as nonexistent
+            @data.delete(key)
+          end
+
+          @data[key] = {
+            value: value,
+            expires_at: ttl ? Time.now + ttl : nil
+          }
+          true
+        end
+      end
+
+      # -- locking --
+
+      def acquire_lock(key, ttl: 10)
+        @mutex.synchronize do
+          existing = @locks[key]
+          if existing.nil? || existing.expired?
+            lock = Lock.new(
+              id: key,
+              token: SecureRandom.hex(16),
+              expires_at: Time.now + ttl
+            )
+            @locks[key] = lock
+            lock
+          end
+        end
+      end
+
+      def release_lock(key, lock)
+        @mutex.synchronize do
+          current = @locks[key]
+          if current && current.token == lock.token && !current.expired?
+            @locks.delete(key)
+            true
+          else
+            false
+          end
+        end
+      end
+
+      # -- queues --
+
+      def enqueue(queue, value)
+        @mutex.synchronize do
+          @queues[queue] ||= []
+          entry = QueueEntry.new(
+            id: SecureRandom.uuid,
+            value: value,
+            enqueued_at: Time.now
+          )
+          @queues[queue] << entry
+          entry
+        end
+      end
+
+      def dequeue(queue)
+        @mutex.synchronize do
+          q = @queues[queue]
+          return nil unless q&.any?
+
+          q.shift
+        end
+      end
+
+      def queue_depth(queue)
+        @mutex.synchronize do
+          (@queues[queue] || []).length
+        end
+      end
+
+      # -- lists --
+
+      def list_append(key, value, max_length: nil)
+        @mutex.synchronize do
+          @lists[key] ||= []
+          @lists[key] << value
+          @lists[key].shift if max_length && @lists[key].length > max_length
+        end
+      end
+
+      def list_range(key, start = 0, stop = -1)
+        @mutex.synchronize do
+          list = @lists[key] || []
+          return list if start == 0 && stop == -1
+
+          stop = list.length - 1 if stop == -1 || stop >= list.length
+          return [] if start > stop
+
+          list[start..stop] || []
+        end
+      end
+
+      def list_remove(key, value)
+        @mutex.synchronize do
+          list = @lists[key]
+          return 0 unless list
+
+          before = list.length
+          list.delete(value)
+          before - list.length
+        end
+      end
+
+      # -- lifecycle --
+
+      def close
+        @mutex.synchronize do
+          @data.clear
+          @locks.clear
+          @queues.clear
+          @lists.clear
+        end
+      end
+    end
+  end
+end

data/lib/ask/version.rb

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

data/lib/ask.rb

@@ -21,3 +21,5 @@ require_relative "ask/stream"
 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.2.5
+  version: 0.4.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -68,7 +68,9 @@ 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
 - lib/ask/tool_def.rb
 - lib/ask/version.rb