ruby-pi 0.1.0

data/lib/ruby_pi/configuration.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/configuration.rb
+#
+# Global configuration for the RubyPi framework. Provides a centralized place
+# to set API keys, retry behavior, timeouts, and default model preferences.
+# Configure via RubyPi.configure { |c| c.gemini_api_key = "..." }.
+
+module RubyPi
+  # Holds all configurable settings for the RubyPi framework.
+  #
+  # @example Setting API keys and retry behavior
+  #   RubyPi.configure do |config|
+  #     config.gemini_api_key   = ENV["GEMINI_API_KEY"]
+  #     config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  #     config.openai_api_key   = ENV["OPENAI_API_KEY"]
+  #     config.max_retries      = 5
+  #     config.retry_base_delay = 2.0
+  #   end
+  class Configuration
+    # @return [String, nil] API key for Google Gemini
+    attr_accessor :gemini_api_key
+
+    # @return [String, nil] API key for Anthropic Claude
+    attr_accessor :anthropic_api_key
+
+    # @return [String, nil] API key for OpenAI
+    attr_accessor :openai_api_key
+
+    # @return [Integer] Maximum number of retry attempts for transient errors (default: 3)
+    attr_accessor :max_retries
+
+    # @return [Float] Base delay in seconds for exponential backoff (default: 1.0)
+    attr_accessor :retry_base_delay
+
+    # @return [Float] Maximum delay in seconds between retries (default: 30.0)
+    attr_accessor :retry_max_delay
+
+    # @return [Integer] HTTP request timeout in seconds (default: 120)
+    attr_accessor :request_timeout
+
+    # @return [Integer] HTTP connection open timeout in seconds (default: 10)
+    attr_accessor :open_timeout
+
+    # @return [String] Default model name for Gemini provider
+    attr_accessor :default_gemini_model
+
+    # @return [String] Default model name for Anthropic provider
+    attr_accessor :default_anthropic_model
+
+    # @return [String] Default model name for OpenAI provider
+    attr_accessor :default_openai_model
+
+    # @return [Logger, nil] Logger instance for debug output
+    attr_accessor :logger
+
+    # Initializes a new Configuration with sensible defaults.
+    def initialize
+      @gemini_api_key        = nil
+      @anthropic_api_key     = nil
+      @openai_api_key        = nil
+      @max_retries           = 3
+      @retry_base_delay      = 1.0
+      @retry_max_delay       = 30.0
+      @request_timeout       = 120
+      @open_timeout          = 10
+      @default_gemini_model  = "gemini-2.0-flash"
+      @default_anthropic_model = "claude-sonnet-4-20250514"
+      @default_openai_model  = "gpt-4o"
+      @logger                = nil
+    end
+
+    # Resets all configuration options to their default values.
+    #
+    # @return [void]
+    def reset!
+      initialize
+    end
+  end
+end

data/lib/ruby_pi/context/compaction.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/context/compaction.rb
+#
+# RubyPi::Context::Compaction — Token estimation and context window management.
+#
+# When the conversation history grows too large for the model's context window,
+# Compaction summarizes older messages while preserving the most recent ones.
+# Token estimation uses a simple heuristic (~4 characters per token) to avoid
+# external tokenizer dependencies. When compaction triggers, older messages are
+# replaced with a single summary message generated by the LLM, and a :compaction
+# event is emitted.
+
+module RubyPi
+  module Context
+    # Manages context window size by summarizing older messages when the
+    # estimated token count exceeds a configurable threshold. The most recent
+    # N messages are always preserved to maintain conversational coherence.
+    #
+    # @example Configuring compaction
+    #   compaction = RubyPi::Context::Compaction.new(
+    #     max_tokens: 8000,
+    #     summary_model: model,
+    #     preserve_last_n: 4
+    #   )
+    #   compacted = compaction.compact(messages, system_prompt)
+    class Compaction
+      # Average characters per token — a rough heuristic that avoids the need
+      # for provider-specific tokenizers. Errs on the conservative side.
+      CHARS_PER_TOKEN = 4
+
+      # @return [Integer] the token threshold above which compaction triggers
+      attr_reader :max_tokens
+
+      # @return [RubyPi::LLM::BaseProvider] the model used to generate summaries
+      attr_reader :summary_model
+
+      # @return [Integer] number of recent messages always preserved
+      attr_reader :preserve_last_n
+
+      # @return [#emit, nil] optional event emitter for :compaction events
+      attr_accessor :emitter
+
+      # Creates a new Compaction instance.
+      #
+      # @param max_tokens [Integer] trigger compaction above this token estimate
+      #   (default: 8000)
+      # @param summary_model [RubyPi::LLM::BaseProvider] model for summarization
+      # @param preserve_last_n [Integer] always keep the last N messages
+      #   (default: 4)
+      def initialize(max_tokens: 8000, summary_model:, preserve_last_n: 4)
+        @max_tokens = max_tokens
+        @summary_model = summary_model
+        @preserve_last_n = preserve_last_n
+        @emitter = nil
+      end
+
+      # Compacts the message history if the estimated token count exceeds
+      # the threshold. Returns the compacted messages array, or nil if no
+      # compaction was needed.
+      #
+      # The compaction process:
+      # 1. Estimate total tokens for system_prompt + all messages.
+      # 2. If under threshold, return nil (no compaction needed).
+      # 3. Split messages into "droppable" (older) and "preserved" (recent).
+      # 4. Summarize the droppable messages via the summary model.
+      # 5. Return a new array: [summary_message] + preserved_messages.
+      #
+      # @param messages [Array<Hash>] the current conversation history
+      # @param system_prompt [String] the system prompt (included in estimate)
+      # @return [Array<Hash>, nil] compacted messages, or nil if not needed
+      def compact(messages, system_prompt)
+        total_tokens = estimate_tokens(system_prompt, messages)
+        return nil if total_tokens <= @max_tokens
+
+        # Split into messages to summarize and messages to keep
+        preserved_count = [@preserve_last_n, messages.size].min
+        droppable = messages[0...(messages.size - preserved_count)]
+        preserved = messages[(messages.size - preserved_count)..]
+
+        # If there's nothing to drop, we can't compact further
+        return nil if droppable.empty?
+
+        # Generate a summary of the dropped messages
+        summary = summarize(droppable)
+
+        # Emit compaction event if an emitter is available
+        @emitter&.emit(:compaction, dropped_count: droppable.size, summary: summary)
+
+        # Build the compacted history: summary as a system-context message + preserved
+        summary_message = {
+          role: :system,
+          content: "[Conversation Summary]\n#{summary}"
+        }
+
+        [summary_message] + preserved
+      end
+
+      # Estimates the total token count for a system prompt and message array
+      # using the character-based heuristic.
+      #
+      # @param system_prompt [String] the system prompt text
+      # @param messages [Array<Hash>] conversation messages
+      # @return [Integer] estimated token count
+      def estimate_tokens(system_prompt, messages)
+        total_chars = system_prompt.to_s.length
+
+        messages.each do |msg|
+          total_chars += msg[:content].to_s.length
+          # Account for role and structural overhead (~10 tokens per message)
+          total_chars += 40
+        end
+
+        (total_chars.to_f / CHARS_PER_TOKEN).ceil
+      end
+
+      private
+
+      # Generates a summary of the given messages using the summary model.
+      # The summary captures key decisions, facts, and context from the
+      # conversation so far.
+      #
+      # @param messages [Array<Hash>] messages to summarize
+      # @return [String] the generated summary text
+      def summarize(messages)
+        summary_prompt = build_summary_prompt(messages)
+
+        response = @summary_model.complete(
+          messages: [
+            { role: :system, content: "You are a precise conversation summarizer. " \
+              "Produce a concise summary that preserves all important facts, decisions, " \
+              "tool results, and context. Do not add any information not present in " \
+              "the conversation." },
+            { role: :user, content: summary_prompt }
+          ],
+          tools: [],
+          stream: false
+        )
+
+        response.content || ""
+      end
+
+      # Builds the prompt text for the summarization LLM call by formatting
+      # each message into a readable transcript.
+      #
+      # @param messages [Array<Hash>] messages to include in the transcript
+      # @return [String] formatted prompt for summarization
+      def build_summary_prompt(messages)
+        transcript = messages.map do |msg|
+          role = msg[:role].to_s.capitalize
+          content = msg[:content].to_s
+          "#{role}: #{content}"
+        end.join("\n\n")
+
+        "Summarize the following conversation, preserving all key facts, " \
+          "decisions, and tool call results:\n\n#{transcript}"
+      end
+    end
+  end
+end

data/lib/ruby_pi/context/transform.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/context/transform.rb
+#
+# RubyPi::Context::Transform — Composable helpers for mutating agent state
+# before each LLM call.
+#
+# Transforms are callables (lambdas/procs) that receive the Agent::State and
+# modify it in place — typically appending context to the system prompt. This
+# module provides factory methods for common transform patterns (datetime
+# injection, user preferences, workspace context) and a `compose` method for
+# chaining multiple transforms into a single callable.
+
+module RubyPi
+  module Context
+    # Factory methods for building transform_context callables. Each method
+    # returns a Proc that accepts an Agent::State and mutates it. Use
+    # `compose` to chain multiple transforms.
+    #
+    # @example Composing transforms
+    #   transform = RubyPi::Context::Transform.compose(
+    #     RubyPi::Context::Transform.inject_datetime,
+    #     RubyPi::Context::Transform.inject_user_preferences { |state| state.user_data[:prefs] }
+    #   )
+    #   agent = RubyPi::Agent.new(transform_context: transform, ...)
+    module Transform
+      class << self
+        # Chains multiple transform callables into a single callable that
+        # executes them in order. Each transform receives the same State
+        # object and can mutate it freely.
+        #
+        # @param transforms [Array<Proc>] transform callables to chain
+        # @return [Proc] a single callable that runs all transforms in sequence
+        #
+        # @example
+        #   combined = Transform.compose(transform_a, transform_b, transform_c)
+        #   combined.call(state) # runs a, then b, then c
+        def compose(*transforms)
+          ->(state) do
+            transforms.each { |t| t.call(state) }
+          end
+        end
+
+        # Returns a transform that appends the current date and time to the
+        # system prompt. Useful for giving the LLM temporal awareness.
+        #
+        # @return [Proc] transform callable
+        #
+        # @example
+        #   transform = Transform.inject_datetime
+        #   # Appends: "\n\nCurrent date and time: 2025-01-15 14:30:00 UTC"
+        def inject_datetime
+          ->(state) do
+            timestamp = Time.now.utc.strftime("%Y-%m-%d %H:%M:%S UTC")
+            state.system_prompt += "\n\nCurrent date and time: #{timestamp}"
+          end
+        end
+
+        # Returns a transform that appends user preferences to the system
+        # prompt. The block is called with the state and should return a
+        # string or hash of preferences. If nil is returned, nothing is
+        # appended.
+        #
+        # @yield [state] block that extracts preferences from the state
+        # @yieldparam state [RubyPi::Agent::State] the current agent state
+        # @yieldreturn [String, Hash, nil] preferences to inject
+        # @return [Proc] transform callable
+        #
+        # @example
+        #   transform = Transform.inject_user_preferences { |s| s.user_data[:prefs] }
+        def inject_user_preferences(&block)
+          ->(state) do
+            preferences = block.call(state)
+            return if preferences.nil?
+
+            prefs_text = preferences.is_a?(Hash) ? format_hash(preferences) : preferences.to_s
+            state.system_prompt += "\n\n[User Preferences]\n#{prefs_text}"
+          end
+        end
+
+        # Returns a transform that appends workspace context to the system
+        # prompt. The block is called with the state and should return
+        # contextual information about the current workspace/project.
+        #
+        # @yield [state] block that extracts workspace context from the state
+        # @yieldparam state [RubyPi::Agent::State] the current agent state
+        # @yieldreturn [String, Hash, nil] workspace context to inject
+        # @return [Proc] transform callable
+        #
+        # @example
+        #   transform = Transform.inject_workspace_context { |s| s.user_data[:workspace] }
+        def inject_workspace_context(&block)
+          ->(state) do
+            context = block.call(state)
+            return if context.nil?
+
+            ctx_text = context.is_a?(Hash) ? format_hash(context) : context.to_s
+            state.system_prompt += "\n\n[Workspace Context]\n#{ctx_text}"
+          end
+        end
+
+        private
+
+        # Formats a hash into a human-readable key-value string for injection
+        # into the system prompt.
+        #
+        # @param hash [Hash] the data to format
+        # @return [String] formatted key-value pairs
+        def format_hash(hash)
+          hash.map { |k, v| "- #{k}: #{v}" }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_pi/errors.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/errors.rb
+#
+# Defines the error hierarchy for the RubyPi framework. All RubyPi exceptions
+# inherit from RubyPi::Error, which itself inherits from StandardError.
+# This allows callers to rescue specific error types or catch all RubyPi
+# errors with a single rescue clause.
+
+module RubyPi
+  # Base error class for all RubyPi exceptions. Rescue this to catch any
+  # error originating from the RubyPi framework.
+  #
+  # @example Catching all RubyPi errors
+  #   begin
+  #     provider.complete(messages: msgs)
+  #   rescue RubyPi::Error => e
+  #     logger.error("RubyPi error: #{e.message}")
+  #   end
+  class Error < StandardError; end
+
+  # Raised when an API request fails due to a server-side or client-side
+  # HTTP error (e.g., 400, 500). Includes the HTTP status code and the
+  # response body for debugging.
+  class ApiError < Error
+    # @return [Integer, nil] the HTTP status code returned by the API
+    attr_reader :status_code
+
+    # @return [String, nil] the raw response body from the API
+    attr_reader :response_body
+
+    # @param message [String] human-readable error description
+    # @param status_code [Integer, nil] HTTP status code
+    # @param response_body [String, nil] raw response body
+    def initialize(message = nil, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message || "API request failed with status #{status_code}")
+    end
+  end
+
+  # Raised when authentication fails (HTTP 401 or 403). Typically indicates
+  # an invalid, expired, or missing API key.
+  class AuthenticationError < ApiError
+    # @param message [String] human-readable error description
+    # @param response_body [String, nil] raw response body
+    def initialize(message = nil, response_body: nil)
+      super(message || "Authentication failed — check your API key", status_code: 401, response_body: response_body)
+    end
+  end
+
+  # Raised when the API returns a rate limit response (HTTP 429). The caller
+  # should back off and retry after the indicated period.
+  class RateLimitError < ApiError
+    # @return [Float, nil] suggested retry delay in seconds, if provided by the API
+    attr_reader :retry_after
+
+    # @param message [String] human-readable error description
+    # @param retry_after [Float, nil] seconds to wait before retrying
+    # @param response_body [String, nil] raw response body
+    def initialize(message = nil, retry_after: nil, response_body: nil)
+      @retry_after = retry_after
+      super(message || "Rate limit exceeded", status_code: 429, response_body: response_body)
+    end
+  end
+
+  # Raised when an HTTP request times out before receiving a response.
+  class TimeoutError < Error
+    # @param message [String] human-readable error description
+    def initialize(message = nil)
+      super(message || "Request timed out")
+    end
+  end
+
+  # Raised when a provider-specific error occurs that does not map to one
+  # of the more specific error types. Includes the provider name for context.
+  class ProviderError < Error
+    # @return [Symbol, String] the name of the provider that raised the error
+    attr_reader :provider
+
+    # @param message [String] human-readable error description
+    # @param provider [Symbol, String] provider identifier (e.g., :gemini, :anthropic)
+    def initialize(message = nil, provider: nil)
+      @provider = provider
+      super(message || "Provider error from #{provider}")
+    end
+  end
+
+  # Raised when a subclass does not implement a required abstract method
+  # from a base class.
+  class NotImplementedError < Error
+    # @param method_name [String, Symbol] the name of the unimplemented method
+    def initialize(method_name = nil)
+      super(method_name ? "Subclass must implement ##{method_name}" : "Subclass must implement this method")
+    end
+  end
+end

data/lib/ruby_pi/extensions/base.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/extensions/base.rb
+#
+# RubyPi::Extensions::Base — Base class for agent extensions with a hook DSL.
+#
+# Extensions allow external modules to tap into the agent lifecycle without
+# modifying core agent code. Subclasses use the `on_event` class method to
+# declare handlers for specific events. When an extension is registered with
+# an agent via `agent.use(MyExtension)`, all declared hooks are automatically
+# subscribed to the agent's event emitter.
+#
+# Hooks are inherited by subclasses, so a base extension can define common
+# behavior that specialized extensions build upon.
+
+module RubyPi
+  module Extensions
+    # Abstract base class for agent extensions. Subclass this and use the
+    # `on_event` DSL to register lifecycle hooks.
+    #
+    # @example Defining an extension
+    #   class AuditExtension < RubyPi::Extensions::Base
+    #     on_event :tool_execution_end do |data, agent|
+    #       AuditLog.record(tool: data[:tool_name], success: data[:success])
+    #     end
+    #
+    #     on_event :agent_end do |data, agent|
+    #       AuditLog.finalize(success: data[:success])
+    #     end
+    #
+    #     def self.name
+    #       "audit"
+    #     end
+    #   end
+    #
+    #   agent.use(AuditExtension)
+    class Base
+      class << self
+        # Registers a hook for the given event type. The block receives the
+        # event data hash and the agent instance when the event fires.
+        #
+        # @param event [Symbol] the event type to hook into (must be in Agent::EVENTS)
+        # @param block [Proc] the hook handler; receives (data, agent)
+        # @return [void]
+        # @raise [ArgumentError] if the event type is not recognized
+        def on_event(event, &block)
+          unless RubyPi::Agent::EVENTS.include?(event)
+            raise ArgumentError,
+                  "Unknown event type: #{event.inspect}. " \
+                  "Must be one of: #{RubyPi::Agent::EVENTS.join(', ')}"
+          end
+
+          own_hooks[event] ||= []
+          own_hooks[event] << block
+        end
+
+        # Returns all registered hooks for this extension class, including
+        # hooks inherited from parent extension classes. Each event type
+        # maps to an array of callable handlers.
+        #
+        # @return [Hash{Symbol => Array<Proc>}] hooks keyed by event type
+        def hooks
+          if superclass.respond_to?(:hooks)
+            # Merge parent hooks with own hooks, preserving order
+            merged = superclass.hooks.dup
+            own_hooks.each do |event, handlers|
+              merged[event] = (merged[event] || []) + handlers
+            end
+            merged
+          else
+            own_hooks.dup
+          end
+        end
+
+        # Returns the extension name. Override in subclasses to provide
+        # a human-readable identifier.
+        #
+        # @return [String] the extension name
+        def name
+          super
+        end
+
+        private
+
+        # Returns the hooks hash defined directly on this class (not
+        # including inherited hooks). Used internally to separate
+        # own hooks from inherited ones.
+        #
+        # @return [Hash{Symbol => Array<Proc>}]
+        def own_hooks
+          @own_hooks ||= {}
+        end
+      end
+    end
+  end
+end