brute 0.4.0 → 1.0.0

data/lib/brute/providers/ollama.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+# Ensure the Ollama provider is loaded (llm.rb lazy-loads providers).
+unless defined?(LLM::Ollama)
+  require "llm/providers/ollama"
+end
+
+module Brute
+  module Providers
+    ##
+    # Brute-level wrapper around LLM::Ollama for local model inference.
+    #
+    # Adds environment-variable-based configuration so that all Brute
+    # examples and the CLI work out of the box with a local Ollama
+    # instance:
+    #
+    #   OLLAMA_HOST  — base URL (default: http://localhost:11434)
+    #   OLLAMA_MODEL — default model (default: llm.rb's default, currently qwen3:latest)
+    #
+    # @example Auto-detect via environment
+    #   export OLLAMA_HOST=http://localhost:11434
+    #   ruby examples/01_basic_agent.rb
+    #
+    # @example Remote Ollama server
+    #   export OLLAMA_HOST=http://192.168.1.50:11434
+    #   export OLLAMA_MODEL=llama3.1:8b
+    #   ruby examples/02_fix_a_bug.rb
+    #
+    class Ollama < LLM::Ollama
+      ##
+      # Parse OLLAMA_HOST into host, port, and ssl components.
+      # Accepts formats like:
+      #   http://localhost:11434
+      #   https://ollama.example.com
+      #   192.168.1.50:11434
+      #   localhost
+      #
+      # @param url [String, nil] raw OLLAMA_HOST value
+      # @return [Hash] with :host, :port, :ssl keys
+      def self.parse_host(url)
+        return { host: LLM::Ollama::HOST, port: 11434, ssl: false } if url.nil? || url.empty?
+
+        # Prepend scheme if missing so URI.parse works
+        url = "http://#{url}" unless url.match?(%r{\A\w+://})
+        uri = URI.parse(url)
+
+        {
+          host: uri.host || LLM::Ollama::HOST,
+          port: uri.port || 11434,
+          ssl: uri.scheme == "https",
+        }
+      end
+
+      ##
+      # @param key [String] ignored (Ollama needs no auth), kept for provider interface
+      def initialize(key: "none", **)
+        config = self.class.parse_host(ENV["OLLAMA_HOST"])
+        super(key: key, host: config[:host], port: config[:port], ssl: config[:ssl], **)
+      end
+
+      ##
+      # @return [Symbol]
+      def name
+        :ollama
+      end
+
+      ##
+      # Returns the default model, preferring OLLAMA_MODEL env var.
+      # @return [String]
+      def default_model
+        ENV["OLLAMA_MODEL"] || super
+      end
+    end
+  end
+end
+
+test do
+  parse = proc { |url| Brute::Providers::Ollama.parse_host(url) }
+
+  describe ".parse_host" do
+    it "returns defaults for nil" do
+      parse.(nil).should == { host: "localhost", port: 11434, ssl: false }
+    end
+
+    it "returns defaults for empty string" do
+      parse.("").should == { host: "localhost", port: 11434, ssl: false }
+    end
+
+    it "parses http URL with port" do
+      parse.("http://192.168.1.50:11434").should == { host: "192.168.1.50", port: 11434, ssl: false }
+    end
+
+    it "parses https URL" do
+      parse.("https://ollama.example.com").should == { host: "ollama.example.com", port: 443, ssl: true }
+    end
+
+    it "parses host:port without scheme" do
+      parse.("192.168.1.50:11434").should == { host: "192.168.1.50", port: 11434, ssl: false }
+    end
+
+    it "parses bare hostname" do
+      parse.("myhost").should == { host: "myhost", port: 80, ssl: false }
+    end
+  end
+
+  describe "#name" do
+    it "returns :ollama" do
+      provider = Brute::Providers::Ollama.new
+      provider.name.should == :ollama
+    end
+  end
+
+  describe "#default_model" do
+    it "falls back to llm.rb default when OLLAMA_MODEL is not set" do
+      original = ENV["OLLAMA_MODEL"]
+      ENV.delete("OLLAMA_MODEL")
+      provider = Brute::Providers::Ollama.new
+      provider.default_model.should == "qwen3:latest"
+    ensure
+      ENV["OLLAMA_MODEL"] = original if original
+    end
+
+    it "uses OLLAMA_MODEL env var when set" do
+      original = ENV["OLLAMA_MODEL"]
+      ENV["OLLAMA_MODEL"] = "llama3.1:8b"
+      provider = Brute::Providers::Ollama.new
+      provider.default_model.should == "llama3.1:8b"
+    ensure
+      ENV["OLLAMA_MODEL"] = original
+    end
+  end
+end

data/lib/brute/providers/opencode_go.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+if __FILE__ == $0
+  require "bundler/setup"
+  require "brute"
+end
+
 module LLM
   ##
   # OpenAI-compatible provider for the OpenCode Go API gateway.

data/lib/brute/providers/opencode_zen.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+if __FILE__ == $0
+  require "bundler/setup"
+  require "brute"
+end
+
 # Ensure the OpenAI provider is loaded (llm.rb lazy-loads providers).
 unless defined?(LLM::OpenAI)
   require "llm/providers/openai"
@@ -41,10 +46,10 @@ module LLM
     end
 
     ##
-    # Returns the default model (Claude Sonnet 4, the most common Zen model).
+    # Returns the default model.
     # @return [String]
     def default_model
-      "claude-sonnet-4-20250514"
+      "zen-bickpickle"
     end
 
     ##

data/lib/brute/providers/shell.rb

@@ -15,7 +15,7 @@ module Brute
     #   nix    - nix eval --expr '...'
     #
     # The provider's #complete method returns a synthetic response
-    # containing a single "shell" tool call. The orchestrator executes
+    # containing a single "shell" tool call. The agent loop executes
     # it through the normal pipeline — all middleware (message tracking,
     # session persistence, token tracking, etc.) fires as usual.
     #
@@ -45,7 +45,7 @@ module Brute
         tools = params[:tools] || []
 
         # nil text means we received tool results (second call) —
-        # return an empty assistant response so the orchestrator exits.
+        # return an empty assistant response so the agent loop exits.
         return ShellResponse.new(model: model, tools: tools) if text.nil?
 
         wrap    = INTERPRETERS.fetch(model, INTERPRETERS["bash"])

data/lib/brute/providers/shell_response.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+if __FILE__ == $0
+  require "bundler/setup"
+  require "brute"
+end
+
 require "securerandom"
 
 module Brute
@@ -7,12 +12,12 @@ module Brute
     # Synthetic completion response returned by Brute::Providers::Shell.
     #
     # When +command+ is present, the response contains a single assistant
-    # message with a "shell" tool call. The orchestrator picks it up and
+    # message with a "shell" tool call. The agent loop picks it up and
     # executes Brute::Tools::Shell through the normal pipeline.
     #
     # When +command+ is nil (tool results round-trip), the response
     # contains an empty assistant message with no tool calls, causing
-    # the orchestrator loop to exit.
+    # the agent loop to exit.
     #
     class ShellResponse
       def initialize(command: nil, model: "bash", tools: [])

data/lib/brute/providers.rb

@@ -0,0 +1,62 @@
+require_relative 'providers/shell_response'
+require_relative 'providers/shell'
+require_relative 'providers/models_dev'
+require_relative 'providers/opencode_zen'
+require_relative 'providers/opencode_go'
+require_relative 'providers/ollama'
+
+module Brute
+  module Providers
+    ALL = {
+      'anthropic' => ->(key) { LLM.anthropic(key: key).tap { Patches::AnthropicToolRole.apply! } },
+      'openai' => ->(key) { LLM.openai(key: key) },
+      'google' => ->(key) { LLM.google(key: key) },
+      'deepseek' => ->(key) { LLM.deepseek(key: key) },
+      'ollama' => ->(_key) { Providers::Ollama.new },
+      'xai' => ->(key) { LLM.xai(key: key) },
+      'opencode_zen' => ->(key) { LLM::OpencodeZen.new(key: key) },
+      'opencode_go' => ->(key) { LLM::OpencodeGo.new(key: key) },
+      'shell' => ->(_key) { Providers::Shell.new },
+    }.freeze
+
+    # Resolve the LLM provider from environment variables.
+    #
+    # Checks in order:
+    #   1. LLM_API_KEY + LLM_PROVIDER (explicit)
+    #   2. OPENCODE_API_KEY (implicit: provider = opencode_zen)
+    #   3. ANTHROPIC_API_KEY (implicit: provider = anthropic)
+    #   4. OPENAI_API_KEY   (implicit: provider = openai)
+    #   5. GOOGLE_API_KEY   (implicit: provider = google)
+    #   6. OLLAMA_HOST      (implicit: provider = ollama, local inference)
+    #
+    # Returns nil if no key is found. Error is deferred to the caller.
+    def self.guess_from_env
+      if ENV['LLM_API_KEY']
+        key = ENV['LLM_API_KEY']
+        name = ENV.fetch('LLM_PROVIDER', 'opencode_zen').downcase
+      elsif ENV['OPENCODE_API_KEY']
+        key = ENV['OPENCODE_API_KEY']
+        name = 'opencode_zen'
+      elsif ENV['ANTHROPIC_API_KEY']
+        key = ENV['ANTHROPIC_API_KEY']
+        name = 'anthropic'
+      elsif ENV['OPENAI_API_KEY']
+        key = ENV['OPENAI_API_KEY']
+        name = 'openai'
+      elsif ENV['GOOGLE_API_KEY']
+        key = ENV['GOOGLE_API_KEY']
+        name = 'google'
+      elsif ENV['OLLAMA_HOST']
+        key = 'none'
+        name = 'ollama'
+      else
+        return nil
+      end
+
+      factory = Providers::ALL[name]
+      raise "Unknown LLM provider: #{name}. Available: #{Providers::ALL.keys.join(', ')}" unless factory
+
+      factory.call(key)
+    end
+  end
+end

data/lib/brute/queue/base_queue.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+require "async"
+require "async/queue"
+require "async/barrier"
+require "async/semaphore"
+
+module Brute
+  module Queue
+  # A queue that dequeues Step objects and runs them, honoring cancellation.
+  #
+  # Composes four async primitives:
+  #   - An inbox (Async::Queue) that holds pending steps
+  #   - A barrier (Async::Barrier) that tracks every task the queue spawns
+  #   - A semaphore (Async::Semaphore) parented to the barrier, limiting concurrency
+  #   - Workers — long-lived tasks that dequeue from the inbox and run steps
+  #
+  # The barrier-semaphore composition via parent: means every task the
+  # semaphore spawns is also tracked by the barrier. One call site
+  # (semaphore.async), two guarantees (scoped lifetime + bounded concurrency).
+  #
+  class BaseQueue
+    attr_reader :steps
+
+    def initialize(concurrency:, worker_count:, parent: Async::Task.current)
+      @steps        = []
+      @inbox        = Async::Queue.new
+      @barrier      = Async::Barrier.new(parent: parent)
+      @semaphore    = Async::Semaphore.new(concurrency, parent: @barrier)
+      @worker_count = worker_count
+      @started      = false
+    end
+
+    def <<(step)
+      @steps << step
+      @inbox.push(step)
+      self
+    end
+
+    def first = @steps.first
+    def last  = @steps.last
+
+    def start
+      return self if @started
+      @started = true
+
+      @worker_count.times do
+        @barrier.async do
+          while (step = @inbox.dequeue)
+            @semaphore.async do |task|
+              step.call(task)
+            end
+          end
+        end
+      end
+      self
+    end
+
+    # Graceful: stop accepting, wait for running work to finish.
+    def drain
+      @inbox.close
+      @barrier.wait
+    end
+
+    # Hard: close inbox, cancel pending steps, cancel running work.
+    def cancel
+      @inbox.close
+      @steps.each do |step|
+        step.cancel if step.state == :pending
+      end
+      @barrier.cancel
+    end
+  end
+  end
+end
+
+test do
+  class CountStep < Brute::Loop::Step
+    def perform(task)
+      @attributes[:counter] << @attributes[:value]
+      @attributes[:value]
+    end
+  end
+
+  class SleepStep < Brute::Loop::Step
+    def perform(task)
+      sleep(@attributes[:duration])
+      "slept"
+    end
+  end
+
+  # -- enqueue --
+
+  it "appends steps to the steps list" do
+    Sync do
+      q = Brute::Queue::BaseQueue.new(concurrency: 1, worker_count: 1)
+      q << CountStep.new(counter: [], value: 1)
+      q.steps.size.should == 1
+    end
+  end
+
+  it "returns self from <<" do
+    Sync do
+      q = Brute::Queue::BaseQueue.new(concurrency: 1, worker_count: 1)
+      (q << CountStep.new(counter: [], value: 1)).should.be.identical_to q
+    end
+  end
+
+  # -- first / last --
+
+  it "returns the first step" do
+    Sync do
+      q = Brute::Queue::BaseQueue.new(concurrency: 1, worker_count: 1)
+      s1 = CountStep.new(counter: [], value: 1)
+      s2 = CountStep.new(counter: [], value: 2)
+      q << s1 << s2
+      q.first.should.be.identical_to s1
+    end
+  end
+
+  it "returns the last step" do
+    Sync do
+      q = Brute::Queue::BaseQueue.new(concurrency: 1, worker_count: 1)
+      s1 = CountStep.new(counter: [], value: 1)
+      s2 = CountStep.new(counter: [], value: 2)
+      q << s1 << s2
+      q.last.should.be.identical_to s2
+    end
+  end
+
+  # -- start + drain --
+
+  it "runs steps to completion on drain" do
+    Sync do
+      results = []
+      q = Brute::Queue::BaseQueue.new(concurrency: 1, worker_count: 1)
+      q << CountStep.new(counter: results, value: "a")
+      q << CountStep.new(counter: results, value: "b")
+      q.start
+      q.drain
+      results.should == ["a", "b"]
+    end
+  end
+
+  it "completes all steps" do
+    Sync do
+      q = Brute::Queue::BaseQueue.new(concurrency: 1, worker_count: 1)
+      q << CountStep.new(counter: [], value: 1)
+      q << CountStep.new(counter: [], value: 2)
+      q.start
+      q.drain
+      q.steps.all? { |s| s.state == :completed }.should.be.true
+    end
+  end
+
+  it "captures results on each step" do
+    Sync do
+      q = Brute::Queue::BaseQueue.new(concurrency: 1, worker_count: 1)
+      q << CountStep.new(counter: [], value: 42)
+      q.start
+      q.drain
+      q.first.result.should == 42
+    end
+  end
+
+  it "is idempotent on start" do
+    Sync do
+      q = Brute::Queue::BaseQueue.new(concurrency: 1, worker_count: 1)
+      q << CountStep.new(counter: [], value: 1)
+      q.start
+      q.start # should not double-spawn workers
+      q.drain
+      q.steps.size.should == 1
+    end
+  end
+
+  # -- cancel --
+
+  it "marks pending steps as cancelled" do
+    Sync do
+      q = Brute::Queue::BaseQueue.new(concurrency: 1, worker_count: 1)
+      s1 = SleepStep.new(duration: 10)
+      s2 = SleepStep.new(duration: 10)
+      s3 = SleepStep.new(duration: 10)
+      q << s1 << s2 << s3
+      q.start
+      sleep 0.01 # let worker pick up s1
+      q.cancel
+      # s2 and s3 should be cancelled (they were pending)
+      [s2, s3].all? { |s| s.state == :cancelled }.should.be.true
+    end
+  end
+
+  # -- concurrent execution --
+
+  it "runs multiple steps concurrently" do
+    Sync do
+      started = []
+      done = []
+
+      steps = 3.times.map do |i|
+        Class.new(Brute::Loop::Step) do
+          define_method(:perform) do |task|
+            started << i
+            sleep 0.05
+            done << i
+            i
+          end
+        end.new
+      end
+
+      q = Brute::Queue::BaseQueue.new(concurrency: 3, worker_count: 3)
+      steps.each { |s| q << s }
+      q.start
+      q.drain
+      done.size.should == 3
+    end
+  end
+end

data/lib/brute/{file_mutation_queue.rb → queue/file_mutation_queue.rb}

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Brute
+  module Queue
   # Per-file serialization queue for concurrent tool execution.
   #
   # When tools run in parallel (via threads or async fibers), multiple tools
@@ -62,38 +63,39 @@ module Brute
 
       private
 
-      # Resolve a file path to a canonical key.
-      # Uses File.realpath to follow symlinks so that aliases to the
-      # same underlying file share one mutex. Falls back to
-      # File.expand_path for files that don't exist yet (e.g., new writes).
-      def canonical_path(path)
-        resolved = File.expand_path(path)
-        begin
-          File.realpath(resolved)
-        rescue Errno::ENOENT
-          resolved
+        # Resolve a file path to a canonical key.
+        # Uses File.realpath to follow symlinks so that aliases to the
+        # same underlying file share one mutex. Falls back to
+        # File.expand_path for files that don't exist yet (e.g., new writes).
+        def canonical_path(path)
+          resolved = File.expand_path(path)
+          begin
+            File.realpath(resolved)
+          rescue Errno::ENOENT
+            resolved
+          end
         end
-      end
 
-      # Get (or create) a mutex for a file path and increment the waiter count.
-      def acquire_mutex(key)
-        @guard.synchronize do
-          @mutexes[key] ||= Mutex.new
-          @waiters[key] += 1
-          @mutexes[key]
+        # Get (or create) a mutex for a file path and increment the waiter count.
+        def acquire_mutex(key)
+          @guard.synchronize do
+            @mutexes[key] ||= Mutex.new
+            @waiters[key] += 1
+            @mutexes[key]
+          end
         end
-      end
 
-      # Decrement the waiter count and clean up the mutex if no one else needs it.
-      def release_mutex(key)
-        @guard.synchronize do
-          @waiters[key] -= 1
-          if @waiters[key] <= 0
-            @mutexes.delete(key)
-            @waiters.delete(key)
+        # Decrement the waiter count and clean up the mutex if no one else needs it.
+        def release_mutex(key)
+          @guard.synchronize do
+            @waiters[key] -= 1
+            if @waiters[key] <= 0
+              @mutexes.delete(key)
+              @waiters.delete(key)
+            end
           end
         end
-      end
     end
   end
+  end
 end

data/lib/brute/queue/parallel_queue.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Queue
+  # A queue that processes steps concurrently up to a limit.
+  # Workers match concurrency slots.
+  class ParallelQueue < BaseQueue
+    def initialize(concurrency: 4, parent: Async::Task.current)
+      super(concurrency: concurrency, worker_count: concurrency, parent: parent)
+    end
+  end
+  end
+end
+
+test do
+  it "runs steps concurrently" do
+    Sync do
+      concurrent = 0
+      max_concurrent = 0
+
+      steps = 4.times.map do
+        Class.new(Brute::Loop::Step) do
+          define_method(:perform) do |task|
+            concurrent += 1
+            max_concurrent = [max_concurrent, concurrent].max
+            sleep 0.05
+            concurrent -= 1
+          end
+        end.new
+      end
+
+      q = Brute::Queue::ParallelQueue.new(concurrency: 4)
+      steps.each { |s| q << s }
+      q.start
+      q.drain
+      (max_concurrent > 1).should.be.true
+    end
+  end
+
+  it "limits concurrency to the specified amount" do
+    Sync do
+      concurrent = 0
+      max_concurrent = 0
+
+      steps = 8.times.map do
+        Class.new(Brute::Loop::Step) do
+          define_method(:perform) do |task|
+            concurrent += 1
+            max_concurrent = [max_concurrent, concurrent].max
+            sleep 0.05
+            concurrent -= 1
+          end
+        end.new
+      end
+
+      q = Brute::Queue::ParallelQueue.new(concurrency: 2)
+      steps.each { |s| q << s }
+      q.start
+      q.drain
+      (max_concurrent <= 2).should.be.true
+    end
+  end
+end

data/lib/brute/queue/sequential_queue.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Queue
+  # A queue that processes steps one at a time, in order.
+  # One worker, one concurrency slot.
+  class SequentialQueue < BaseQueue
+    def initialize(parent: Async::Task.current)
+      super(concurrency: 1, worker_count: 1, parent: parent)
+    end
+  end
+  end
+end
+
+test do
+  class OrderStep < Brute::Loop::Step
+    def perform(task)
+      @attributes[:log] << @attributes[:value]
+      sleep(@attributes[:delay]) if @attributes[:delay]
+      @attributes[:value]
+    end
+  end
+
+  it "processes steps in order" do
+    Sync do
+      log = []
+      q = Brute::Queue::SequentialQueue.new
+      q << OrderStep.new(log: log, value: "a", delay: 0.01)
+      q << OrderStep.new(log: log, value: "b", delay: 0.01)
+      q << OrderStep.new(log: log, value: "c", delay: 0.01)
+      q.start
+      q.drain
+      log.should == ["a", "b", "c"]
+    end
+  end
+
+  it "runs only one step at a time" do
+    Sync do
+      concurrent = 0
+      max_concurrent = 0
+
+      steps = 3.times.map do
+        Class.new(Brute::Loop::Step) do
+          define_method(:perform) do |task|
+            concurrent += 1
+            max_concurrent = [max_concurrent, concurrent].max
+            sleep 0.02
+            concurrent -= 1
+          end
+        end.new
+      end
+
+      q = Brute::Queue::SequentialQueue.new
+      steps.each { |s| q << s }
+      q.start
+      q.drain
+      max_concurrent.should == 1
+    end
+  end
+end