llms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0bedbc3fd0a0429738df4a4272c7752269229ebbbb4291caf235ebdbd83cc88a
+  data.tar.gz: 903c0baae14561bbff1ff32af10e07e218b8a22bdee3eb56f8c8d1b5817e31da
+SHA512:
+  metadata.gz: 55e3cf99b5c462155251de3eb6ca40c0469a67184422f79027e57ec760fb363484eb78759aa11a8e34c3887472a3bc51fdfe47c1f7a9e303188a9ddd047e65ac
+  data.tar.gz: efb53841dd57e9fd3c17050b1552c16dcc5dcdb04edfb2c7bb9ea5120f8e367e4c528b8b1ec756661d51ed0ba7e77c4878f0d0b410ecfb94bb44bccc04561123

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ben Lund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# LLMs
+
+A Ruby library for interacting with Large Language Model (LLM) providers including Anthropic, Google Gemini, X.ai, and other OpenAI-compatible API providers (including local models).
+
+Supports streaming, event-handling, conversation management, tool-use, image input, and cost-tracking.
+
+
+## Current Version
+
+0.1.0
+
+Just about usable in production.
+
+
+## Installation
+
+Add to your Gemfile:
+```ruby
+gem 'llms'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install llms
+```
+
+## Quick Start
+
+```ruby
+require 'llms'
+
+# Create an executor for a specific model
+executor = LLMs::Executors.instance(
+  model_name: 'claude-sonnet-4-0',
+  temperature: 0.0,
+  max_completion_tokens: 1000
+)
+
+# Simple prompt execution
+puts executor.execute_prompt("What is 2+2?")
+
+# Streaming response
+executor.execute_prompt("What is the airspeed velocitty of an unladen swallow?") do |chunk|
+  print chunk
+end
+
+# Simple Chat
+conversation = LLMs::Conversation.new
+while true
+  print "> "
+  conversation.add_user_message($stdin.gets)
+  response = executor.execute_conversation(conversation){|chunk| print chunk}
+  puts
+  conversation.add_assistant_message(response)
+end
+
+# Add a custom model
+LLMs::Models.add_model('ollama', 'qwen3:8b',
+  executor: 'OpenAICompatibleExecutor', base_url: 'http://localhost:11434/api')
+
+executor = LLMs::Executors.instance(model_name: 'qwen3:8b', api_key: 'none')
+puts executor.execute_prompt("What is 2+2?")
+
+# Handle Streaming Events
+
+executor.stream_conversation(conversation) do |emitter|
+  emitter.on :tool_call_completed do |event|
+    puts event.name
+    puts event.arguments.inspect
+  end
+end
+```
+
+## Supported Models
+
+LLMs from Anthropic, Google, xAI, and various open-weight inference hosts are pre-configured in this release. See `lib/llms/public_models.json` for the full list. No models from OpenAI are pre-configured but you can set them up them manually in your application code along the lines of the exmaple above.
+
+
+## Configuration
+
+Set your API keys as environment variables:
+
+```bash
+export ANTHROPIC_API_KEY="your-anthropic-key"
+export GOOGLE_GEMINI_API_KEY="your-gemini-key"
+```
+
+See lib/public_models.json for supported providers and their corresponding API key env vars.
+
+Or pass to directly into Executor initialization:
+
+```ruby
+
+require 'llms'
+
+executor = LLMs::Executors::AnthropicExecutor.new(
+  model_name: 'claude-sonnet-4-0',
+  temperature: 0.0,
+  max_completion_tokens: 1000,
+  api_key: 'api-key-here'
+)
+```
+
+
+
+## CLI Usage
+
+### Interactive Chat
+
+```bash
+llms-chat --model model-name
+```
+
+or if model-name would be ambiguous:
+
+```bash
+llms-chat --model provider:model-name
+```
+
+or to run against a local model (e.g. LMStudio):
+
+```bash
+llms-chat --oac-base-url "http://127.0.0.1:1234/v1" -m qwen/qwen3-32b --oac-api-key none
+```
+
+### List Available Models
+
+```bash
+llms-chat --list-models
+```
+
+### Test various features against all models
+
+```bash
+llms-test-model-access # send a cshort question with a custom system prompt to all models in turn
+llms-test-model-tool-usage # configures a simple tool and asks all models in turn to call it
+llms-test-model-image-support # sends an image to every model asking it to describe the image
+llms-test-prompt-caching # send a long prompt and see if it is cached
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rspec` to run the tests.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/benlund/llms
+
+
+## License
+
+This gem is available as open source under the terms of the MIT License.

data/bin/llms-chat

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+#!/usr/bin/env ruby
+
+require_relative '../lib/llms/cli'
+LLMs::CLI::Chat.new('llms-chat').run

data/bin/llms-test-model-access

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/llms/cli'
+LLMs::CLI::TestAccess.new('llms-test-model-access').run

data/bin/llms-test-model-image-support

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/llms/cli'
+LLMs::CLI::TestImageSupport.new('llms-test-model-image-support').run

data/bin/llms-test-model-prompt-caching

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/llms/cli'
+LLMs::CLI::TestPromptCaching.new('llms-test-model-prompt-caching').run

data/bin/llms-test-model-tool-use

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/llms/cli'
+
+LLMs::CLI::TestToolUse.new('llms-test-model-tool-use').run

data/lib/llms/adapters/anthropic_message_adapter.rb

@@ -0,0 +1,73 @@
+require_relative '../conversation_message'
+require_relative './base_message_adapter'
+require_relative './anthropic_tool_call_adapter'
+
+module LLMs
+  module Adapters
+    class AnthropicMessageAdapter < BaseMessageAdapter
+
+
+      def self.to_api_format(message, caching_enabled = false)
+        content = []
+
+        message.tool_results&.each do |tool_result|
+          tr = {type: 'tool_result', tool_use_id: tool_result.tool_call_id, content: tool_result.results}
+          if tool_result.is_error
+            tr[:is_error] = true
+          end
+          content << tr
+        end
+
+        message.parts&.each do |part|
+          if part[:text]
+            content << {type: 'text', text: part[:text]}
+          end
+          if part[:image]
+            content << {
+              type: 'image',
+              source: {
+                type: 'base64',
+                media_type: part[:media_type],
+                data: part[:image]
+              }
+            }
+          end
+        end
+
+        message.tool_calls&.each do |tool_call|
+          content << {type: 'tool_use', id: tool_call.tool_call_id, name: tool_call.name, input: tool_call.arguments}
+        end
+
+        if caching_enabled
+          content.last[:cache_control] = {type: 'ephemeral'}
+        end
+
+        {
+          role: message.role,
+          content: content
+        }
+      end
+
+      def self.transform_tool_call(api_response_format_part, index)
+        LLMs::Adapters::AnthropicToolCallAdapter.from_api_format(api_response_format_part, index)
+      end
+
+      def self.find_role(api_response_format)
+        api_response_format['role']
+      end
+
+      def self.find_message_id(api_response_format)
+        api_response_format['id']
+      end
+
+      def self.find_text(api_response_format)
+        api_response_format['content']&.map { |c| c['text'] }&.compact&.join
+      end
+
+      def self.find_tool_calls(api_response_format)
+        api_response_format['content']&.select { |c| c['type'] == 'tool_use' }
+      end
+
+    end
+  end
+end

data/lib/llms/adapters/anthropic_tool_call_adapter.rb

@@ -0,0 +1,20 @@
+require_relative '../conversation_tool_call'
+
+module LLMs
+  module Adapters
+    class AnthropicToolCallAdapter
+
+      def self.from_api_format(api_response_format_part, index)
+        LLMs::ConversationToolCall.new(
+          index,
+          api_response_format_part['id'],
+          api_response_format_part['type'],
+          api_response_format_part['name'],
+          api_response_format_part['input'],
+        )
+      end
+
+    end
+  end
+end
+  

data/lib/llms/adapters/base_message_adapter.rb

@@ -0,0 +1,60 @@
+require_relative '../conversation_message'
+
+module LLMs
+  module Adapters
+    class BaseMessageAdapter
+
+
+      def self.to_api_format(message, caching_enabled = false)
+        raise "Not implemented"
+      end
+
+      def self.message_from_api_format(api_format)
+        if self.has_message?(api_format)
+          role = transform_role(find_role(api_format))
+          text = transform_text(find_text(api_format))
+          tool_calls = transform_tool_calls(find_tool_calls(api_format))
+          LLMs::ConversationMessage.new(role, [{text: text}], tool_calls, nil)
+        else
+          nil
+        end
+      end
+
+      def self.has_message?(api_format)
+        !find_role(api_format).nil?
+      end
+
+      def self.transform_role(role)
+        role
+      end
+
+      def self.transform_text(text)
+        text
+      end
+
+      def self.transform_tool_calls(tool_calls)
+        tool_calls.nil? ? nil : tool_calls.map.with_index { |tool_call, index| transform_tool_call(tool_call, index) }
+      end
+
+      def self.transform_tool_call(tool_call, index)
+        raise "Not implemented"
+      end
+
+      def self.find_message_id(api_format)
+        raise "Not implemented"
+      end
+
+      def self.find_role(api_response_format)
+        raise "Not implemented"
+      end
+
+      def self.find_text(api_response_format)
+        raise "Not implemented"
+      end
+
+      def self.find_tool_calls(api_response_format)
+        raise "Not implemented"
+      end
+    end
+  end
+end

data/lib/llms/adapters/google_gemini_message_adapter.rb

@@ -0,0 +1,72 @@
+require_relative '../conversation_message'
+require_relative './base_message_adapter'
+require_relative './google_gemini_tool_call_adapter'
+
+module LLMs
+  module Adapters
+    class GoogleGeminiMessageAdapter < BaseMessageAdapter
+
+      def self.to_api_format(message)
+        parts = []
+        ## TODO order is important here - results must be given in same order as corresponding calls.
+        ## Currently the order is just assumed to be correctly preserved in the tool_results array
+        message.tool_results&.each do |tool_result|
+          parts << {functionResponse: { name: tool_result.name, response: { name: tool_result.name, content: tool_result.results}}}
+        end
+
+        message.parts&.each do |part|
+          if part[:text]
+            parts << {text: part[:text]}
+          end
+          if part[:image]
+            parts << {
+              inline_data: {
+                mime_type: part[:media_type] || 'image/png',
+                data: part[:image]
+              }
+            }
+          end
+        end
+
+
+        message.tool_calls&.each do |tool_call|
+          parts << {functionCall: {name: tool_call.name, args: tool_call.arguments}}
+        end
+        {
+          role: reverse_transform_role(message.role), ##TODO also gets changed later, fix this
+          parts: parts
+        }
+      end
+
+      def self.transform_role(role)
+        role == 'model' ? 'assistant' : role
+      end
+
+      def self.reverse_transform_role(role)
+        role == 'assistant' ? 'model' : role
+      end
+
+      def self.transform_tool_call(api_response_format_part, index)
+        LLMs::Adapters::GoogleGeminiToolCallAdapter.from_api_format(api_response_format_part, index)
+      end
+
+      def self.find_role(api_response_format)
+        api_response_format.dig('candidates', 0, 'role') || api_response_format.dig('candidates', 0, 'content', 'role')
+      end
+
+      def self.find_message_id(api_response_format)
+        nil ## no message id in the response
+      end
+
+      def self.find_text(api_response_format)
+        text_parts = api_response_format.dig('candidates', 0, 'content', 'parts')&.map { |c| c['text'] }&.compact
+        text_parts.nil? || text_parts.empty? ? nil : text_parts.join
+      end
+
+      def self.find_tool_calls(api_response_format)
+        api_response_format.dig('candidates', 0, 'content', 'parts')&.map { |c| c['functionCall'] }&.compact
+      end
+
+    end
+  end
+end

data/lib/llms/adapters/google_gemini_tool_call_adapter.rb

@@ -0,0 +1,20 @@
+require_relative '../conversation_tool_call'
+
+module LLMs
+  module Adapters
+    class GoogleGeminiToolCallAdapter
+
+      def self.from_api_format(api_response_format_part, index)
+        LLMs::ConversationToolCall.new(
+          index,
+          nil,
+          nil,
+          api_response_format_part['name'],
+          api_response_format_part['args'],
+        )
+      end
+
+    end
+  end
+end
+  

data/lib/llms/adapters/open_ai_compatible_message_adapter.rb

@@ -0,0 +1,88 @@
+require_relative '../conversation_message'
+require_relative './base_message_adapter'
+require_relative './open_ai_compatible_tool_call_adapter'
+
+module LLMs
+  module Adapters
+    class OpenAICompatibleMessageAdapter < BaseMessageAdapter
+
+      def self.to_api_format(message, _caching_enabled = false)
+        formatted_messages = []
+
+        message.tool_results&.each do |tool_result|
+          formatted_messages << {
+            role: 'tool',
+            name: tool_result.name,
+            tool_call_id: tool_result.tool_call_id,
+            content: tool_result.results
+          }
+        end
+
+        m = {
+          role: message.role
+        }
+
+        if message.system? && message.text
+          m[:content] = message.text
+        else
+          has_images = message.parts&.any? { |part| part[:image] }
+          
+          if has_images
+            m[:content] = []
+            message.parts&.each do |part|
+              if part[:text]
+                m[:content] << {type: 'text', text: part[:text]}
+              end
+
+              if part[:image]
+                m[:content] << {type: 'image_url', image_url: {url: "data:#{part[:media_type] || 'image/png'};base64,#{part[:image]}"}}
+              end
+            end
+          else
+            ## TODO check this
+            # For text-only messages, use array format to match test expectations
+            m[:content] = [{type: 'text', text: message.text}]
+          end
+        end
+
+        message.tool_calls&.each do |tool_call|
+          m[:tool_calls] ||= []
+          arguments = tool_call.arguments.is_a?(String) ? tool_call.arguments : JSON.dump(tool_call.arguments)
+          m[:tool_calls] << {
+            id: tool_call.tool_call_id,
+            type: 'function',
+            function: {
+              name: tool_call.name,
+              arguments: arguments
+            }
+          }
+        end
+
+        formatted_messages << m if m[:content] || m[:tool_calls]
+
+        formatted_messages
+      end
+
+      def self.transform_tool_call(api_response_format_part, index)
+        LLMs::Adapters::OpenAICompatibleToolCallAdapter.from_api_format(api_response_format_part, index)
+      end
+
+      def self.find_role(api_response_format)
+        api_response_format.dig('choices', 0, 'message', 'role')
+      end
+
+      def self.find_message_id(api_response_format)
+        api_response_format['id']
+      end
+
+      def self.find_text(api_response_format)
+        api_response_format.dig('choices', 0, 'message', 'content')
+      end
+
+      def self.find_tool_calls(api_response_format)
+        api_response_format.dig('choices', 0, 'message', 'tool_calls')
+      end
+
+    end
+  end
+end

data/lib/llms/adapters/open_ai_compatible_tool_call_adapter.rb

@@ -0,0 +1,67 @@
+require_relative '../conversation_tool_call'
+
+module LLMs
+  module Adapters
+    class OpenAICompatibleToolCallAdapter
+
+      def self.from_api_format(api_response_format_part, index)
+        name = api_response_format_part.dig('function', 'name')
+        arguments_value = api_response_format_part.dig('function', 'arguments')
+
+        if work_around_arguments_value = hyperbolic_workaround(arguments_value)
+          function_value = work_around_arguments_value['function']
+          name = function_value['_name']
+          function_value.delete('_name')
+          arguments_value = function_value
+        end
+
+        if arguments_value.nil?
+          {}
+
+        elsif arguments_value.is_a?(String)
+          arguments = JSON.parse(arguments_value)
+
+        # Hyperbolic returns a hash (in correct format) in non-streaming mode
+        elsif arguments_value.is_a?(Hash)
+          arguments = arguments_value
+
+        else
+          raise "Unexpected arguments value: #{arguments_value}"
+        end
+
+        # Some endpoints (Together at least?) return nested JSON strings that need parsing
+        arguments.each do |key, value|
+          if value.is_a?(String) && ( (value.start_with?('{') && value.end_with?('}')) || ((value.start_with?('[') && value.end_with?(']'))) )
+            begin
+              arguments[key] = JSON.parse(value)
+            rescue JSON::ParserError
+              # If it's not valid JSON, keep the original string
+            end
+          end
+        end
+
+        LLMs::ConversationToolCall.new(
+          index,
+          api_response_format_part['id'],
+          api_response_format_part['type'],
+          name,
+          arguments,
+        )
+      end
+
+      ## Work around for Hyperbolic bugs:
+      ## 1. In streaming mode Hyperbolic returns an arguments string that ends with '<|im_end|>'
+      ## 2. In streming mode, the function name is null, and the arguments JSON has an additional nested level with _name key and arguments key
+      ## 3. In non-streaming mode Hyperbolic returns an arguments hash, not a JSON parsable string (but we deal with that above)
+      ## Returns a hash with the parsed arguments (in uncorrected Hyperbolic format) if they are detected, otherwise nil
+      def self.hyperbolic_workaround(arguments_value)
+        if arguments_value.is_a?(String) && arguments_value.end_with?('<|im_end|>')
+          JSON.parse(arguments_value[0..-11])
+        else
+          nil
+        end
+      end
+
+    end
+  end
+end

data/lib/llms/adapters.rb

@@ -0,0 +1,12 @@
+require_relative 'adapters/base_message_adapter'
+require_relative 'adapters/anthropic_message_adapter'
+require_relative 'adapters/anthropic_tool_call_adapter'
+require_relative 'adapters/google_gemini_message_adapter'
+require_relative 'adapters/google_gemini_tool_call_adapter'
+require_relative 'adapters/open_ai_compatible_message_adapter'
+require_relative 'adapters/open_ai_compatible_tool_call_adapter'
+
+module LLMs
+  module Adapters
+  end
+end

data/lib/llms/apis/google_gemini_api.rb

@@ -0,0 +1,45 @@
+require 'net/http'
+require 'json'
+
+module LLMs
+  module APIs
+    class GoogleGeminiAPI
+
+      def initialize(api_key)
+        @api_key = api_key
+      end
+
+      def generate_content(model_name, messages, params = {})
+        stream = params.delete(:stream)
+
+        path = "/#{model_name}:#{!!stream ? 'streamGenerateContent?alt=sse&' : 'generateContent?'}key=#{@api_key}"
+        uri = URI("https://generativelanguage.googleapis.com/v1beta/models#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+
+        request = Net::HTTP::Post.new(uri)
+        request['Content-Type'] = 'application/json'
+
+        request.body = params.merge({
+          contents: messages
+        }).to_json
+
+        if stream
+          http.request(request) do |response|
+            if response.code.to_s == '200'
+              response.read_body do |data|
+                stream.call(data)
+              end
+              return nil ## return nil to indicate that there's no separate api response other than the stream
+            else
+              return JSON.parse(response.body)
+            end
+          end
+        else
+          response = http.request(request)
+          JSON.parse(response.body)
+        end
+      end
+    end
+  end
+end