ruby-pi 0.1.0

data/lib/ruby_pi/agent/events.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/agent/events.rb
+#
+# Defines the canonical set of agent lifecycle event types and the EventEmitter
+# mixin that provides publish/subscribe functionality. Any class that includes
+# EventEmitter gains the ability to register event handlers with `on`, fire them
+# with `emit`, and remove them with `off`. The Agent::Core class uses this to
+# broadcast progress events (text deltas, tool execution, errors) to subscribers.
+
+module RubyPi
+  module Agent
+    # Canonical event types emitted during the agent lifecycle. Each symbol
+    # represents a specific moment or occurrence:
+    #
+    # - :text_delta           — An incremental text chunk from the LLM stream.
+    # - :tool_execution_start — A tool is about to be executed.
+    # - :tool_execution_end   — A tool has finished executing.
+    # - :turn_start           — A new think-act-observe cycle is beginning.
+    # - :turn_end             — A think-act-observe cycle has completed.
+    # - :agent_end            — The agent has finished its run (final event).
+    # - :error                — A recoverable or fatal error occurred.
+    # - :compaction           — Context compaction was triggered.
+    EVENTS = %i[
+      text_delta
+      tool_execution_start
+      tool_execution_end
+      turn_start
+      turn_end
+      agent_end
+      error
+      compaction
+    ].freeze
+
+    # Mixin that adds event subscription and emission to any class. Include
+    # this module and call `on`, `emit`, and `off` to wire up event-driven
+    # communication between components.
+    #
+    # @example Using EventEmitter in a class
+    #   class MyService
+    #     include RubyPi::Agent::EventEmitter
+    #   end
+    #
+    #   svc = MyService.new
+    #   svc.on(:text_delta) { |data| puts data[:content] }
+    #   svc.emit(:text_delta, content: "Hello")
+    module EventEmitter
+      # Subscribes a handler block to a specific event type. The block will
+      # be called every time `emit` fires for that event. Multiple handlers
+      # can be registered for the same event — they are invoked in the order
+      # they were registered.
+      #
+      # @param event [Symbol] the event type to subscribe to (must be in EVENTS)
+      # @param block [Proc] the handler to invoke when the event fires
+      # @return [Proc] the registered handler block, for later removal via `off`
+      # @raise [ArgumentError] if the event type is not in EVENTS
+      def on(event, &block)
+        validate_event!(event)
+        event_handlers[event] << block
+        block
+      end
+
+      # Fires all handlers registered for the given event type. Each handler
+      # receives the `data` hash as its argument. Handlers that raise are
+      # rescued individually — one failing handler does not prevent others
+      # from executing.
+      #
+      # @param event [Symbol] the event type to fire
+      # @param data [Hash] arbitrary payload passed to each handler
+      # @return [void]
+      def emit(event, data = {})
+        validate_event!(event)
+        event_handlers[event].each do |handler|
+          handler.call(data)
+        rescue StandardError => e
+          # Log but do not propagate handler errors — they should not break
+          # the agent loop. Emit an :error event if this is not already an
+          # error event (to prevent infinite recursion).
+          if event != :error
+            emit(:error, error: e, source: :event_handler, event: event)
+          end
+        end
+      end
+
+      # Removes a specific handler from an event's subscriber list. If the
+      # handler is not found, this is a no-op. Pass the same block reference
+      # that was given to `on`.
+      #
+      # @param event [Symbol] the event type to unsubscribe from
+      # @param block [Proc] the handler to remove
+      # @return [Proc, nil] the removed handler, or nil if not found
+      def off(event, &block)
+        validate_event!(event)
+        event_handlers[event].delete(block)
+      end
+
+      private
+
+      # Returns (and lazily initializes) the internal handler registry.
+      # Each event type maps to an array of callable handler blocks.
+      #
+      # @return [Hash{Symbol => Array<Proc>}] handlers keyed by event type
+      def event_handlers
+        @event_handlers ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # Validates that the given event symbol is a recognized event type.
+      #
+      # @param event [Symbol] the event type to validate
+      # @raise [ArgumentError] if the event is not in EVENTS
+      def validate_event!(event)
+        return if EVENTS.include?(event)
+
+        raise ArgumentError,
+              "Unknown event type: #{event.inspect}. " \
+              "Must be one of: #{EVENTS.join(', ')}"
+      end
+    end
+  end
+end

data/lib/ruby_pi/agent/loop.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/agent/loop.rb
+#
+# RubyPi::Agent::Loop — Implements the think-act-observe agentic cycle.
+#
+# The Loop drives the core agent behavior: calling the LLM (think), executing
+# any tool calls (act), feeding results back into the conversation (observe),
+# and repeating until the LLM signals completion or the max iteration limit
+# is reached. It handles streaming, lifecycle events, compaction, and all
+# pre/post tool call hooks.
+
+module RubyPi
+  module Agent
+    # Executes the think-act-observe cycle against a given State, emitting
+    # events through the provided EventEmitter-compatible emitter. Returns
+    # an Agent::Result when the cycle terminates.
+    #
+    # The cycle:
+    #   1. THINK — Call the LLM with current messages and tools. Apply
+    #      transform_context if present. Emit :turn_start and stream
+    #      :text_delta events.
+    #   2. ACT — If the LLM returned tool calls, execute them via
+    #      Tools::Executor. Fire before_tool_call / after_tool_call hooks
+    #      and emit :tool_execution_start / :tool_execution_end events.
+    #   3. OBSERVE — Append tool results to messages and loop back to THINK.
+    #   4. DONE — Return when finish_reason == "stop" (no more tool calls)
+    #      or max_iterations is reached.
+    #
+    # @example Running the loop directly
+    #   loop = RubyPi::Agent::Loop.new(state: state, emitter: agent)
+    #   result = loop.run
+    class Loop
+      # Creates a new Loop bound to the given state and event emitter.
+      #
+      # @param state [RubyPi::Agent::State] mutable agent state
+      # @param emitter [#emit] object that responds to `emit(event, data)`
+      # @param compaction [RubyPi::Context::Compaction, nil] optional compaction
+      #   strategy for managing context window size
+      def initialize(state:, emitter:, compaction: nil)
+        @state = state
+        @emitter = emitter
+        @compaction = compaction
+        @tool_calls_made = []
+        @total_usage = { input_tokens: 0, output_tokens: 0 }
+      end
+
+      # Runs the think-act-observe cycle until completion or max iterations.
+      # Returns an Agent::Result capturing the final content, messages, tool
+      # calls, usage, and turn count.
+      #
+      # @return [RubyPi::Agent::Result] the outcome of the agent run
+      def run
+        loop do
+          # Check iteration limit before starting a new turn
+          if @state.max_iterations_reached?
+            return build_result(content: last_assistant_content)
+          end
+
+          # Apply context compaction if configured and needed
+          compact_if_needed!
+
+          # THINK: Call the LLM
+          response = think
+
+          # Track usage from this turn
+          accumulate_usage(response.usage)
+
+          # Increment iteration counter
+          @state.increment_iteration!
+
+          if response.tool_calls?
+            # ACT: Execute tool calls
+            act(response)
+
+            # OBSERVE: Tool results have been added to messages; loop continues
+            @emitter.emit(:turn_end, turn: @state.iteration, has_tool_calls: true)
+          else
+            # No tool calls — the LLM is done
+            @emitter.emit(:turn_end, turn: @state.iteration, has_tool_calls: false)
+            return build_result(content: response.content)
+          end
+        end
+      rescue StandardError => e
+        @emitter.emit(:error, error: e, source: :agent_loop)
+        Result.new(
+          content: nil,
+          messages: @state.messages,
+          tool_calls_made: @tool_calls_made,
+          usage: @total_usage,
+          turns: @state.iteration,
+          error: e
+        )
+      end
+
+      private
+
+      # THINK phase: applies transforms, calls the LLM, and streams text
+      # deltas back through the emitter.
+      #
+      # @return [RubyPi::LLM::Response] the LLM response
+      def think
+        # Apply transform_context hook before the LLM call
+        @state.transform_context&.call(@state)
+
+        @emitter.emit(:turn_start, turn: @state.iteration + 1)
+
+        # Build the messages array for the LLM call, prepending the system prompt
+        messages = build_llm_messages
+
+        # Build tools array for the LLM
+        tools = build_tools_array
+
+        # Accumulate streamed content
+        streamed_content = +""
+
+        # Call the LLM with streaming
+        response = @state.model.complete(
+          messages: messages,
+          tools: tools,
+          stream: true
+        ) do |event|
+          if event.text_delta?
+            streamed_content << event.data.to_s
+            @emitter.emit(:text_delta, content: event.data)
+          end
+        end
+
+        # Add the assistant's response to conversation history
+        assistant_message = { role: :assistant, content: response.content }
+        if response.tool_calls?
+          assistant_message[:tool_calls] = response.tool_calls.map(&:to_h)
+        end
+        @state.add_message(**assistant_message)
+
+        response
+      end
+
+      # ACT phase: executes each tool call from the LLM response, firing
+      # lifecycle hooks and events around each execution.
+      #
+      # @param response [RubyPi::LLM::Response] the LLM response with tool calls
+      # @return [void]
+      def act(response)
+        executor = RubyPi::Tools::Executor.new(
+          @state.tools,
+          mode: :parallel,
+          timeout: 30
+        )
+
+        # Prepare call hashes for the executor
+        calls = response.tool_calls.map do |tc|
+          { name: tc.name, arguments: tc.arguments }
+        end
+
+        # Fire before_tool_call hooks and emit start events
+        response.tool_calls.each do |tc|
+          @state.before_tool_call&.call(tc)
+          @emitter.emit(:tool_execution_start, tool_name: tc.name, arguments: tc.arguments)
+        end
+
+        # Execute all tool calls
+        results = executor.execute(calls)
+
+        # Fire after_tool_call hooks, emit end events, and add results to messages
+        response.tool_calls.each_with_index do |tc, idx|
+          result = results[idx]
+
+          @state.after_tool_call&.call(tc, result)
+          @emitter.emit(:tool_execution_end,
+                        tool_name: tc.name,
+                        result: result,
+                        success: result.success?,
+                        duration_ms: result.duration_ms)
+
+          # Record the tool call for the final result
+          @tool_calls_made << {
+            tool_name: tc.name,
+            arguments: tc.arguments,
+            result: result.to_h
+          }
+
+          # Add tool result to conversation as a tool-role message
+          result_content = result.success? ? JSON.generate(result.value) : "Error: #{result.error}"
+          @state.add_message(
+            role: :tool,
+            content: result_content,
+            tool_call_id: tc.id,
+            name: tc.name
+          )
+        end
+      end
+
+      # Builds the messages array for the LLM, prepending the system prompt
+      # as the first message.
+      #
+      # @return [Array<Hash>] messages formatted for the LLM provider
+      def build_llm_messages
+        system_message = { role: :system, content: @state.system_prompt }
+        [system_message] + @state.messages
+      end
+
+      # Converts the tool registry into an array of tool definition hashes
+      # suitable for the LLM call. Returns an empty array if no tools are
+      # registered.
+      #
+      # @return [Array<Hash>] tool definitions
+      def build_tools_array
+        return [] unless @state.tools
+
+        @state.tools.all
+      end
+
+      # Accumulates token usage from a single LLM response into the running
+      # total.
+      #
+      # @param usage [Hash] usage from one response
+      # @return [void]
+      def accumulate_usage(usage)
+        return unless usage.is_a?(Hash)
+
+        @total_usage[:input_tokens] += (usage[:prompt_tokens] || usage[:input_tokens] || 0)
+        @total_usage[:output_tokens] += (usage[:completion_tokens] || usage[:output_tokens] || 0)
+      end
+
+      # Triggers context compaction if a compaction strategy is configured
+      # and the estimated token count exceeds the threshold.
+      #
+      # @return [void]
+      def compact_if_needed!
+        return unless @compaction
+
+        compacted = @compaction.compact(@state.messages, @state.system_prompt)
+        return unless compacted # nil means no compaction was needed
+
+        @state.messages = compacted
+      end
+
+      # Extracts the last assistant message content from the conversation
+      # history. Used as the final content when max iterations are reached.
+      #
+      # @return [String, nil] the last assistant content or nil
+      def last_assistant_content
+        @state.messages
+              .select { |m| m[:role] == :assistant }
+              .last
+              &.dig(:content)
+      end
+
+      # Constructs the final Agent::Result from the current state.
+      #
+      # @param content [String, nil] the final text content
+      # @return [RubyPi::Agent::Result]
+      def build_result(content:)
+        Result.new(
+          content: content,
+          messages: @state.messages,
+          tool_calls_made: @tool_calls_made,
+          usage: @total_usage,
+          turns: @state.iteration
+        )
+      end
+    end
+  end
+end

data/lib/ruby_pi/agent/result.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/agent/result.rb
+#
+# RubyPi::Agent::Result — Immutable value object encapsulating the outcome of
+# an agent run. Contains the final text content, full conversation history,
+# tool calls that were executed, token usage, turn count, and any error that
+# occurred. The agent loop returns a Result when it completes (either by
+# receiving a stop signal from the LLM or hitting the max iteration limit).
+
+module RubyPi
+  module Agent
+    # Value object returned by Agent::Core#run and Agent::Core#continue.
+    # Captures everything about the completed agent interaction in a single,
+    # inspectable object.
+    #
+    # @example Inspecting an agent result
+    #   result = agent.run("Hello")
+    #   if result.success?
+    #     puts result.content
+    #     puts "Used #{result.turns} turns"
+    #     result.tool_calls_made.each { |tc| puts "  Called: #{tc[:tool_name]}" }
+    #   else
+    #     puts "Error: #{result.error.message}"
+    #   end
+    class Result
+      # @return [String, nil] the final text content from the assistant
+      attr_reader :content
+
+      # @return [Array<Hash>] the full conversation history (all messages)
+      attr_reader :messages
+
+      # @return [Array<Hash>] tool calls that were executed, each with
+      #   :tool_name, :arguments, and :result keys
+      attr_reader :tool_calls_made
+
+      # @return [Hash] aggregate token usage with :input_tokens and
+      #   :output_tokens keys
+      attr_reader :usage
+
+      # @return [Integer] the number of think-act-observe cycles completed
+      attr_reader :turns
+
+      # @return [RubyPi::Error, StandardError, nil] the error if the run failed
+      attr_reader :error
+
+      # Creates a new Result instance.
+      #
+      # @param content [String, nil] the final assistant text
+      # @param messages [Array<Hash>] full conversation history
+      # @param tool_calls_made [Array<Hash>] executed tool call records
+      # @param usage [Hash] token usage statistics
+      # @param turns [Integer] number of completed cycles
+      # @param error [Exception, nil] error if the run failed
+      def initialize(content: nil, messages: [], tool_calls_made: [], usage: {}, turns: 0, error: nil)
+        @content = content
+        @messages = Array(messages).freeze
+        @tool_calls_made = Array(tool_calls_made).freeze
+        @usage = usage
+        @turns = turns
+        @error = error
+      end
+
+      # Returns true if the agent run completed without error.
+      #
+      # @return [Boolean] true unless an error is present
+      def success?
+        @error.nil?
+      end
+
+      # Returns a hash representation of the result for serialization.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          content: @content,
+          messages: @messages,
+          tool_calls_made: @tool_calls_made,
+          usage: @usage,
+          turns: @turns,
+          error: @error&.message,
+          success: success?
+        }
+      end
+
+      # Returns a human-readable string representation of the result.
+      #
+      # @return [String]
+      def to_s
+        status = success? ? "success" : "error"
+        parts = ["status=#{status}", "turns=#{@turns}"]
+        parts << "tools=#{@tool_calls_made.size}" unless @tool_calls_made.empty?
+        parts << "content=#{@content&.slice(0, 80).inspect}" if @content
+        parts << "error=#{@error.class}: #{@error.message}" if @error
+        "#<RubyPi::Agent::Result #{parts.join(', ')}>"
+      end
+
+      alias_method :inspect, :to_s
+    end
+  end
+end

data/lib/ruby_pi/agent/state.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/agent/state.rb
+#
+# RubyPi::Agent::State — Mutable container for all agent runtime state.
+#
+# State holds the conversation history, system prompt, model reference, tool
+# registry, iteration counter, lifecycle hooks (transform_context, before_tool_call,
+# after_tool_call), and an arbitrary user_data hash for extension-provided context.
+# The agent loop reads and mutates State as it progresses through think-act-observe
+# cycles.
+
+module RubyPi
+  module Agent
+    # Mutable state object threaded through the agent loop. Encapsulates the
+    # full conversation history, configuration, and hook callables so that
+    # the loop, compaction, and transforms all operate on a single shared
+    # object.
+    #
+    # @example Creating and using state
+    #   state = RubyPi::Agent::State.new(
+    #     system_prompt: "You are helpful.",
+    #     model: RubyPi::LLM.model(:gemini, "gemini-2.0-flash"),
+    #     tools: registry,
+    #     max_iterations: 10
+    #   )
+    #   state.add_message(role: :user, content: "Hi!")
+    #   state.messages  # => [{ role: :user, content: "Hi!" }]
+    class State
+      # @return [String] the system prompt prepended to every LLM call
+      attr_accessor :system_prompt
+
+      # @return [RubyPi::LLM::BaseProvider] the LLM provider instance
+      attr_reader :model
+
+      # @return [RubyPi::Tools::Registry] the registry of available tools
+      attr_reader :tools
+
+      # @return [Integer] maximum think-act-observe iterations before halting
+      attr_reader :max_iterations
+
+      # @return [Proc, nil] callable invoked with state before each LLM call
+      #   to transform context (system prompt, messages)
+      attr_accessor :transform_context
+
+      # @return [Proc, nil] callable invoked before each tool call; receives
+      #   the RubyPi::LLM::ToolCall
+      attr_accessor :before_tool_call
+
+      # @return [Proc, nil] callable invoked after each tool call; receives
+      #   the ToolCall and the RubyPi::Tools::Result
+      attr_accessor :after_tool_call
+
+      # @return [Hash] arbitrary user-provided data accessible by transforms
+      #   and extensions
+      attr_accessor :user_data
+
+      # Creates a new State instance with the given configuration.
+      #
+      # @param system_prompt [String] the system-level instruction prompt
+      # @param model [RubyPi::LLM::BaseProvider] the LLM provider to use
+      # @param tools [RubyPi::Tools::Registry, nil] tool registry (nil for no tools)
+      # @param messages [Array<Hash>] initial conversation history
+      # @param max_iterations [Integer] max think-act-observe cycles (default: 10)
+      # @param transform_context [Proc, nil] context transform hook
+      # @param before_tool_call [Proc, nil] pre-tool-execution hook
+      # @param after_tool_call [Proc, nil] post-tool-execution hook
+      # @param user_data [Hash] arbitrary data bag for extensions/transforms
+      def initialize(
+        system_prompt:,
+        model:,
+        tools: nil,
+        messages: [],
+        max_iterations: 10,
+        transform_context: nil,
+        before_tool_call: nil,
+        after_tool_call: nil,
+        user_data: {}
+      )
+        @system_prompt = system_prompt
+        @model = model
+        @tools = tools
+        @messages = Array(messages).dup
+        @max_iterations = max_iterations
+        @transform_context = transform_context
+        @before_tool_call = before_tool_call
+        @after_tool_call = after_tool_call
+        @user_data = user_data
+        @iteration = 0
+      end
+
+      # Appends a message to the conversation history.
+      #
+      # @param role [Symbol, String] the message role (:user, :assistant, :system, :tool)
+      # @param content [String, nil] the text content of the message
+      # @param options [Hash] additional fields (e.g., :tool_call_id, :tool_calls)
+      # @return [Array<Hash>] the updated messages array
+      def add_message(role:, content: nil, **options)
+        message = { role: role.to_sym, content: content }.merge(options)
+        @messages << message
+        @messages
+      end
+
+      # Returns a frozen copy of the conversation history. Callers cannot
+      # accidentally mutate the internal array through this reference.
+      #
+      # @return [Array<Hash>] the full conversation history
+      def messages
+        @messages.dup.freeze
+      end
+
+      # Replaces the entire conversation history. Used by compaction to swap
+      # in a shortened message array.
+      #
+      # @param new_messages [Array<Hash>] the replacement message array
+      # @return [Array<Hash>] the new messages array
+      def messages=(new_messages)
+        @messages = Array(new_messages).dup
+      end
+
+      # Returns the current iteration count (number of completed think-act-observe
+      # cycles).
+      #
+      # @return [Integer] the iteration count
+      def iteration
+        @iteration
+      end
+
+      # Increments the iteration counter by one. Called by the agent loop at
+      # the end of each think-act-observe cycle.
+      #
+      # @return [Integer] the new iteration count
+      def increment_iteration!
+        @iteration += 1
+      end
+
+      # Returns true if the iteration count has reached or exceeded max_iterations.
+      #
+      # @return [Boolean]
+      def max_iterations_reached?
+        @iteration >= @max_iterations
+      end
+
+      # Provides a human-readable summary of the current state for debugging.
+      #
+      # @return [String]
+      def inspect
+        "#<RubyPi::Agent::State " \
+          "iteration=#{@iteration}/#{@max_iterations} " \
+          "messages=#{@messages.size} " \
+          "tools=#{@tools&.size || 0}>"
+      end
+    end
+  end
+end