llm.rb 0.7.2 → 0.9.0

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

@@ -8,22 +8,24 @@ class LLM::OpenAI
   # conversation state across multiple requests. This is useful when you want to
   # save bandwidth and/or not maintain the message thread by yourself.
   #
-  # @example
+  # @example example #1
   #   #!/usr/bin/env ruby
   #   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
+  #
+  # @example example #2
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
   #   llm  = LLM.openai(ENV["KEY"])
   #   file = llm.files.create file: "/images/hat.png"
   #   res  = llm.responses.create ["Describe the image", file]
-  # @example
+  #
+  # @example example #3
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
@@ -58,7 +60,7 @@ class LLM::OpenAI
       messages = [*(params.delete(:input) || []), LLM::Message.new(role, prompt)]
       body = JSON.dump({input: [format(messages, :response)].flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
-      res = request(http, req)
+      res = execute(request: req)
       LLM::Response::Respond.new(res).extend(response_parser)
     end
 
@@ -72,7 +74,7 @@ class LLM::OpenAI
       response_id = response.respond_to?(:id) ? response.id : response
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/responses/#{response_id}?#{query}", headers)
-      res = request(http, req)
+      res = execute(request: req)
       LLM::Response::Respond.new(res).extend(response_parser)
     end
 
@@ -81,24 +83,20 @@ 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)
+      res = execute(request: req)
+      LLM::Object.from_hash JSON.parse(res.body)
     end
 
     private
 
-    def http
-      @provider.instance_variable_get(:@http)
-    end
-
     [:response_parser, :headers,
-     :request, :set_body_stream,
+     :execute, :set_body_stream,
      :format_schema, :format_tools].each do |m|
-      define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
+      define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end
 end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class LLM::OpenAI
+  ##
+  # @private
+  class StreamParser
+    ##
+    # Returns the fully constructed response body
+    # @return [LLM::Object]
+    attr_reader :body
+
+    ##
+    # @return [LLM::OpenAI::Chunk]
+    def initialize(io)
+      @body = LLM::Object.new
+      @io = io
+    end
+
+    ##
+    # @param [Hash] chunk
+    # @return [LLM::OpenAI::Chunk]
+    def parse!(chunk)
+      tap { merge!(chunk) }
+    end
+
+    private
+
+    def merge!(chunk)
+      chunk.each do |key, value|
+        if key == "choices"
+          @body["choices"] ||= []
+          merge_choices!(value)
+        else
+          @body[key] = value
+        end
+      end
+    end
+
+    def merge_choices!(choices)
+      choices.each do |choice|
+        if @body.choices[choice["index"]]
+          target = @body["choices"][choice["index"]]["message"]
+          delta = choice["delta"]
+          delta.each do |key, value|
+            if target[key]
+              if key == "content"
+                target[key] << value
+                @io << value if @io.respond_to?(:<<)
+              elsif key == "tool_calls"
+                merge_tools!(target, value)
+              else
+                target[key] = value
+              end
+            else
+              target[key] = value
+            end
+          end
+        else
+          target = {"message" => {"role" => "assistant"}}
+          @body["choices"][choice["index"]] = target
+          target["message"].merge!(choice["delta"])
+        end
+      end
+    end
+
+    def merge_tools!(target, tools)
+      tools.each.with_index do |toola, index|
+        toolb = target["tool_calls"][index]
+        if toolb
+          toola["function"].each { toolb["function"][_1] << _2 }
+        else
+          target["tool_calls"][index] = toola
+        end
+      end
+    end
+  end
+end

data/lib/llm/providers/openai.rb

@@ -5,16 +5,17 @@ module LLM
   # The OpenAI class implements a provider for
   # [OpenAI](https://platform.openai.com/)
   class OpenAI < Provider
-    require_relative "openai/format"
     require_relative "openai/error_handler"
+    require_relative "openai/format"
+    require_relative "openai/stream_parser"
     require_relative "openai/response_parser"
-    require_relative "openai/response_parser/completion_parser"
-    require_relative "openai/response_parser/respond_parser"
+    require_relative "openai/models"
     require_relative "openai/responses"
     require_relative "openai/images"
     require_relative "openai/audio"
     require_relative "openai/files"
-    require_relative "openai/models"
+    require_relative "openai/moderations"
+
     include Format
 
     HOST = "api.openai.com"
@@ -36,7 +37,7 @@ module LLM
     def embed(input, model: "text-embedding-3-small", **params)
       req = Net::HTTP::Post.new("/v1/embeddings", headers)
       req.body = JSON.dump({input:, model:}.merge!(params))
-      res = request(@http, req)
+      res = execute(request: req)
       Response::Embedding.new(res).extend(response_parser)
     end
 
@@ -53,12 +54,13 @@ module LLM
     def complete(prompt, params = {})
       params = {role: :user, model: default_model}.merge!(params)
       params = [params, format_schema(params), format_tools(params)].inject({}, &:merge!).compact
-      role = params.delete(:role)
+      role, stream = params.delete(:role), params.delete(:stream)
+      params[:stream] = true if stream.respond_to?(:<<) || stream == true
       req = Net::HTTP::Post.new("/v1/chat/completions", headers)
       messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
       body = JSON.dump({messages: format(messages, :complete).flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
-      res = request(@http, req)
+      res = execute(request: req, stream:)
       Response::Completion.new(res).extend(response_parser)
     end
 
@@ -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
@@ -129,6 +140,10 @@ module LLM
       LLM::OpenAI::ResponseParser
     end
 
+    def stream_parser
+      LLM::OpenAI::StreamParser
+    end
+
     def error_handler
       LLM::OpenAI::ErrorHandler
     end

data/lib/llm/providers/voyageai/error_handler.rb

@@ -21,11 +21,11 @@ class LLM::VoyageAI
     def raise_error!
       case res
       when Net::HTTPUnauthorized
-        raise LLM::Error::Unauthorized.new { _1.response = res }, "Authentication error"
+        raise LLM::UnauthorizedError.new { _1.response = res }, "Authentication error"
       when Net::HTTPTooManyRequests
-        raise LLM::Error::RateLimit.new { _1.response = res }, "Too many requests"
+        raise LLM::RateLimitError.new { _1.response = res }, "Too many requests"
       else
-        raise LLM::Error::ResponseError.new { _1.response = res }, "Unexpected response"
+        raise LLM::ResponseError.new { _1.response = res }, "Unexpected response"
       end
     end
   end

data/lib/llm/providers/voyageai.rb

@@ -20,7 +20,7 @@ module LLM
     def embed(input, model: "voyage-2", **params)
       req = Net::HTTP::Post.new("/v1/embeddings", headers)
       req.body = JSON.dump({input:, model:}.merge!(params))
-      res = request(@http, req)
+      res = execute(request: req)
       Response::Embedding.new(res).extend(response_parser)
     end
 

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.9.0"
 end

data/lib/llm.rb

@@ -2,8 +2,8 @@
 
 module LLM
   require "stringio"
-  require_relative "json/schema"
-  require_relative "llm/core_ext/ostruct"
+  require_relative "llm/json/schema"
+  require_relative "llm/object"
   require_relative "llm/version"
   require_relative "llm/utils"
   require_relative "llm/error"
@@ -14,9 +14,11 @@ module LLM
   require_relative "llm/file"
   require_relative "llm/model"
   require_relative "llm/provider"
-  require_relative "llm/chat"
+  require_relative "llm/bot"
   require_relative "llm/buffer"
   require_relative "llm/function"
+  require_relative "llm/eventstream"
+  require_relative "llm/event_handler"
 
   module_function
 
@@ -57,11 +59,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,8 +10,8 @@ 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 " \
-                 "and composable – with full support for chat, tool calling, audio, " \
+                 "Anthropic, DeepSeek, Ollama, and LlamaCpp. It’s fast, simple " \
+                 "and composable – with full support for chat, streaming, tool calling, audio, " \
                  "images, files, and JSON Schema generation."
   spec.description = spec.summary
   spec.homepage = "https://github.com/llmrb/llm"

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Antar Azri
 - '0x1eef'
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: webmock
@@ -152,9 +151,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, streaming, tool calling, audio, images,
+  files, and JSON Schema generation.
 email:
 - azantar@proton.me
 - 0x1eef@proton.me
@@ -164,31 +163,37 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- lib/json/schema.rb
-- lib/json/schema/array.rb
-- lib/json/schema/boolean.rb
-- lib/json/schema/integer.rb
-- lib/json/schema/leaf.rb
-- lib/json/schema/null.rb
-- lib/json/schema/number.rb
-- lib/json/schema/object.rb
-- lib/json/schema/string.rb
-- lib/json/schema/version.rb
 - lib/llm.rb
+- lib/llm/bot.rb
+- lib/llm/bot/builder.rb
+- lib/llm/bot/conversable.rb
+- lib/llm/bot/prompt/completion.rb
+- lib/llm/bot/prompt/respond.rb
 - lib/llm/buffer.rb
-- lib/llm/chat.rb
-- lib/llm/chat/builder.rb
-- 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/event_handler.rb
+- lib/llm/eventstream.rb
+- lib/llm/eventstream/event.rb
+- lib/llm/eventstream/parser.rb
 - lib/llm/file.rb
 - lib/llm/function.rb
+- lib/llm/json/schema.rb
+- lib/llm/json/schema/array.rb
+- lib/llm/json/schema/boolean.rb
+- lib/llm/json/schema/integer.rb
+- lib/llm/json/schema/leaf.rb
+- lib/llm/json/schema/null.rb
+- lib/llm/json/schema/number.rb
+- lib/llm/json/schema/object.rb
+- lib/llm/json/schema/string.rb
+- lib/llm/json/schema/version.rb
 - lib/llm/message.rb
 - 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 +202,10 @@ 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/anthropic/stream_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
@@ -207,6 +216,7 @@ files:
 - lib/llm/providers/gemini/models.rb
 - lib/llm/providers/gemini/response_parser.rb
 - lib/llm/providers/gemini/response_parser/completion_parser.rb
+- lib/llm/providers/gemini/stream_parser.rb
 - lib/llm/providers/llamacpp.rb
 - lib/llm/providers/ollama.rb
 - lib/llm/providers/ollama/error_handler.rb
@@ -215,19 +225,23 @@ files:
 - lib/llm/providers/ollama/models.rb
 - lib/llm/providers/ollama/response_parser.rb
 - lib/llm/providers/ollama/response_parser/completion_parser.rb
+- lib/llm/providers/ollama/stream_parser.rb
 - lib/llm/providers/openai.rb
 - lib/llm/providers/openai/audio.rb
 - lib/llm/providers/openai/error_handler.rb
 - 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
 - lib/llm/providers/openai/responses.rb
+- lib/llm/providers/openai/stream_parser.rb
 - lib/llm/providers/voyageai.rb
 - lib/llm/providers/voyageai/error_handler.rb
 - lib/llm/providers/voyageai/response_parser.rb
@@ -242,6 +256,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
@@ -252,7 +268,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/llmrb/llm
   source_code_uri: https://github.com/llmrb/llm
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -267,11 +282,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 3.6.8
 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, streaming, tool calling, audio, images,
+  files, and JSON Schema generation.
 test_files: []

data/lib/llm/chat/conversable.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-class LLM::Chat
-  ##
-  # @private
-  module Conversable
-    private
-
-    ##
-    # Queues a response to be sent to the provider.
-    # @param [String] prompt The prompt
-    # @param [Hash] params
-    # @return [void]
-    def async_response(prompt, params = {})
-      role = params.delete(:role)
-      @messages << [LLM::Message.new(role, prompt), @params.merge(params), :respond]
-    end
-
-    ##
-    # Sends a response to the provider and returns the response.
-    # @param [String] prompt The prompt
-    # @param [Hash] params
-    # @return [LLM::Response::Respond]
-    def sync_response(prompt, params = {})
-      role = params[:role]
-      @response = create_response!(prompt, params)
-      @messages.concat [Message.new(role, prompt), @response.outputs[0]]
-    end
-
-    ##
-    # Queues a completion to be sent to the provider.
-    # @param [String] prompt The prompt
-    # @param [Hash] params
-    # @return [void]
-    def async_completion(prompt, params = {})
-      role = params.delete(:role)
-      @messages.push [LLM::Message.new(role, prompt), @params.merge(params), :complete]
-    end
-
-    ##
-    # Sends a completion to the provider and returns the completion.
-    # @param [String] prompt The prompt
-    # @param [Hash] params
-    # @return [LLM::Response::Completion]
-    def sync_completion(prompt, params = {})
-      role = params[:role]
-      completion = create_completion!(prompt, params)
-      @messages.concat [Message.new(role, prompt), completion.choices[0]]
-    end
-
-    include LLM
-  end
-end