brute 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3594fba62fc4a71baaaf36b878eb1a3c02a3c06f7b0b2517b434556468bcde5
-  data.tar.gz: d8f74e82c95d7698c11ecbe5792f57ace4739a81f4d625d3cb729123eb0b7179
+  metadata.gz: 19cba194a6650394c2b81805f70adcc5f774999962ca7d16123c7a335afc0532
+  data.tar.gz: c2a1d5bb0d1d2acceada34711f67adb586c3a366d68f22636dd754dce1587e19
 SHA512:
-  metadata.gz: 861ab5262a21c876fa6592d1fc22612c39aada6e33a30e35ce81adb1bbbdfa978b9dab7b31ce7d653bf0f8e8ed09256a37d3d50bbe0024b889c5583e1fb690b6
-  data.tar.gz: '082b158a7deec18b8ba1fededb03e7b1c08d7e744b03da7840d9e4af4234bb86b89d9266a560cc81e9d13a7f3a4bbca4f831a343fbaa18052acc3381075b4b8e'
+  metadata.gz: b61457cd8041c561ddbd4764968cd0df6903b59e593f40af8bff9b63bb69624bf8f73f879130e336d64c25dce10f6f9d44d377837871db6ce9f19c0b20ff6cb3
+  data.tar.gz: 30989eae4bec648ba08036641cd5404a19c22ca477094896ccb6ca20d8a2ace194e82d1ffab4b5ef37436f38de350b90531c35ffb611974385888c3a0ea827ee

data/lib/brute/agent.rb

@@ -1,14 +1,80 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+require 'brute/pipeline'
+
 module Brute
-  class Agent
-    attr_reader :provider, :model, :tools, :system_prompt
+  DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant, hellbent on taking over the world."
+
+  # An agent is a Pipeline configured for LLM turns. It carries the
+  # provider/model/tools configuration and shapes env from a Session
+  # (the conversation message log).
+  #
+  # Usage:
+  #
+  #   agent = Brute::Agent.new(
+  #     provider: Brute.provider,
+  #     model:    "claude-sonnet-4-20250514",
+  #     tools:    Brute::Tools::ALL,
+  #   ) do
+  #     use Brute::Middleware::EventHandler, handler_class: TerminalOutput
+  #     use Brute::Middleware::SystemPrompt
+  #     use Brute::Middleware::MaxIterations
+  #     use Brute::Middleware::Question
+  #     use Brute::Middleware::ToolCall
+  #     run Brute::Middleware::LLMCall.new
+  #   end
+  #
+  #   session = Brute::Session.new
+  #   session.user("fix the failing tests")
+  #   agent.call(session)
+  #
+  class Agent < Pipeline
+    attr_reader :provider, :model, :tools
 
-    def initialize(provider:, model:, tools: Brute::Tools::ALL, system_prompt: nil)
+    def initialize(provider:, model: nil, tools: [], &block)
       @provider = provider
-      @model = model
-      @tools = tools
-      @system_prompt = system_prompt
+      @model    = model
+      @tools    = tools
+      super(&block)
+    end
+
+    # Run one turn against the given session. The session is mutated
+    # in place (assistant + tool messages appended) and returned.
+    def call(session, events: NullSink.new)
+      env = {
+        messages:          session,
+        provider:          @provider,
+        model:             @model,
+        tools:             @tools,
+        events:            events,
+        metadata:          {},
+        system_prompt:     DEFAULT_SYSTEM_PROMPT,
+        current_iteration: 1,
+      }
+      super(env)
+      session
     end
   end
 end
+
+test do
+  it "runs a turn and returns the session" do
+    agent = Brute::Agent.new(provider: :stub) do
+      run ->(env) { env[:messages].assistant("hello") }
+    end
+    session = Brute::Session.new
+    session.user("hi")
+    agent.call(session).should == session
+  end
+
+  it "passes provider/model/tools through env" do
+    captured = nil
+    capture = ->(env) { captured = env.slice(:provider, :model, :tools) }
+
+    agent = Brute::Agent.new(provider: :stub, model: "m", tools: [:a]) { run capture }
+    agent.call(Brute::Session.new)
+    captured.should == { provider: :stub, model: "m", tools: [:a] }
+  end
+end

data/lib/brute/events/handler.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'brute'
+
+module Brute
+  module Events
+    # EXAMPLES:
+    # class TerminalOutput < Brute::Events::Handler
+    #   def <<(event)
+    #     h = event.to_h
+    #     case h[:type]
+    #     when :content       then write(h[:data])
+    #     when :tool_result   then write("  ✓ #{h[:data][:name]}\n")
+    #     when :log           then write("[#{h[:data]}]\n")
+    #     end
+    #     super  # forward to whatever's wrapped underneath
+    #   end
+    # 
+    #   private
+    #   def write(text); $stderr.write(text); $stderr.flush; end
+    # end
+    # 
+    # class JsonlTrace < Brute::Events::Handler
+    #   def initialize(inner, path:)
+    #     super(inner)
+    #     @file = File.open(path, "a")
+    #   end
+    # 
+    #   def <<(event)
+    #     @file.puts(JSON.generate(event.to_h))
+    #     @file.flush
+    #     super
+    #   end
+    # end
+    # 
+    # class FilterNoise < Brute::Events::Handler
+    #   # Drop reasoning chunks before they reach the terminal
+    #   def <<(event)
+    #     return self if event.to_h[:type] == :reasoning
+    #     super
+    #   end
+    # end
+    #
+    # pipeline = Brute::Pipeline.new do
+    #   use Brute::Middleware::EventHandler, handler_class: JsonlTrace, path: "trace.jsonl"
+    #   use Brute::Middleware::EventHandler, handler_class: FilterNoise
+    #   use Brute::Middleware::EventHandler, handler_class: TerminalOutput
+    # end
+    #
+    class Handler
+      def initialize(inner)
+        @inner = inner
+      end
+
+      # Default: pass through. Subclasses override <<, do their thing,
+      # then super (or don't, to swallow the event).
+      def <<(event)
+        tap do
+          @inner << event if @inner
+        end
+      end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/events/prefixed_terminal_output.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Events
+    # TerminalOutput variant that prefixes all output with a label.
+    # Useful for sub-agents running concurrently — the prefix makes it
+    # clear which agent produced each line.
+    #
+    # Usage in a middleware stack:
+    #
+    #   use Brute::Middleware::EventHandler,
+    #       handler_class: Brute::Events::PrefixedTerminalOutput,
+    #       prefix: "explore"
+    #
+    class PrefixedTerminalOutput < Brute::Events::Handler
+      def initialize(inner, prefix: "sub-agent")
+        super(inner)
+        @prefix = prefix
+        @tag = "[#{@prefix}]".light_black
+      end
+
+      def <<(event)
+        $stdout.sync = true
+
+        type = event.to_h[:type]
+        data = event.to_h[:data]
+
+        method = "on_#{type}"
+        send(method, data) if respond_to?(method, true)
+
+        super
+      end
+
+      private
+
+        def on_content(data)
+          # Prefix each line so interleaved output is distinguishable
+          data.to_s.each_line { |line| $stdout.write("#{@tag} #{line}") }
+        end
+
+        def on_tool_call_start(data)
+          puts
+          data.each do |tool_call|
+            puts "#{@tag} [tool] #{tool_call[:name]} - #{tool_call[:arguments]}"
+          end
+        end
+
+        def on_tool_result(data)
+          puts "#{@tag} [tool] #{data[:name]} - done"
+        end
+
+        def on_log(data)
+          $stderr.puts "#{@tag} #{data}".light_black
+        end
+
+        def on_error(data)
+          if data.is_a?(Hash)
+            $stderr.puts "#{@tag} error: #{data[:message]}"
+          else
+            $stderr.puts "#{@tag} error: #{data}"
+          end
+        end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/events/terminal_output_handler.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'brute'
+
+module Brute
+  module Events
+    class TerminalOutput < Brute::Events::Handler
+      def <<(event)
+        $stdout.sync = true
+
+        type = event.to_h[:type]
+        data = event.to_h[:data]
+
+        method = "on_#{type}"
+
+        if respond_to?(method, true)
+          send(method, data) 
+        end
+
+        super
+      end
+
+      private
+
+        def on_content(data)
+          $stdout.write(data)
+        end
+
+        def on_reasoning(data)
+          $stderr.write(data.to_s.gsub(/^/, "  │ "))
+        end
+
+        def on_tool_call_start(data)
+          puts
+          data.each do |tool_call|
+            puts "[tool] #{tool_call[:name]} - #{tool_call[:arguments]}"
+          end
+        end
+
+        def on_tool_result(data)
+          puts "[tool] #{data[:name]} - done"
+        end
+
+        def on_log(data)
+          $stderr.puts "#{data}".light_black
+        end
+
+        def on_assistant_complete(_)
+          puts
+        end
+
+        def on_error(data)
+          if data.is_a?(Hash)
+            $stderr.puts "✗ #{data[:error].class}: #{data[:message]}"
+            $stderr.puts "  provider: #{data[:provider].inspect}"
+            $stderr.puts "  model:    #{data[:model].inspect}"
+          else
+            $stderr.puts "✗ #{data.class}: #{data.message}"
+          end
+        end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/middleware/001_otel_span.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Outermost OTel middleware. Creates a span per LLM stack call
+    # and passes it through env[:span] for inner OTel middlewares to
+    # decorate with events and attributes.
+    #
+    # When opentelemetry-sdk is not loaded, this is a pure pass-through.
+    #
+    # Stack position: outermost (wraps everything including retries).
+    #
+    #   use Brute::Middleware::OTel::Span
+    #   use Brute::Middleware::OTel::ToolResultLoop
+    #   use Brute::Middleware::OTel::ToolCalls
+    #   use Brute::Middleware::OTel::TokenUsage
+    #   # ... existing middleware ...
+    #   run Brute::Middleware::LLMCall.new
+    #
+    class OtelSpan
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        #return @app.call(env) unless defined?(::OpenTelemetry::SDK)
+
+        #provider_name = provider_type(env[:provider])
+        #model = env[:model] || (env[:provider].default_model rescue nil)
+        #span_name = model ? "llm.call #{model}" : "llm.call"
+
+        #attributes = {
+        #  "brute.provider" => provider_name,
+        #  "brute.streaming" => !!env[:streaming],
+        #  "brute.context_messages" => env[:messages].size,
+        #}
+        #attributes["brute.model"] = model.to_s if model
+        #attributes["brute.session_id"] = env[:metadata][:session_id].to_s if env.dig(:metadata, :session_id)
+
+        #tracer.in_span(span_name, attributes: attributes, kind: :internal) do |span|
+        #  env[:span] = span
+        #  response = @app.call(env)
+
+        #  # Record response model if it differs from request model
+        #  resp_model = begin; response.model; rescue; nil; end
+        #  span.set_attribute("brute.response_model", resp_model.to_s) if resp_model && resp_model != model
+
+        #  response
+        #rescue ::StandardError => e
+        #  span.record_exception(e)
+        #  span.status = ::OpenTelemetry::Trace::Status.error(e.message)
+        #  raise
+        #ensure
+        #  env.delete(:span)
+        #end
+        @app.all(env)
+      end
+
+      private
+
+        def tracer
+          @tracer ||= ::OpenTelemetry.tracer_provider.tracer("brute", Brute::VERSION)
+        end
+
+        def provider_type(provider)
+          provider.name.to_s
+        end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/middleware/003_tool_result_loop.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Re-invokes the inner stack whenever the last message is a :tool result.
+    #
+    # After the inner pipeline runs (LLMCall responds, ToolCall executes tools
+    # and appends :tool messages), this middleware checks if tool results are
+    # pending. If so, it increments the iteration counter and loops — sending
+    # the tool results back through MaxIterations → ToolCall → LLMCall so the
+    # LLM can see them.
+    #
+    # The loop breaks when:
+    #   - The LLM responds with text only (no tool calls) — last message is :assistant
+    #   - env[:should_exit] is set (e.g. by MaxIterations)
+    #
+    class ToolResultLoop
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        loop do
+          @app.call(env)
+
+          break if env[:should_exit]
+          break unless env[:messages].last&.role == :tool
+
+          env[:current_iteration] += 1
+        end
+
+        env
+      end
+    end
+  end
+end
+
+test do
+  require "brute/session"
+
+  it "loops until last message is not a tool result" do
+    call_count = 0
+
+    # Fake inner app: first call appends a :tool message, second call appends :assistant
+    inner = ->(env) do
+      call_count += 1
+      if call_count == 1
+        env[:messages] << RubyLLM::Message.new(role: :tool, content: "result", tool_call_id: "tc1")
+      else
+        env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      end
+    end
+
+    mw = Brute::Middleware::ToolResultLoop.new(inner)
+    env = { messages: Brute::Session.new, current_iteration: 1 }
+    env[:messages].user("hi")
+
+    mw.call(env)
+
+    call_count.should == 2
+    env[:current_iteration].should == 2
+    env[:messages].last.role.should == :assistant
+  end
+
+  it "stops when should_exit is set" do
+    call_count = 0
+
+    inner = ->(env) do
+      call_count += 1
+      env[:messages] << RubyLLM::Message.new(role: :tool, content: "result", tool_call_id: "tc#{call_count}")
+      env[:should_exit] = { reason: "max" } if call_count >= 2
+    end
+
+    mw = Brute::Middleware::ToolResultLoop.new(inner)
+    env = { messages: Brute::Session.new, current_iteration: 1 }
+    env[:messages].user("hi")
+
+    mw.call(env)
+
+    call_count.should == 2
+  end
+
+  it "does not loop when last message is assistant" do
+    call_count = 0
+
+    inner = ->(env) do
+      call_count += 1
+      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "hello")
+    end
+
+    mw = Brute::Middleware::ToolResultLoop.new(inner)
+    env = { messages: Brute::Session.new, current_iteration: 1 }
+    env[:messages].user("hi")
+
+    mw.call(env)
+
+    call_count.should == 1
+    env[:current_iteration].should == 1
+  end
+end

data/lib/brute/middleware/004_summarize.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Runs a final tool-free LLM call after the ToolResultLoop completes,
+    # ensuring the agent produces a clean summary response.
+    #
+    # This middleware sits above ToolResultLoop in the stack. After the tool
+    # loop finishes (either naturally or via MaxIterations), Summarize
+    # injects a summary prompt and calls the inner stack one more time
+    # with tools removed. The LLM responds with text only, giving the
+    # agent a proper final answer.
+    #
+    # Stack order:
+    #
+    #   use Summarize
+    #   use ToolResultLoop
+    #   use MaxIterations
+    #   use ToolCall
+    #   run LLMCall.new
+    #
+    class Summarize
+      DEFAULT_PROMPT = "Provide your complete findings based on everything you've explored."
+
+      def initialize(app, prompt: DEFAULT_PROMPT)
+        @app = app
+        @prompt = prompt
+      end
+
+      def call(env)
+        @app.call(env)
+
+        saved_tools = env[:tools]
+        env[:tools] = []
+        env[:current_iteration] = 1
+        env[:messages] << RubyLLM::Message.new(role: :user, content: @prompt)
+        @app.call(env)
+        env[:tools] = saved_tools
+
+        env
+      end
+    end
+  end
+end
+
+test do
+  require "brute/session"
+
+  it "produces a final assistant message after tool loop" do
+    call_count = 0
+
+    # Fake inner app: first call simulates a tool loop ending with a tool message,
+    # second call (summary) produces an assistant message.
+    inner = ->(env) do
+      call_count += 1
+      if call_count == 1
+        env[:messages] << RubyLLM::Message.new(role: :tool, content: "some result", tool_call_id: "tc1")
+      else
+        env[:messages] << RubyLLM::Message.new(role: :assistant, content: "Here is my complete summary.")
+      end
+    end
+
+    mw = Brute::Middleware::Summarize.new(inner)
+    session = Brute::Session.new
+    session.user("explore the codebase")
+    env = { messages: session, tools: [:some_tool], current_iteration: 5 }
+    mw.call(env)
+
+    env[:messages].last.role.should == :assistant
+    env[:messages].last.content.should =~ /summary/i
+  end
+
+  it "restores tools after summary call" do
+    inner = ->(env) {
+      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+    }
+
+    mw = Brute::Middleware::Summarize.new(inner)
+    tools = [:read, :search]
+    env = { messages: Brute::Session.new, tools: tools.dup, current_iteration: 1 }
+    env[:messages].user("hi")
+    mw.call(env)
+
+    env[:tools].should == tools
+  end
+
+  it "resets current_iteration for the summary call" do
+    captured_iteration = nil
+    inner = ->(env) {
+      captured_iteration = env[:current_iteration]
+      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+    }
+
+    mw = Brute::Middleware::Summarize.new(inner)
+    env = { messages: Brute::Session.new, tools: [], current_iteration: 99 }
+    env[:messages].user("hi")
+    mw.call(env)
+
+    # The second call (summary) should have iteration reset to 1
+    captured_iteration.should == 1
+  end
+
+  it "injects a summary prompt message" do
+    messages_at_second_call = nil
+    call_count = 0
+    inner = ->(env) {
+      call_count += 1
+      messages_at_second_call = env[:messages].map(&:content) if call_count == 2
+      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+    }
+
+    mw = Brute::Middleware::Summarize.new(inner)
+    env = { messages: Brute::Session.new, tools: [], current_iteration: 1 }
+    env[:messages].user("hi")
+    mw.call(env)
+
+    messages_at_second_call.last.should =~ /findings/i
+  end
+
+  it "accepts a custom prompt" do
+    messages_at_second_call = nil
+    call_count = 0
+    inner = ->(env) {
+      call_count += 1
+      messages_at_second_call = env[:messages].map(&:content) if call_count == 2
+      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+    }
+
+    mw = Brute::Middleware::Summarize.new(inner, prompt: "Give me the TL;DR.")
+    env = { messages: Brute::Session.new, tools: [], current_iteration: 1 }
+    env[:messages].user("hi")
+    mw.call(env)
+
+    messages_at_second_call.last.should == "Give me the TL;DR."
+  end
+end