brute 5.0.5 → 5.1.0

data/lib/brute/token_counter/approximate.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module TokenCounter
+    # Tokens from text length, at a flat ratio of characters to tokens.
+    #
+    # Four characters to the token is the usual approximation. It needs no
+    # dependency and it is close enough to decide what to give up; put a
+    # Tiktoken counter on env[:token_counter] when the difference matters.
+    #
+    # `per_message` is what the rendering cannot see: every message is wrapped
+    # in the provider's own chat template on the way out, and that framing
+    # costs a few tokens each whatever the message says.
+    class Approximate
+      def initialize(chars_per_token: 4.0, per_message: 4)
+        unless chars_per_token.positive?
+          raise ArgumentError, "chars_per_token must be greater than 0, got #{chars_per_token}"
+        end
+
+        @chars_per_token = chars_per_token
+        @per_message = per_message
+      end
+
+      def count(messages, tools: nil)
+        text = Rendering.conversation(messages) + Rendering.tools(tools)
+
+        (text.length / @chars_per_token).to_i + (Array(messages).length * @per_message)
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/token_counter/approximate" do
+  it "divides the rendered text by the ratio, and charges for the envelope each message rides in" do
+    log = Brute.log
+    log.user("a" * 400)
+
+    # "user: " + 400 characters, four to the token, plus the envelope.
+    Brute::TokenCounter::Approximate.new.count(log).should == 105
+
+    # The ratio and the envelope are both settings, not truths.
+    Brute::TokenCounter::Approximate.new(chars_per_token: 2.0).count(log).should == 207
+    Brute::TokenCounter::Approximate.new(per_message: 0).count(log).should == 101
+
+    Brute::TokenCounter::Approximate.new.count([]).should == 0
+
+    lambda { Brute::TokenCounter::Approximate.new(chars_per_token: 0) }.should.raise(ArgumentError)
+  end
+end

data/lib/brute/token_counter/tiktoken.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module TokenCounter
+    # Tokens from OpenAI's byte-pair encoder, through the tiktoken_ruby gem.
+    #
+    #   gem "tiktoken_ruby"
+    #   use Brute::Middleware::DefaultCompactionPipeline,
+    #     window:        200_000,
+    #     token_counter: Brute::TokenCounter::Tiktoken.new
+    #
+    # Brute depends on no LLM library, and this is no exception: the gem is
+    # required the first time the counter is asked for a number, so an agent
+    # that never installs it never pays for it and never hears about it.
+    #
+    # It is exact about the text and still approximate about the request --
+    # `per_message` stands in for the chat-template framing, which is the
+    # provider's and not in any encoder.
+    class Tiktoken
+      ENCODING = "o200k_base"
+
+      def initialize(encoding: ENCODING, per_message: 4, encoder: nil)
+        @encoding = encoding
+        @per_message = per_message
+        @encoder = encoder
+      end
+
+      # Load the encoder, downloading its vocabulary if it is not cached yet.
+      def warm_up
+        @encoder ||= load_encoder
+      end
+
+      def count(messages, tools: nil)
+        warm_up
+        text = Rendering.conversation(messages) + Rendering.tools(tools)
+
+        @encoder.encode(text).length + (Array(messages).length * @per_message)
+      end
+
+      private
+
+        def load_encoder
+          begin
+            require "tiktoken_ruby"
+          rescue LoadError
+            raise LoadError, "#{self.class} needs the tiktoken_ruby gem: add `gem \"tiktoken_ruby\"` to your Gemfile"
+          end
+
+          ::Tiktoken.get_encoding(@encoding)
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/token_counter/tiktoken" do
+  it "encodes the same rendering the approximate counter measures, and says what to install when it cannot" do
+    encoded = []
+    encoder = Object.new
+    encoder.define_singleton_method(:encode) { |text| encoded << text; text.split(/\b/) }
+
+    log = Brute.log
+    log.user("what changed?")
+
+    counter = Brute::TokenCounter::Tiktoken.new(encoder: encoder, per_message: 4)
+    counter.count(log).should == encoder.encode("user: what changed?").length + 4
+    encoded.last.should == "user: what changed?"
+
+    # The vocabulary is loaded once, on the first count rather than at boot.
+    counter.warm_up.should.equal? encoder
+
+    missing = Brute::TokenCounter::Tiktoken.new(encoding: "nothing-real")
+    missing.define_singleton_method(:require) { |_name| raise LoadError }
+    lambda { missing.count(log) }.should.raise(LoadError).message.should.include "tiktoken_ruby"
+  end
+end

data/lib/brute/token_counter.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "json"
+
+module Brute
+  # How big a conversation is, in tokens.
+  #
+  # A counter is anything answering `count(messages, tools: nil)`. The tools
+  # are part of the question because their schemas ride in every request
+  # alongside the messages -- an agent carrying a dozen of them is spending
+  # context on JSON Schema before anyone has said a word.
+  #
+  #   counter = Brute::TokenCounter::Approximate.new
+  #   counter.count(env[:messages], tools: env[:tools])
+  #
+  # What a turn is *currently* costing is a different question, and
+  # `estimate` answers it: the provider counted the conversation exactly when
+  # it answered, so that number is trusted and only what has been appended
+  # since is counted locally.
+  #
+  #   Brute::TokenCounter.estimate(env)
+  #
+  module TokenCounter
+    def self.default = Approximate.new
+
+    # What the whole turn costs right now.
+    #
+    # :counter defaults to the one the turn already decided on
+    # (env[:token_counter]), :tools to the ones the pipeline advertises
+    # (env[:tools]).
+    #
+    # The reported total already covers the system prompt, the tool schemas
+    # and the provider's own chat-template overhead, so the warm path adds
+    # only the messages that landed after the reply it describes -- and never
+    # the schemas, which are already inside it. Anything else double counts.
+    def self.estimate(env, counter: nil, tools: nil)
+      counter ||= env[:token_counter] || default
+      tools = env[:tools] if tools.nil?
+      messages = env[:messages] || []
+      reported = env.dig(:metadata, :last_llm_usage)&.total.to_i
+      answered = messages.rindex { |message| message.role == :assistant }
+
+      # Nothing sent yet, or a conversation the reported number no longer
+      # describes -- a compaction that left no reply behind, say. Count it all.
+      if reported.zero? || answered.nil?
+        counter.count(messages, tools: tools)
+      else
+        reported + counter.count(messages[(answered + 1)..])
+      end
+    end
+
+    # The text a counter measures.
+    #
+    # One rendering, so two counters cannot disagree about what the
+    # conversation even is -- and it is the same text a summariser reads,
+    # which is why it says who spoke and what was called rather than being
+    # the shortest thing that could be measured.
+    module Rendering
+      def self.conversation(messages) = Array(messages).map { |message| message(message) }.join("\n")
+
+      def self.message(message)
+        parts = ["#{message.role}:", message.content.to_s]
+
+        message.tool_calls&.each do |call|
+          parts << "#{call.name}(#{JSON.generate(call.arguments)}) -> #{call.id}"
+        end
+
+        unless message.tool_call_id.nil?
+          parts << "(answering #{message.tool_call_id})"
+        end
+
+        parts.reject(&:empty?).join(" ")
+      end
+
+      # The schemas as the provider is given them, which is what they cost.
+      def self.tools(tools)
+        wrapped = Brute::Tools::Adapter.wrap_all(tools || [])
+
+        if wrapped.empty?
+          ""
+        else
+          JSON.generate(wrapped.values.map(&:to_h))
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/token_counter" do
+  def usage(total) = Brute::UsageDetection::Usage.new(total: total)
+
+  it "measures a conversation and its schemas, and trusts the provider for what it already counted" do
+    log = Brute.log
+    log.system("you are a helpful agent")
+    log.user("what changed?")
+
+    counter = Brute::TokenCounter.default
+    counter.should.be.kind_of Brute::TokenCounter::Approximate
+
+    text = Brute::TokenCounter::Rendering.conversation(log)
+    text.should == "system: you are a helpful agent\nuser: what changed?"
+
+    # A tool call and the result answering it are rendered too -- both cost
+    # tokens, and neither is in the message's content.
+    log << Brute::Message.new(
+      role: :assistant,
+      content: "",
+      tool_calls: [{ id: "tc1", name: "search", arguments: { "query" => "fed" } }]
+    )
+    log.tool("found nothing", tool_call_id: "tc1")
+    Brute::TokenCounter::Rendering.conversation(log).should.include 'search({"query":"fed"}) -> tc1'
+    Brute::TokenCounter::Rendering.conversation(log).should.include "(answering tc1)"
+
+    # Schemas ride in every request, so they are part of the question.
+    tool = Brute::Turn::ToolPipeline.new(name: "search", description: "search the web") do
+      run ->(env) { env[:result] = "" }
+    end
+    Brute::TokenCounter::Rendering.tools(nil).should == ""
+    Brute::TokenCounter::Rendering.tools([tool]).should.include "search the web"
+    counter.count(log, tools: [tool]).should > counter.count(log)
+
+    # Nothing reported yet: everything is counted, schemas included.
+    cold = { messages: log, tools: [tool], metadata: {} }
+    Brute::TokenCounter.estimate(cold).should == counter.count(log, tools: [tool])
+
+    # Reported: the provider's number, plus only what landed after the reply
+    # it describes. The schemas are already inside it.
+    log.assistant("nothing changed")
+    log.user("are you sure?")
+    warm = { messages: log, tools: [tool], metadata: { last_llm_usage: usage(9_000) } }
+    Brute::TokenCounter.estimate(warm).should == 9_000 + counter.count([log.last])
+
+    # A conversation the reported number no longer describes -- a compaction
+    # that left no reply behind -- is counted from scratch rather than added
+    # to a total for a conversation that is gone.
+    stale = { messages: Brute.log.tap { |l| l.user("only me") }, metadata: { last_llm_usage: usage(9_000) } }
+    Brute::TokenCounter.estimate(stale).should == counter.count(stale[:messages])
+
+    # The counter the turn already decided on is the one that gets used.
+    given = { messages: log, metadata: {}, token_counter: Object.new }
+    given[:token_counter].define_singleton_method(:count) { |_messages, tools: nil| 7 }
+    Brute::TokenCounter.estimate(given).should == 7
+  end
+end

data/lib/brute/tools/adapter.rb

@@ -118,6 +118,10 @@ module Brute
         )
       end
 
+      # The tool object this adapter wraps (Brute::Tool, Brute::Turn::ToolPipeline,
+      # SubAgent, Hash definition, ...).
+      attr_reader :original
+
       def initialize(name:, description:, params:, handler:, schema: nil, original: nil)
         @name        = name
         @description = description
@@ -127,10 +131,6 @@ module Brute
         @original    = original
       end
 
-      # The tool object this adapter wraps (Brute::Tool, Brute::Turn::ToolPipeline,
-      # SubAgent, Hash definition, ...).
-      attr_reader :original
-
       # Execute the tool. Accepts string- or symbol-keyed argument hashes,
       # as delivered by LLM providers.
       def call(arguments = {})

data/lib/brute/tools/skill_load.rb

@@ -40,13 +40,13 @@ module Brute
 
       FILE_LIMIT = 10
 
-      def name; "skill"; end
-
       def initialize(cwd: Dir.pwd)
         super()
         @cwd = cwd
       end
 
+      def name; "skill"; end
+
       def execute(name:)
         skill = Brute::Skill.get(name, cwd: @cwd)
         return unknown_skill(name) unless skill

data/lib/brute/tools/sub_agent.rb

@@ -21,7 +21,7 @@ module Brute
     #     use Brute::Middleware::SystemPrompt
     #     use Brute::Middleware::Loop::ToolResult
     #     use Brute::Middleware::MaxIterations, max_iterations: 10
-    #     use Brute::Middleware::ToolPipeline, tools: [Brute::Tools::FSRead, Brute::Tools::FSSearch]
+    #     use Brute::Middleware::DefaultToolPipeline, tools: [Brute::Tools::FSRead, Brute::Tools::FSSearch]
     #     run ->(env) do
     #       # The LLM call, written with your library of choice. Convert
     #       # env[:messages] to its format, call it, and append the response
@@ -32,7 +32,7 @@ module Brute
     #
     #   # The SubAgent IS a tool — hand it to a parent agent's ToolPipeline:
     #   main_agent = Brute.agent do
-    #     use Brute::Middleware::ToolPipeline, tools: [Brute::Tools::FSRead, researcher]
+    #     use Brute::Middleware::DefaultToolPipeline, tools: [Brute::Tools::FSRead, researcher]
     #     run ->(env) { ... }
     #   end
     #   main_agent.start("delegate some research")

data/lib/brute/turn/compaction_pipeline.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/turn/pipeline"
+
+module Brute
+  module Turn
+    # A compactor built out of middleware.
+    #
+    # Like ToolPipeline it *composes* a Pipeline rather than inheriting: the
+    # definition block is instance_eval'd into the internal Pipeline, so `use`
+    # / `run` inside it are the builder's methods.
+    #
+    # The stack order is the policy. A layer that got the conversation under
+    # target does not call the next one, so the strategies that cost nothing
+    # sit at the top and the terminal app -- the summariser, the only thing
+    # here that spends money -- is reached only when they could not get there.
+    # That is `run` meaning what it means everywhere else in Brute: the model
+    # call, at the bottom, with the layers deciding what reaches it.
+    #
+    #   Brute::Turn::CompactionPipeline.new do
+    #     use Brute::Compaction::Middleware::ToolResults,   keep_steps: 1
+    #     use Brute::Compaction::Middleware::SlidingWindow, keep_steps: 2
+    #
+    #     run Brute::Compaction::Summarize.new(
+    #       Brute::Completion::OpenRouter.new(config: { access_token: key }),
+    #     )
+    #   end
+    #
+    # A pipeline that must never spend a call is the first two layers and
+    # `run ->(env) { env }` -- a policy said out loud rather than configured.
+    #
+    # The conversation being compacted rides on `env[:conversation]`, leaving
+    # `env[:messages]` to mean what it means to every other terminal app in
+    # Brute: the prompt going down, the reply coming back.
+    #
+    # It answers #compact, so what comes out drops into
+    # Brute::Middleware::DefaultCompactionPipeline as that turn's compactor.
+    class CompactionPipeline
+      def initialize(&block)
+        @pipeline = Pipeline.new
+        @pipeline.instance_eval(&block) if block
+      end
+
+      # Answer a smaller conversation, or nil when nothing was given up.
+      def compact(messages, target:, events: Pipeline::NullSink.new, token_counter: nil)
+        env = {
+          conversation:  messages,
+          target:        target,
+          token_counter: token_counter,
+          applied:       [],
+          messages:      Brute.log,
+          events:        events,
+          metadata:      {},
+        }
+        @pipeline.call(env)
+
+        unless env[:applied].empty?
+          env[:conversation]
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/turn/compaction_pipeline" do
+  def said(content) = Brute::Message.new(role: :user, content: content)
+
+  def layer(name, &block)
+    Class.new(Brute::Compaction::Middleware::Strategy) do
+      define_method(:strategy) { name }
+      define_method(:rewrite) { |conversation, target:| block.call(conversation, target) }
+    end
+  end
+
+  it "composes strategies into one compactor, and only reaches run when they could not" do
+    reached = []
+    halves = layer("halves") { |c, _t| reached << "halves"; c.first(c.length / 2) }
+    never  = layer("never")  { |_c, _t| reached << "never"; nil }
+    # A terminal belongs to one pipeline: the builder binds an emit onto it
+    # and refuses to bind a second, so each pipeline gets its own.
+    terminal = lambda do
+      Object.new.tap { |it| it.define_singleton_method(:call) { |env| reached << "run"; env } }
+    end
+
+    four = [said("a" * 4_000), said("b" * 4_000), said("c" * 4_000), said("d" * 4_000)]
+
+    # Halving is enough, so the terminal -- the one that costs money -- is
+    # never reached. The stack order is the policy.
+    pipeline = Brute::Turn::CompactionPipeline.new do
+      use halves
+      run terminal.call
+    end
+    pipeline.compact(four, target: 3_000).map { |m| m.content[0, 1] }.should == ["a", "b"]
+    reached.should == ["halves"]
+
+    # A strategy that declines lets the turn fall through to it.
+    reached.clear
+    Brute::Turn::CompactionPipeline.new do
+      use never
+      run terminal.call
+    end.compact(four, target: 3_000).should.be.nil
+    reached.should == ["never", "run"]
+
+    # Nothing given up at all is nil, not the conversation it was handed --
+    # the caller applies whatever else comes back.
+    reached.clear
+    pipeline.compact(four, target: 500_000).should.be.nil
+    reached.should == []
+
+    # The conversation rides on :conversation, leaving :messages to mean what
+    # it means to every other terminal app -- the prompt down, the reply back.
+    seen = nil
+    Brute::Turn::CompactionPipeline.new do
+      run ->(env) { seen = [env[:conversation].length, env[:messages], env[:target]] }
+    end.compact(four, target: 10)
+    seen.should == [4, [], 10]
+  end
+end

data/lib/brute/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brute
-  VERSION = "5.0.5"
+  VERSION = "5.1.0"
 end

data/lib/brute.rb

@@ -42,7 +42,7 @@ module Brute
   #
   #   agent = Brute.agent
   #     .use(Brute::Middleware::SystemPrompt)
-  #     .use(Brute::Middleware::ToolPipeline, tools: Brute::Tools::ALL)
+  #     .use(Brute::Middleware::DefaultToolPipeline, tools: Brute::Tools::ALL)
   #     .run ->(env) { ... }      # the LLM-call proc (provider/model/creds here)
   #
   #   agent.start("what changed?")
@@ -93,7 +93,14 @@ end
 require_relative "brute/version"
 require_relative "brute/hooks"
 require_relative "brute/messages"
+require_relative "brute/env"
 require_relative "brute/middleware/000_base"
+require_relative "brute/compaction"
+require_relative "brute/compaction/transcript"
+require_relative "brute/compaction/middleware/strategy"
+require_relative "brute/compaction/middleware/tool_results"
+require_relative "brute/compaction/middleware/sliding_window"
+require_relative "brute/compaction/summarize"
 require_relative "brute/completion/open_router"
 require_relative "brute/completion/lang_chain"
 require_relative "brute/completion/llmrb"
@@ -124,8 +131,10 @@ require_relative "brute/middleware/008_checkpoint"
 require_relative "brute/middleware/010_max_iterations"
 require_relative "brute/middleware/020_system_prompt"
 require_relative "brute/middleware/025_skills"
+require_relative "brute/middleware/040_default_compaction_pipeline"
 require_relative "brute/middleware/040_compaction_check"
 require_relative "brute/middleware/060_questions"
+require_relative "brute/middleware/070_default_tool_pipeline"
 require_relative "brute/middleware/070_tool_pipeline"
 require_relative "brute/middleware/event_handler"
 require_relative "brute/middleware/user_queue"
@@ -157,6 +166,9 @@ require_relative "brute/prompts/tool_usage"
 require_relative "brute/rack/adapter"
 require_relative "brute/skill"
 require_relative "brute/system_prompt"
+require_relative "brute/token_counter"
+require_relative "brute/token_counter/approximate"
+require_relative "brute/token_counter/tiktoken"
 require_relative "brute/tool"
 require_relative "brute/tools"
 require_relative "brute/tools/adapter"
@@ -179,7 +191,9 @@ require_relative "brute/tools/todo_write"
 require_relative "brute/truncation"
 require_relative "brute/turn/agent_pipeline"
 require_relative "brute/turn/pipeline"
+require_relative "brute/turn/compaction_pipeline"
 require_relative "brute/turn/tool_pipeline"
+require_relative "brute/eval"
 require_relative "brute/utils/diff"
 
 # gangsta g-dogg bruh...

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brute
 version: !ruby/object:Gem::Version
-  version: 5.0.5
+  version: 5.1.0
 platform: ruby
 authors:
 - Brute Contributors
@@ -282,12 +282,24 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/brute.rb
+- lib/brute/compaction.rb
+- lib/brute/compaction/middleware/sliding_window.rb
+- lib/brute/compaction/middleware/strategy.rb
+- lib/brute/compaction/middleware/tool_results.rb
+- lib/brute/compaction/summarize.rb
+- lib/brute/compaction/transcript.rb
 - lib/brute/completion/lang_chain.rb
 - lib/brute/completion/llmrb.rb
 - lib/brute/completion/open_router.rb
 - lib/brute/completion/ruby_llm.rb
 - lib/brute/contrib/log_file.rb
 - lib/brute/contrib/otel.rb
+- lib/brute/env.rb
+- lib/brute/eval.rb
+- lib/brute/eval/case.rb
+- lib/brute/eval/suite.rb
+- lib/brute/eval/transcript.rb
+- lib/brute/eval/world.rb
 - lib/brute/events/handler.rb
 - lib/brute/events/prefixed_terminal_output.rb
 - lib/brute/events/terminal_output_handler.rb
@@ -311,7 +323,9 @@ files:
 - lib/brute/middleware/020_system_prompt.rb
 - lib/brute/middleware/025_skills.rb
 - lib/brute/middleware/040_compaction_check.rb
+- lib/brute/middleware/040_default_compaction_pipeline.rb
 - lib/brute/middleware/060_questions.rb
+- lib/brute/middleware/070_default_tool_pipeline.rb
 - lib/brute/middleware/070_tool_pipeline.rb
 - lib/brute/middleware/event_handler.rb
 - lib/brute/middleware/user_queue.rb
@@ -362,6 +376,9 @@ files:
 - lib/brute/rack/adapter.rb
 - lib/brute/skill.rb
 - lib/brute/system_prompt.rb
+- lib/brute/token_counter.rb
+- lib/brute/token_counter/approximate.rb
+- lib/brute/token_counter/tiktoken.rb
 - lib/brute/tool.rb
 - lib/brute/tools.rb
 - lib/brute/tools/adapter.rb
@@ -383,6 +400,7 @@ files:
 - lib/brute/tools/todo_write.rb
 - lib/brute/truncation.rb
 - lib/brute/turn/agent_pipeline.rb
+- lib/brute/turn/compaction_pipeline.rb
 - lib/brute/turn/pipeline.rb
 - lib/brute/turn/tool_pipeline.rb
 - lib/brute/usage_detection/lang_chain.rb