llm.rb 0.7.1 → 0.8.0

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,19 +86,19 @@ 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
 
     def headers
-      {
+      (@headers || {}).merge(
         "Content-Type" => "application/json",
         "Authorization" => "Bearer #{@key}"
-      }
+      )
     end
 
     def response_parser

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
@@ -119,10 +130,10 @@ module LLM
     private
 
     def headers
-      {
+      (@headers || {}).merge(
         "Content-Type" => "application/json",
         "Authorization" => "Bearer #{@key}"
-      }
+      )
     end
 
     def response_parser

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.1"
+  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.1
+  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: []