llm_gateway 0.2.0 → 0.4.0

data/Rakefile

@@ -10,10 +10,9 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 begin
-  require "gem/release"
-
   desc "Release with changelog"
   task :gem_release do
+    require "gem/release"
     # Safety checks: ensure we're on main and up-to-date
     current_branch = `git branch --show-current`.strip
     unless current_branch == "main"
@@ -62,12 +61,18 @@ begin
     sh "git add ."
     sh "git commit -m \"Bump llm_gateway to #{new_version}\""
 
+    # Build the gem first
+    gem_file = `gem build llm_gateway.gemspec | grep 'File:' | awk '{print $2}'`.strip
+
     # Tag and push
     sh "git tag v#{new_version}"
     sh "git push origin main --tags"
 
+    # Create GitHub release with gem file
+    sh "gh release create v#{new_version} #{gem_file} --title \"Release v#{new_version}\" --generate-notes"
+
     # Release the gem
-    sh "gem push $(gem build llm_gateway.gemspec | grep 'File:' | awk '{print $2}')"
+    sh "gem push #{gem_file}"
   end
 rescue LoadError
   # gem-release not available in this environment

data/docs/migration-guide.md

@@ -0,0 +1,135 @@
+# Dont use LlmGateway::Client 
+
+use the provider pattern instead 
+# Migrating from `chat` to `stream`
+
+The `chat` method will be deprecated. New code should use `stream`.
+
+If your application only needs the final assistant response, call `stream` without a block. You do not need to handle streaming events.
+
+## Basic migration
+
+### Before
+
+```ruby
+result = adapter.chat("Write one short sentence about Ruby.")
+```
+
+### After
+
+```ruby
+result = adapter.stream("Write one short sentence about Ruby.")
+```
+
+`stream` returns the final assembled `AssistantMessage`, so most response-handling code can stay the same.
+
+## Migrating calls with options
+
+Pass the same options to `stream` that you passed to `chat`.
+
+### Before
+
+```ruby
+result = adapter.chat(
+  transcript,
+  tools: tools,
+  system: "You are a helpful assistant.",
+  reasoning: "high"
+)
+```
+
+### After
+
+```ruby
+result = adapter.stream(
+  transcript,
+  tools: tools,
+  system: "You are a helpful assistant.",
+  reasoning: "high"
+)
+```
+
+## Reading the final response
+
+The returned object has the same final assistant message shape your existing `chat` code expects:
+
+```ruby
+result = adapter.stream(transcript)
+
+puts result.role
+puts result.stop_reason
+puts result.usage.inspect
+
+text = result.content
+  .select { |block| block.type == "text" }
+  .map(&:text)
+  .join
+
+puts text
+```
+
+## Tool-call flows
+
+If your existing `chat` flow inspected the final response for tool calls, keep the same pattern after switching to `stream`:
+
+```ruby
+response = adapter.stream(transcript, tools: [weather_tool])
+
+tool_uses = response.content.select { |block| block.type == "tool_use" }
+
+# Execute tools, append tool_result messages to the transcript,
+# then call stream again for the next assistant response.
+```
+
+## Recommended migration steps
+
+1. Replace `adapter.chat(...)` with `adapter.stream(...)`.
+2. Do not pass a block if you only need the final response.
+3. Run tests that verify text extraction, tool-call detection, stop reasons, and usage accounting.
+4. Remove new uses of `chat` from application code before deprecation.
+
+# Update ClassNames
+
+If you are using any of these classes you should use the new names
+
+## Clients
+
+- LlmGateway::Clients::Claude → LlmGateway::Clients::Anthropic
+- LlmGateway::Clients::OpenAi → LlmGateway::Clients::OpenAI
+
+## Adapters: Anthropic side
+
+- LlmGateway::Adapters::Claude::* → LlmGateway::Adapters::Anthropic::*
+    - Client
+    - MessagesAdapter
+    - InputMapper
+    - OutputMapper
+    - StreamMapper
+    - BidirectionalMessageMapper
+    - FileOutputMapper
+
+## Adapters: OpenAI side
+
+- LlmGateway::Adapters::OpenAi::* → LlmGateway::Adapters::OpenAI::*
+    - Client
+    - ChatCompletionsAdapter
+    - ResponsesAdapter
+    - PromptCacheOptionMapper
+    - FileOutputMapper
+    - ChatCompletions
+    - Responses
+
+## Adapters: Groq side
+
+Groq now reuses the OpenAI Chat Completions mapper stack via `ActsLikeOpenAIChatCompletions`.
+The dedicated Groq mapper classes were removed rather than aliased:
+
+- LlmGateway::Adapters::Groq::InputMapper → LlmGateway::Adapters::OpenAI::ChatCompletions::InputMapper
+- LlmGateway::Adapters::Groq::OutputMapper → LlmGateway::Adapters::OpenAI::ChatCompletions::OutputMapper
+- LlmGateway::Adapters::Groq::BidirectionalMessageMapper → LlmGateway::Adapters::OpenAI::ChatCompletions::BidirectionalMessageMapper
+
+Still provider-specific:
+
+- LlmGateway::Clients::Groq
+- LlmGateway::Adapters::Groq::ChatCompletionsAdapter
+- LlmGateway::Adapters::Groq::OptionMapper

data/lib/llm_gateway/adapters/adapter.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative "stream_accumulator"
+require_relative "structs"
+
+module LlmGateway
+  module Adapters
+    class Adapter
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def chat(message, tools: nil, system: nil, **options)
+        normalized_input = map_input({
+          messages: sanitize_messages(normalize_messages(message)),
+          tools: tools,
+          system: normalize_system(system)
+        })
+
+        result = perform_chat(
+          normalized_input[:messages],
+          tools: normalized_input[:tools],
+          system: normalized_input[:system],
+          **map_options(options)
+        )
+
+        map_output(result)
+      end
+
+      def stream(message, tools: nil, system: nil, **options, &block)
+        raise LlmGateway::Errors::MissingMapperForProvider, "No stream_mapper configured" unless stream_mapper
+
+        normalized_input = map_input({
+          messages: sanitize_messages(normalize_messages(message)),
+          tools: tools,
+          system: normalize_system(system)
+        })
+
+        accumulator = ::StreamAccumulator.new
+        mapper = stream_mapper.new
+
+        perform_stream(
+          normalized_input[:messages],
+          tools: normalized_input[:tools],
+          system: normalized_input[:system],
+          **map_options(options)
+        ) do |chunk|
+          event = mapper.map(chunk)
+          accumulator.push(event)
+          block.call(event) if block && event
+        end
+
+        AssistantMessage.new(
+          accumulator.result.merge(
+            provider: LlmGateway::Client.provider_id_from_client(client),
+            api: api_name
+          )
+        )
+      end
+
+      def upload_file(filename:, content:, mime_type: "application/octet-stream", purpose: "assistants")
+        raise LlmGateway::Errors::MissingMapperForProvider, "No file_output_mapper configured" unless file_output_mapper
+
+        upload_params = client.method(:upload_file).parameters
+        supports_purpose = upload_params.any? { |type, name| [ :key, :keyreq ].include?(type) && name == :purpose }
+
+        result = if supports_purpose
+          client.upload_file(filename, content, mime_type, purpose: purpose)
+        else
+          client.upload_file(filename, content, mime_type)
+        end
+
+        file_output_mapper.map(result)
+      end
+
+      def download_file(file_id:)
+        raise LlmGateway::Errors::MissingMapperForProvider, "No file_output_mapper configured" unless file_output_mapper
+
+        result = client.download_file(file_id)
+        file_output_mapper.map(result)
+      end
+
+      private
+
+      def input_mapper
+        raise NotImplementedError, "#{self.class} must implement #input_mapper"
+      end
+
+      def input_sanitizer
+        nil
+      end
+
+      def output_mapper
+        raise NotImplementedError, "#{self.class} must implement #output_mapper"
+      end
+
+      def file_output_mapper
+        nil
+      end
+
+      def option_mapper
+        OptionMapper
+      end
+
+      def map_input(input)
+        input_mapper.map(input)
+      end
+
+      def map_output(output)
+        output_mapper.map(output)
+      end
+
+      def map_options(options)
+        option_mapper.map(options)
+      end
+
+      def perform_chat(messages, tools:, system:, **options)
+        client.chat(messages, tools: tools, system: system, **options)
+      end
+
+      def perform_stream(messages, tools:, system:, **options, &block)
+        client.stream(messages, tools: tools, system: system, **options, &block)
+      end
+
+      def api_name
+        self.class.name.split("::").last.gsub(/Adapter$/, "").downcase
+      end
+
+      def stream_mapper
+        nil
+      end
+
+      def sanitize_messages(messages)
+        return messages unless input_sanitizer
+
+        target_provider = LlmGateway::Client.provider_id_from_client(client)
+        target_api = api_name
+        target_model = client.model_key
+
+        return messages if target_provider.nil? || target_api.nil? || target_model.nil?
+
+        input_sanitizer.sanitize(
+          messages,
+          target_provider: target_provider,
+          target_api: target_api,
+          target_model: target_model
+        )
+      end
+
+      def normalize_system(system)
+        if system.nil?
+          []
+        elsif system.is_a?(String)
+          [ { role: "system", content: system } ]
+        elsif system.is_a?(Array)
+          system
+        else
+          raise ArgumentError, "System parameter must be a string or array, got #{system.class}"
+        end
+      end
+
+      def normalize_messages(message)
+        if message.is_a?(String)
+          [ { role: "user", content: message } ]
+        else
+          message
+        end
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/anthropic/acts_like_messages.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module ActsLikeAnthropicMessages
+      private
+
+      def api_name = "messages"
+
+      def input_mapper = Anthropic::InputMapper
+
+      def input_sanitizer = InputMessageSanitizer
+
+      def output_mapper = Anthropic::OutputMapper
+
+      def file_output_mapper = Anthropic::FileOutputMapper
+
+      def option_mapper = AnthropicOptionMapper
+
+      def stream_mapper = Anthropic::StreamMapper
+    end
+  end
+end

data/lib/llm_gateway/adapters/anthropic/bidirectional_message_mapper.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module Anthropic
+      class BidirectionalMessageMapper
+        attr_reader :direction
+
+        def initialize(direction)
+          @direction = direction
+        end
+
+        def map_content(content)
+          # Convert string content to text format
+          content = { type: "text", text: content } unless content.is_a?(Hash)
+
+          case content[:type]
+          when "text"
+            map_text_content(content)
+          when "file"
+            map_file_content(content)
+          when "image"
+            map_image_content(content)
+          when "tool_use"
+            map_tool_use_content(content)
+          when "tool_result"
+            map_tool_result_content(content)
+          when "thinking", "reasoning"
+            map_reasoning_content(content)
+          else
+            content
+          end
+        end
+
+        private
+
+        def map_text_content(content)
+          result = {
+            type: "text",
+            text: content[:text]
+          }
+          result[:cache_control] = content[:cache_control] if content[:cache_control]
+          result
+        end
+
+        def map_file_content(content)
+          {
+            type: "document",
+            source: {
+              data: content[:data],
+              type: "text",
+              media_type: content[:media_type]
+            }
+          }
+        end
+
+        def map_image_content(content)
+          {
+            type: "image",
+            source: {
+              data: content[:data],
+              type: "base64",
+              media_type: content[:media_type]
+            }
+          }
+        end
+
+        def map_tool_use_content(content)
+          {
+            type: "tool_use",
+            id: content[:id],
+            name: content[:name],
+            input: content[:input]
+          }
+        end
+
+        def map_tool_result_content(content)
+          mapped_content = content[:content]
+          if mapped_content.is_a?(Array)
+            mapped_content = mapped_content.map do |item|
+              item.is_a?(Hash) ? map_content(item.transform_keys(&:to_sym)) : item
+            end
+          end
+
+          {
+            type: "tool_result",
+            tool_use_id: content[:tool_use_id],
+            content: mapped_content
+          }
+        end
+
+        def map_reasoning_content(content)
+          if direction == LlmGateway::DIRECTION_IN
+            result = {
+              type: "thinking",
+              thinking: content[:reasoning]
+            }
+            result[:signature] = content[:signature] unless content[:signature].nil?
+            result
+          else
+            {
+              type: "reasoning",
+              reasoning: content[:thinking] || content[:reasoning],
+              signature: content[:signature]
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/{claude → anthropic}/input_mapper.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "bidirectional_message_mapper"
+
 module LlmGateway
   module Adapters
-    module Claude
+    module Anthropic
       class InputMapper
         def self.map(data)
           {
             messages: map_messages(data[:messages]),
-            response_format: data[:response_format],
             tools: data[:tools],
             system: map_system(data[:system])
           }
@@ -18,20 +19,19 @@ module LlmGateway
         def self.map_messages(messages)
           return messages unless messages
 
+          message_mapper = BidirectionalMessageMapper.new(LlmGateway::DIRECTION_IN)
+
           messages.map do |msg|
             msg = msg.merge(role: "user") if msg[:role] == "developer"
-            msg.slice(:role, :content)
+
             content = if msg[:content].is_a?(Array)
                 msg[:content].map do |content|
-                  if content[:type] == "file"
-                    { type: "document", source: { data: content[:data], type: "text", media_type: content[:media_type] } }
-                  else
-                    content
-                  end
+                  message_mapper.map_content(content)
                 end
             else
-              msg[:content]
+              [ message_mapper.map_content(msg[:content]) ]
             end
+
             {
               role: msg[:role],
               content: content
@@ -44,7 +44,9 @@ module LlmGateway
             nil
           elsif system.length == 1 && system.first[:role] == "system"
             # If we have a single system message, convert to Claude format
-            [ { type: "text", text: system.first[:content] } ]
+            mapped = { type: "text", text: system.first[:content] }
+            mapped[:cache_control] = system.first[:cache_control] if system.first[:cache_control]
+            [ mapped ]
           else
             # For multiple messages or non-standard format, pass through
             system

data/lib/llm_gateway/adapters/anthropic/messages_adapter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../adapter"
+require_relative "acts_like_messages"
+require_relative "../anthropic_option_mapper"
+require_relative "../input_message_sanitizer"
+require_relative "input_mapper"
+require_relative "output_mapper"
+require_relative "stream_mapper"
+
+module LlmGateway
+  module Adapters
+    module Anthropic
+      class MessagesAdapter < Adapter
+        include ActsLikeAnthropicMessages
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/anthropic/output_mapper.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module Anthropic
+      class FileOutputMapper
+        def self.map(data)
+          data.delete(:type) # Didnt see much value in this only option is "file"
+          data.merge(
+            expires_at: nil, # came from open ai api
+            purpose: "user_data",  # came from open ai api
+          )
+        end
+      end
+
+      class OutputMapper
+        def self.map(data)
+          {
+            id: data[:id],
+            model: data[:model],
+            usage: data[:usage],
+            choices: map_choices(data)
+          }
+        end
+
+        private
+
+        def self.map_choices(data)
+          message_mapper = BidirectionalMessageMapper.new(LlmGateway::DIRECTION_OUT)
+
+          content = if data[:content].is_a?(Array)
+              data[:content].map do |content|
+                message_mapper.map_content(content)
+              end
+          else
+            data[:content] ? [ message_mapper.map_content(data[:content]) ] : []
+          end
+
+          # Claude returns content directly at root level, not in a choices array
+          # We need to construct the choices array from the full response data
+          [ {
+            content: content, # Use content directly from Claude response
+            finish_reason: data[:stop_reason],
+            role: "assistant"
+          } ]
+        end
+      end
+    end
+  end
+end