ruby-pi 0.1.0

data/lib/ruby_pi/llm/response.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/llm/response.rb
+#
+# Represents a unified response from any LLM provider. Normalizes the varied
+# response formats of Gemini, Anthropic, and OpenAI into a single, consistent
+# structure that calling code can depend on regardless of provider.
+
+module RubyPi
+  module LLM
+    # A normalized response object returned by all LLM providers after a
+    # completion request. Encapsulates the generated text content, any tool
+    # calls the model wants to invoke, token usage statistics, and the reason
+    # the model stopped generating.
+    #
+    # @example Accessing response data
+    #   response = provider.complete(messages: messages)
+    #   puts response.content
+    #   response.tool_calls.each { |tc| handle_tool(tc) }
+    #   puts "Tokens used: #{response.usage[:total_tokens]}"
+    class Response
+      # @return [String, nil] the generated text content from the model
+      attr_reader :content
+
+      # @return [Array<RubyPi::LLM::ToolCall>] tool calls the model wants to invoke
+      attr_reader :tool_calls
+
+      # @return [Hash] token usage statistics with keys like :prompt_tokens,
+      #   :completion_tokens, :total_tokens
+      attr_reader :usage
+
+      # @return [String, nil] the reason the model stopped generating
+      #   (e.g., "stop", "tool_calls", "max_tokens")
+      attr_reader :finish_reason
+
+      # Creates a new Response instance.
+      #
+      # @param content [String, nil] the generated text content
+      # @param tool_calls [Array<RubyPi::LLM::ToolCall>] list of tool invocations
+      # @param usage [Hash] token usage statistics
+      # @param finish_reason [String, nil] why the model stopped generating
+      def initialize(content: nil, tool_calls: [], usage: {}, finish_reason: nil)
+        @content = content
+        @tool_calls = Array(tool_calls)
+        @usage = usage
+        @finish_reason = finish_reason
+      end
+
+      # Returns true if the response includes one or more tool calls.
+      #
+      # @return [Boolean]
+      def tool_calls?
+        !@tool_calls.empty?
+      end
+
+      # Returns a hash representation of the response for serialization.
+      #
+      # @return [Hash] the response as a plain hash
+      def to_h
+        {
+          content: @content,
+          tool_calls: @tool_calls.map(&:to_h),
+          usage: @usage,
+          finish_reason: @finish_reason
+        }
+      end
+
+      # Returns a human-readable string representation of the response.
+      #
+      # @return [String]
+      def to_s
+        parts = []
+        parts << "content=#{@content.inspect}" if @content
+        parts << "tool_calls=#{@tool_calls.length}" if tool_calls?
+        parts << "finish_reason=#{@finish_reason}" if @finish_reason
+        "#<RubyPi::LLM::Response #{parts.join(', ')}>"
+      end
+
+      alias_method :inspect, :to_s
+    end
+  end
+end

data/lib/ruby_pi/llm/stream_event.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/llm/stream_event.rb
+#
+# Represents a single event in a streaming LLM response. When streaming is
+# enabled, the provider yields a sequence of StreamEvent objects to the caller's
+# block, allowing incremental processing of text deltas and tool call fragments.
+
+module RubyPi
+  module LLM
+    # An event yielded during a streaming completion. Events carry a type
+    # indicating what kind of data they contain and a data payload with
+    # the actual content.
+    #
+    # @example Processing streaming events
+    #   provider.complete(messages: msgs, stream: true) do |event|
+    #     case event.type
+    #     when :text_delta
+    #       print event.data
+    #     when :tool_call_delta
+    #       accumulate_tool_call(event.data)
+    #     when :done
+    #       puts "\nStream complete"
+    #     end
+    #   end
+    class StreamEvent
+      # Valid event types for stream events.
+      VALID_TYPES = %i[text_delta tool_call_delta done].freeze
+
+      # @return [Symbol] the type of stream event — one of :text_delta,
+      #   :tool_call_delta, or :done
+      attr_reader :type
+
+      # @return [Object] the event payload. For :text_delta this is a String
+      #   fragment; for :tool_call_delta it is a Hash with partial tool call
+      #   data; for :done it is nil or a final summary hash.
+      attr_reader :data
+
+      # Creates a new StreamEvent instance.
+      #
+      # @param type [Symbol] event type (:text_delta, :tool_call_delta, :done)
+      # @param data [Object] event payload
+      # @raise [ArgumentError] if the type is not recognized
+      def initialize(type:, data: nil)
+        unless VALID_TYPES.include?(type)
+          raise ArgumentError, "Invalid stream event type: #{type.inspect}. Must be one of: #{VALID_TYPES.join(', ')}"
+        end
+
+        @type = type
+        @data = data
+      end
+
+      # Returns true if this is a text delta event.
+      #
+      # @return [Boolean]
+      def text_delta?
+        @type == :text_delta
+      end
+
+      # Returns true if this is a tool call delta event.
+      #
+      # @return [Boolean]
+      def tool_call_delta?
+        @type == :tool_call_delta
+      end
+
+      # Returns true if this is a done/completion event.
+      #
+      # @return [Boolean]
+      def done?
+        @type == :done
+      end
+
+      # Returns a hash representation of the stream event.
+      #
+      # @return [Hash]
+      def to_h
+        { type: @type, data: @data }
+      end
+
+      # Returns a human-readable string representation.
+      #
+      # @return [String]
+      def to_s
+        "#<RubyPi::LLM::StreamEvent type=#{@type.inspect} data=#{@data.inspect}>"
+      end
+
+      alias_method :inspect, :to_s
+    end
+  end
+end

data/lib/ruby_pi/llm/tool_call.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/llm/tool_call.rb
+#
+# Represents a tool (function) call requested by the LLM. When the model
+# decides to invoke a tool, it returns one or more ToolCall objects describing
+# which function to call and with what arguments.
+
+module RubyPi
+  module LLM
+    # A tool call extracted from an LLM response. Contains the unique call ID,
+    # the function name, and the parsed arguments hash. Provider-specific
+    # formats are normalized into this common structure.
+    #
+    # @example Handling a tool call
+    #   response.tool_calls.each do |tool_call|
+    #     result = dispatch(tool_call.name, tool_call.arguments)
+    #     # Feed result back into conversation
+    #   end
+    class ToolCall
+      # @return [String] unique identifier for this tool call, used to match
+      #   results back to the calling context
+      attr_reader :id
+
+      # @return [String] the name of the tool/function to invoke
+      attr_reader :name
+
+      # @return [Hash] the parsed arguments to pass to the tool
+      attr_reader :arguments
+
+      # Creates a new ToolCall instance.
+      #
+      # @param id [String] unique call identifier
+      # @param name [String] tool/function name
+      # @param arguments [Hash] parsed arguments hash
+      def initialize(id:, name:, arguments: {})
+        @id = id
+        @name = name
+        @arguments = arguments.is_a?(Hash) ? arguments : parse_arguments(arguments)
+      end
+
+      # Returns a hash representation of the tool call for serialization.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          id: @id,
+          name: @name,
+          arguments: @arguments
+        }
+      end
+
+      # Returns a human-readable string representation of the tool call.
+      #
+      # @return [String]
+      def to_s
+        "#<RubyPi::LLM::ToolCall id=#{@id.inspect} name=#{@name.inspect} arguments=#{@arguments.inspect}>"
+      end
+
+      alias_method :inspect, :to_s
+
+      private
+
+      # Attempts to parse a JSON string into a Hash. Falls back to wrapping
+      # the raw value in a hash if parsing fails.
+      #
+      # @param raw [String, Object] raw arguments data
+      # @return [Hash] parsed arguments
+      def parse_arguments(raw)
+        return {} if raw.nil? || raw.empty?
+
+        JSON.parse(raw.to_s)
+      rescue JSON::ParserError
+        { "_raw" => raw.to_s }
+      end
+    end
+  end
+end

data/lib/ruby_pi/tools/definition.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/tools/definition.rb
+#
+# RubyPi::Tools::Definition — Describes a callable tool with its metadata.
+#
+# A Definition encapsulates everything needed to declare and invoke a tool:
+# its name, description, category, parameter schema, and implementation block.
+# It also provides format converters for major LLM provider APIs (Gemini,
+# Anthropic, OpenAI) so the same tool definition can be used across providers.
+#
+# Usage:
+#   tool = RubyPi::Tools::Definition.new(
+#     name: "create_post",
+#     description: "Creates a social media post",
+#     category: :content,
+#     parameters: RubyPi::Schema.object(
+#       content: RubyPi::Schema.string("Post content", required: true)
+#     )
+#   ) { |args| { post_id: "123", status: "created" } }
+#
+#   tool.call(content: "Hello world")
+#   # => { post_id: "123", status: "created" }
+
+module RubyPi
+  module Tools
+    class Definition
+      # @return [Symbol] The unique name identifying this tool.
+      attr_reader :name
+
+      # @return [String] A human-readable description of what this tool does.
+      attr_reader :description
+
+      # @return [Symbol, nil] An optional category for grouping related tools.
+      attr_reader :category
+
+      # @return [Hash] A JSON Schema hash describing the tool's parameters.
+      attr_reader :parameters
+
+      # Creates a new tool definition.
+      #
+      # @param name [String, Symbol] Unique identifier for the tool.
+      # @param description [String] What the tool does (shown to the LLM).
+      # @param category [Symbol, nil] Optional grouping category.
+      # @param parameters [Hash] JSON Schema hash for the tool's input parameters.
+      # @yield [Hash] Block that implements the tool logic. Receives a hash of arguments.
+      # @raise [ArgumentError] If name or description is missing, or no block given.
+      def initialize(name:, description:, category: nil, parameters: {}, &block)
+        raise ArgumentError, "Tool name is required" if name.nil? || name.to_s.strip.empty?
+        raise ArgumentError, "Tool description is required" if description.nil? || description.strip.empty?
+        raise ArgumentError, "Tool implementation block is required" unless block_given?
+
+        @name = name.to_sym
+        @description = description
+        @category = category&.to_sym
+        @parameters = parameters
+        @implementation = block
+      end
+
+      # Invokes the tool with the given arguments.
+      #
+      # @param args [Hash] The arguments to pass to the tool implementation.
+      # @return [Object] Whatever the implementation block returns.
+      def call(args = {})
+        @implementation.call(args)
+      end
+
+      # Converts this tool definition to Google Gemini function declaration format.
+      #
+      # Gemini expects:
+      #   { name: "...", description: "...", parameters: { ... } }
+      #
+      # @return [Hash] The tool in Gemini's function declaration format.
+      def to_gemini_format
+        declaration = {
+          name: @name.to_s,
+          description: @description
+        }
+        declaration[:parameters] = @parameters unless @parameters.empty?
+        declaration
+      end
+
+      # Converts this tool definition to Anthropic's tool format.
+      #
+      # Anthropic expects:
+      #   { name: "...", description: "...", input_schema: { ... } }
+      #
+      # @return [Hash] The tool in Anthropic's tool format.
+      def to_anthropic_format
+        tool = {
+          name: @name.to_s,
+          description: @description
+        }
+        tool[:input_schema] = @parameters unless @parameters.empty?
+        tool
+      end
+
+      # Converts this tool definition to OpenAI's function calling format.
+      #
+      # OpenAI expects:
+      #   { type: "function", function: { name: "...", description: "...", parameters: { ... } } }
+      #
+      # @return [Hash] The tool in OpenAI's function format.
+      def to_openai_format
+        function = {
+          name: @name.to_s,
+          description: @description
+        }
+        function[:parameters] = @parameters unless @parameters.empty?
+        {
+          type: "function",
+          function: function
+        }
+      end
+
+      # Provides a human-readable string representation of the definition.
+      #
+      # @return [String] A summary string for debugging/logging.
+      def inspect
+        "#<RubyPi::Tools::Definition name=#{@name.inspect} category=#{@category.inspect}>"
+      end
+    end
+  end
+
+  # Top-level convenience module for defining tools with a short syntax.
+  #
+  # Usage:
+  #   tool = RubyPi::Tool.define(name: "my_tool", description: "Does stuff") { |args| ... }
+  module Tool
+    class << self
+      # Creates a new tool Definition using the same arguments as Definition.new.
+      #
+      # This is the primary public API for defining tools. It provides a cleaner
+      # entry point than instantiating Definition directly.
+      #
+      # @param (see RubyPi::Tools::Definition#initialize)
+      # @return [RubyPi::Tools::Definition] The constructed tool definition.
+      def define(name:, description:, category: nil, parameters: {}, &block)
+        Tools::Definition.new(
+          name: name,
+          description: description,
+          category: category,
+          parameters: parameters,
+          &block
+        )
+      end
+    end
+  end
+end

data/lib/ruby_pi/tools/executor.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/tools/executor.rb
+#
+# RubyPi::Tools::Executor — Executes tool calls in parallel or sequentially.
+#
+# The Executor takes a Registry of tools and a list of tool call requests,
+# dispatching each call to the appropriate tool. In `:parallel` mode it uses
+# `concurrent-ruby`'s thread pool (Concurrent::Future) to run tools concurrently.
+# In `:sequential` mode, tools are executed one after another.
+#
+# Each execution is wrapped in error handling: if a tool raises an exception,
+# the error is captured in a Result with `success: false`. A configurable
+# per-tool timeout (default 30 seconds) prevents runaway executions.
+#
+# Usage:
+#   executor = RubyPi::Tools::Executor.new(registry, mode: :parallel, timeout: 30)
+#   results = executor.execute([
+#     { name: "create_post", arguments: { content: "Hello" } },
+#     { name: "get_analytics", arguments: { period: "7d" } }
+#   ])
+#   # => Array of RubyPi::Tools::Result
+
+require "concurrent"
+
+module RubyPi
+  module Tools
+    class Executor
+      # Default timeout for each tool execution, in seconds.
+      DEFAULT_TIMEOUT = 30
+
+      # @return [Symbol] The execution mode (:parallel or :sequential).
+      attr_reader :mode
+
+      # @return [Numeric] The per-tool timeout in seconds.
+      attr_reader :timeout
+
+      # Creates a new Executor.
+      #
+      # @param registry [RubyPi::Tools::Registry] The registry to look up tools from.
+      # @param mode [Symbol] Execution mode — :parallel or :sequential.
+      # @param timeout [Numeric] Per-tool timeout in seconds (default: 30).
+      # @raise [ArgumentError] If mode is not :parallel or :sequential.
+      def initialize(registry, mode: :parallel, timeout: DEFAULT_TIMEOUT)
+        unless %i[parallel sequential].include?(mode)
+          raise ArgumentError, "Mode must be :parallel or :sequential, got #{mode.inspect}"
+        end
+
+        @registry = registry
+        @mode = mode
+        @timeout = timeout
+      end
+
+      # Executes a list of tool calls and returns their results.
+      #
+      # Each call is a hash with `:name` (String or Symbol) and `:arguments` (Hash).
+      # Tools are looked up in the registry; if a tool is not found, a failure
+      # Result is returned for that call.
+      #
+      # @param calls [Array<Hash>] Tool call requests, each with :name and :arguments.
+      # @return [Array<RubyPi::Tools::Result>] Results in the same order as the calls.
+      def execute(calls)
+        case @mode
+        when :parallel
+          execute_parallel(calls)
+        when :sequential
+          execute_sequential(calls)
+        end
+      end
+
+      private
+
+      # Executes tool calls sequentially, one after another.
+      #
+      # @param calls [Array<Hash>] The tool call requests.
+      # @return [Array<RubyPi::Tools::Result>] Ordered results.
+      def execute_sequential(calls)
+        calls.map { |call| execute_single(call) }
+      end
+
+      # Executes tool calls in parallel using concurrent-ruby Futures.
+      #
+      # Each call is dispatched as a Future on the global I/O thread pool.
+      # Results are collected in order, respecting the per-tool timeout.
+      #
+      # @param calls [Array<Hash>] The tool call requests.
+      # @return [Array<RubyPi::Tools::Result>] Ordered results.
+      def execute_parallel(calls)
+        futures = calls.map do |call|
+          Concurrent::Future.execute(executor: :io) do
+            execute_single(call)
+          end
+        end
+
+        # Collect results, respecting the configured timeout for each future.
+        futures.map do |future|
+          future.value(@timeout) || Result.new(
+            name: "unknown",
+            success: false,
+            error: "Tool execution timed out after #{@timeout}s",
+            duration_ms: @timeout * 1000.0
+          )
+        end
+      end
+
+      # Executes a single tool call with error handling and timing.
+      #
+      # @param call [Hash] A tool call with :name and :arguments keys.
+      # @return [RubyPi::Tools::Result] The execution result.
+      def execute_single(call)
+        tool_name = (call[:name] || call["name"]).to_s
+        arguments = call[:arguments] || call["arguments"] || {}
+
+        tool = @registry.find(tool_name)
+
+        # Return an error result if the tool is not registered
+        unless tool
+          return Result.new(
+            name: tool_name,
+            success: false,
+            error: "Tool '#{tool_name}' not found in registry",
+            duration_ms: 0.0
+          )
+        end
+
+        # Execute the tool with timeout and error handling
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          value = Timeout.timeout(@timeout) do
+            tool.call(arguments)
+          end
+          elapsed_ms = elapsed_since(start_time)
+
+          Result.new(
+            name: tool_name,
+            success: true,
+            value: value,
+            duration_ms: elapsed_ms
+          )
+        rescue Timeout::Error
+          elapsed_ms = elapsed_since(start_time)
+          Result.new(
+            name: tool_name,
+            success: false,
+            error: "Tool '#{tool_name}' timed out after #{@timeout}s",
+            duration_ms: elapsed_ms
+          )
+        rescue StandardError => e
+          elapsed_ms = elapsed_since(start_time)
+          Result.new(
+            name: tool_name,
+            success: false,
+            error: "#{e.class}: #{e.message}",
+            duration_ms: elapsed_ms
+          )
+        end
+      end
+
+      # Calculates milliseconds elapsed since a monotonic clock timestamp.
+      #
+      # @param start_time [Float] The start timestamp from Process.clock_gettime.
+      # @return [Float] Elapsed time in milliseconds.
+      def elapsed_since(start_time)
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+      end
+    end
+  end
+end

data/lib/ruby_pi/tools/registry.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/tools/registry.rb
+#
+# RubyPi::Tools::Registry — A thread-safe store for tool definitions.
+#
+# The Registry holds a collection of tool definitions and provides methods
+# for looking them up by name, filtering by category, and extracting subsets.
+# It uses a Mutex for thread safety when registering tools concurrently.
+#
+# Usage:
+#   registry = RubyPi::Tools::Registry.new
+#   registry.register(my_tool)
+#   registry.find(:my_tool)            # => Definition or nil
+#   registry.by_category(:content)     # => [Definition, ...]
+#   registry.subset([:tool_a, :tool_b])# => Registry (new instance)
+#   registry.names                     # => [:tool_a, :tool_b, ...]
+
+module RubyPi
+  module Tools
+    class Registry
+      # Creates a new, empty Registry.
+      def initialize
+        @tools = {}
+        @mutex = Mutex.new
+      end
+
+      # Registers a tool definition in the registry.
+      #
+      # If a tool with the same name already exists, it will be overwritten
+      # and a warning is emitted to stderr.
+      #
+      # @param tool [RubyPi::Tools::Definition] The tool to register.
+      # @return [RubyPi::Tools::Definition] The registered tool.
+      # @raise [ArgumentError] If the argument is not a Definition.
+      def register(tool)
+        unless tool.is_a?(RubyPi::Tools::Definition)
+          raise ArgumentError, "Expected a RubyPi::Tools::Definition, got #{tool.class}"
+        end
+
+        @mutex.synchronize do
+          if @tools.key?(tool.name)
+            warn "RubyPi::Tools::Registry: overwriting existing tool '#{tool.name}'"
+          end
+          @tools[tool.name] = tool
+        end
+
+        tool
+      end
+
+      # Finds a tool by name.
+      #
+      # @param name [String, Symbol] The name of the tool to look up.
+      # @return [RubyPi::Tools::Definition, nil] The tool, or nil if not found.
+      def find(name)
+        @tools[name.to_sym]
+      end
+
+      # Returns a new Registry containing only the tools with the given names.
+      #
+      # Tools that are not found in this registry are silently skipped.
+      #
+      # @param names [Array<String, Symbol>] The tool names to include.
+      # @return [RubyPi::Tools::Registry] A new registry with the matching tools.
+      def subset(names)
+        sub = Registry.new
+        names.each do |name|
+          tool = find(name)
+          sub.register(tool) if tool
+        end
+        sub
+      end
+
+      # Returns all tools that belong to the given category.
+      #
+      # @param category [Symbol, String] The category to filter by.
+      # @return [Array<RubyPi::Tools::Definition>] Tools matching the category.
+      def by_category(category)
+        cat = category.to_sym
+        @tools.values.select { |tool| tool.category == cat }
+      end
+
+      # Returns all registered tool definitions.
+      #
+      # @return [Array<RubyPi::Tools::Definition>] All tools in registration order.
+      def all
+        @tools.values
+      end
+
+      # Returns the names of all registered tools.
+      #
+      # @return [Array<Symbol>] An array of tool name symbols.
+      def names
+        @tools.keys
+      end
+
+      # Returns the number of registered tools.
+      #
+      # @return [Integer] The count of tools.
+      def size
+        @tools.size
+      end
+
+      # Checks whether a tool with the given name is registered.
+      #
+      # @param name [String, Symbol] The tool name to check.
+      # @return [Boolean] true if the tool exists in the registry.
+      def registered?(name)
+        @tools.key?(name.to_sym)
+      end
+
+      # Provides a human-readable string representation.
+      #
+      # @return [String] Summary of the registry contents.
+      def inspect
+        "#<RubyPi::Tools::Registry tools=#{names.inspect}>"
+      end
+    end
+  end
+end