llm.rb 4.14.0 → 4.16.0

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

@@ -31,7 +31,7 @@ class LLM::OpenAI
     # @return [LLM::Response]
     def all(**params)
       query = URI.encode_www_form(params)
-      req = Net::HTTP::Get.new("/v1/vector_stores?#{query}", headers)
+      req = Net::HTTP::Get.new(path("/vector_stores?#{query}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -47,7 +47,7 @@ class LLM::OpenAI
     # @return [LLM::Response]
     # @see https://platform.openai.com/docs/api-reference/vector_stores/create OpenAI docs
     def create(name:, file_ids: nil, **params)
-      req = Net::HTTP::Post.new("/v1/vector_stores", headers)
+      req = Net::HTTP::Post.new(path("/vector_stores"), headers)
       req.body = LLM.json.dump(params.merge({name:, file_ids:}).compact)
       res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
@@ -72,7 +72,7 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/vector_stores/retrieve OpenAI docs
     def get(vector:)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
-      req = Net::HTTP::Get.new("/v1/vector_stores/#{vector_id}", headers)
+      req = Net::HTTP::Get.new(path("/vector_stores/#{vector_id}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -89,7 +89,7 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/vector_stores/modify OpenAI docs
     def modify(vector:, name: nil, **params)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
-      req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}", headers)
+      req = Net::HTTP::Post.new(path("/vector_stores/#{vector_id}"), headers)
       req.body = LLM.json.dump(params.merge({name:}).compact)
       res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
@@ -105,7 +105,7 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/vector_stores/delete OpenAI docs
     def delete(vector:)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
-      req = Net::HTTP::Delete.new("/v1/vector_stores/#{vector_id}", headers)
+      req = Net::HTTP::Delete.new(path("/vector_stores/#{vector_id}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -122,7 +122,7 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/vector_stores/search OpenAI docs
     def search(vector:, query:, **params)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
-      req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}/search", headers)
+      req = Net::HTTP::Post.new(path("/vector_stores/#{vector_id}/search"), headers)
       req.body = LLM.json.dump(params.merge({query:}).compact)
       res, span, tracer = execute(request: req, operation: "retrieval")
       res = ResponseAdapter.adapt(res, type: :enumerable)
@@ -140,7 +140,7 @@ class LLM::OpenAI
     def all_files(vector:, **params)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       query = URI.encode_www_form(params)
-      req = Net::HTTP::Get.new("/v1/vector_stores/#{vector_id}/files?#{query}", headers)
+      req = Net::HTTP::Get.new(path("/vector_stores/#{vector_id}/files?#{query}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -159,7 +159,7 @@ class LLM::OpenAI
     def add_file(vector:, file:, attributes: nil, **params)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       file_id = file.respond_to?(:id) ? file.id : file
-      req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}/files", headers)
+      req = Net::HTTP::Post.new(path("/vector_stores/#{vector_id}/files"), headers)
       req.body = LLM.json.dump(params.merge({file_id:, attributes:}).compact)
       res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
@@ -190,7 +190,7 @@ class LLM::OpenAI
     def update_file(vector:, file:, attributes:, **params)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       file_id = file.respond_to?(:id) ? file.id : file
-      req = Net::HTTP::Post.new("/v1/vector_stores/#{vector_id}/files/#{file_id}", headers)
+      req = Net::HTTP::Post.new(path("/vector_stores/#{vector_id}/files/#{file_id}"), headers)
       req.body = LLM.json.dump(params.merge({attributes:}).compact)
       res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
@@ -209,7 +209,7 @@ class LLM::OpenAI
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       file_id = file.respond_to?(:id) ? file.id : file
       query = URI.encode_www_form(params)
-      req = Net::HTTP::Get.new("/v1/vector_stores/#{vector_id}/files/#{file_id}?#{query}", headers)
+      req = Net::HTTP::Get.new(path("/vector_stores/#{vector_id}/files/#{file_id}?#{query}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -226,7 +226,7 @@ class LLM::OpenAI
     def delete_file(vector:, file:)
       vector_id = vector.respond_to?(:id) ? vector.id : vector
       file_id = file.respond_to?(:id) ? file.id : file
-      req = Net::HTTP::Delete.new("/v1/vector_stores/#{vector_id}/files/#{file_id}", headers)
+      req = Net::HTTP::Delete.new(path("/vector_stores/#{vector_id}/files/#{file_id}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -259,7 +259,7 @@ class LLM::OpenAI
 
     private
 
-    [:headers, :execute, :set_body_stream].each do |m|
+    [:path, :headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

data/lib/llm/providers/openai.rb

@@ -32,8 +32,8 @@ module LLM
 
     ##
     # @param key (see LLM::Provider#initialize)
-    def initialize(**)
-      super(host: HOST, **)
+    def initialize(base_path: "/v1", **)
+      super(host: HOST, base_path:, **)
     end
 
     ##
@@ -52,7 +52,7 @@ module LLM
     # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#embed)
     def embed(input, model: "text-embedding-3-small", **params)
-      req = Net::HTTP::Post.new("/v1/embeddings", headers)
+      req = Net::HTTP::Post.new(path("/embeddings"), headers)
       req.body = LLM.json.dump({input:, model:}.merge!(params))
       res, span, tracer = execute(request: req, operation: "embeddings", model:)
       res = ResponseAdapter.adapt(res, type: :embedding)
@@ -187,7 +187,7 @@ module LLM
     private
 
     def completions_path
-      "/v1/chat/completions"
+      path("/chat/completions")
     end
 
     def headers

data/lib/llm/response.rb

@@ -2,10 +2,18 @@
 
 module LLM
   ##
-  # {LLM::Response LLM::Response} encapsulates a response
-  # from an LLM provider. It is returned by all methods
-  # that make requests to a provider, and sometimes extended
-  # with provider-specific functionality.
+  # {LLM::Response LLM::Response} is the normalized base shape for
+  # provider and endpoint responses in llm.rb.
+  #
+  # Provider calls return an instance of this class, then extend it
+  # with provider-, endpoint-, or context-specific modules so response
+  # handling can share one common surface without flattening away
+  # specialized behavior.
+  #
+  # The normalized response still keeps the original
+  # {Net::HTTPResponse Net::HTTPResponse} available through {#res}
+  # when callers need direct access to raw HTTP details such as
+  # headers, status codes, or unadapted bodies.
   class Response
     require "json"
 

data/lib/llm/sequel/plugin.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module LLM::Sequel
+  ##
+  # Sequel plugin for persisting {LLM::Context LLM::Context} state.
+  #
+  # This plugin maps model columns onto provider selection, model
+  # selection, usage accounting, and serialized context data while
+  # leaving application-specific concerns such as credentials,
+  # associations, and UI shaping to the host app.
+  #
+  # Context state can be stored as a JSON string (`format: :string`, the
+  # default) or as a structured object (`format: :json` / `:jsonb`) for
+  # databases such as PostgreSQL that can persist JSON natively.
+  # `:json` and `:jsonb` expect a real JSON column type with Sequel handling
+  # JSON typecasting for the model.
+  module Plugin
+    EMPTY_HASH = {}.freeze
+    DEFAULT_USAGE_COLUMNS = {
+      input_tokens: :input_tokens,
+      output_tokens: :output_tokens,
+      total_tokens: :total_tokens
+    }.freeze
+    DEFAULTS = {
+      provider_column: :provider,
+      model_column: :model,
+      data_column: :data,
+      format: :string,
+      usage_columns: DEFAULT_USAGE_COLUMNS,
+      provider: EMPTY_HASH,
+      context: EMPTY_HASH
+    }.freeze
+
+    ##
+    # Called by Sequel when the plugin is first applied to a model class.
+    #
+    # This hook installs the plugin's class- and instance-level behavior on
+    # the target model. It runs before {configure}, so it should only attach
+    # methods and not depend on per-model plugin options.
+    #
+    # @param [Class] model
+    # @return [void]
+    def self.apply(model, **)
+      model.extend ClassMethods
+      model.include InstanceMethods
+    end
+
+    ##
+    # Called by Sequel after {apply} with the options passed to
+    # `plugin :llm, ...`.
+    #
+    # This hook merges plugin defaults with the model's explicit settings and
+    # stores the resolved configuration on the model class for later use by
+    # instance methods such as {InstanceMethods#llm} and {InstanceMethods#ctx}.
+    #
+    # @param [Class] model
+    # @param [Hash] options
+    # @option options [Symbol] :format
+    #   Storage format for the serialized context. Use `:string` for text
+    #   columns, or `:json` / `:jsonb` for structured JSON columns with Sequel
+    #   JSON typecasting enabled.
+    # @return [void]
+    def self.configure(model, options = EMPTY_HASH)
+      options = DEFAULTS.merge(options)
+      usage_columns = DEFAULT_USAGE_COLUMNS.merge(options[:usage_columns] || EMPTY_HASH)
+      model.instance_variable_set(
+        :@llm_plugin_options,
+        options.merge(usage_columns: usage_columns.freeze).freeze
+      )
+    end
+  end
+
+  module Plugin::ClassMethods
+    ##
+    # @return [Hash]
+    def llm_plugin_options
+      @llm_plugin_options || DEFAULTS
+    end
+  end
+
+  module Plugin::InstanceMethods
+    ##
+    # Continues the stored context with new input and flushes it.
+    # @see LLM::Context#talk
+    # @return [LLM::Response]
+    def talk(...)
+      ctx.talk(...).tap { flush }
+    end
+
+    ##
+    # Continues the stored context through the Responses API and flushes it.
+    # @see LLM::Context#respond
+    # @return [LLM::Response]
+    def respond(...)
+      ctx.respond(...).tap { flush }
+    end
+
+    ##
+    # Waits for queued tool work to finish.
+    # @see LLM::Context#wait
+    # @return [Array<LLM::Function::Return>]
+    def wait(...)
+      ctx.wait(...)
+    end
+
+    ##
+    # Calls into the stored context.
+    # @see LLM::Context#call
+    # @return [Object]
+    def call(...)
+      ctx.call(...)
+    end
+
+    ##
+    # @see LLM::Context#messages
+    # @return [Array<LLM::Message>]
+    def messages
+      ctx.messages
+    end
+
+    ##
+    # @note The bang is used because Sequel reserves `model` for the
+    #   underlying model class on instances.
+    # @see LLM::Context#model
+    # @return [String]
+    def model!
+      ctx.model
+    end
+
+    ##
+    # @see LLM::Context#functions
+    # @return [Array<LLM::Function>]
+    def functions
+      ctx.functions
+    end
+
+    ##
+    # @see LLM::Context#cost
+    # @return [LLM::Cost]
+    def cost
+      ctx.cost
+    end
+
+    ##
+    # @see LLM::Context#context_window
+    # @return [Integer]
+    def context_window
+      ctx.context_window
+    rescue LLM::NoSuchModelError, LLM::NoSuchRegistryError
+      0
+    end
+
+    ##
+    # Returns usage from the mapped usage columns.
+    # @return [LLM::Object]
+    def usage
+      LLM::Object.from(
+        input_tokens: self[columns[:input_tokens]] || 0,
+        output_tokens: self[columns[:output_tokens]] || 0,
+        total_tokens: self[columns[:total_tokens]] || 0
+      )
+    end
+
+    private
+
+    ##
+    # Returns the resolved provider instance for this record.
+    # @return [LLM::Provider]
+    def llm
+      options = self.class.llm_plugin_options
+      provider = self[columns[:provider_column]]
+      kwargs = resolve_options(options[:provider])
+      @llm ||= LLM.method(provider).call(**kwargs)
+    end
+
+    ##
+    # @return [LLM::Context]
+    def ctx
+      @ctx ||= begin
+        options = self.class.llm_plugin_options
+        params = resolve_options(options[:context]).dup
+        params[:model] ||= self[columns[:model_column]]
+        ctx = LLM::Context.new(llm, params.compact)
+        data = self[columns[:data_column]]
+        if data.nil? || data == ""
+          ctx
+        else
+          string = case options[:format]
+          when :string then data
+          when :json, :jsonb then LLM.json.dump(data)
+          else raise ArgumentError, "Unknown format: #{options[:format].inspect}"
+          end
+          ctx.restore(string:)
+        end
+      end
+    end
+
+    ##
+    # @return [void]
+    def flush
+      options = self.class.llm_plugin_options
+      update({
+        columns[:data_column] => serialize_context(options[:format]),
+        columns[:input_tokens] => ctx.usage.input_tokens,
+        columns[:output_tokens] => ctx.usage.output_tokens,
+        columns[:total_tokens] => ctx.usage.total_tokens
+      })
+    end
+
+    ##
+    # @return [Hash]
+    def resolve_option(option)
+      case option
+      when Proc then instance_exec(&option)
+      when Hash then option.dup
+      else option
+      end
+    end
+
+    ##
+    # @return [Hash]
+    def resolve_options(option)
+      case option
+      when Proc, Hash then resolve_option(option)
+      else EMPTY_HASH.dup
+      end
+    end
+
+    def serialize_context(format)
+      case format
+      when :string then ctx.to_json
+      when :json, :jsonb then ctx.to_h
+      else raise ArgumentError, "Unknown format: #{format.inspect}"
+      end
+    end
+
+    def columns
+      @columns ||= begin
+        options = self.class.llm_plugin_options
+        usage_columns = options[:usage_columns]
+        {
+          provider_column: options[:provider_column],
+          model_column: options[:model_column],
+          data_column: options[:data_column],
+          input_tokens: usage_columns[:input_tokens],
+          output_tokens: usage_columns[:output_tokens],
+          total_tokens: usage_columns[:total_tokens]
+        }.freeze
+      end
+    end
+  end
+end

data/lib/llm/stream/queue.rb

@@ -54,9 +54,9 @@ class LLM::Stream
     private
 
     def fire_hooks(tasks, results)
-      results.each_with_index do |ret, idx|
+      results.each_with_index do |result, idx|
         tool = tasks[idx]&.function
-        @stream.on_tool_return(tool, ret) if tool
+        @stream.on_tool_return(tool, result) if tool
       end
       results
     end

data/lib/llm/stream.rb

@@ -86,10 +86,10 @@ module LLM
     #   `tool.spawn(:fiber)`, or `tool.spawn(:task)`.
     # @param [LLM::Function] tool
     #  The tool that returned.
-    # @param [LLM::Function::Return] ret
+    # @param [LLM::Function::Return] result
     #  The completed tool return.
     # @return [nil]
-    def on_tool_return(tool, ret)
+    def on_tool_return(tool, result)
       nil
     end
 

data/lib/llm/version.rb

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

data/lib/sequel/plugins/llm.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Sequel
+  module Plugins
+    require "llm/sequel/plugin"
+    Llm = LLM::Sequel::Plugin
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.14.0
+  version: 4.16.0
 platform: ruby
 authors:
 - Antar Azri
@@ -228,6 +228,8 @@ files:
 - data/xai.json
 - data/zai.json
 - lib/llm.rb
+- lib/llm/active_record.rb
+- lib/llm/active_record/acts_as_llm.rb
 - lib/llm/agent.rb
 - lib/llm/bot.rb
 - lib/llm/buffer.rb
@@ -367,6 +369,7 @@ files:
 - lib/llm/schema/parser.rb
 - lib/llm/schema/string.rb
 - lib/llm/schema/version.rb
+- lib/llm/sequel/plugin.rb
 - lib/llm/server_tool.rb
 - lib/llm/session.rb
 - lib/llm/stream.rb
@@ -381,6 +384,7 @@ files:
 - lib/llm/usage.rb
 - lib/llm/utils.rb
 - lib/llm/version.rb
+- lib/sequel/plugins/llm.rb
 - llm.gemspec
 homepage: https://github.com/llmrb/llm.rb
 licenses: