llm.rb 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d5d93a645b666da3d6947c2076189063aec26e7bc3381cfb84d6a6aea4ce8fa
-  data.tar.gz: db764cd8e9180a3c21ca5bf2b35d8a5fa3f525cb63101381aca09f9e92cb5d37
+  metadata.gz: 9b4e83ac151c51faaa4a1e275058091a9ce6f61c3dc10e879a6215b0f1498aad
+  data.tar.gz: f78b7bbeaece69384d6b38014e9d1d99816195d8536a310a25d2a23479dda122
 SHA512:
-  metadata.gz: c17999419e02e8c2d9d689299d149dd76077b1f52154557253dd9fe3876ff1109eaaa29d7d7aceda8147f38aa572261b455eaa253fbede212b874af42c8e03e0
-  data.tar.gz: 1061af3f752a1e8cbc37c8929a23f6bfa97328f66f3adf030e435f468785ffa6a3aae32fe5120936f872b60d8a48a31fcbf35cee0de66b8ee12ddedf17228beb
+  metadata.gz: e117602fae5643713a159d633201cd88e94a339763710bbb788b3b1439e39bbbff9f2c221975fc58e1b57aabdf8d0d935d69dbc6acbece84e98701e129cf3c3d
+  data.tar.gz: 79f2ef053bf500ba9e5ab76c62abdb69ab93ba43b2f11fce867d008e64fbe09e154c1a30fbfdeb08ae30a5442b5d7e5876aa42c788dce8d0778c786f0a69adee

data/README.md

@@ -1,9 +1,9 @@
 ## About
 
 llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
-includes OpenAI, Gemini, Anthropic, Ollama, and LlamaCpp. It’s fast, simple
-and composable – with full support for chat, tool calling, audio,
-images, files, and JSON Schema generation.
+includes OpenAI, Gemini, Anthropic, DeepSeek, Ollama, and LlamaCpp.
+It's fast, simple and composable – with full support for chat,
+tool calling, audio, images, files, and JSON Schema generation.
 
 ## Features
 
@@ -11,7 +11,6 @@ images, files, and JSON Schema generation.
 - ✅ A single unified interface for multiple providers
 - 📦 Zero dependencies outside Ruby's standard library
 - 🚀 Optimized for performance and low memory usage
-- 🔌 Retrieve models dynamically for introspection and selection
 
 #### Chat, Agents
 - 🧠 Stateless and stateful chat via completions and responses API
@@ -24,8 +23,9 @@ images, files, and JSON Schema generation.
 - 📎 File uploads and prompt-aware file interaction
 - 💡 Multimodal prompts (text, images, PDFs, URLs, files)
 
-#### Embeddings
+#### Miscellaneous
 - 🧮 Text embeddings and vector support
+- 🔌 Retrieve models dynamically for introspection and selection
 
 ## Demos
 
@@ -35,13 +35,13 @@ images, files, and JSON Schema generation.
 </details>
 
 <details>
-  <summary><b>2. Files: import at boot time</b></summary>
-  <img src="share/llm-shell/examples/files-boottime.gif">
+  <summary><b>2. Files: import at runtime</b></summary>
+  <img src="share/llm-shell/examples/files-runtime.gif">
 </details>
 
 <details>
-<summary><b>3. Files: import at runtime</b></summary>
-  <img src="share/llm-shell/examples/files-runtime.gif">
+  <summary><b>3. Files: import at boot time</b></summary>
+  <img src="share/llm-shell/examples/files-boottime.gif">
 </details>
 
 ## Examples
@@ -59,12 +59,18 @@ using an API key (if required) and an optional set of configuration options via
 #!/usr/bin/env ruby
 require "llm"
 
+##
+# cloud providers
 llm = LLM.openai(key: "yourapikey")
 llm = LLM.gemini(key: "yourapikey")
 llm = LLM.anthropic(key: "yourapikey")
+llm = LLM.deepseek(key: "yourapikey")
+llm = LLM.voyageai(key: "yourapikey")
+
+##
+# local providers
 llm = LLM.ollama(key: nil)
 llm = LLM.llamacpp(key: nil)
-llm = LLM.voyageai(key: "yourapikey")
 ```
 
 ### Conversations
@@ -73,7 +79,7 @@ llm = LLM.voyageai(key: "yourapikey")
 
 > This example uses the stateless chat completions API that all
 > providers support. A similar example for OpenAI's stateful
-> responses API is available in the [docs/](docs/OPENAI_RESPONSES.md)
+> responses API is available in the [docs/](docs/OPENAI.md)
 > directory.
 
 The following example enables lazy mode for a
@@ -121,11 +127,12 @@ msgs.each { print "[#{_1.role}] ", _1.content, "\n" }
 
 #### Structured
 
-All LLM providers except Anthropic allow a client to describe the structure
-of a response that a LLM emits according to a schema that is described by JSON.
-The schema lets a client describe what JSON object (or value) an LLM should emit,
-and the LLM will abide by the schema. See also: [JSON Schema website](https://json-schema.org/overview/what-is-jsonschema).
- We will use the
+All LLM providers except Anthropic and DeepSeek allow a client to describe
+the structure of a response that a LLM emits according to a schema that is
+described by JSON. The schema lets a client describe what JSON object (or value)
+an LLM should emit, and the LLM will abide by the schema.
+See also: [JSON Schema website](https://json-schema.org/overview/what-is-jsonschema).
+We will use the
 [llmrb/json-schema](https://github.com/llmrb/json-schema)
 library for the sake of the examples &ndash; the interface is designed so you
 could drop in any other library in its place:
@@ -134,22 +141,31 @@ could drop in any other library in its place:
 #!/usr/bin/env ruby
 require "llm"
 
+##
+# Objects
 llm = LLM.openai(key: ENV["KEY"])
-schema = llm.schema.object({fruit: llm.schema.string.enum("Apple", "Orange", "Pineapple")})
+schema = llm.schema.object(answer: llm.schema.integer.required)
+bot = LLM::Chat.new(llm, schema:).lazy
+bot.chat "Does the earth orbit the sun?", role: :user
+bot.messages.find(&:assistant?).content! # => {probability: 1}
+
+##
+# Enums
+schema = llm.schema.object(fruit: llm.schema.string.enum("Apple", "Orange", "Pineapple"))
 bot = LLM::Chat.new(llm, schema:).lazy
 bot.chat "Your favorite fruit is Pineapple", role: :system
 bot.chat "What fruit is your favorite?", role: :user
 bot.messages.find(&:assistant?).content! # => {fruit: "Pineapple"}
 
-schema = llm.schema.object({answer: llm.schema.integer.required})
+##
+# Arrays
+schema = llm.schema.object(answers: llm.schema.array(llm.schema.integer.required))
 bot = LLM::Chat.new(llm, schema:).lazy
+bot.chat "Answer all of my questions", role: :system
 bot.chat "Tell me the answer to ((5 + 5) / 2)", role: :user
-bot.messages.find(&:assistant?).content! # => {answer: 5}
-
-schema = llm.schema.object({probability: llm.schema.number.required})
-bot = LLM::Chat.new(llm, schema:).lazy
-bot.chat "Does the earth orbit the sun?", role: :user
-bot.messages.find(&:assistant?).content! # => {probability: 1}
+bot.chat "Tell me the answer to ((5 + 5) / 2) * 2", role: :user
+bot.chat "Tell me the answer to ((5 + 5) / 2) * 2 + 1", role: :user
+bot.messages.find(&:assistant?).content! # => {answers: [5, 10, 11]}
 ```
 
 ### Tools

data/lib/json/schema/array.rb

@@ -7,7 +7,7 @@ class JSON::Schema
   # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
   # can act as constraints.
   class Array < Leaf
-    def initialize(*items)
+    def initialize(items)
       @items = items
     end
 

data/lib/llm/buffer.rb

@@ -82,7 +82,7 @@ module LLM
         message.content,
         params.merge(role:, messages:)
       )
-      @completed.concat([*pendings, message, completion.choices[0]])
+      @completed.concat([*pendings, message, *completion.choices[0]])
       @pending.clear
     end
 
@@ -95,7 +95,7 @@ module LLM
         @response ? {previous_response_id: @response.id} : {}
       ].inject({}, &:merge!)
       @response = @provider.responses.create(message.content, params.merge(role:))
-      @completed.concat([*pendings, message, @response.outputs[0]])
+      @completed.concat([*pendings, message, *@response.outputs[0]])
       @pending.clear
     end
   end

data/lib/llm/chat/conversable.rb

@@ -24,7 +24,7 @@ class LLM::Chat
     def sync_response(prompt, params = {})
       role = params[:role]
       @response = create_response!(prompt, params)
-      @messages.concat [Message.new(role, prompt), @response.outputs[0]]
+      @messages.concat [Message.new(role, prompt), *@response.outputs[0]]
     end
 
     ##
@@ -45,7 +45,7 @@ class LLM::Chat
     def sync_completion(prompt, params = {})
       role = params[:role]
       completion = create_completion!(prompt, params)
-      @messages.concat [Message.new(role, prompt), completion.choices[0]]
+      @messages.concat [Message.new(role, prompt), *completion.choices[0]]
     end
 
     include LLM

data/lib/llm/error.rb

@@ -16,11 +16,11 @@ module LLM
       # @return [Net::HTTPResponse]
       #  Returns the response associated with an error
       attr_accessor :response
-    end
 
-    ##
-    # When a prompt is given an object that's not understood
-    PromptError = Class.new(Error)
+      def message
+        [super, response.body].join("\n")
+      end
+    end
 
     ##
     # HTTPUnauthorized
@@ -29,5 +29,13 @@ module LLM
     ##
     # HTTPTooManyRequests
     RateLimit = Class.new(ResponseError)
+
+    ##
+    # When an given an input that is not understood
+    FormatError = Class.new(Error)
+
+    ##
+    # When given a prompt that is not understood
+    PromptError = Class.new(FormatError)
   end
 end

data/lib/llm/message.rb

@@ -121,7 +121,7 @@ module LLM
     private
 
     def tool_calls
-      @tool_calls ||= OpenStruct.from_hash(@extra[:tool_calls] || [])
+      @tool_calls ||= LLM::Object.from_hash(@extra[:tool_calls] || [])
     end
   end
 end

data/lib/llm/model.rb

@@ -4,7 +4,7 @@
 # The {LLM::Model LLM::Model} class represents an LLM model that
 # is available to use. Its properties are delegated to the underlying
 # response body, and vary by provider.
-class LLM::Model < OpenStruct
+class LLM::Model < LLM::Object
   ##
   # Returns a subclass of {LLM::Provider LLM::Provider}
   # @return [LLM::Provider]

data/lib/llm/{core_ext/ostruct.rb → object/builder.rb}

@@ -1,17 +1,18 @@
 # frozen_string_literal: true
 
-require "ostruct"
-class OpenStruct
-  module FromHash
+class LLM::Object
+  ##
+  # @private
+  module Builder
     ##
     # @example
-    #   obj = OpenStruct.from_hash(person: {name: 'John'})
+    #   obj = LLM::Object.from_hash(person: {name: 'John'})
     #   obj.person.name  # => 'John'
-    #   obj.person.class # => OpenStruct
+    #   obj.person.class # => LLM::Object
     # @param [Hash, Array] obj
     #   A Hash object
-    # @return [OpenStruct]
-    #   An OpenStruct object initialized by visiting `obj` with recursion
+    # @return [LLM::Object]
+    #   An LLM::Object object initialized by visiting `obj` with recursion
     def from_hash(obj)
       case obj
       when self then from_hash(obj.to_h)
@@ -35,9 +36,4 @@ class OpenStruct
       end
     end
   end
-  extend FromHash
-
-  def to_json(...)
-    to_h.to_json(...)
-  end
 end

data/lib/llm/object/kernel.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class LLM::Object
+  ##
+  # @private
+  module Kernel
+    def tap(...)
+      ::Kernel.instance_method(:tap).bind(self).call(...)
+    end
+
+    def instance_of?(...)
+      ::Kernel.instance_method(:instance_of?).bind(self).call(...)
+    end
+
+    def method(...)
+      ::Kernel.instance_method(:method).bind(self).call(...)
+    end
+
+    def kind_of?(...)
+      ::Kernel.instance_method(:kind_of?).bind(self).call(...)
+    end
+    alias_method :is_a?, :kind_of?
+
+    def respond_to?(m, include_private = false)
+      @h.key?(m.to_sym) || self.class.instance_methods.include?(m) || super
+    end
+
+    def respond_to_missing?(m, include_private = false)
+      @h.key?(m.to_sym) || super
+    end
+
+    def object_id
+      ::Kernel.instance_method(:object_id).bind(self).call
+    end
+
+    def class
+      ::Kernel.instance_method(:class).bind(self).call
+    end
+
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} @h=#{to_h.inspect}>"
+    end
+    alias_method :to_s, :inspect
+  end
+end

data/lib/llm/object.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::Object LLM::Object} class encapsulates a Hash object, and it
+# allows a consumer to get and set Hash keys via regular methods. It is
+# similar in spirit to OpenStruct, and it was introduced after OpenStruct
+# became a bundled gem (and not a default gem) in Ruby 3.5.
+class LLM::Object < BasicObject
+  require_relative "object/builder"
+  require_relative "object/kernel"
+
+  extend Builder
+  include Kernel
+  include ::Enumerable
+  defined?(::PP) ? include(::PP::ObjectMixin) : nil
+
+  ##
+  # @param [Hash] h
+  # @return [LLM::Object]
+  def initialize(h)
+    @h = h.transform_keys(&:to_sym) || h
+  end
+
+  ##
+  # Yields a key|value pair to a block.
+  # @yieldparam [Symbol] k
+  # @yieldparam [Object] v
+  # @return [void]
+  def each(&)
+    @h.each(&)
+  end
+
+  ##
+  # @param [Symbol, #to_sym] k
+  # @return [Object]
+  def [](k)
+    @h[k.to_sym]
+  end
+
+  ##
+  # @param [Symbol, #to_sym] k
+  # @param [Object] v
+  # @return [void]
+  def []=(k, v)
+    @h[k.to_sym] = v
+  end
+
+  ##
+  # @return [String]
+  def to_json(...)
+    to_h.to_json(...)
+  end
+
+  ##
+  # @return [Hash]
+  def to_h
+    @h
+  end
+
+  private
+
+  def method_missing(m, *args, &b)
+    if m.to_s.end_with?("=")
+      @h[m[0..-2].to_sym] = args.first
+    elsif @h.key?(m)
+      @h[m]
+    else
+      nil
+    end
+  end
+end

data/lib/llm/provider.rb

@@ -168,6 +168,13 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # @return [LLM::OpenAI::Moderations]
+  #  Returns an interface to the moderations API
+  def moderations
+    raise NotImplementedError
+  end
+
   ##
   # @return [String]
   #  Returns the role of the assistant in the conversation.
@@ -193,6 +200,20 @@ class LLM::Provider
     end
   end
 
+  ##
+  # Add one or more headers to all requests
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   llm.with(headers: {"OpenAI-Organization" => ENV["ORG"]})
+  #   llm.with(headers: {"OpenAI-Project" => ENV["PROJECT"]})
+  # @param [Hash<String,String>] headers
+  #  One or more headers
+  # @return [LLM::Provider]
+  #  Returns self
+  def with(headers:)
+    tap { (@headers ||= {}).merge!(headers) }
+  end
+
   private
 
   ##

data/lib/llm/providers/anthropic/response_parser/completion_parser.rb

@@ -5,7 +5,7 @@ module LLM::Anthropic::ResponseParser
   # @private
   class CompletionParser
     def initialize(body)
-      @body = OpenStruct.from_hash(body)
+      @body = LLM::Object.from_hash(body)
     end
 
     def format(response)
@@ -34,7 +34,7 @@ module LLM::Anthropic::ResponseParser
           name: tool.name,
           arguments: tool.input
         }
-        OpenStruct.new(tool)
+        LLM::Object.new(tool)
       end
     end
 

data/lib/llm/providers/anthropic.rb

@@ -84,11 +84,11 @@ module LLM
     private
 
     def headers
-      {
+      (@headers || {}).merge(
         "Content-Type" => "application/json",
         "x-api-key" => @key,
         "anthropic-version" => "2023-06-01"
-      }
+      )
     end
 
     def response_parser

data/lib/llm/providers/deepseek/format/completion_format.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module LLM::DeepSeek::Format
+  ##
+  # @private
+  class CompletionFormat
+    ##
+    # @param [LLM::Message, Hash] message
+    #  The message to format
+    def initialize(message)
+      @message = message
+    end
+
+    ##
+    # Formats the message for the OpenAI chat completions API
+    # @return [Hash]
+    def format
+      catch(:abort) do
+        if Hash === message
+          {role: message[:role], content: format_content(message[:content])}
+        elsif message.tool_call?
+          {role: message.role, content: nil, tool_calls: message.extra[:original_tool_calls]}
+        else
+          format_message
+        end
+      end
+    end
+
+    private
+
+    def format_content(content)
+      case content
+      when String
+        content.to_s
+      when LLM::Message
+        format_content(content.content)
+      when LLM::Function::Return
+        throw(:abort, {role: "tool", tool_call_id: content.id, content: JSON.dump(content.value)})
+      else
+        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                       "is not supported by the DeepSeek chat completions API"
+      end
+    end
+
+    def format_message
+      case content
+      when Array
+        format_array
+      else
+        {role: message.role, content: format_content(content)}
+      end
+    end
+
+    def format_array
+      if content.empty?
+        nil
+      elsif returns.any?
+        returns.map { {role: "tool", tool_call_id: _1.id, content: JSON.dump(_1.value)} }
+      else
+        {role: message.role, content: content.flat_map { format_content(_1) }}
+      end
+    end
+
+    def message = @message
+    def content = message.content
+    def returns = content.grep(LLM::Function::Return)
+  end
+end

data/lib/llm/providers/deepseek/format.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class LLM::DeepSeek
+  ##
+  # @private
+  module Format
+    require_relative "format/completion_format"
+    ##
+    # @param [Array<LLM::Message>] messages
+    #  The messages to format
+    # @return [Array<Hash>]
+    def format(messages, ...)
+      messages.filter_map do |message|
+        CompletionFormat.new(message).format
+      end
+    end
+
+    private
+
+    ##
+    # @param [Hash] params
+    # @return [Hash]
+    def format_tools(params)
+      tools = params.delete(:tools)
+      (tools.nil? || tools.empty?) ? {} : {tools: tools.map { _1.format(self) }}
+    end
+  end
+end

data/lib/llm/providers/deepseek.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "openai" unless defined?(LLM::OpenAI)
+
+module LLM
+  ##
+  # The DeepSeek class implements a provider for
+  # [DeepSeek](https://deepseek.com)
+  # through its OpenAI-compatible API provided via
+  # their [web platform](https://platform.deepseek.com).
+  class DeepSeek < OpenAI
+    require_relative "deepseek/format"
+    include DeepSeek::Format
+
+    ##
+    # @param (see LLM::Provider#initialize)
+    # @return [LLM::DeepSeek]
+    def initialize(host: "api.deepseek.com", port: 443, ssl: true, **)
+      super
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def files
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def images
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def audio
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def moderations
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def responses
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # @see https://api-docs.deepseek.com/quick_start/pricing deepseek-chat
+    # @return [String]
+    def default_model
+      "deepseek-chat"
+    end
+  end
+end

data/lib/llm/providers/gemini/files.rb

@@ -61,7 +61,7 @@ class LLM::Gemini
       LLM::Response::FileList.new(res).tap { |filelist|
         files = filelist.body["files"]&.map do |file|
           file = file.transform_keys { snakecase(_1) }
-          OpenStruct.from_hash(file)
+          LLM::Object.from_hash(file)
         end || []
         filelist.files = files
       }

data/lib/llm/providers/gemini/response_parser/completion_parser.rb

@@ -3,7 +3,7 @@
 module LLM::Gemini::ResponseParser
   class CompletionParser
     def initialize(body)
-      @body = OpenStruct.from_hash(body)
+      @body = LLM::Object.from_hash(body)
     end
 
     def format(response)
@@ -32,7 +32,7 @@ module LLM::Gemini::ResponseParser
     def format_tool_calls(tools)
       (tools || []).map do |tool|
         function = {name: tool.name, arguments: tool.args}
-        OpenStruct.new(function)
+        LLM::Object.new(function)
       end
     end
 

data/lib/llm/providers/gemini.rb

@@ -131,9 +131,9 @@ module LLM
     private
 
     def headers
-      {
+      (@headers || {}).merge(
         "Content-Type" => "application/json"
-      }
+      )
     end
 
     def response_parser