llm_gateway 0.1.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86c8c0937c6d8d78b1b4b3c2dfa1ed749fbd74eb40e52ccf084dbf0e3cccbb8e
-  data.tar.gz: 682021570b7d903ba44bfc606a9ca9e9fc45ce897bb8637a32d563bfd5497de4
+  metadata.gz: 972dac306c8d8f59b41c462f0133d0ce415e689515fbd84d5503541a9fee6f93
+  data.tar.gz: 6014254f858af1b83906b29950811e2ce84940f0ff49301a9b36dd19f592b7a8
 SHA512:
-  metadata.gz: b684e11152959b054bb30213982845e0978dfe91a2473de7e2a326ca37d2c9e6ec8411be1b5a729e3d99bfb0654bfc420bacf7b752219286295cf80d2c1245f1
-  data.tar.gz: 3da1cf5fcc649024b9e08859905430e1a89082333ec614c39b6fd22ff360143fe5be5f1efb9d7ddf81e8d9f08e62549c23ae1daadc8ef82e234fb6e433a4b899
+  metadata.gz: 388573aa9afe19a075c561f17d5e4a6b8e550de25b73c3e6d9583403096f1c26f13667055d5920408c2c06f9add888af81a0bf34434762b8ece4a58de32ee3c3
+  data.tar.gz: 42d0b37c296ee058109cb38daaeefc269ce128a39bfbb3b89745eb734653a2828ec8c54f8acd1a12242aa03d1706304507c627074a53e4e6cddc7eb27324d69d

data/.rubocop.yml

@@ -3,3 +3,32 @@ inherit_gem:
 
 AllCops:
   TargetRubyVersion: 3.1
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
+
+Layout/FirstHashElementLineBreak:
+  Enabled: true
+
+Layout/FirstHashElementIndentation:
+  Enabled: true
+  EnforcedStyle: consistent
+
+Layout/MultilineHashKeyLineBreaks:
+  Enabled: true
+
+Layout/HashAlignment:
+  Enabled: true
+  EnforcedHashRocketStyle: key
+  EnforcedColonStyle: key
+
+Layout/IndentationConsistency:
+  Enabled: true
+  EnforcedStyle: normal
+
+Layout/IndentationWidth:
+  Width: 2
+
+Layout/MultilineHashBraceLayout:
+  Enabled: true
+  EnforcedStyle: new_line

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [v0.3.0](https://github.com/Hyper-Unearthing/llm_gateway/tree/v0.3.0) (2025-08-19)
+
+[Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/v0.2.0...v0.3.0)
+
+**Merged pull requests:**
+
+- feat: create a method called responses to implement modern apis [\#30](https://github.com/Hyper-Unearthing/llm_gateway/pull/30) ([billybonks](https://github.com/billybonks))
+- test: Create a test that asserts the transcript format. [\#29](https://github.com/Hyper-Unearthing/llm_gateway/pull/29) ([billybonks](https://github.com/billybonks))
+- refactor: move open ai chat completions to its own folder [\#28](https://github.com/Hyper-Unearthing/llm_gateway/pull/28) ([billybonks](https://github.com/billybonks))
+- refactor: bundle all provider resources in a hash [\#27](https://github.com/Hyper-Unearthing/llm_gateway/pull/27) ([billybonks](https://github.com/billybonks))
+- refactor: message mapper to become bidirectional mapper [\#26](https://github.com/Hyper-Unearthing/llm_gateway/pull/26) ([billybonks](https://github.com/billybonks))
+- refactor: extract message mapper from input mapper [\#25](https://github.com/Hyper-Unearthing/llm_gateway/pull/25) ([billybonks](https://github.com/billybonks))
+- docs: add more information about how the library works [\#24](https://github.com/Hyper-Unearthing/llm_gateway/pull/24) ([billybonks](https://github.com/billybonks))
+- feat: enable uploading and downloading files from openai anthropic [\#23](https://github.com/Hyper-Unearthing/llm_gateway/pull/23) ([billybonks](https://github.com/billybonks))
+- ci: upload build version to github when we release [\#22](https://github.com/Hyper-Unearthing/llm_gateway/pull/22) ([billybonks](https://github.com/billybonks))
+
+## [v0.2.0](https://github.com/Hyper-Unearthing/llm_gateway/tree/v0.2.0) (2025-08-08)
+
+[Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/v0.1.6...v0.2.0)
+
+**Merged pull requests:**
+
+- feat: improve read me  [\#21](https://github.com/Hyper-Unearthing/llm_gateway/pull/21) ([billybonks](https://github.com/billybonks))
+- refactor: remove fluent mapper from the lib [\#20](https://github.com/Hyper-Unearthing/llm_gateway/pull/20) ([billybonks](https://github.com/billybonks))
+- test: dont fail vcr if key order changes [\#19](https://github.com/Hyper-Unearthing/llm_gateway/pull/19) ([billybonks](https://github.com/billybonks))
+- burn: fluent mapper from input mappers [\#18](https://github.com/Hyper-Unearthing/llm_gateway/pull/18) ([billybonks](https://github.com/billybonks))
+- test: open ai mapper [\#17](https://github.com/Hyper-Unearthing/llm_gateway/pull/17) ([billybonks](https://github.com/billybonks))
+- feat: handle basic text document handling [\#16](https://github.com/Hyper-Unearthing/llm_gateway/pull/16) ([billybonks](https://github.com/billybonks))
+- test: improve issues [\#15](https://github.com/Hyper-Unearthing/llm_gateway/pull/15) ([billybonks](https://github.com/billybonks))
+- style: format aligment of content automatically to my preference [\#14](https://github.com/Hyper-Unearthing/llm_gateway/pull/14) ([billybonks](https://github.com/billybonks))
+- fix: tool calling open ai [\#13](https://github.com/Hyper-Unearthing/llm_gateway/pull/13) ([billybonks](https://github.com/billybonks))
+
 ## [v0.1.6](https://github.com/Hyper-Unearthing/llm_gateway/tree/v0.1.6) (2025-08-05)
 
 [Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/v0.1.5...v0.1.6)

data/README.md

@@ -1,8 +1,65 @@
 # LlmGateway
 
-Provide nuts and bolts for LLM APIs. The goal is to provide a unified interface for multiple LLM provider API's; And Enable developers to have as much control as they want.
+Provide a unified translation interface for LLM Provider API's, While allowing developers to have as much control as possible, This does make it more complicated because we dont want developers to be blocked at using something that the provider supports. As time progress the library will mature and support more responses
 
-You can use the clients directly, Or you can use the gateway to have interop between clients.
+
+## Principles:
+1. Transcription integrity is most important
+2. Input messages must have bidirectional integrity
+3. Allow developers as much control as possible
+
+## Assumptions
+things that do not support unidirectional format, probably cant be sent between providers
+
+## Mechanics
+Messages either support unidirectional or bidirectional format. (unidirectional means we can format it as an output but should not be added as an input).
+
+The result from the llm is in the format that can be sent to the provider, but if you want to consolidate complex messages like code_execution, you must run a mapper we provide manually, but dont send that format back to the provider.
+
+### bidirectional Support
+Messages
+- Text
+- Tool Use
+- Tool Response
+
+Tools
+- Server Tools
+- Tools
+
+### Unidirectional Support
+- Server Tool Use Reponse
+
+### Example flow
+
+
+```mermaid
+sequenceDiagram
+        actor developer
+        participant llm_gateway
+        participant llm_provider
+
+        developer ->> llm_gateway: Send Text Message
+        llm_gateway ->> llm_gateway: transform to provider format
+        llm_gateway ->> llm_provider: Transformed Text Message
+        llm_provider ->> llm_gateway: Response <br />(transcript in provider format)
+        llm_gateway ->> developer:  Response <br />(transcript in combination <br />of gatway and provider formats)
+        Note over llm_gateway,developer: llm_gateway will transform <br /> messages that support bi-direction
+        developer ->> developer: save the transcript
+        loop ProcessMessage
+            developer ->> llm_gateway: format message
+            llm_gateway ->> developer: return transformed message
+            Note over llm_gateway,developer: if the message: <br /> supports bidirection format returns as is <br /> otherwise will transform <br />into consolidated format
+            developer ->> developer: append earlier saved transcript
+            Note over developer, developer: for example tool use
+        end
+        developer -> llm_gateway: Transcript
+        llm_gateway ->> llm_gateway: transform to provider format
+        Note over llm_gateway,llm_gateway: non bidirectional messages are sent as is
+        llm_gateway ->> llm_provider: etc etc etc
+
+
+
+```
 
 ## Supported Providers
 Anthropic, OpenAi, Groq
@@ -30,17 +87,113 @@ gem install llm_gateway
 require 'llm_gateway'
 
 # Simple text completion
-result = LlmGateway::Client.chat(
+LlmGateway::Client.chat(
   'claude-sonnet-4-20250514',
   'What is the capital of France?'
 )
 
 # With system message
-result = LlmGateway::Client.chat(
+LlmGateway::Client.chat(
   'gpt-4',
   'What is the capital of France?',
   system: 'You are a helpful geography teacher.'
 )
+
+# With inline file
+LlmGateway::Client.chat(
+  "claude-sonnet-4-20250514",
+  [
+    {
+      role: "user", content: [
+        { type: "text", text: "return the content of the document exactly" },
+        { type: "file", data: "abc\n", media_type: "text/plain", name: "small.txt"  }
+      ]
+    },
+  ]
+)
+
+# Transcript
+LlmGateway::Client.chat('llama-3.3-70b-versatile',[
+    { role: "user", content: "Tell Me a joke" },
+    { role: "assistant", content: "what kind of content"},
+    { role: "user", content: "About Sparkling water" },
+  ]
+)
+
+
+# Tool usage
+LlmGateway::Client.chat('gpt-5',[
+    { role: "user", content: "What's the weather in Singapore? reply in 10 words and no special characters" },
+    { role: "assistant",
+        content: [
+          { id: "call_gpXfy9l9QNmShNEbNI1FyuUZ", type: "tool_use", name: "get_weather", input: { location: "Singapore" } }
+        ]
+    },
+    { role: "developer",
+      content: [
+        { content: "-15 celcius", type: "tool_result", tool_use_id: "call_gpXfy9l9QNmShNEbNI1FyuUZ" }
+      ]
+    }
+  ],
+  tools: [ { name: "get_weather", description: "Get current weather for a location", input_schema: { type: "object", properties: { location: { type: "string", description: "City name" } }, required: [ "location" ] } } ]
+)
+```
+
+### Supported Roles
+
+- user
+- developer
+- assistant
+
+#### Examples
+```ruby
+# tool call
+{ role: "developer",
+  content: [
+    { content: "-15 celcius", type: "tool_result", tool_use_id: "call_gpXfy9l9QNmShNEbNI1FyuUZ" }
+  ]
+}
+# plain message
+{ role: "user", content: "What's the weather in Singapore? reply in 10 words and no special characters" }
+
+# plain response
+{ role: "assistant", content: "what kind of content"},
+
+# tool call response
+{ role: "assistant",
+    content: [
+      { id: "call_gpXfy9l9QNmShNEbNI1FyuUZ", type: "tool_use", name: "get_weather", input: { location: "Singapore" } }
+    ]
+},
+```
+
+developer is an open ai role, but i thought it was usefull for tracing if message sent from server or user so i added
+it to the list of roles, when it is not supported it will be mapped to user instead.
+
+you can assume developer and user to be interchangeable
+
+
+### Files
+
+Many providers offer the ability to upload files which can be referenced in conversations, or for other purposes like batching. Downloading files is also used for when llm generates something or batches complete.
+
+## Examples
+
+```ruby
+# Upload File
+result = LlmGateway::Client.upload_file("openai", filename: "test.txt", content: "Hello, world!", mime_type: "text/plain")
+result = LlmGateway::Client.download_file("openai", file_id: "file-Kb6X7f8YDffu7FG1NcaPVu")
+# Response Format
+{
+  id: "file-Kb6X7f8YDffu7FG1NcaPVu",
+  size_bytes: 13,  # follows anthropic naming cause clearer
+  created_at: "2025-08-08T06:03:16.000000Z", # follow anthropic style cause easier to read as human
+  filename: "test.txt",
+  mime_type: nil,
+  downloadable: true, # anthropic returns this for other providers it is infered
+  expires_at: nil,
+  purpose: "user_data" # for anthropic this is always user_data
+}
 ```
 
 ### Sample Application

data/Rakefile

@@ -62,12 +62,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/lib/llm_gateway/adapters/claude/bidirectional_message_mapper.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  module Adapters
+    module Claude
+      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)
+          else
+            content
+          end
+        end
+
+        private
+
+        def map_text_content(content)
+          {
+            type: "text",
+            text: content[:text]
+          }
+        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)
+          {
+            type: "tool_result",
+            tool_use_id: content[:tool_use_id],
+            content: content[:content]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/claude/client.rb

@@ -28,6 +28,10 @@ module LlmGateway
           get("files/#{file_id}/content")
         end
 
+        def upload_file(filename, content, mime_type = "application/octet-stream")
+          post_file("files", content, filename, mime_type: mime_type)
+        end
+
         private
 
         def build_headers

data/lib/llm_gateway/adapters/claude/input_mapper.rb

@@ -1,33 +1,56 @@
 # frozen_string_literal: true
 
+require_relative "bidirectional_message_mapper"
+
 module LlmGateway
   module Adapters
     module Claude
       class InputMapper
-        extend LlmGateway::FluentMapper
+        def self.map(data)
+          {
+            messages: map_messages(data[:messages]),
+            response_format: data[:response_format],
+            tools: data[:tools],
+            system: map_system(data[:system])
+          }
+        end
+
+        private
+
+        def self.map_messages(messages)
+          return messages unless messages
+
+          message_mapper = BidirectionalMessageMapper.new(LlmGateway::DIRECTION_IN)
 
-        map :messages do |_, value|
-          value.map do |msg|
+          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|
+                  message_mapper.map_content(content)
+                end
+            else
+              [ message_mapper.map_content(msg[:content]) ]
+            end
+
+            {
+              role: msg[:role],
+              content: content
+            }
           end
         end
 
-        map :system do |_, value|
-          if value.empty?
+        def self.map_system(system)
+          if !system || system.empty?
             nil
-          elsif value.length == 1 && value.first[:role] == "system"
+          elsif system.length == 1 && system.first[:role] == "system"
             # If we have a single system message, convert to Claude format
-            [ { type: "text", text: value.first[:content] } ]
+            [ { type: "text", text: system.first[:content] } ]
           else
             # For multiple messages or non-standard format, pass through
-            value
+            system
           end
         end
-
-        map :tools do |_, value|
-          value
-        end
       end
     end
   end

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

@@ -3,18 +3,44 @@
 module LlmGateway
   module Adapters
     module Claude
+      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
-        extend LlmGateway::FluentMapper
+        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
 
-        map :id
-        map :model
-        map :usage
-        map :choices do |_, _|
           # 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: @data[:content] || [], # Use content directly from Claude response
-            finish_reason: @data[:stop_reason],
+            content: content, # Use content directly from Claude response
+            finish_reason: data[:stop_reason],
             role: "assistant"
           } ]
         end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../open_ai/chat_completions/bidirectional_message_mapper"
+
+module LlmGateway
+  module Adapters
+    module Groq
+      class BidirectionalMessageMapper < OpenAi::ChatCompletions::BidirectionalMessageMapper
+        private
+
+        def map_file_content(content)
+          # Groq doesn't support files, return as text
+          content[:text] || "[File: #{content[:name]}]"
+        end
+      end
+    end
+  end
+end

data/lib/llm_gateway/adapters/groq/input_mapper.rb

@@ -1,76 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "bidirectional_message_mapper"
+require_relative "../open_ai/chat_completions/input_mapper"
+
 module LlmGateway
   module Adapters
     module Groq
-      class InputMapper
-        extend LlmGateway::FluentMapper
-
-        map :system
-        map :response_format
-
-        mapper :tool_usage do
-          map :role, default: "assistant"
-          map :content do
-            nil
-          end
-          map :tool_calls, from: :content do |_, value|
-            value.map do |content|
-              {
-                'id': content[:id],
-                'type': "function",
-                'function': {
-                  'name': content[:name],
-                  'arguments': content[:input].to_json
-                }
-              }
-            end
-          end
-        end
-
-        mapper :tool_result_message do
-          map :role, default: "tool"
-          map :tool_call_id, from: "tool_use_id"
-          map :content
-        end
-
-        map :messages do |_, value|
-          value.map do |msg|
-            if msg[:role] == "user"
-              msg
-            elsif msg[:content].is_a?(Array)
-              results = []
-              # Handle tool_use messages
-              tool_uses = msg[:content].select { |c| c[:type] == "tool_use" }
-              results << map_single(msg, with: :tool_usage) if tool_uses.any?
-              # Handle tool_result messages
-              tool_results = msg[:content].select { |c| c[:type] == "tool_result" }
-              tool_results.each do |content|
-                results << map_single(content, with: :tool_result_message)
-              end
-
-              results
-            else
-              msg
-            end
-          end.flatten
-        end
+      class InputMapper < OpenAi::ChatCompletions::InputMapper
+        private
 
-        map :tools do |_, value|
-          if value
-            value.map do |tool|
-              {
-                type: "function",
-                function: {
-                  name: tool[:name],
-                  description: tool[:description],
-                  parameters: tool[:input_schema]
-                }
-              }
-            end
-          else
-            value
-          end
+        def self.map_system(system)
+          system
         end
       end
     end

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

@@ -3,43 +3,7 @@
 module LlmGateway
   module Adapters
     module Groq
-      class OutputMapper
-        extend LlmGateway::FluentMapper
-
-        mapper :tool_call do
-          map :id
-          map :type do
-            "tool_use" # Always return 'tool_use' regardless of input
-          end
-          map :name, from: "function.name"
-          map :input, from: "function.arguments" do |_, value|
-            parsed = value.is_a?(String) ? JSON.parse(value) : value
-            parsed
-          end
-        end
-
-        mapper :content_item do
-          map :text, from: "content"
-          map :type, default: "text"
-        end
-
-        map :id
-        map :model
-        map :usage
-        map :choices, from: "choices" do |_, value|
-          value.map do |choice|
-            message = choice[:message] || {}
-            content_item = map_single(message, with: :content_item, default: {})
-            tool_calls = map_collection(message[:tool_calls], with: :tool_call, default: [])
-
-            # Only include content_item if it has actual text content
-            content_array = []
-            content_array << content_item if LlmGateway::Utils.present?(content_item["text"])
-            content_array += tool_calls
-
-            { content: content_array }
-          end
-        end
+      class OutputMapper < LlmGateway::Adapters::OpenAi::ChatCompletions::OutputMapper
       end
     end
   end