ruby-pi 0.1.0

data/lib/ruby_pi/llm/gemini.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/llm/gemini.rb
+#
+# LLM provider for Google Gemini. Implements the BaseProvider interface using
+# the Gemini REST API for both synchronous and streaming completions, including
+# tool/function calling support.
+
+module RubyPi
+  module LLM
+    # Google Gemini provider implementation. Communicates with the Gemini
+    # generativelanguage API to generate text completions, handle tool calls,
+    # and stream responses.
+    #
+    # @example Basic usage
+    #   provider = RubyPi::LLM::Gemini.new(
+    #     model: "gemini-2.0-flash",
+    #     api_key: ENV["GEMINI_API_KEY"]
+    #   )
+    #   response = provider.complete(messages: [{ role: "user", content: "Hello!" }])
+    #   puts response.content
+    class Gemini < BaseProvider
+      # Base URL for the Gemini generativelanguage API.
+      BASE_URL = "https://generativelanguage.googleapis.com"
+
+      # API version prefix for endpoint paths.
+      API_VERSION = "v1beta"
+
+      # Creates a new Gemini provider instance.
+      #
+      # @param model [String] the Gemini model identifier (e.g., "gemini-2.0-flash")
+      # @param api_key [String, nil] Gemini API key (falls back to global config)
+      # @param options [Hash] additional options passed to BaseProvider
+      def initialize(model: nil, api_key: nil, **options)
+        super(**options)
+        config = RubyPi.configuration
+        @model = model || config.default_gemini_model
+        @api_key = api_key || config.gemini_api_key
+      end
+
+      # Returns the Gemini model identifier.
+      #
+      # @return [String]
+      def model_name
+        @model
+      end
+
+      # Returns :gemini as the provider identifier.
+      #
+      # @return [Symbol]
+      def provider_name
+        :gemini
+      end
+
+      private
+
+      # Performs the completion request against the Gemini API.
+      #
+      # @param messages [Array<Hash>] conversation messages
+      # @param tools [Array<Hash>] tool definitions
+      # @param stream [Boolean] whether to use streaming
+      # @yield [event] streaming events if stream is true
+      # @return [RubyPi::LLM::Response]
+      def perform_complete(messages:, tools:, stream:, &block)
+        body = build_request_body(messages, tools)
+
+        if stream && block_given?
+          perform_streaming_request(body, &block)
+        else
+          perform_standard_request(body)
+        end
+      end
+
+      # Builds the Gemini API request body from messages and tools.
+      #
+      # @param messages [Array<Hash>] conversation messages
+      # @param tools [Array<Hash>] tool definitions
+      # @return [Hash] the request body
+      def build_request_body(messages, tools)
+        body = {
+          contents: messages.map { |msg| format_message(msg) }
+        }
+
+        unless tools.empty?
+          body[:tools] = [{
+            functionDeclarations: tools.map { |t| format_tool(t) }
+          }]
+        end
+
+        body
+      end
+
+      # Converts a normalized message hash to Gemini's content format.
+      #
+      # @param message [Hash] a message with :role and :content keys
+      # @return [Hash] Gemini-formatted content object
+      def format_message(message)
+        role = message[:role]&.to_s || message["role"]&.to_s || "user"
+        content = message[:content] || message["content"] || ""
+
+        # Gemini uses "user" and "model" roles
+        gemini_role = role == "assistant" ? "model" : role
+
+        {
+          role: gemini_role,
+          parts: [{ text: content.to_s }]
+        }
+      end
+
+      # Converts a tool definition to Gemini's function declaration format.
+      # Accepts either a RubyPi::Tools::Definition or a plain Hash.
+      #
+      # @param tool [RubyPi::Tools::Definition, Hash] tool definition
+      # @return [Hash] Gemini function declaration
+      def format_tool(tool)
+        return tool.to_gemini_format if tool.respond_to?(:to_gemini_format)
+
+        declaration = {
+          name: tool[:name] || tool["name"],
+          description: tool[:description] || tool["description"] || ""
+        }
+
+        params = tool[:parameters] || tool["parameters"]
+        declaration[:parameters] = params if params
+
+        declaration
+      end
+
+      # Executes a standard (non-streaming) request to the Gemini API.
+      #
+      # @param body [Hash] the request body
+      # @return [RubyPi::LLM::Response]
+      def perform_standard_request(body)
+        conn = build_connection(base_url: BASE_URL)
+        url = "/#{API_VERSION}/models/#{@model}:generateContent?key=#{@api_key}"
+
+        response = conn.post(url) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+
+        handle_error_response(response) unless response.success?
+        parse_response(JSON.parse(response.body))
+      end
+
+      # Executes a streaming request to the Gemini API, yielding events.
+      #
+      # @param body [Hash] the request body
+      # @yield [event] StreamEvent objects
+      # @return [RubyPi::LLM::Response] final aggregated response
+      def perform_streaming_request(body, &block)
+        conn = build_connection(base_url: BASE_URL)
+        url = "/#{API_VERSION}/models/#{@model}:streamGenerateContent?key=#{@api_key}&alt=sse"
+
+        accumulated_text = +""
+        accumulated_tool_calls = []
+        usage_data = {}
+
+        response = conn.post(url) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+
+        handle_error_response(response) unless response.success?
+
+        # Parse SSE events from the response body
+        parse_sse_events(response.body) do |data|
+          candidates = data.dig("candidates") || []
+          candidate = candidates.first
+          next unless candidate
+
+          parts = candidate.dig("content", "parts") || []
+          parts.each do |part|
+            if part.key?("text")
+              text_chunk = part["text"]
+              accumulated_text << text_chunk
+              block.call(StreamEvent.new(type: :text_delta, data: text_chunk))
+            elsif part.key?("functionCall")
+              fc = part["functionCall"]
+              tool_call = ToolCall.new(
+                id: "gemini_#{accumulated_tool_calls.length}",
+                name: fc["name"],
+                arguments: fc["args"] || {}
+              )
+              accumulated_tool_calls << tool_call
+              block.call(StreamEvent.new(type: :tool_call_delta, data: tool_call.to_h))
+            end
+          end
+
+          # Capture usage metadata if present
+          if data.key?("usageMetadata")
+            meta = data["usageMetadata"]
+            usage_data = {
+              prompt_tokens: meta["promptTokenCount"],
+              completion_tokens: meta["candidatesTokenCount"],
+              total_tokens: meta["totalTokenCount"]
+            }
+          end
+        end
+
+        # Signal completion
+        block.call(StreamEvent.new(type: :done))
+
+        Response.new(
+          content: accumulated_text.empty? ? nil : accumulated_text,
+          tool_calls: accumulated_tool_calls,
+          usage: usage_data,
+          finish_reason: "stop"
+        )
+      end
+
+      # Parses a Gemini API response hash into a normalized Response object.
+      #
+      # @param data [Hash] parsed JSON response from Gemini
+      # @return [RubyPi::LLM::Response]
+      def parse_response(data)
+        candidates = data["candidates"] || []
+        candidate = candidates.first || {}
+
+        content = nil
+        tool_calls = []
+
+        parts = candidate.dig("content", "parts") || []
+        parts.each do |part|
+          if part.key?("text")
+            content = (content || +"") << part["text"]
+          elsif part.key?("functionCall")
+            fc = part["functionCall"]
+            tool_calls << ToolCall.new(
+              id: "gemini_#{tool_calls.length}",
+              name: fc["name"],
+              arguments: fc["args"] || {}
+            )
+          end
+        end
+
+        # Extract usage metadata
+        usage = {}
+        if data.key?("usageMetadata")
+          meta = data["usageMetadata"]
+          usage = {
+            prompt_tokens: meta["promptTokenCount"],
+            completion_tokens: meta["candidatesTokenCount"],
+            total_tokens: meta["totalTokenCount"]
+          }
+        end
+
+        # Map Gemini finish reason to normalized string
+        finish_reason = candidate["finishReason"]&.downcase
+
+        Response.new(
+          content: content,
+          tool_calls: tool_calls,
+          usage: usage,
+          finish_reason: finish_reason
+        )
+      end
+    end
+  end
+end

data/lib/ruby_pi/llm/model.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/llm/model.rb
+#
+# Represents a model identifier combining a provider and model name. Used as
+# a lightweight descriptor that can be passed around and later instantiated
+# into a full provider instance via the factory method.
+
+module RubyPi
+  module LLM
+    # A model descriptor that pairs a provider identifier with a specific
+    # model name. Use the factory method RubyPi::LLM.model to create provider
+    # instances directly, or instantiate a Model object for deferred construction.
+    #
+    # @example Creating a model descriptor
+    #   model = RubyPi::LLM::Model.new(provider: :gemini, name: "gemini-2.0-flash")
+    #   model.provider  # => :gemini
+    #   model.name       # => "gemini-2.0-flash"
+    #   provider = model.build  # => RubyPi::LLM::Gemini instance
+    #
+    # @example Using the factory shortcut
+    #   provider = RubyPi::LLM.model(:openai, "gpt-4o")
+    class Model
+      # @return [Symbol] the provider identifier (:gemini, :anthropic, :openai)
+      attr_reader :provider
+
+      # @return [String] the model name within the provider
+      attr_reader :name
+
+      # Creates a new Model descriptor.
+      #
+      # @param provider [Symbol, String] provider identifier
+      # @param name [String] model name
+      def initialize(provider:, name:)
+        @provider = provider.to_sym
+        @name = name.to_s
+      end
+
+      # Builds a configured provider instance from this model descriptor.
+      # Delegates to RubyPi::LLM.model for provider construction.
+      #
+      # @param options [Hash] additional options passed to the provider constructor
+      # @return [RubyPi::LLM::BaseProvider] a configured provider instance
+      def build(**options)
+        RubyPi::LLM.model(@provider, @name, **options)
+      end
+
+      # Returns a hash representation of the model descriptor.
+      #
+      # @return [Hash]
+      def to_h
+        { provider: @provider, name: @name }
+      end
+
+      # Returns a human-readable string representation.
+      #
+      # @return [String]
+      def to_s
+        "#<RubyPi::LLM::Model provider=#{@provider.inspect} name=#{@name.inspect}>"
+      end
+
+      alias_method :inspect, :to_s
+
+      # Equality comparison based on provider and name.
+      #
+      # @param other [RubyPi::LLM::Model] another model descriptor
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(Model) && @provider == other.provider && @name == other.name
+      end
+
+      alias_method :eql?, :==
+
+      # Hash code for use in hash keys and sets.
+      #
+      # @return [Integer]
+      def hash
+        [@provider, @name].hash
+      end
+    end
+  end
+end

data/lib/ruby_pi/llm/openai.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/llm/openai.rb
+#
+# LLM provider for OpenAI. Implements the BaseProvider interface using the
+# OpenAI Chat Completions API for both synchronous and streaming completions,
+# including function/tool calling support.
+
+module RubyPi
+  module LLM
+    # OpenAI provider implementation. Communicates with the OpenAI Chat
+    # Completions API to generate text completions, handle tool/function calls,
+    # and stream responses via Server-Sent Events.
+    #
+    # @example Basic usage
+    #   provider = RubyPi::LLM::OpenAI.new(
+    #     model: "gpt-4o",
+    #     api_key: ENV["OPENAI_API_KEY"]
+    #   )
+    #   response = provider.complete(messages: [{ role: "user", content: "Hello!" }])
+    #   puts response.content
+    class OpenAI < BaseProvider
+      # Base URL for the OpenAI API.
+      BASE_URL = "https://api.openai.com"
+
+      # Creates a new OpenAI provider instance.
+      #
+      # @param model [String] the OpenAI model identifier (e.g., "gpt-4o")
+      # @param api_key [String, nil] OpenAI API key (falls back to global config)
+      # @param options [Hash] additional options passed to BaseProvider
+      def initialize(model: nil, api_key: nil, **options)
+        super(**options)
+        config = RubyPi.configuration
+        @model = model || config.default_openai_model
+        @api_key = api_key || config.openai_api_key
+      end
+
+      # Returns the OpenAI model identifier.
+      #
+      # @return [String]
+      def model_name
+        @model
+      end
+
+      # Returns :openai as the provider identifier.
+      #
+      # @return [Symbol]
+      def provider_name
+        :openai
+      end
+
+      private
+
+      # Performs the completion request against the OpenAI API.
+      #
+      # @param messages [Array<Hash>] conversation messages
+      # @param tools [Array<Hash>] tool definitions
+      # @param stream [Boolean] whether to use streaming
+      # @yield [event] streaming events if stream is true
+      # @return [RubyPi::LLM::Response]
+      def perform_complete(messages:, tools:, stream:, &block)
+        body = build_request_body(messages, tools, stream)
+
+        if stream && block_given?
+          perform_streaming_request(body, &block)
+        else
+          perform_standard_request(body)
+        end
+      end
+
+      # Builds the OpenAI Chat Completions request body.
+      #
+      # @param messages [Array<Hash>] conversation messages
+      # @param tools [Array<Hash>] tool definitions
+      # @param stream [Boolean] whether streaming is enabled
+      # @return [Hash] the request body
+      def build_request_body(messages, tools, stream)
+        body = {
+          model: @model,
+          messages: messages.map { |msg| format_message(msg) }
+        }
+
+        body[:stream] = true if stream
+
+        unless tools.empty?
+          body[:tools] = tools.map { |t| format_tool(t) }
+        end
+
+        body
+      end
+
+      # Converts a normalized message hash to OpenAI's message format.
+      #
+      # @param message [Hash] a message with :role and :content keys
+      # @return [Hash] OpenAI-formatted message
+      def format_message(message)
+        {
+          role: (message[:role] || message["role"]).to_s,
+          content: (message[:content] || message["content"]).to_s
+        }
+      end
+
+      # Converts a tool definition to OpenAI's function tool format.
+      # Accepts either a RubyPi::Tools::Definition or a plain Hash.
+      #
+      # @param tool [RubyPi::Tools::Definition, Hash] tool definition
+      # @return [Hash] OpenAI tool definition
+      def format_tool(tool)
+        return tool.to_openai_format if tool.respond_to?(:to_openai_format)
+
+        {
+          type: "function",
+          function: {
+            name: tool[:name] || tool["name"],
+            description: tool[:description] || tool["description"] || "",
+            parameters: tool[:parameters] || tool["parameters"] || { type: "object", properties: {} }
+          }
+        }
+      end
+
+      # Executes a standard (non-streaming) request to the OpenAI API.
+      #
+      # @param body [Hash] the request body
+      # @return [RubyPi::LLM::Response]
+      def perform_standard_request(body)
+        conn = build_connection(
+          base_url: BASE_URL,
+          headers: default_headers
+        )
+
+        response = conn.post("/v1/chat/completions") do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+
+        handle_error_response(response) unless response.success?
+        parse_response(JSON.parse(response.body))
+      end
+
+      # Executes a streaming request to the OpenAI API, yielding events.
+      #
+      # @param body [Hash] the request body
+      # @yield [event] StreamEvent objects
+      # @return [RubyPi::LLM::Response] final aggregated response
+      def perform_streaming_request(body, &block)
+        conn = build_connection(
+          base_url: BASE_URL,
+          headers: default_headers
+        )
+
+        accumulated_text = +""
+        tool_call_accumulators = {}
+        finish_reason = nil
+
+        response = conn.post("/v1/chat/completions") do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+
+        handle_error_response(response) unless response.success?
+
+        # Parse SSE events from the response body
+        parse_sse_events(response.body) do |data|
+          choices = data["choices"] || []
+          choice = choices.first
+          next unless choice
+
+          delta = choice["delta"] || {}
+          finish_reason = choice["finish_reason"] if choice["finish_reason"]
+
+          # Handle text content deltas
+          if delta.key?("content") && delta["content"]
+            text = delta["content"]
+            accumulated_text << text
+            block.call(StreamEvent.new(type: :text_delta, data: text))
+          end
+
+          # Handle tool call deltas
+          if delta.key?("tool_calls")
+            delta["tool_calls"].each do |tc_delta|
+              index = tc_delta["index"] || 0
+
+              # Initialize accumulator for this tool call
+              tool_call_accumulators[index] ||= { id: nil, name: +"", arguments: +"" }
+              acc = tool_call_accumulators[index]
+
+              acc[:id] = tc_delta["id"] if tc_delta["id"]
+
+              if tc_delta.dig("function", "name")
+                acc[:name] << tc_delta["function"]["name"]
+              end
+
+              if tc_delta.dig("function", "arguments")
+                acc[:arguments] << tc_delta["function"]["arguments"]
+              end
+
+              block.call(StreamEvent.new(type: :tool_call_delta, data: {
+                index: index,
+                id: acc[:id],
+                name: acc[:name],
+                arguments_fragment: tc_delta.dig("function", "arguments") || ""
+              }))
+            end
+          end
+        end
+
+        # Build final tool calls from accumulators
+        tool_calls = tool_call_accumulators.sort_by { |k, _| k }.map do |_, acc|
+          arguments = acc[:arguments].empty? ? {} : JSON.parse(acc[:arguments])
+          ToolCall.new(id: acc[:id], name: acc[:name], arguments: arguments)
+        end
+
+        # Signal completion
+        block.call(StreamEvent.new(type: :done))
+
+        Response.new(
+          content: accumulated_text.empty? ? nil : accumulated_text,
+          tool_calls: tool_calls,
+          usage: {},
+          finish_reason: normalize_finish_reason(finish_reason)
+        )
+      end
+
+      # Returns the default HTTP headers required by the OpenAI API.
+      #
+      # @return [Hash] headers hash
+      def default_headers
+        {
+          "Authorization" => "Bearer #{@api_key}"
+        }
+      end
+
+      # Parses an OpenAI Chat Completions response into a normalized Response.
+      #
+      # @param data [Hash] parsed JSON response from OpenAI
+      # @return [RubyPi::LLM::Response]
+      def parse_response(data)
+        choice = (data["choices"] || []).first || {}
+        message = choice["message"] || {}
+
+        content = message["content"]
+        tool_calls = []
+
+        (message["tool_calls"] || []).each do |tc|
+          func = tc["function"] || {}
+          arguments = func["arguments"] ? JSON.parse(func["arguments"]) : {}
+          tool_calls << ToolCall.new(
+            id: tc["id"],
+            name: func["name"],
+            arguments: arguments
+          )
+        end
+
+        # Extract usage
+        usage = {}
+        if data.key?("usage")
+          usage_info = data["usage"]
+          usage = {
+            prompt_tokens: usage_info["prompt_tokens"],
+            completion_tokens: usage_info["completion_tokens"],
+            total_tokens: usage_info["total_tokens"]
+          }
+        end
+
+        Response.new(
+          content: content,
+          tool_calls: tool_calls,
+          usage: usage,
+          finish_reason: normalize_finish_reason(choice["finish_reason"])
+        )
+      end
+
+      # Normalizes OpenAI-specific finish reasons to common values.
+      #
+      # @param reason [String, nil] OpenAI finish reason
+      # @return [String, nil] normalized finish reason
+      def normalize_finish_reason(reason)
+        case reason
+        when "stop" then "stop"
+        when "tool_calls" then "tool_calls"
+        when "length" then "max_tokens"
+        else reason
+        end
+      end
+    end
+  end
+end