llm.rb 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c8c175d5b640f4d04e114569781bb2cad10b17f76489f4eaecd2ea7963c2baf
-  data.tar.gz: b00e4c4b7bf9211157e66f1ac015540ecec86b1f4d6d8b3bcaa46068ac97fbaf
+  metadata.gz: 9b4e83ac151c51faaa4a1e275058091a9ce6f61c3dc10e879a6215b0f1498aad
+  data.tar.gz: f78b7bbeaece69384d6b38014e9d1d99816195d8536a310a25d2a23479dda122
 SHA512:
-  metadata.gz: e1d27b0fa9a59ec4baf55e7863675c71827c66af091f4b4d2db268e08d83709bbb87c23175c0dda8e2583ced40a2c76bafcba95f118ec64e6f44245878e668dd
-  data.tar.gz: 0201f576e4180dfef2ace9b699711eb013ac4556baf2bc9a584060000ec94fb7f764d1bb1e0d9d8187f76deeea6761e2323f661974e5e93fb50a29e0a62207d8
+  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.

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/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/llamacpp.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "openai" unless defined?(LLM::OpenAI)
+
 module LLM
   ##
   # The LlamaCpp class implements a provider for
@@ -32,12 +34,24 @@ module LLM
       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://ollama.com/library llama3.2
+    # @see https://ollama.com/library/qwen3 qwen3
     # @return [String]
     def default_model
-      "llama3.2"
+      "qwen3"
     end
   end
 end

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

@@ -63,7 +63,7 @@ module LLM::Ollama::Format
       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) }}]
+        content.flat_map { {role: message.role }.merge(format_content(_1)) }
       end
     end
 

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

@@ -5,7 +5,7 @@ module LLM::Ollama::ResponseParser
   # @private
   class CompletionParser
     def initialize(body)
-      @body = OpenStruct.from_hash(body)
+      @body = LLM::Object.from_hash(body)
     end
 
     def format(response)
@@ -29,7 +29,7 @@ module LLM::Ollama::ResponseParser
       return [] unless tools
       tools.filter_map do |tool|
         next unless tool["function"]
-        OpenStruct.new(tool["function"])
+        LLM::Object.new(tool["function"])
       end
     end
 

data/lib/llm/providers/ollama.rb

@@ -40,7 +40,7 @@ module LLM
     # @param params (see LLM::Provider#embed)
     # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#embed)
-    def embed(input, model: "llama3.2", **params)
+    def embed(input, model: default_model, **params)
       params   = {model:}.merge!(params)
       req      = Net::HTTP::Post.new("/v1/embeddings", headers)
       req.body = JSON.dump({input:}.merge!(params))
@@ -86,10 +86,10 @@ module LLM
 
     ##
     # Returns the default model for chat completions
-    # @see https://ollama.com/library llama3.2
+    # @see https://ollama.com/library/qwen3 qwen3
     # @return [String]
     def default_model
-      "llama3.2"
+      "qwen3:latest"
     end
 
     private

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

@@ -53,7 +53,7 @@ class LLM::OpenAI
       req = Net::HTTP::Get.new("/v1/files?#{query}", headers)
       res = request(http, req)
       LLM::Response::FileList.new(res).tap { |filelist|
-        files = filelist.body["data"].map { OpenStruct.from_hash(_1) }
+        files = filelist.body["data"].map { LLM::Object.from_hash(_1) }
         filelist.files = files
       }
     end
@@ -127,12 +127,12 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/files/delete OpenAI docs
     # @param [#id, #to_s] file The file ID
     # @raise (see LLM::Provider#request)
-    # @return [OpenStruct] Response body
+    # @return [LLM::Object] Response body
     def delete(file:)
       file_id = file.respond_to?(:id) ? file.id : file
       req = Net::HTTP::Delete.new("/v1/files/#{file_id}", headers)
       res = request(http, req)
-      OpenStruct.from_hash JSON.parse(res.body)
+      LLM::Object.from_hash JSON.parse(res.body)
     end
 
     private

data/lib/llm/providers/openai/format/moderation_format.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module LLM::OpenAI::Format
+  ##
+  # @private
+  class ModerationFormat
+    ##
+    # @param [String, URI, Array<String, URI>] inputs
+    #  The inputs to format
+    # @return [LLM::OpenAI::Format::ModerationFormat]
+    def initialize(inputs)
+      @inputs = inputs
+    end
+
+    ##
+    # Formats the inputs for the OpenAI moderations API
+    # @return [Array<Hash>]
+    def format
+      [*inputs].flat_map do |input|
+        if String === input
+          {type: :text, text: input}
+        elsif URI === input
+          {type: :image_url, url: input.to_s}
+        else
+          raise LLM::Error::FormatError, "The given object (an instance of #{input.class}) " \
+                                         "is not supported by OpenAI moderations API"
+        end
+      end
+    end
+
+    private
+
+    attr_reader :inputs
+  end
+end

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

@@ -6,6 +6,7 @@ class LLM::OpenAI
   module Format
     require_relative "format/completion_format"
     require_relative "format/respond_format"
+    require_relative "format/moderation_format"
 
     ##
     # @param [Array<LLM::Message>] messages
@@ -43,9 +44,8 @@ class LLM::OpenAI
     # @param [Hash] params
     # @return [Hash]
     def format_tools(params)
-      return {} unless params and params[:tools]&.any?
-      tools = params[:tools]
-      {tools: tools.map { _1.format(self) }}
+      tools = params.delete(:tools)
+      (tools.nil? || tools.empty?) ? {} : {tools: tools.map { _1.format(self) }}
     end
   end
 end

data/lib/llm/providers/openai/moderations.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # The {LLM::OpenAI::Moderations LLM::OpenAI::Moderations} class provides a moderations
+  # object for interacting with [OpenAI's moderations API](https://platform.openai.com/docs/api-reference/moderations).
+  # The moderations API can categorize content into different categories, such as
+  # hate speech, self-harm, and sexual content. It can also provide a confidence score
+  # for each category.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   mod = llm.moderations.create input: "I hate you"
+  #   print "categories: #{mod.categories}", "\n"
+  #   print "scores: #{mod.scores}", "\n"
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   mod = llm.moderations.create input: URI.parse("https://example.com/image.png")
+  #   print "categories: #{mod.categories}", "\n"
+  #   print "scores: #{mod.scores}", "\n"
+  #
+  # @see https://platform.openai.com/docs/api-reference/moderations/create OpenAI docs
+  # @see https://platform.openai.com/docs/models#moderation OpenAI moderation models
+  class Moderations
+    ##
+    # Returns a new Moderations object
+    # @param [LLM::Provider] provider
+    # @return [LLM::OpenAI::Moderations]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # Create a moderation
+    # @see https://platform.openai.com/docs/api-reference/moderations/create OpenAI docs
+    # @see https://platform.openai.com/docs/models#moderation OpenAI moderation models
+    # @note
+    # Although OpenAI mentions an array as a valid input, and that it can return one
+    # or more moderations, in practice the API only returns one moderation object. We
+    # recommend using a single input string or URI, and to keep in mind that llm.rb
+    # returns a Moderation object but has code in place to return multiple objects in
+    # the future (in case OpenAI documentation ever matches the actual API).
+    # @param [String, URI, Array<String, URI>] input
+    # @param [String, LLM::Model] model The model to use
+    # @return [LLM::Response::ModerationList::Moderation]
+    def create(input:, model: "omni-moderation-latest", **params)
+      req = Net::HTTP::Post.new("/v1/moderations", headers)
+      input = Format::ModerationFormat.new(input).format
+      req.body = JSON.dump({input:, model:}.merge!(params))
+      res = request(http, req)
+      LLM::Response::ModerationList.new(res).extend(response_parser).first
+    end
+
+    private
+
+    def http
+      @provider.instance_variable_get(:@http)
+    end
+
+    [:response_parser, :headers, :request].each do |m|
+      define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
+    end
+  end
+end

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

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

data/lib/llm/providers/openai/response_parser/respond_parser.rb

@@ -5,7 +5,7 @@ module LLM::OpenAI::ResponseParser
   # @private
   class RespondParser
     def initialize(body)
-      @body = OpenStruct.from_hash(body)
+      @body = LLM::Object.from_hash(body)
     end
 
     def format(response)
@@ -37,7 +37,7 @@ module LLM::OpenAI::ResponseParser
     end
 
     def format_tool(tool)
-      OpenStruct.new(
+      LLM::Object.new(
         id: tool.call_id,
         name: tool.name,
         arguments: JSON.parse(tool.arguments)

data/lib/llm/providers/openai/response_parser.rb

@@ -20,6 +20,18 @@ class LLM::OpenAI
       RespondParser.new(body).format(self)
     end
 
+    ##
+    # @param [Hash] body
+    #  The response body from the LLM provider
+    # @return [Hash]
+    def parse_moderation_list(body)
+      {
+        id: body["id"],
+        model: body["model"],
+        moderations: body["results"].map { LLM::Response::ModerationList::Moderation.new(_1) }
+      }
+    end
+
     ##
     # @param [Hash] body
     #  The response body from the LLM provider

data/lib/llm/providers/openai/responses.rb

@@ -13,8 +13,8 @@ class LLM::OpenAI
   #   require "llm"
   #
   #   llm = LLM.openai(ENV["KEY"])
-  #   res1 = llm.responses.create "Your task is to help me with math", :developer
-  #   res2 = llm.responses.create "5 + 5  = ?", :user, previous_response_id: res1.id
+  #   res1 = llm.responses.create "Your task is to help me with math", role: :developer
+  #   res2 = llm.responses.create "5 + 5  = ?", role: :user, previous_response_id: res1.id
   #   [res1,res2].each { llm.responses.delete(_1) }
   # @example
   #   #!/usr/bin/env ruby
@@ -81,12 +81,12 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/responses/delete OpenAI docs
     # @param [#id, #to_s] response Response ID
     # @raise (see LLM::Provider#request)
-    # @return [OpenStruct] Response body
+    # @return [LLM::Object] Response body
     def delete(response)
       response_id = response.respond_to?(:id) ? response.id : response
       req = Net::HTTP::Delete.new("/v1/responses/#{response_id}", headers)
       res = request(http, req)
-      OpenStruct.from_hash JSON.parse(res.body)
+      LLM::Object.from_hash JSON.parse(res.body)
     end
 
     private

data/lib/llm/providers/openai.rb

@@ -15,6 +15,8 @@ module LLM
     require_relative "openai/audio"
     require_relative "openai/files"
     require_relative "openai/models"
+    require_relative "openai/moderations"
+
     include Format
 
     HOST = "api.openai.com"
@@ -102,6 +104,15 @@ module LLM
       LLM::OpenAI::Models.new(self)
     end
 
+    ##
+    # Provides an interface to OpenAI's moderation API
+    # @see https://platform.openai.com/docs/api-reference/moderations/create OpenAI docs
+    # @see https://platform.openai.com/docs/models#moderation OpenAI moderation models
+    # @return [LLM::OpenAI::Moderations]
+    def moderations
+      LLM::OpenAI::Moderations.new(self)
+    end
+
     ##
     # @return (see LLM::Provider#assistant_role)
     def assistant_role

data/lib/llm/response/filelist.rb

@@ -5,7 +5,7 @@ module LLM
   # The {LLM::Response::FileList LLM::Response::FileList} class represents a
   # list of file objects that are returned by a provider. It is an Enumerable
   # object, and can be used to iterate over the file objects in a way that is
-  # similar to an array. Each element is an instance of OpenStruct.
+  # similar to an array. Each element is an instance of LLM::Object.
   class Response::FileList < Response
     include Enumerable
 

data/lib/llm/response/image.rb

@@ -8,7 +8,7 @@ module LLM
   class Response::Image < Response
     ##
     # Returns one or more image objects, or nil
-    # @return [Array<OpenStruct>, nil]
+    # @return [Array<LLM::Object>, nil]
     def images
       parsed[:images].any? ? parsed[:images] : nil
     end

data/lib/llm/response/modellist.rb

@@ -5,7 +5,7 @@ module LLM
   # The {LLM::Response::ModelList LLM::Response::ModelList} class represents a
   # list of model objects that are returned by a provider. It is an Enumerable
   # object, and can be used to iterate over the model objects in a way that is
-  # similar to an array. Each element is an instance of OpenStruct.
+  # similar to an array. Each element is an instance of LLM::Object.
   class Response::ModelList < Response
     include Enumerable
 

data/lib/llm/response/moderationlist/moderation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class LLM::Response::ModerationList
+  ##
+  # The {LLM::Response::ModerationList::Moderation Moderation}
+  # class represents a moderation object that is returned by
+  # the moderations interface.
+  # @see LLM::Response::ModerationList
+  # @see LLM::OpenAI::Moderations
+  class Moderation
+    ##
+    # @param [Hash] moderation
+    # @return [LLM::Response::ModerationList::Moderation]
+    def initialize(moderation)
+      @moderation = moderation
+    end
+
+    ##
+    # Returns true if the moderation is flagged
+    # @return [Boolean]
+    def flagged?
+      @moderation["flagged"]
+    end
+
+    ##
+    # Returns the moderation categories
+    # @return [Array<String>]
+    def categories
+      @moderation["categories"].filter_map { _2 ? _1 : nil }
+    end
+
+    ##
+    # Returns the moderation scores
+    # @return [Hash]
+    def scores
+      @moderation["category_scores"].select { categories.include?(_1) }
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} " \
+      "categories=#{categories} " \
+      "scores=#{scores}>"
+    end
+  end
+end

data/lib/llm/response/moderationlist.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Response::ModerationList LLM::Response::ModerationList} class
+  # represents a response from the moderations API. It is an Enumerable that
+  # yields an instance of {LLM::Response::ModerationList::Moderation LLM::Response::ModerationList::Moderation},
+  # and each moderation object contains the categories and scores for a given
+  # input.
+  # @see LLM::OpenAI::Moderations LLM::OpenAI::Moderations
+  class Response::ModerationList < Response
+    require_relative "moderationlist/moderation"
+    include Enumerable
+
+    ##
+    # Returns the moderation ID
+    # @return [String]
+    def id
+      parsed[:id]
+    end
+
+    ##
+    # Returns the moderation model
+    # @return [String]
+    def model
+      parsed[:model]
+    end
+
+    ##
+    # Yields each moderation object
+    # @yieldparam [OpenStruct] moderation
+    # @yieldreturn [void]
+    # @return [void]
+    def each(&)
+      moderations.each(&)
+    end
+
+    private
+
+    def parsed
+      @parsed ||= parse_moderation_list(body)
+    end
+
+    ##
+    # Returns an array of moderation objects
+    # @return [Array<OpenStruct>]
+    def moderations
+      parsed[:moderations]
+    end
+  end
+end

data/lib/llm/response.rb

@@ -14,6 +14,7 @@ module LLM
     require_relative "response/filelist"
     require_relative "response/download_file"
     require_relative "response/modellist"
+    require_relative "response/moderationlist"
 
     ##
     # @param [Net::HTTPResponse] res

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "0.7.2"
+  VERSION = "0.8.0"
 end

data/lib/llm.rb

@@ -3,7 +3,7 @@
 module LLM
   require "stringio"
   require_relative "json/schema"
-  require_relative "llm/core_ext/ostruct"
+  require_relative "llm/object"
   require_relative "llm/version"
   require_relative "llm/utils"
   require_relative "llm/error"
@@ -57,11 +57,18 @@ module LLM
   # @param key (see LLM::Provider#initialize)
   # @return (see LLM::LlamaCpp#initialize)
   def llamacpp(key: nil, **)
-    require_relative "llm/providers/openai" unless defined?(LLM::OpenAI)
     require_relative "llm/providers/llamacpp" unless defined?(LLM::LlamaCpp)
     LLM::LlamaCpp.new(key:, **)
   end
 
+  ##
+  # @param key (see LLM::Provider#initialize)
+  # @return (see LLM::DeepSeek#initialize)
+  def deepseek(**)
+    require_relative "llm/providers/deepseek" unless defined?(LLM::DeepSeek)
+    LLM::DeepSeek.new(**)
+  end
+
   ##
   # @param key (see LLM::Provider#initialize)
   # @return (see LLM::OpenAI#initialize)

data/llm.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 
   spec.summary = "llm.rb is a zero-dependency Ruby toolkit for " \
                  "Large Language Models that includes OpenAI, Gemini, " \
-                 "Anthropic, Ollama, and LlamaCpp. It’s fast, simple " \
+                 "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."
   spec.description = spec.summary

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Antar Azri
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-11 00:00:00.000000000 Z
+date: 2025-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: webmock
@@ -152,9 +152,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.8'
 description: 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.
 email:
 - azantar@proton.me
 - 0x1eef@proton.me
@@ -181,7 +181,6 @@ files:
 - lib/llm/chat/conversable.rb
 - lib/llm/chat/prompt/completion.rb
 - lib/llm/chat/prompt/respond.rb
-- lib/llm/core_ext/ostruct.rb
 - lib/llm/error.rb
 - lib/llm/file.rb
 - lib/llm/function.rb
@@ -189,6 +188,9 @@ files:
 - lib/llm/mime.rb
 - lib/llm/model.rb
 - lib/llm/multipart.rb
+- lib/llm/object.rb
+- lib/llm/object/builder.rb
+- lib/llm/object/kernel.rb
 - lib/llm/provider.rb
 - lib/llm/providers/anthropic.rb
 - lib/llm/providers/anthropic/error_handler.rb
@@ -197,6 +199,9 @@ files:
 - lib/llm/providers/anthropic/models.rb
 - lib/llm/providers/anthropic/response_parser.rb
 - lib/llm/providers/anthropic/response_parser/completion_parser.rb
+- lib/llm/providers/deepseek.rb
+- lib/llm/providers/deepseek/format.rb
+- lib/llm/providers/deepseek/format/completion_format.rb
 - lib/llm/providers/gemini.rb
 - lib/llm/providers/gemini/audio.rb
 - lib/llm/providers/gemini/error_handler.rb
@@ -221,9 +226,11 @@ files:
 - lib/llm/providers/openai/files.rb
 - lib/llm/providers/openai/format.rb
 - lib/llm/providers/openai/format/completion_format.rb
+- lib/llm/providers/openai/format/moderation_format.rb
 - lib/llm/providers/openai/format/respond_format.rb
 - lib/llm/providers/openai/images.rb
 - lib/llm/providers/openai/models.rb
+- lib/llm/providers/openai/moderations.rb
 - lib/llm/providers/openai/response_parser.rb
 - lib/llm/providers/openai/response_parser/completion_parser.rb
 - lib/llm/providers/openai/response_parser/respond_parser.rb
@@ -242,6 +249,8 @@ files:
 - lib/llm/response/filelist.rb
 - lib/llm/response/image.rb
 - lib/llm/response/modellist.rb
+- lib/llm/response/moderationlist.rb
+- lib/llm/response/moderationlist/moderation.rb
 - lib/llm/response/respond.rb
 - lib/llm/utils.rb
 - lib/llm/version.rb
@@ -271,7 +280,7 @@ rubygems_version: 3.5.23
 signing_key:
 specification_version: 4
 summary: 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.
+  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.
 test_files: []