llm.rb 4.20.2 → 4.22.0

data/lib/llm/active_record/acts_as_agent.rb

@@ -13,6 +13,7 @@ module LLM::ActiveRecord
     EMPTY_HASH = LLM::ActiveRecord::ActsAsLLM::EMPTY_HASH
     DEFAULT_USAGE_COLUMNS = LLM::ActiveRecord::ActsAsLLM::DEFAULT_USAGE_COLUMNS
     DEFAULTS = LLM::ActiveRecord::ActsAsLLM::DEFAULTS
+    Utils = LLM::ActiveRecord::ActsAsLLM::Utils
 
     module ClassMethods
       def model(model = nil)
@@ -52,7 +53,7 @@ module LLM::ActiveRecord
       # @param [Class] model
       # @return [void]
       def self.extended(model)
-        options = model.llm_agent_options
+        options = model.llm_plugin_options
         model.validates options[:provider_column], options[:model_column], presence: true
         model.include LLM::ActiveRecord::ActsAsLLM::InstanceMethods unless model.ancestors.include?(LLM::ActiveRecord::ActsAsLLM::InstanceMethods)
         model.include InstanceMethods unless model.ancestors.include?(InstanceMethods)
@@ -79,8 +80,8 @@ module LLM::ActiveRecord
     def acts_as_agent(options = EMPTY_HASH, &block)
       options = DEFAULTS.merge(options)
       usage_columns = DEFAULT_USAGE_COLUMNS.merge(options[:usage_columns] || EMPTY_HASH)
-      class_attribute :llm_agent_options, instance_accessor: false, default: DEFAULTS unless respond_to?(:llm_agent_options)
-      self.llm_agent_options = options.merge(usage_columns: usage_columns.freeze).freeze
+      class_attribute :llm_plugin_options, instance_accessor: false, default: DEFAULTS unless respond_to?(:llm_plugin_options)
+      self.llm_plugin_options = options.merge(usage_columns: usage_columns.freeze).freeze
       extend Hooks
       class_exec(&block) if block
     end
@@ -90,12 +91,13 @@ module LLM::ActiveRecord
       # Returns the resolved provider instance for this record.
       # @return [LLM::Provider]
       def llm
-        options = self.class.llm_agent_options
+        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], ActsAsAgent::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
 
@@ -105,8 +107,9 @@ module LLM::ActiveRecord
       # @return [LLM::Agent]
       def ctx
         @ctx ||= begin
-          options = self.class.llm_agent_options
-          params = resolve_options(options[:context]).dup
+          options = self.class.llm_plugin_options
+          columns = Utils.columns(options)
+          params = Utils.resolve_options(self, options[:context], ActsAsAgent::EMPTY_HASH).dup
           params[:model] ||= self[columns[:model_column]]
           ctx = self.class.agent.new(llm, params.compact)
           data = self[columns[:data_column]]
@@ -121,62 +124,6 @@ module LLM::ActiveRecord
           end
         end
       end
-
-      ##
-      # @return [void]
-      def flush
-        attrs = {
-          columns[:data_column] => serialize_context(self.class.llm_agent_options[:format]),
-          columns[:input_tokens] => ctx.usage.input_tokens,
-          columns[:output_tokens] => ctx.usage.output_tokens,
-          columns[:total_tokens] => ctx.usage.total_tokens
-        }
-        assign_attributes(attrs)
-        save!
-      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 ActsAsAgent::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_agent_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
 end

data/lib/llm/active_record/acts_as_llm.rb

@@ -33,6 +33,77 @@ module LLM::ActiveRecord
       context: EMPTY_HASH
     }.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.assign_attributes(
+          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
+        )
+        obj.save!
+      end
+    end
+
     module Hooks
       ##
       # Called when hooks are extended onto an ActiveRecord model.
@@ -72,7 +143,8 @@ module LLM::ActiveRecord
       # @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
 
       ##
@@ -80,7 +152,8 @@ module LLM::ActiveRecord
       # @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
 
       ##
@@ -155,6 +228,7 @@ module LLM::ActiveRecord
       # 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,
@@ -211,11 +285,12 @@ module LLM::ActiveRecord
       # @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], ActsAsLLM::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
 
@@ -226,7 +301,8 @@ module LLM::ActiveRecord
       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], ActsAsLLM::EMPTY_HASH).dup
           params[:model] ||= self[columns[:model_column]]
           ctx = LLM::Context.new(llm, params.compact)
           data = self[columns[:data_column]]
@@ -241,62 +317,6 @@ module LLM::ActiveRecord
           end
         end
       end
-
-      ##
-      # @return [void]
-      def flush
-        attrs = {
-          columns[:data_column] => serialize_context(self.class.llm_plugin_options[:format]),
-          columns[:input_tokens] => ctx.usage.input_tokens,
-          columns[:output_tokens] => ctx.usage.output_tokens,
-          columns[:total_tokens] => ctx.usage.total_tokens
-        }
-        assign_attributes(attrs)
-        save!
-      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 ActsAsLLM::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
 end

data/lib/llm/agent.rb

@@ -14,7 +14,7 @@ module LLM
   # `respond`, instead of leaving tool loops to the caller.
   #
   # **Notes:**
-  # * Instructions are injected only on the first request.
+  # * Instructions are injected once unless a system message is already present.
   # * An agent automatically executes tool loops (unlike {LLM::Context LLM::Context}).
   # * Tool loop execution can be configured with `concurrency :call`,
   #   `:thread`, `:task`, `:fiber`, `:ractor`, or a list of queued task
@@ -59,6 +59,17 @@ module LLM
       @tools = tools.flatten
     end
 
+    ##
+    # Set or get the default skills
+    # @param [Array<String>, nil] skills
+    #  One or more skill directories
+    # @return [Array<String>, nil]
+    #  Returns the current skills when no argument is provided
+    def self.skills(*skills)
+      return @skills if skills.empty?
+      @skills = skills.flatten
+    end
+
     ##
     # Set or get the default schema
     # @param [#to_json, nil] schema
@@ -110,10 +121,11 @@ module LLM
     #  not only those listed here.
     # @option params [String] :model Defaults to the provider's default model
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
+    # @option params [Array<String>, nil] :skills Defaults to nil
     # @option params [#to_json, nil] :schema Defaults to nil
     # @option params [Symbol, Array<Symbol>, nil] :concurrency Defaults to the agent class concurrency
     def initialize(llm, params = {})
-      defaults = {model: self.class.model, tools: self.class.tools, schema: self.class.schema}.compact
+      defaults = {model: self.class.model, tools: self.class.tools, skills: self.class.skills, schema: self.class.schema}.compact
       @concurrency = params.delete(:concurrency) || self.class.concurrency
       @llm = llm
       @ctx = LLM::Context.new(llm, defaults.merge(params))
@@ -337,16 +349,28 @@ module LLM
       instr = self.class.instructions
       return new_prompt unless instr
       if LLM::Prompt === new_prompt
-        new_prompt.system(instr) if @ctx.messages.empty?
+        new_prompt.system(instr) if inject_instructions?(new_prompt)
         new_prompt
       else
         prompt do
-          _1.system(instr) if @ctx.messages.empty?
+          _1.system(instr) if inject_instructions?
           _1.user(new_prompt)
         end
       end
     end
 
+    ##
+    # Returns true when agent instructions should be injected for the turn.
+    # Instructions are injected once unless a system message is already
+    # present in the existing context or the prompt being sent.
+    # @param [LLM::Prompt, nil] prompt
+    # @return [Boolean]
+    def inject_instructions?(prompt = nil)
+      return false if @ctx.messages.any?(&:system?)
+      return true if prompt.nil?
+      !prompt.to_a.any?(&:system?)
+    end
+
     ##
     # @return [Array<LLM::Function::Return>]
     def call_functions

data/lib/llm/context.rb

@@ -54,6 +54,13 @@ module LLM
     # @return [Symbol]
     attr_reader :mode
 
+    ##
+    # Returns the default params for this context
+    # @return [Hash]
+    def params
+      @params.dup
+    end
+
     ##
     # @param [LLM::Provider] llm
     #  A provider
@@ -64,10 +71,13 @@ module LLM
     # @option params [Symbol] :mode Defaults to :completions
     # @option params [String] :model Defaults to the provider's default model
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
+    # @option params [Array<String>, nil] :skills Defaults to nil
     def initialize(llm, params = {})
       @llm = llm
       @mode = params.delete(:mode) || :completions
+      tools = [*params.delete(:tools), *load_skills(params.delete(:skills))]
       @params = {model: llm.default_model, schema: nil}.compact.merge!(params)
+      @params[:tools] = tools unless tools.empty?
       @messages = LLM::Buffer.new(llm)
     end
 
@@ -345,6 +355,10 @@ module LLM
       stream.extra[:tracer] = tracer
       stream.extra[:model] = model
     end
+
+    def load_skills(skills)
+      [*skills].map { LLM::Skill.load(_1).to_tool(self) }
+    end
   end
 
   # Backward-compatible alias

data/lib/llm/sequel/agent.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module LLM::Sequel
+  ##
+  # Sequel plugin for persisting {LLM::Agent LLM::Agent} state.
+  #
+  # This wrapper reuses the same record-backed runtime surface as
+  # {LLM::Sequel::Plugin}, but builds an {LLM::Agent LLM::Agent} instead of an
+  # {LLM::Context LLM::Context}. Agent defaults such as model, tools, schema,
+  # instructions, and concurrency are configured on the model class and
+  # forwarded to an internal agent subclass.
+  module Agent
+    require_relative "plugin"
+    EMPTY_HASH = LLM::Sequel::Plugin::EMPTY_HASH
+    DEFAULT_USAGE_COLUMNS = LLM::Sequel::Plugin::DEFAULT_USAGE_COLUMNS
+    DEFAULTS = LLM::Sequel::Plugin::DEFAULTS
+    Utils = LLM::Sequel::Plugin::Utils
+
+    def self.apply(model, **)
+      model.extend ClassMethods
+      model.include LLM::Sequel::Plugin::InstanceMethods
+      model.include InstanceMethods
+    end
+
+    def self.configure(model, options = EMPTY_HASH, &block)
+      options = DEFAULTS.merge(options)
+      usage_columns = DEFAULT_USAGE_COLUMNS.merge(options[:usage_columns] || EMPTY_HASH)
+      model.instance_variable_set(
+        :@llm_agent_options,
+        options.merge(usage_columns: usage_columns.freeze).freeze
+      )
+      model.instance_exec(&block) if block
+    end
+
+    module ClassMethods
+      def llm_plugin_options
+        @llm_agent_options || Agent::DEFAULTS
+      end
+
+      def model(model = nil)
+        return agent.model if model.nil?
+        agent.model(model)
+      end
+
+      def tools(*tools)
+        return agent.tools if tools.empty?
+        agent.tools(*tools)
+      end
+
+      def schema(schema = nil)
+        return agent.schema if schema.nil?
+        agent.schema(schema)
+      end
+
+      def instructions(instructions = nil)
+        return agent.instructions if instructions.nil?
+        agent.instructions(instructions)
+      end
+
+      def concurrency(concurrency = nil)
+        return agent.concurrency if concurrency.nil?
+        agent.concurrency(concurrency)
+      end
+
+      def agent
+        @agent ||= Class.new(LLM::Agent)
+      end
+    end
+
+    module InstanceMethods
+      private
+
+      def ctx
+        @ctx ||= begin
+          options = self.class.llm_plugin_options
+          columns = Agent::Utils.columns(options)
+          params = Agent::Utils.resolve_options(self, options[:context], Agent::EMPTY_HASH).dup
+          params[:model] ||= self[columns[:model_column]]
+          ctx = self.class.agent.new(llm, params.compact)
+          data = self[columns[:data_column]]
+          if data.nil? || data == ""
+            ctx
+          else
+            case options[:format]
+            when :string then ctx.restore(string: data)
+            when :json, :jsonb then ctx.restore(data:)
+            else raise ArgumentError, "Unknown format: #{options[:format].inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end