Class: RubyPi::Extensions::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby_pi/extensions/base.rb

Overview

Abstract base class for agent extensions. Subclass this and use the ‘on_event` DSL to register lifecycle hooks.

Examples:

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 Method Summary collapse

Class Method Details

.hooks ⇒ Hash{Symbol => Array<Proc>}

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.

Returns:

  • (Hash{Symbol => Array<Proc>}) —

    hooks keyed by event type



62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/ruby_pi/extensions/base.rb', line 62

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

.name ⇒ String

Returns the extension name. Override in subclasses to provide a human-readable identifier.

Returns:

  • (String) —

    the extension name



79
80
81
 
# File 'lib/ruby_pi/extensions/base.rb', line 79

def name
  super
end

.on_event(event, &block) ⇒ void

This method returns an undefined value.

Registers a hook for the given event type. The block receives the event data hash and the agent instance when the event fires.

Parameters:

  • event (Symbol) —

    the event type to hook into (must be in Agent::EVENTS)

  • block (Proc) —

    the hook handler; receives (data, agent)

Raises:

  • (ArgumentError) —

    if the event type is not recognized



46
47
48
49
50
51
52
53
54
55
 
# File 'lib/ruby_pi/extensions/base.rb', line 46

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