brute 4.3.1 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8264f0e2d23e001a3c980d3edd0f88ac3ceb8a3f167359c56391e3fe9702e59
-  data.tar.gz: 7439466f57b0f3e18aae290a723f8cb4077970b200f1a8e0f7970fd7d863aee6
+  metadata.gz: b9b592266887d7f4099f89d132ae3fb0af1b7b360f8b4a819c10b300b8e0484e
+  data.tar.gz: d761c4ab24c37596acf52235e5e640177ec4b4d6ba528c5c9c0936452fdffc88
 SHA512:
-  metadata.gz: 5fa71cbfe00b6069e2bdb90872cff9fe2f88eb2f48c7ff614feb59ead8f03890739c4772c863b09edf27fd7c2c122ac486fc5c3d84f582f477527f5f69d2dee4
-  data.tar.gz: 866794dc4f87f5433508b1e883db27788b00bb57157211ea2942fe64ccaa46969c3cfdd36fe917b9717fe7bdc385f4fd9881b1a5ce47c9763e859d7e00fbf356
+  metadata.gz: 98083c184fcea3e2213fe6b244a151aabdb4d136ef11bd130d35ecf4a07881925b961df267e75de5574927b5e8cf18c2fda9f9fea1ec10e57740c76e8c0a2c23
+  data.tar.gz: 41f4df4d86383fb6eb3cddaeb4d64e27dd37f3bccd09e5e80d2f5b98eaac7f1b7df886c16cb77a714b8d1888becf3cca5495723d8a6e9539771b36623bb413c0

data/lib/brute/completion/async_faraday.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Completion
+    # Faraday's own default adapter is Net::HTTP, which works under Async but
+    # opens a fresh connection for every request. Provider gems build their
+    # own Faraday connections and give no seam to configure them, so the
+    # adapter is swapped at the only place it can be: Faraday's default.
+    #
+    # Called by each completion whose provider gem rides on Faraday, after
+    # that gem is required — so it only fires when Faraday is genuinely in
+    # play, and an app that uses a completion which doesn't (llm.rb speaks
+    # Net::HTTP directly) never loads any of it.
+    def self.async_faraday!
+      return false unless defined?(::Faraday)
+
+      require "async/http/faraday/default"
+      true
+    end
+  end
+end
+
+__END__
+
+describe "brute/completion/async_faraday" do
+  it "points Faraday's default adapter at async-http, and does nothing without Faraday" do
+    require "faraday"
+    Brute::Completion.async_faraday!.should.be.true
+    ::Faraday.default_adapter.should == :async_http
+
+    # Idempotent: a second completion constructing does not undo the first.
+    Brute::Completion.async_faraday!.should.be.true
+    ::Faraday.default_adapter.should == :async_http
+  end
+end

data/lib/brute/completion/lang_chain.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/hooks"
+
+module Brute
+  module Completion
+    # Completion backed by the langchainrb gem
+    # (https://github.com/patterns-ai-core/langchainrb). Its LLM classes wrap
+    # many providers; build one and hand it over:
+    #
+    #   Brute.agent
+    #     .use(Brute::Middleware::SystemPrompt)
+    #     .run(Brute::Completion::LangChain.new(
+    #       llm: Langchain::LLM::OpenAI.new(api_key: ENV["OPENAI_API_KEY"]),
+    #     ))
+    #
+    #   llm:         a Langchain::LLM instance (required; client: is an alias)
+    #   model:       model id override (falls back to env[:model], then the
+    #                llm instance's own default)
+    #   tools:       tools list, any shape Tools::Adapter accepts
+    #   temperature: sampling temperature (default 0.7)
+    class LangChain
+      include Brute::Hooks
+
+      DEFAULT_TEMPERATURE = 0.7
+
+      def initialize(llm: nil, client: nil, **options)
+        # Brute depends on no LLM library: the provider gem is required here,
+        # at point of use, and only for this completion.
+        begin
+          require "langchain"
+        rescue LoadError
+          raise LoadError, "#{self.class} needs the 'langchainrb' gem — add `gem \"langchainrb\"` to your Gemfile."
+        end
+
+        Brute::Completion.async_faraday!
+
+        @llm = llm || client or
+          raise ArgumentError, "#{self.class} needs an llm: option, e.g. Langchain::LLM::OpenAI.new(api_key: ...)"
+
+        @options = options
+      end
+
+      def call(env)
+        emit(BEFORE_LLM_EVENT, env)
+
+        response = nil
+        emit(LLM_DURATION_EVENT, env) { response = @llm.chat(**params(env)) }
+
+        if (usage = Brute::MessageTransport::LangChain.usage_metrics(response))
+          (env[:metadata] ||= {})[:last_llm_usage] = usage
+        end
+
+        # langchainrb speaks the OpenAI-style wire format both ways.
+        Brute::MessageTransport::LangChain.wrap_each(reply(response)) do |message|
+          env[:messages] << message
+        end
+
+        emit(AFTER_LLM_EVENT, env)
+        env
+      rescue => error
+        emit(LLM_FAILURE_EVENT, env)
+
+        if defined?(::Faraday::Error) && error.is_a?(::Faraday::Error)
+          emit(FARADAY_ERROR_EVENT, env, error)
+        else
+          emit(STANDARD_ERROR_EVENT, env, error)
+        end
+
+        env
+      end
+
+      private
+
+        attr_reader :options
+
+        def params(env)
+          params = {
+            messages:    Brute::MessageTransport::LangChain.dump_all(env[:messages]),
+            temperature: temperature(env),
+          }
+
+          tools = tool_definitions(env)
+          params[:tools] = tools if tools.any?
+
+          model = option(env, :model)
+          params[:model] = model if model
+
+          params
+        end
+
+        def reply(response)
+          {
+            "role"       => "assistant",
+            "content"    => response.chat_completion,
+            "tool_calls" => Array(response.tool_calls),
+          }
+        end
+
+        def tool_definitions(env)
+          Brute::Tools::Adapter.wrap_all(option(env, :tools) || []).values.map do |adapter|
+            { type: "function", function: adapter.to_h }
+          end
+        end
+
+        def option(env, key) = options.fetch(key) { env[key] }
+
+        def temperature(env) = options.fetch(:temperature) { env.fetch(:temperature, DEFAULT_TEMPERATURE) }
+    end
+  end
+end
+
+__END__
+
+describe "brute/completion/lang_chain" do
+  require "brute/messages"
+
+  # langchainrb's own suite fakes the LLM with `receive(:chat)` returning a
+  # response that answers chat_completion / tool_calls; this is that shape.
+  FakeLangChainResponse = Struct.new(:chat_completion, :tool_calls) unless defined?(FakeLangChainResponse)
+
+  FakeLangChainLLM = Class.new do
+    attr_reader :calls
+
+    def initialize(response)
+      @response = response
+      @calls = []
+    end
+
+    def chat(**params)
+      @calls << params
+      @response
+    end
+  end unless defined?(FakeLangChainLLM)
+
+  it "sends the log as OpenAI-style messages and appends the reply, tool calls included" do
+    response = FakeLangChainResponse.new("via langchain", [])
+    llm = FakeLangChainLLM.new(response)
+
+    env = { messages: Brute.log, tools: [], events: [] }
+    env[:messages].user("hi")
+
+    seen = []
+    pipeline = Brute::Turn::Pipeline.new
+    pipeline.run Brute::Completion::LangChain.new(llm: llm, model: "gpt-4o-mini")
+    pipeline.on(Brute::Hooks::BEFORE_LLM_EVENT) { |_env| seen << :before }
+    pipeline.on(Brute::Hooks::AFTER_LLM_EVENT) { |_env| seen << :after }
+    pipeline.call(env)
+
+    env[:messages].last.role.should == :assistant
+    env[:messages].last.content.should == "via langchain"
+    seen.should == [:before, :after]
+
+    llm.calls.first[:model].should == "gpt-4o-mini"
+    llm.calls.first[:temperature].should == 0.7
+    llm.calls.first[:messages].first[:role].should == "user"
+
+    # A tool call comes back in the OpenAI shape and lands as a ToolCall.
+    calling = FakeLangChainLLM.new(FakeLangChainResponse.new(nil, [
+      { "id" => "tc1", "type" => "function", "function" => { "name" => "echo", "arguments" => { "text" => "hi" } } },
+    ]))
+    tool_env = { messages: Brute.log, tools: [], events: [] }
+    tool_env[:messages].user("call it")
+    Brute::Turn::Pipeline.new.tap { |p| p.run Brute::Completion::LangChain.new(llm: calling) }.call(tool_env)
+    tool_env[:messages].last.tool_calls.first.name.should == "echo"
+
+    # A raising provider is reported through the hooks, not up the stack.
+    boom = Object.new
+    boom.define_singleton_method(:chat) { |**_params| raise "no route to host" }
+    failed = []
+    failing = Brute::Turn::Pipeline.new
+    failing.run Brute::Completion::LangChain.new(llm: boom)
+    failing.on(Brute::Hooks::STANDARD_ERROR_EVENT) { |_env, error| failed << error.message }
+
+    error_env = { messages: Brute.log, tools: [], events: [] }
+    error_env[:messages].user("hi")
+    failing.call(error_env)
+    failed.should == ["no route to host"]
+
+    # An llm is not optional.
+    should.raise(ArgumentError) { Brute::Completion::LangChain.new }
+  end
+end

data/lib/brute/completion/llmrb.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/hooks"
+
+module Brute
+  module Completion
+    # Completion backed by the llm.rb gem (https://github.com/llmrb/llm.rb).
+    #
+    #   Brute.agent
+    #     .use(Brute::Middleware::SystemPrompt)
+    #     .run(Brute::Completion::LLMrb.new(
+    #       provider:         :openai,
+    #       provider_options: { key: ENV["OPENAI_API_KEY"] },
+    #       model:            "gpt-4o-mini",
+    #     ))
+    #
+    #   # or hand over a provider llm.rb has already built:
+    #   run Brute::Completion::LLMrb.new(client: LLM.ollama(key: nil), model: "llama3.2:latest")
+    #
+    #   client:           an LLM::Provider instance (takes precedence)
+    #   provider:         llm.rb constructor name (:openai, :anthropic,
+    #                     :ollama, ...); falls back to env[:provider]
+    #   provider_options: kwargs for that constructor, e.g. { key: "..." }
+    #   model:            model id (falls back to env[:model])
+    #   tools:            tools list, any shape Tools::Adapter accepts
+    #   temperature:      sampling temperature (default 0.7)
+    class LLMrb
+      include Brute::Hooks
+
+      DEFAULT_TEMPERATURE = 0.7
+
+      def initialize(**options)
+        # Brute depends on no LLM library: the provider gem is required here,
+        # at point of use, and only for this completion.
+        begin
+          require "llm"
+        rescue LoadError
+          raise LoadError, "#{self.class} needs the 'llm.rb' gem — add `gem \"llm.rb\"` to your Gemfile."
+        end
+
+        @options = options
+      end
+
+      def call(env)
+        emit(BEFORE_LLM_EVENT, env)
+
+        # llm.rb takes the last message as the prompt and the rest as history.
+        messages = Brute::MessageTransport::LLM.dump_all(env[:messages])
+        prompt = messages.pop
+
+        response = nil
+        emit(LLM_DURATION_EVENT, env) { response = client(env).complete(prompt, **params(env, messages)) }
+
+        if (usage = Brute::MessageTransport::LLM.usage_metrics(response))
+          (env[:metadata] ||= {})[:last_llm_usage] = usage
+        end
+
+        Brute::MessageTransport::LLM.wrap_each(response) do |message|
+          env[:messages] << message
+        end
+
+        emit(AFTER_LLM_EVENT, env)
+        env
+      rescue => error
+        emit(LLM_FAILURE_EVENT, env)
+
+        if defined?(::Faraday::Error) && error.is_a?(::Faraday::Error)
+          emit(FARADAY_ERROR_EVENT, env, error)
+        else
+          emit(STANDARD_ERROR_EVENT, env, error)
+        end
+
+        env
+      end
+
+      private
+
+        attr_reader :options
+
+        def params(env, history)
+          params = {
+            role:        nil,
+            model:       option(env, :model),
+            messages:    history,
+            temperature: temperature(env),
+          }.compact
+
+          functions = functions(env)
+          params[:tools] = functions if functions.any?
+          params
+        end
+
+        def client(env)
+          options[:client] || begin
+            provider = option(env, :provider) or
+              raise ArgumentError, "#{self.class} needs a client: or provider: option"
+
+            ::LLM.public_send(provider, **(options[:provider_options] || {}))
+          end
+        end
+
+        # Brute tools as llm.rb functions, executed by llm.rb's own dispatch.
+        def functions(env)
+          Brute::Tools::Adapter.wrap_all(option(env, :tools) || []).values.map do |adapter|
+            schema = adapter.to_h[:parameters]
+
+            ::LLM.function(adapter.name) do |fn|
+              fn.description adapter.description
+              fn.params { schema }
+              fn.define { |**args| adapter.call(args) }
+            end
+          end
+        end
+
+        def option(env, key) = options.fetch(key) { env[key] }
+
+        def temperature(env) = options.fetch(:temperature) { env.fetch(:temperature, DEFAULT_TEMPERATURE) }
+    end
+  end
+end
+
+__END__
+
+describe "brute/completion/llmrb" do
+  require "brute/messages"
+
+  # llm.rb's own suite drives a real provider and stubs the HTTP; the seam it
+  # leaves for a caller is the provider object's #complete, which is what a
+  # client: option replaces.
+  FakeLLMrbClient = Class.new do
+    attr_reader :calls
+
+    def initialize(content = "via llm.rb")
+      @content = content
+      @calls = []
+    end
+
+    def complete(prompt, **params)
+      @calls << { prompt: prompt, params: params }
+      ::LLM::Message.new(:assistant, @content)
+    end
+  end unless defined?(FakeLLMrbClient)
+
+  it "sends the last message as the prompt, the rest as history, and appends the reply" do
+    client = FakeLLMrbClient.new("hello from llm.rb")
+
+    env = { messages: Brute.log, provider: :stub, model: "env-model", tools: [], events: [] }
+    env[:messages].user("first")
+    env[:messages] << Brute::Message.new(role: :assistant, content: "earlier")
+    env[:messages].user("latest")
+
+    seen = []
+    pipeline = Brute::Turn::Pipeline.new
+    pipeline.run Brute::Completion::LLMrb.new(client: client, temperature: 0.1)
+    pipeline.on(Brute::Hooks::BEFORE_LLM_EVENT) { |_env| seen << :before }
+    pipeline.on(Brute::Hooks::AFTER_LLM_EVENT) { |_env| seen << :after }
+    pipeline.call(env)
+
+    env[:messages].last.role.should == :assistant
+    env[:messages].last.content.should == "hello from llm.rb"
+    seen.should == [:before, :after]
+
+    call = client.calls.first
+    call[:prompt].content.should == "latest"
+    call[:params][:messages].size.should == 2
+    call[:params][:temperature].should == 0.1
+    call[:params][:model].should == "env-model" # falls back to env
+
+    # Without a client, a provider is required to build one.
+    no_provider = Brute::Turn::Pipeline.new
+    no_provider.run Brute::Completion::LLMrb.new
+    failed = []
+    no_provider.on(Brute::Hooks::STANDARD_ERROR_EVENT) { |_env, error| failed << error.class }
+
+    bare = { messages: Brute.log, tools: [], events: [] }
+    bare[:messages].user("hi")
+    no_provider.call(bare)
+    failed.should == [ArgumentError]
+  end
+end

data/lib/brute/completion/open_router.rb

@@ -13,30 +13,45 @@ module Brute
   # its own provider, and only when you use it.
   module Completion
     class OpenRouter
+      include Brute::Hooks
+
       # config:   keyword arguments for OpenRouter::Client.new
       #           (access_token:, request_timeout:, uri_base:, extra_headers:).
       #           Defaults to OpenRouter.configuration's global settings.
       # options:  keyword arguments for OpenRouter::CompletionOptions.new
       #           (model:, temperature:, tools:, ...).
-      def initialize(app, config: {}, **options)
-        @app = app
+      def initialize(config: {}, **options)
+        # Brute depends on no LLM library: the provider gem is required here,
+        # at point of use, and only for this completion.
+        begin
+          require "open_router"
+        rescue LoadError
+          raise LoadError, "#{self.class} needs the 'open_router_enhanced' gem — add `gem \"open_router_enhanced\"` to your Gemfile."
+        end
+
+        Brute::Completion.async_faraday!
+
         @config = config
         @options = ::OpenRouter::CompletionOptions.new(**options)
       end
 
       def call(env)
-        env[:hooks]&.emit(:before_llm, env)
+        emit(BEFORE_LLM_EVENT, env)
 
         messages = Brute::MessageTransport::OpenRouter.dump_all(env[:messages])
 
         ::OpenRouter::Client.new(**@config).then do |client|
-          client.complete(messages, @options).then do |response|
+          response = nil
+          emit(LLM_DURATION_EVENT, env) { response = client.complete(messages, @options) }
+
+          response.then do |response|
 
             # Expose the provider's usage for downstream accounting
-            # middleware (goal budgets, autonomous limits, compaction
-            # thresholds, usage attribution) — additive metadata only.
-            if response.respond_to?(:usage) && response.usage
-              (env[:metadata] ||= {})[:last_llm_usage] = response.usage
+            # (goal budgets, autonomous limits, compaction thresholds, usage
+            # attribution) — additive metadata only, normalised so a reader
+            # does not have to know which provider answered.
+            if (usage = Brute::MessageTransport::OpenRouter.usage_metrics(response))
+              (env[:metadata] ||= {})[:last_llm_usage] = usage
             end
 
             # OpenRouter in fact only returns a single message...
@@ -47,23 +62,23 @@ module Brute
           end
         end
 
-        env[:hooks]&.emit(:after_llm, env)
+        emit(AFTER_LLM_EVENT, env)
         env
       # A provider call that raises is reported through the hooks rather than
       # up the stack: :llm_failure with the turn env, then one hook naming the
       # kind of failure. The classes are looked up defensively — the provider
       # gem is only a dependency of the app that uses this middleware.
       rescue => error
-        env[:hooks]&.emit(:llm_failure, env)
+        emit(LLM_FAILURE_EVENT, env)
 
         if defined?(::Faraday::Error) && error.is_a?(::Faraday::Error)
-          env[:hooks]&.emit(:faraday_error, error)
+          emit(FARADAY_ERROR_EVENT, env, error)
 
         elsif defined?(::OpenRouter::ServerError) && error.is_a?(::OpenRouter::ServerError)
-          env[:hooks]&.emit(:open_router_server_error, error)
+          emit(OPEN_ROUTER_SERVER_ERROR_EVENT, env, error)
 
         else
-          env[:hooks]&.emit(:standard_error, error)
+          emit(STANDARD_ERROR_EVENT, env, error)
 
         end
 
@@ -78,25 +93,23 @@ __END__
 describe "brute/completion/open_router" do
   require "brute/messages"
 
-  # The repo suite has no open_router gem; stub the two constants the
-  # middleware touches (the transport wraps duck-typed responses fine).
-  begin
-    require "open_router"
-  rescue LoadError
-    module OpenRouter
-      CompletionOptions = Class.new { def initialize(**_opts); end }
-      Client = Class.new
-    end
-  end
-
   FakeUsageResponse = Struct.new(:usage) do
     def choices
       [{ "message" => { "role" => "assistant", "content" => "hello" } }]
     end
   end unless defined?(FakeUsageResponse)
 
+  # A completion only gets its emit from the pipeline that runs it, so every
+  # turn here goes through a builder rather than calling the object directly.
+  running = lambda do |completion, &block|
+    pipeline = Brute::Turn::Pipeline.new
+    pipeline.run completion
+    block&.call(pipeline)
+    pipeline
+  end
+
   # Run one turn against a stubbed OpenRouter::Client and hand back the env.
-  with_fake_client = lambda do |middleware, response|
+  with_fake_client = lambda do |completion, response|
     fake_client = Object.new
     fake_client.define_singleton_method(:complete) { |_messages, _options| response }
     original = OpenRouter::Client.method(:new)
@@ -104,7 +117,7 @@ describe "brute/completion/open_router" do
     begin
       env = { messages: Brute.log }
       env[:messages].user("hi")
-      middleware.call(env)
+      running.call(completion).call(env)
       env
     ensure
       OpenRouter::Client.define_singleton_method(:new, original)
@@ -113,24 +126,23 @@ describe "brute/completion/open_router" do
 
   it "records the provider usage into env metadata and appends the message" do
     response = FakeUsageResponse.new({ "prompt_tokens" => 10, "completion_tokens" => 5, "total_tokens" => 15 })
-    env = with_fake_client.call(Brute::Completion::OpenRouter.new(->(e) { e }), response)
+    env = with_fake_client.call(Brute::Completion::OpenRouter.new, response)
 
     env[:messages].last.role.should == :assistant
-    env[:metadata][:last_llm_usage]["total_tokens"].should == 15
+    # Normalised, not the provider's raw hash.
+    env[:metadata][:last_llm_usage].total.should == 15
+    env[:metadata][:last_llm_usage].input.should == 10
+    env[:metadata][:last_llm_usage].output.should == 5
   end
 
   it "leaves metadata alone when the response has no usage" do
-    env = with_fake_client.call(Brute::Completion::OpenRouter.new(->(e) { e }), FakeUsageResponse.new(nil))
+    env = with_fake_client.call(Brute::Completion::OpenRouter.new, FakeUsageResponse.new(nil))
 
     env.key?(:metadata).should.be.false
   end
 
   it "reports a failed provider call through the hooks instead of raising" do
     seen = []
-    hooks = Brute::Hooks.new
-    %i[llm_failure standard_error after_llm].each do |event|
-      hooks.on(event) { |payload| seen << [event, payload] }
-    end
 
     boom = RuntimeError.new("no route to host")
     fake_client = Object.new
@@ -139,24 +151,23 @@ describe "brute/completion/open_router" do
     OpenRouter::Client.define_singleton_method(:new) { |**_config| fake_client }
 
     begin
-      env = { messages: Brute.log, hooks: hooks }
+      env = { messages: Brute.log }
       env[:messages].user("hi")
-      returned = Brute::Completion::OpenRouter.new(->(e) { e }).call(env)
+      pipeline = Brute::Turn::Pipeline.new
+      pipeline.run Brute::Completion::OpenRouter.new
+      %i[llm_failure standard_error after_llm].each do |event|
+        pipeline.on(event) { |hook_env, extra| seen << [event, hook_env, extra] }
+      end
+      returned = pipeline.call(env)
 
       returned.should.be.identical_to env
       seen.map(&:first).should == [:llm_failure, :standard_error]
-      seen.first.last.should.be.identical_to env
-      seen.last.last.should.be.identical_to boom
+      seen.first[1].should.be.identical_to env
+      seen.last[1].should.be.identical_to env
+      seen.last[2].should.be.identical_to boom
     ensure
       OpenRouter::Client.define_singleton_method(:new, original)
     end
   end
 
-  it "still answers to the deprecated Middleware::OpenRouter::Completion name" do
-    deprecated = Brute::Middleware::OpenRouter::Completion.new(->(e) { e })
-    deprecated.should.be.kind_of?(Brute::Completion::OpenRouter)
-
-    env = with_fake_client.call(deprecated, FakeUsageResponse.new(nil))
-    env[:messages].last.content.should == "hello"
-  end
 end