llm.rb 11.3.1 → 12.1.0

data/lib/llm/schema.rb

@@ -34,6 +34,7 @@
 class LLM::Schema
   require_relative "schema/version"
   require_relative "schema/parser"
+  require_relative "schema/renderer"
   require_relative "schema/leaf"
   require_relative "schema/object"
   require_relative "schema/array"
@@ -121,6 +122,19 @@ class LLM::Schema
     end
   end
 
+  ##
+  # @param [Hash] defaults
+  # @return [LLM::Schema::Object]
+  def self.defaults(defaults)
+    lock do
+      object.tap do |schema|
+        defaults.each do |name, val|
+          Utils.fetch(schema.properties, name).default(val)
+        end
+      end
+    end
+  end
+
   ##
   # @api private
   # @return [LLM::Schema]
@@ -139,6 +153,14 @@ class LLM::Schema
     end
   end
 
+  ##
+  # Render the schema as a prompt-friendly string.
+  # @return [String]
+  def self.to_s
+    Renderer.render(object, root: true)
+  end
+  (class << self; self; end).alias_method(:inspect, :to_s)
+
   ##
   # @api private
   def self.lock(&)
@@ -220,4 +242,12 @@ class LLM::Schema
   def null
     Null.new
   end
+
+  ##
+  # Render a schema leaf as a prompt-friendly string.
+  # @return [String]
+  def to_s
+    self.class.to_s
+  end
+  alias_method :inspect, :to_s
 end

data/lib/llm/sequel/agent.rb

@@ -7,8 +7,7 @@ module LLM::Sequel
   # 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.
+  # instructions, and concurrency are configured on an internal agent subclass.
   module Agent
     require_relative "plugin"
     EMPTY_HASH = LLM::Sequel::Plugin::EMPTY_HASH
@@ -25,7 +24,7 @@ module LLM::Sequel
       options = DEFAULTS.merge(options)
       model.db.extension :pg_json if %i[json jsonb].include?(options[:format])
       model.instance_variable_set(:@llm_agent_options, options.freeze)
-      model.instance_exec(&block) if block
+      block_given? ? model.instance_exec(model.agent, &block) : nil
     end
 
     module ClassMethods
@@ -33,46 +32,6 @@ module LLM::Sequel
         @llm_agent_options || Agent::DEFAULTS
       end
 
-      def model(model = nil, &block)
-        return agent.model if model.nil? && !block
-        agent.model(model, &block)
-      end
-
-      def tools(*tools, &block)
-        return agent.tools if tools.empty? && !block
-        agent.tools(*tools, &block)
-      end
-
-      def skills(*skills, &block)
-        return agent.skills if skills.empty? && !block
-        agent.skills(*skills, &block)
-      end
-
-      def schema(schema = nil, &block)
-        return agent.schema if schema.nil? && !block
-        agent.schema(schema, &block)
-      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 confirm(*tool_names, &block)
-        return agent.confirm if tool_names.empty? && !block
-        agent.confirm(*tool_names, &block)
-      end
-
-      def tracer(tracer = nil, &block)
-        return agent.tracer if tracer.nil? && !block
-        agent.tracer(tracer, &block)
-      end
-
       def agent
         @agent ||= Class.new(LLM::Agent)
       end

data/lib/llm/sequel/plugin.rb

@@ -16,6 +16,13 @@ module LLM::Sequel
   # JSON typecasting for the model. `provider:`, `context:`, and `tracer:`
   # can also be configured as symbols that are called on the model.
   module Plugin
+    DEFAULTS = {
+      data_column: :data,
+      format: :string,
+      provider: :set_provider,
+      context: :set_context,
+      tracer: :set_tracer
+    }.freeze
     EMPTY_HASH = {}.freeze
 
     ##
@@ -94,13 +101,6 @@ module LLM::Sequel
         end
       end
     end
-    DEFAULTS = {
-      data_column: :data,
-      format: :string,
-      tracer: nil,
-      provider: nil,
-      context: EMPTY_HASH
-    }.freeze
 
     ##
     # Called by Sequel when the plugin is first applied to a model class.
@@ -304,6 +304,24 @@ module LLM::Sequel
 
     private
 
+    ##
+    # @return [LLM::Provider]
+    def set_provider
+      raise NotImplementedError, "implement the set_provider callback"
+    end
+
+    ##
+    # @return [Hash]
+    def set_context
+      Plugin::EMPTY_HASH.dup
+    end
+
+    ##
+    # @return [LLM::Tracer]
+    def set_tracer
+      nil
+    end
+
     ##
     # @return [LLM::Context]
     def ctx

data/lib/llm/tools/chdir.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Chdir LLM::Tool::Chdir} class implements
+  # a tool that can change the current working directory.
+  class Chdir < self
+    name "chdir"
+    description "change the current working directory"
+    parameter :path, String, "the new working directory"
+    required %i[path]
+
+    ##
+    # @param [String] path
+    # @return [Hash]
+    def call(path:)
+      Dir.chdir(path)
+      {ok: true, cwd: path}
+    end
+  end
+end

data/lib/llm/tools/git.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Git LLM::Tool::Git} class implements
+  # a tool that can perform a select number of git actions.
+  # The actions it can perform are read-only - at least for
+  # the time being.
+  class Git < self
+    name "git"
+    description "perform an action with git"
+    parameter :action, Enum["log", "diff", "commit", "checkout", "branch", "show"], "the git operation to perform"
+    parameter :arguments, Array[String], "one or more arguments for the git action"
+    required %i[action]
+
+    ##
+    # @param [String] path
+    # @param [Integer] start
+    # @param [Integer] stop
+    # @return [Hash]
+    def call(action:, arguments: nil)
+      command = spawn(action:, arguments:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    end
+
+    private
+
+    def spawn(action:, arguments:)
+      Command
+        .new("git")
+        .argv(action)
+        .argv(*[*arguments])
+        .spawn
+    end
+
+    LLM.require "test-cmd.rb"
+    Command = Test::Cmd
+  end
+end

data/lib/llm/tools/mkdir.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Mkdir LLM::Tool::Mkdir} class implements
+  # a tool that can create a tree of new directories.
+  class Mkdir < self
+    name "mkdir"
+    description "create a new directory"
+    parameter :path, String, "the path to the directory"
+
+    ##
+    # @param [String] path
+    # @return [Hash]
+    def call(path:)
+      command = spawn(path:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    end
+
+    private
+
+    def spawn(path:)
+      Command
+        .new("mkdir")
+        .argv("-p", path)
+        .spawn
+    end
+
+    LLM.require "test-cmd.rb"
+    Command = Test::Cmd
+  end
+end

data/lib/llm/tools/pwd.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Pwd LLM::Tool::Pwd} class implements
+  # a tool that can reveal the current working directory.
+  class Pwd < self
+    name "pwd"
+    description "returns the current working directory"
+
+    ##
+    # @param [String] path
+    # @return [Hash]
+    def call
+      {ok: true, cwd: Dir.getwd}
+    end
+  end
+end

data/lib/llm/tools/read_file.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::ReadFile LLM::Tool::ReadFile} class implements
+  # a tool that can read the contents of a file. The tool accepts
+  # two optional offsets: a start line, and a stop line. Without
+  # either the entire file contents are read into memory.
+  class ReadFile < self
+    name "read-file"
+    description "read the contents of a file"
+    parameter :path, String, "the path to the file"
+    parameter :start, Integer, "start line number"
+    parameter :stop, Integer, "stop line number"
+    required %i[path]
+
+    ##
+    # @param [String] path
+    # @param [Integer] start
+    # @param [Integer] stop
+    # @return [Hash]
+    def call(path:, start: 1, stop: -1)
+      content, cursor = nil, 1
+      File.open(path, "r") do |f|
+        while cursor < start
+          f.gets
+          cursor += 1
+        end
+        if stop == -1
+          content = f.read
+        else
+          content = start.upto(stop).map { f.gets }.join
+        end
+      end
+      {ok: true, content:}
+    end
+  end
+end

data/lib/llm/tools/rg.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Rg LLM::Tool::Rg} class implements
+  # a frontend to the popular 'rg' tool. The tool can
+  # recursively search the current working directory
+  # for one or more patterns.
+  class Rg < self
+    name "rg"
+    description "recursively search the current directory for lines matching a pattern"
+    parameter :patterns, Array[String], "one or more search patterns"
+    parameter :path, String, "the path where the search is performed (default is cwd)"
+    required %i[patterns]
+
+    ##
+    # @param [String] pattern
+    # @return [Hash]
+    def call(patterns:, path: Dir.getwd)
+      validate!(patterns:, path:)
+      command = spawn(patterns:, path:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    end
+
+    private
+
+    def validate!(patterns:, path:)
+      if path == "/"
+        raise RuntimeError, "you can't search from the root of the filesystem"
+      elsif patterns == ["."]
+        raise RuntimeError, "narrow your search"
+      end
+    end
+
+    def spawn(patterns:, path:)
+      Command.new("rg")
+        .argv(*[*patterns].flat_map { ["-e", _1] }, path)
+        .spawn
+    end
+
+    LLM.require "test-cmd.rb"
+    Command = Test::Cmd
+  end
+end

data/lib/llm/tools/shell.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# frozen_string_literal
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Shell} class implements a tool that can
+  # spawn a command. That can be dangerous given a low-quality
+  # model, or a high-quality model that simply makes a bad
+  # decision. The risk can be reduced through a confirmation
+  # step such as {LLM::Agent.confirm LLM::Agent.confirm}, or
+  # by managing the tool loop manually through
+  # {LLM::Context LLM::Context}.
+  class Shell < self
+    name "shell"
+    description "run a shell command"
+    parameter :name, String, "the command name"
+    parameter :arguments, Array[String], "one or more command arguments"
+    required %i[name]
+
+    ##
+    # @param [String] name
+    #  The name of a command
+    # @param [Array<String>] arguments
+    #  One or more command-line arguments
+    # @return [Hash]
+    def call(name:, arguments: nil)
+      command = spawn(name:, arguments:)
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    end
+
+    private
+
+    ##
+    # @param [String] name
+    # @param [Array<String>] arguments
+    # @return [Command]
+    def spawn(name:, arguments:)
+      Command
+        .new(name)
+        .argv(*[*arguments])
+        .spawn
+    end
+
+    LLM.require "test-cmd.rb"
+    Command = Test::Cmd
+  end
+end

data/lib/llm/tools/swap_text.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::SwapText LLM::Tool::SwapText} class
+  # implements a tool that can substitute one piece of
+  # text for another piece of text in a given file.
+  class SwapText < self
+    name "swap-text"
+    description "Replace an exact snippet in a file"
+    parameter :path, String, "Path to file"
+    parameter :before, String, "Exact text to replace"
+    parameter :after, String, "Replacement text"
+    parameter :expected_count, Integer, "How many matches should be replaced"
+    required %i[path before after]
+
+    def call(path:, before:, after:, expected_count: 1)
+      content = File.read(path)
+      count = content.scan(before).length
+      raise "expected #{expected_count} match(es), found #{count}" unless count == expected_count.to_i
+      File.write(path, content.sub(before, after))
+      {ok: true, replaced: count}
+    end
+  end
+end

data/lib/llm/tools/write_file.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::WriteFile LLM::Tool::WriteFile} class
+  # implements a tool that can write a given string to a
+  # given file path.
+  class WriteFile < self
+    name "write-file"
+    description "write to a file"
+    parameter :path, String, "The file path"
+    parameter :content, String, "The file content"
+    required %i[path content]
+
+    ##
+    # @param [String] path
+    # @param [String] content
+    # @return [Hash]
+    def call(path:, content:)
+      File.open(path, "w") { _1.write(content) }
+      {ok: true}
+    end
+  end
+end

data/lib/llm/tools.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Dir[File.join(__dir__, "tools", "*.rb")].each do
+  require(_1)
+end

data/lib/llm/tracer/telemetry.rb

@@ -30,8 +30,7 @@ module LLM
   #   require "llm"
   #   require "opentelemetry-exporter-otlp"
   #
-  #   endpoint = "https://api.smith.langchain.com/otel/v1/traces"
-  #   exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint:)
+  #   exporter = OpenTelemetry::Exporter::OTLP::Exporter.new
   #
   #   llm = LLM.openai(key: ENV["KEY"])
   #   llm.tracer = LLM::Tracer::Telemetry.new(llm, exporter:)
@@ -59,7 +58,6 @@ module LLM
     # @return [self]
     def start_trace(trace_group_id: nil, name: "llm", attributes: {}, metadata: nil)
       return self if trace_group_id.to_s.empty?
-
       span_context = span_context_from_trace_group_id(trace_group_id.to_s)
       parent_ctx = ::OpenTelemetry::Trace.context_with_span(
         ::OpenTelemetry::Trace.non_recording_span(span_context)
@@ -316,7 +314,7 @@ module LLM
       set_span_attributes(span, consume_extra_outputs.merge(outputs || {}))
       finish_metadata = consume_finish_metadata_proc(res)
       metadata = (metadata || {}).merge(finish_metadata || {})
-      set_span_attributes(span, metadata.transform_keys { "langsmith.metadata.#{_1}" })
+      set_span_attributes(span, metadata.transform_keys { "llm.metadata.#{_1}" })
       span.add_event("gen_ai.request.finish")
       span.tap(&:finish)
     end
@@ -326,7 +324,7 @@ module LLM
         "gen_ai.operation.name" => operation
       }.merge!(finish_attributes(operation, res)).compact
       chunks_json = retrieval_chunks_json(res)
-      attributes["langsmith.metadata.chunks"] = chunks_json if chunks_json
+      attributes["llm.metadata.chunks"] = chunks_json if chunks_json
       attributes.each { span.set_attribute(_1, _2) }
       span.add_event("gen_ai.request.finish")
       span.tap(&:finish)
@@ -334,7 +332,7 @@ module LLM
 
     ##
     # @api private
-    # Serialize retrieval response chunks for span attributes (e.g. langsmith.metadata.chunks).
+    # Serialize retrieval response chunks for span attributes.
     # Returns a JSON string or nil when res has no data.
     def consume_finish_metadata_proc(res)
       key = LLM::Tracer::FINISH_METADATA_PROC_KEY

data/lib/llm/tracer.rb

@@ -11,7 +11,6 @@ module LLM
   class Tracer
     require_relative "tracer/logger"
     require_relative "tracer/telemetry"
-    require_relative "tracer/langsmith"
     require_relative "tracer/null"
 
     ##
@@ -45,7 +44,7 @@ module LLM
     # @param [Object, nil] span
     # @param [String] model
     # @param [Hash, nil] outputs Optional span attributes (e.g. gen_ai.output.messages) from llm.rb or caller.
-    # @param [Hash, nil] metadata Optional metadata (emitted as langsmith.metadata.*) from llm.rb or caller.
+    # @param [Hash, nil] metadata Optional metadata from llm.rb or caller.
     # @return [void]
     def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
@@ -110,8 +109,7 @@ module LLM
     # @param [Hash] attributes
     #  OpenTelemetry attributes to set on the root span.
     # @param [Hash, nil] metadata
-    #  Optional. Trace-level metadata merged into the trace (e.g. langsmith.metadata.*).
-    #  Only used by tracers that support it (e.g. {LLM::Tracer::Langsmith}).
+    #  Optional. Trace-level metadata merged into the trace by tracers that support it.
     # @return [self]
     def start_trace(trace_group_id: nil, name: "llm", attributes: {}, metadata: nil)
       self
@@ -150,11 +148,10 @@ module LLM
     ##
     # Merges extra attributes for the current trace/span. Used by applications
     # (e.g. chatbot) to add metadata, span inputs, or span outputs to the next
-    # span or to the trace. No-op by default; {LLM::Tracer::Langsmith} merges
-    # into fiber-local storage and emits them as langsmith/GenAI attributes.
+    # span or to the trace. No-op by default.
     #
     # @param [Hash, nil] metadata
-    #  Key-value pairs merged into trace/span metadata (e.g. langsmith.metadata.*).
+    #  Key-value pairs merged into trace/span metadata.
     # @param [Hash, nil] inputs
     #  Key-value pairs set on the next span at start (e.g. gen_ai.input.messages).
     #  Consumed when the span is created.
@@ -169,9 +166,9 @@ module LLM
     ##
     # Optional: set a proc to supply metadata when the next chat span finishes.
     # The proc is called with the response (res) and should return a Hash of
-    # metadata (e.g. { intent: "...", confidence: 1.0 }) to merge onto the span
-    # as langsmith.metadata.*. Cleared after use. Used by apps to attach
-    # routing/intent that is only known after the response.
+    # metadata (e.g. { intent: "...", confidence: 1.0 }) to merge onto the span.
+    # Cleared after use. Used by apps to attach routing/intent that is only
+    # known after the response.
     #
     # @param [Proc, nil] proc (res) -> Hash or nil
     # @return [self]
@@ -182,19 +179,10 @@ module LLM
 
     FINISH_METADATA_PROC_KEY = :"llm.tracer.finish_metadata_proc"
 
-    ##
-    # Returns the current extra bag (metadata, inputs, outputs) for the current
-    # thread/trace. Used by subclasses; default returns empty hashes.
-    #
-    # @return [Hash] { metadata: {}, inputs: {}, outputs: {} }
-    def current_extra
-      {}
-    end
-
     ##
     # Returns and clears extra inputs for the next span. Called by the telemetry
-    # tracer when starting a span. Subclasses (e.g. Langsmith) override to
-    # return fiber-local inputs; default returns {}.
+    # tracer when starting a span. Subclasses can override to return stored
+    # inputs; default returns {}.
     #
     # @return [Hash] Attribute key => value to set on the span at start
     def consume_extra_inputs

data/lib/llm/transport/execution.rb

@@ -59,9 +59,24 @@ class LLM::Transport
     # @return [LLM::Object, String]
     def parse_response(res)
       case res["content-type"]
-      when %r{\Aapplication/json\s*} then LLM::Object.from(LLM.json.load(res.body))
+      when %r{\Aapplication/json\s*}
+        body = read_body(res.body)
+        LLM::Object.from(LLM.json.load(body))
       else res.body
       end
     end
+
+    ##
+    # @param [#class] body
+    # @return [String]
+    def read_body(body)
+      case body.class.to_s
+      when "Net::ReadAdapter"
+        str = +""
+        body.read_body { str << _1 }
+        str
+      else body
+      end
+    end
   end
 end

data/lib/llm/transport/net_http_adapter.rb

@@ -21,7 +21,7 @@ class LLM::Transport
       when :put then ::Net::HTTP::Put.new(path, headers)
       when :patch then ::Net::HTTP::Patch.new(path, headers)
       when :delete then ::Net::HTTP::Delete.new(path, headers)
-      else ::Net::HTTP::GenericRequest.new(method, path, nil, headers)
+      else ::Net::HTTPGenericRequest.new(method, path, nil, headers)
       end
       if req.body
         http_req.body = req.body

data/lib/llm/uridata.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LLM
+  class URIData < Struct.new(:content_type, :encoding_type, :encoded, :decoded)
+    ##
+    # @param [String] str
+    #  A string
+    # @return [URIData]
+    def self.parse(str)
+      _, data = str.split(":")
+      content_type, data = data.split(";")
+      encoding_type, data = data.split(",")
+      URIData.new(content_type, encoding_type, data, StringIO.new(data.unpack1("m0")))
+    end
+  end
+end

data/lib/llm/version.rb

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