llm.rb 4.20.2 → 4.22.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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Skill LLM::Skill} represents a directory-backed packaged capability.
+  # A skill directory must contain a `SKILL.md` file with YAML frontmatter.
+  # Skills can expose themselves as normal {LLM::Tool LLM::Tool} classes through
+  # {#to_tool}. This keeps skills on the same execution path as local tools.
+  class Skill
+    ##
+    # Load a skill from a directory.
+    # @param [String, Pathname] path
+    # @return [LLM::Skill]
+    def self.load(path)
+      new(path).tap(&:load!)
+    end
+
+    ##
+    # Returns the skill directory.
+    # @return [String]
+    attr_reader :path
+
+    ##
+    # Returns the skill name.
+    # @return [String]
+    attr_reader :name
+
+    ##
+    # Returns the skill description.
+    # @return [String]
+    attr_reader :description
+
+    ##
+    # Returns the skill instructions.
+    # @return [String]
+    attr_reader :instructions
+
+    ##
+    # Returns the skill frontmatter.
+    # @return [LLM::Object]
+    attr_reader :frontmatter
+
+    ##
+    # Returns the skill tools.
+    # @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)
+      @description = "Skill: #{@name}"
+      @instructions = ""
+      @frontmatter = LLM::Object.from({})
+      @tools = []
+    end
+
+    ##
+    # Load and parse the skill.
+    # @return [LLM::Skill]
+    def load!
+      path = ::File.join(@path, "SKILL.md")
+      parse(::File.read(path))
+      self
+    end
+
+    ##
+    # Execute the skill by wrapping it in a small agent with the skill
+    # 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(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)
+        tools(*tools)
+      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 context is bound explicitly
+    # when the tool class is built.
+    # @param [LLM::Context] ctx
+    # @return [Class<LLM::Tool>]
+    def to_tool(ctx)
+      skill = self
+      Class.new(LLM::Tool) do
+        name skill.name
+        description skill.description
+
+        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
+        @instructions = content
+        return
+      end
+      require "yaml" unless defined?(::YAML)
+      @frontmatter = LLM::Object.from(YAML.safe_load(match[1]) || {})
+      @name = @frontmatter.name || @name
+      @description = @frontmatter.description || @description
+      @tools = [*@frontmatter.tools].map { LLM::Tool.find_by_name!(_1) }
+      @instructions = match[2]
+    end
+  end
+end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -29,6 +29,7 @@ module LLM
   require_relative "llm/eventstream"
   require_relative "llm/eventhandler"
   require_relative "llm/tool"
+  require_relative "llm/skill"
   require_relative "llm/server_tool"
   require_relative "llm/mcp"
 

data/lib/sequel/plugins/agent.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Sequel
+  module Plugins
+    require "llm/sequel/agent"
+    Agent = LLM::Sequel::Agent
+  end
+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.20.2
+  version: 4.22.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,
@@ -371,9 +413,11 @@ files:
 - lib/llm/schema/parser.rb
 - lib/llm/schema/string.rb
 - lib/llm/schema/version.rb
+- lib/llm/sequel/agent.rb
 - lib/llm/sequel/plugin.rb
 - lib/llm/server_tool.rb
 - lib/llm/session.rb
+- lib/llm/skill.rb
 - lib/llm/stream.rb
 - lib/llm/stream/queue.rb
 - lib/llm/tool.rb
@@ -386,6 +430,7 @@ files:
 - lib/llm/usage.rb
 - lib/llm/utils.rb
 - lib/llm/version.rb
+- lib/sequel/plugins/agent.rb
 - lib/sequel/plugins/llm.rb
 - llm.gemspec
 homepage: https://github.com/llmrb/llm.rb