llms 0.1.0

data/lib/llms/stream/events.rb

@@ -0,0 +1,104 @@
+module LLMs
+  module Stream
+    class Events
+      class Base
+        attr_reader :timestamp
+        def initialize
+          @timestamp = Time.now
+        end
+      end
+
+      class MessageStarted < Base
+        attr_reader :message_id, :text
+        def initialize(message_id, text = '')
+          super()
+          @message_id = message_id
+          @text = text
+        end
+      end
+
+      class UsageUpdated < Base
+        attr_reader :message_id, :usage
+        def initialize(message_id, usage)
+          super()
+          @message_id = message_id
+          @usage = usage
+        end
+      end
+
+      class ThinkingDelta < Base
+        attr_reader :message_id, :thinking
+        def initialize(message_id, thinking)
+          super()
+          @message_id = message_id
+          @thinking = thinking
+        end
+      end
+
+      class TextDelta < Base
+        attr_reader :message_id, :text
+        def initialize(message_id, text)
+          super()
+          @message_id = message_id
+          @text = text
+        end
+      end
+
+      class ToolCallStarted < Base
+        attr_reader :message_id, :tool_call_id, :index, :name, :arguments
+        def initialize(message_id, tool_call_id, index, name, arguments)
+          super()
+          @message_id = message_id
+          @tool_call_id = tool_call_id
+          @index = index
+          @name = name
+          @arguments = arguments
+        end
+      end
+
+      class ToolCallArgumentsJsonDelta < Base
+        attr_reader :message_id, :tool_call_id, :index, :json_delta
+        def initialize(message_id, tool_call_id, index, json_delta)
+          super()
+          @message_id = message_id
+          @tool_call_id = tool_call_id
+          @index = index
+          @json_delta = json_delta
+        end
+      end
+
+      ## Holds the current parse-attempted state of the arguments object, not a delta
+      class ToolCallArgumentsUpdated < Base
+        attr_reader :message_id, :tool_call_id, :index, :arguments
+        def initialize(message_id, tool_call_id, index, arguments)
+          super()
+          @message_id = message_id
+          @tool_call_id = tool_call_id
+          @index = index
+          @arguments = arguments
+        end
+      end
+
+      class ToolCallCompleted < Base
+        attr_reader :message_id, :tool_call_id, :index, :name, :arguments
+        def initialize(message_id, tool_call_id, index, name, arguments)
+          super()
+          @message_id = message_id
+          @tool_call_id = tool_call_id
+          @index = index
+          @name = name
+          @arguments = arguments
+        end
+      end
+
+      class MessageCompleted < Base
+        attr_reader :message_id, :response
+        def initialize(message_id, response)
+          super()
+          @message_id = message_id
+          @response = response
+        end
+      end
+    end
+  end
+end

data/lib/llms/usage/cost_calculator.rb

@@ -0,0 +1,75 @@
+module LLMs
+  module Usage
+    class CostCalculator
+      def initialize(pricing)
+        @pricing = pricing || {}
+      end
+
+      def calculate(usage_data, model = nil)
+        pricing = model&.pricing || @pricing
+        components = []
+        total_cost = 0.0
+
+        if usage_data.input_tokens > 0 && pricing[:input]
+          cost = (usage_data.input_tokens / 1_000_000.0) * pricing[:input]
+          components << {
+            type: :input,
+            tokens: usage_data.input_tokens,
+            rate: pricing[:input],
+            cost: cost
+          }
+          total_cost += cost
+        end
+
+        if usage_data.output_tokens > 0 && pricing[:output]
+          cost = (usage_data.output_tokens / 1_000_000.0) * pricing[:output]
+          components << {
+            type: :output,
+            tokens: usage_data.output_tokens,
+            rate: pricing[:output],
+            cost: cost
+          }
+          total_cost += cost
+        end
+
+        if usage_data.cache_read_tokens > 0 && pricing[:cache_read]
+          cost = (usage_data.cache_read_tokens / 1_000_000.0) * pricing[:cache_read]
+          components << {
+            type: :cache_read,
+            tokens: usage_data.cache_read_tokens,
+            rate: pricing[:cache_read],
+            cost: cost
+          }
+          total_cost += cost
+        end
+
+        if usage_data.cache_write_tokens > 0 && pricing[:cache_write]
+          cost = (usage_data.cache_write_tokens / 1_000_000.0) * pricing[:cache_write]
+          components << {
+            type: :cache_write,
+            tokens: usage_data.cache_write_tokens,
+            rate: pricing[:cache_write],
+            cost: cost
+          }
+          total_cost += cost
+        end
+
+        {
+          total_cost: total_cost,
+          components: components,
+          currency: 'USD'
+        }
+      end
+
+      def calculate_simple(input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0)
+        usage_data = UsageData.new(
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          cache_read_tokens: cache_read_tokens,
+          cache_write_tokens: cache_write_tokens
+        )
+        calculate(usage_data)
+      end
+    end
+  end
+end 

data/lib/llms/usage/usage_data.rb

@@ -0,0 +1,46 @@
+module LLMs
+  module Usage
+    class UsageData
+      attr_reader :input_tokens, :output_tokens, :cache_read_tokens, 
+                  :cache_write_tokens, :execution_time, :model_name
+
+      def initialize(input_tokens: 0, output_tokens: 0, 
+                     cache_read_tokens: 0, cache_write_tokens: 0,
+                     execution_time: 0, model_name: nil)
+        @input_tokens = input_tokens.to_i
+        @output_tokens = output_tokens.to_i
+        @cache_read_tokens = cache_read_tokens.to_i
+        @cache_write_tokens = cache_write_tokens.to_i
+        @execution_time = execution_time.to_f
+        @model_name = model_name
+      end
+
+      def total_tokens
+        @input_tokens + @output_tokens + @cache_read_tokens + @cache_write_tokens
+      end
+
+      def to_h
+        {
+          input_tokens: @input_tokens,
+          output_tokens: @output_tokens,
+          cache_read_tokens: @cache_read_tokens,
+          cache_write_tokens: @cache_write_tokens,
+          total_tokens: total_tokens,
+          execution_time: @execution_time,
+          model_name: @model_name
+        }
+      end
+
+      def to_s
+        if total_tokens == 0
+          "Usage: 0 tokens () in #{@execution_time.round(2)}s"
+        else
+          "Usage: #{total_tokens} tokens (#{@input_tokens} input, #{@output_tokens} output" +
+          "#{@cache_read_tokens > 0 ? ", #{@cache_read_tokens} cache_read" : ""}" +
+          "#{@cache_write_tokens > 0 ? ", #{@cache_write_tokens} cache_write" : ""}" +
+          ") in #{@execution_time.round(2)}s"
+        end
+      end
+    end
+  end
+end 

data/lib/llms.rb

@@ -0,0 +1,16 @@
+require_relative 'llms/exceptions'
+require_relative 'llms/conversation'
+require_relative 'llms/conversation_message'
+require_relative 'llms/conversation_tool_call'
+require_relative 'llms/conversation_tool_result'
+require_relative 'llms/executors'
+require_relative 'llms/adapters'
+require_relative 'llms/models'
+require_relative 'llms/usage/usage_data'
+require_relative 'llms/usage/cost_calculator'
+require_relative 'llms/models/provider'
+require_relative 'llms/models/model'
+
+module LLMs
+  VERSION = '0.1.0'
+end 

metadata

@@ -0,0 +1,243 @@
+--- !ruby/object:Gem::Specification
+name: llms
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ben Lund
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-anthropic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: readline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Ruby library for interacting with various LLM providers including Anthropic,
+  Google Gemini, xAI, and other OpenAI-compatible API providers (including local models).
+  Supports streaming, event-handling, conversation management, tool-use, image input,
+  and cost-tracking.
+email:
+- ben@benlund.com
+executables:
+- llms-chat
+- llms-test-model-access
+- llms-test-model-image-support
+- llms-test-model-prompt-caching
+- llms-test-model-tool-use
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/llms-chat
+- bin/llms-test-model-access
+- bin/llms-test-model-image-support
+- bin/llms-test-model-prompt-caching
+- bin/llms-test-model-tool-use
+- lib/llms.rb
+- lib/llms/adapters.rb
+- lib/llms/adapters/anthropic_message_adapter.rb
+- lib/llms/adapters/anthropic_tool_call_adapter.rb
+- lib/llms/adapters/base_message_adapter.rb
+- lib/llms/adapters/google_gemini_message_adapter.rb
+- lib/llms/adapters/google_gemini_tool_call_adapter.rb
+- lib/llms/adapters/open_ai_compatible_message_adapter.rb
+- lib/llms/adapters/open_ai_compatible_tool_call_adapter.rb
+- lib/llms/apis/google_gemini_api.rb
+- lib/llms/apis/open_ai_compatible_api.rb
+- lib/llms/cli.rb
+- lib/llms/cli/base.rb
+- lib/llms/cli/chat.rb
+- lib/llms/cli/test_access.rb
+- lib/llms/cli/test_image_support.rb
+- lib/llms/cli/test_prompt_caching.rb
+- lib/llms/cli/test_tool_use.rb
+- lib/llms/conversation.rb
+- lib/llms/conversation_message.rb
+- lib/llms/conversation_tool_call.rb
+- lib/llms/conversation_tool_result.rb
+- lib/llms/exceptions.rb
+- lib/llms/executors.rb
+- lib/llms/executors/anthropic_executor.rb
+- lib/llms/executors/base_executor.rb
+- lib/llms/executors/google_gemini_executor.rb
+- lib/llms/executors/hugging_face_executor.rb
+- lib/llms/executors/open_ai_compatible_executor.rb
+- lib/llms/models.rb
+- lib/llms/models/model.rb
+- lib/llms/models/provider.rb
+- lib/llms/parsers/anthropic_chat_response_stream_parser.rb
+- lib/llms/parsers/google_gemini_chat_response_stream_parser.rb
+- lib/llms/parsers/open_ai_compatible_chat_response_stream_parser.rb
+- lib/llms/parsers/partial_json_parser.rb
+- lib/llms/parsers/sse_chat_response_stream_parser.rb
+- lib/llms/public_models.json
+- lib/llms/stream/event_emitter.rb
+- lib/llms/stream/events.rb
+- lib/llms/usage/cost_calculator.rb
+- lib/llms/usage/usage_data.rb
+homepage: https://github.com/benlund/llms
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/benlund/llms
+  source_code_uri: https://github.com/benlund/llms
+  changelog_uri: https://github.com/benlund/llms/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Ruby library for using LLM APIs across multiple providers
+test_files: []