llm.rb 4.21.0 → 4.23.0

data/lib/llm/sequel/plugin.rb

@@ -22,6 +22,76 @@ module LLM::Sequel
       output_tokens: :output_tokens,
       total_tokens: :total_tokens
     }.freeze
+
+    ##
+    # Shared helper methods for the ORM wrapper.
+    #
+    # These utilities keep persistence plumbing out of the wrapped model's
+    # method namespace so the injected surface stays focused on the runtime
+    # API itself.
+    # @api private
+    module Utils
+      ##
+      # Resolves a single configured option against a model instance.
+      # @return [Object]
+      def self.resolve_option(obj, option)
+        case option
+        when Proc then obj.instance_exec(&option)
+        when Symbol then obj.send(option)
+        when Hash then option.dup
+        else option
+        end
+      end
+
+      ##
+      # Resolves hash-like wrapper options against a model instance.
+      # @return [Hash]
+      def self.resolve_options(obj, option, empty_hash)
+        case option
+        when Proc, Symbol, Hash then resolve_option(obj, option)
+        else empty_hash.dup
+        end
+      end
+
+      ##
+      # Serializes the runtime into the configured storage format.
+      # @return [String, Hash]
+      def self.serialize_context(ctx, 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
+
+      ##
+      # Maps wrapper options onto the record's storage columns.
+      # @return [Hash]
+      def self.columns(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
+
+      ##
+      # Persists the runtime state and usage columns back onto the record.
+      # @return [void]
+      def self.save(obj, ctx, options)
+        columns = self.columns(options)
+        obj.update(
+          columns[:data_column] => serialize_context(ctx, options[:format]),
+          columns[:input_tokens] => ctx.usage.input_tokens,
+          columns[:output_tokens] => ctx.usage.output_tokens,
+          columns[:total_tokens] => ctx.usage.total_tokens
+        )
+      end
+    end
     DEFAULTS = {
       provider_column: :provider,
       model_column: :model,
@@ -84,12 +154,15 @@ module LLM::Sequel
   end
 
   module Plugin::InstanceMethods
+    Utils = Plugin::Utils
+
     ##
     # Continues the stored context with new input and flushes it.
     # @see LLM::Context#talk
     # @return [LLM::Response]
     def talk(...)
-      ctx.talk(...).tap { flush }
+      options = self.class.llm_plugin_options
+      ctx.talk(...).tap { Utils.save(self, ctx, options) }
     end
 
     ##
@@ -97,7 +170,8 @@ module LLM::Sequel
     # @see LLM::Context#respond
     # @return [LLM::Response]
     def respond(...)
-      ctx.respond(...).tap { flush }
+      options = self.class.llm_plugin_options
+      ctx.respond(...).tap { Utils.save(self, ctx, options) }
     end
 
     ##
@@ -173,6 +247,7 @@ module LLM::Sequel
     # Returns usage from the mapped usage columns.
     # @return [LLM::Object]
     def usage
+      columns = Utils.columns(self.class.llm_plugin_options)
       LLM::Object.from(
         input_tokens: self[columns[:input_tokens]] || 0,
         output_tokens: self[columns[:output_tokens]] || 0,
@@ -229,11 +304,12 @@ module LLM::Sequel
     # @return [LLM::Provider]
     def llm
       options = self.class.llm_plugin_options
+      columns = Utils.columns(options)
       provider = self[columns[:provider_column]]
-      kwargs = resolve_options(options[:provider])
+      kwargs = Utils.resolve_options(self, options[:provider], Plugin::EMPTY_HASH)
       return @llm if @llm
       @llm = LLM.method(provider).call(**kwargs)
-      @llm.tracer = resolve_option(options[:tracer]) if options[:tracer]
+      @llm.tracer = Utils.resolve_option(self, options[:tracer]) if options[:tracer]
       @llm
     end
 
@@ -244,7 +320,8 @@ module LLM::Sequel
     def ctx
       @ctx ||= begin
         options = self.class.llm_plugin_options
-        params = resolve_options(options[:context]).dup
+        columns = Utils.columns(options)
+        params = Utils.resolve_options(self, options[:context], Plugin::EMPTY_HASH).dup
         params[:model] ||= self[columns[:model_column]]
         ctx = LLM::Context.new(llm, params.compact)
         data = self[columns[:data_column]]
@@ -259,60 +336,5 @@ module LLM::Sequel
         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 Symbol then send(option)
-      when Hash then option.dup
-      else option
-      end
-    end
-
-    ##
-    # @return [Hash]
-    def resolve_options(option)
-      case option
-      when Proc, Symbol, Hash then resolve_option(option)
-      else Plugin::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/skill.rb

@@ -45,6 +45,10 @@ module LLM
     # @return [Array<Class<LLM::Tool>>]
     attr_reader :tools
 
+    ##
+    # @param [String] path
+    #  The path to a directory
+    # @return [LLM::Skill]
     def initialize(path)
       @path = path.to_s
       @name = ::File.basename(@path)
@@ -65,40 +69,51 @@ module LLM
 
     ##
     # Execute the skill by wrapping it in a small agent with the skill
-    # instructions. The provider is bound explicitly by the caller.
-    # @param [LLM::Provider] llm
-    # @param [Hash] input
+    # instructions. The context is bound explicitly by the caller so the
+    # nested agent can inherit context-level behavior such as streaming.
+    # @param [LLM::Context] ctx
     # @return [Hash]
-    def call(llm, **)
-      instructions = self.instructions
-      tools = self.tools
+    def call(ctx)
+      instructions, tools = self.instructions, self.tools
+      params = ctx.params.merge(mode: ctx.mode).reject { [:tools, :schema].include?(_1) }
       agent = Class.new(LLM::Agent) do
-        instructions instructions
+        instructions(instructions)
         tools(*tools)
-      end.new(llm)
-      res = agent.talk(instructions)
+      end.new(ctx.llm, params)
+      agent.messages.concat(messages_for(ctx))
+      res = agent.talk("Solve the user's query.")
       {content: res.content}
     end
 
     ##
-    # Expose the skill as a normal LLM::Tool. The provider is bound explicitly
+    # Expose the skill as a normal LLM::Tool. The context is bound explicitly
     # when the tool class is built.
-    # @param [LLM::Provider] llm
+    # @param [LLM::Context] ctx
     # @return [Class<LLM::Tool>]
-    def to_tool(llm)
+    def to_tool(ctx)
       skill = self
       Class.new(LLM::Tool) do
         name skill.name
         description skill.description
 
-        define_method(:call) do |**input|
-          skill.call(llm, **input)
+        define_method(:call) do
+          skill.call(ctx)
         end
       end
     end
 
     private
 
+    def messages_for(ctx)
+      messages = ctx.messages
+        .to_a
+        .select { _1.user? || _1.assistant? }
+        .reject { _1.tool_call? || _1.tool_return? }
+        .last(8)
+      return messages if messages.empty?
+      [LLM::Message.new(:user, "Recent context:"), *messages]
+    end
+
     def parse(content)
       match = content.match(/\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m)
       unless match

data/lib/llm/stream.rb

@@ -18,7 +18,8 @@ module LLM
   #
   # The most common callback is {#on_content}, which also maps to {#<<}.
   # Providers may also call {#on_reasoning_content} and {#on_tool_call} when
-  # that data is available.
+  # that data is available. Runtime features such as context compaction may
+  # also emit lifecycle callbacks like {#on_compaction}.
   class Stream
     require_relative "stream/queue"
 
@@ -103,6 +104,24 @@ module LLM
       nil
     end
 
+    ##
+    # Called before a context compaction starts.
+    # @param [LLM::Context] ctx
+    # @param [LLM::Compactor] compactor
+    # @return [nil]
+    def on_compaction(ctx, compactor)
+      nil
+    end
+
+    ##
+    # Called after a context compaction finishes.
+    # @param [LLM::Context] ctx
+    # @param [LLM::Compactor] compactor
+    # @return [nil]
+    def on_compaction_finish(ctx, compactor)
+      nil
+    end
+
     # @endgroup
 
     # @group Error handlers

data/lib/llm/tool.rb

@@ -171,4 +171,18 @@ class LLM::Tool
   def self.mcp?
     false
   end
+
+  ##
+  # Returns a function bound to this tool instance.
+  # @return [LLM::Function]
+  def function
+    @function ||= self.class.function.dup.tap { _1.register(self) }
+  end
+
+  ##
+  # Returns true if the tool is an MCP tool
+  # @return [Boolean]
+  def mcp?
+    self.class.mcp?
+  end
 end

data/lib/llm/version.rb

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

data/llm.gemspec

@@ -54,4 +54,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "net-http-persistent", "~> 4.0"
   spec.add_development_dependency "opentelemetry-sdk", "~> 1.10"
   spec.add_development_dependency "logger", "~> 1.7"
+  spec.add_development_dependency "activerecord", "~> 8.0"
+  spec.add_development_dependency "sequel", "~> 5.0"
+  spec.add_development_dependency "sqlite3", "~> 2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.21.0
+  version: 4.23.0
 platform: ruby
 authors:
 - Antar Azri
@@ -194,6 +194,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: |
   llm.rb is a lightweight runtime for building capable AI systems in Ruby.
   It is not just an API wrapper. llm.rb gives you one runtime for providers,
@@ -229,6 +271,7 @@ files:
 - lib/llm/agent.rb
 - lib/llm/bot.rb
 - lib/llm/buffer.rb
+- lib/llm/compactor.rb
 - lib/llm/context.rb
 - lib/llm/context/deserializer.rb
 - lib/llm/context/serializer.rb