Integration Guide

from pathlib import Path
from pulse import PulseRegistry

class AgentKernel:
    def __init__(self):
        # Initialize Pulse
        self.pulse = PulseRegistry(
            watch_dirs=[],  # Populated from module fingerprints
            threshold=0.65,  # Global default (can be overridden per-module)
            model_save_path=Path.home() / ".macroa" / "pulse" / "models"
        )
        
        # Track activation IDs for feedback
        self._active_questions: dict[str, str] = {}  # question -> activation_id
        
        # Don't start yet - register modules first

class AgentKernel:
    def register_pulse_module(self, module_id: str, fingerprint: dict):
        """
        Register a module with Pulse.
        
        The fingerprint can come from:
        - A static configuration file
        - The module's own registration method
        - Dynamic generation based on user preferences
        """
        try:
            self.pulse.register_module(module_id, fingerprint)
            print(f"✓ Registered {module_id} with Pulse")
        except ValueError as e:
            print(f"✗ Failed to register {module_id}: {e}")

# Static registration during kernel init
kernel = AgentKernel()

homework_fingerprint = {
    "module_id": "homework-agent",
    "cluster": "academic",
    "version": "1.0",
    "question_template": "A new file appeared at {location}. Is this file related to a course assignment or homework?",
    "default_threshold": 0.65,
    "signal_priors": {
        "filesystem": {
            "watch_directories": ["~/Downloads", "~/Documents"],
            "relevant_extensions": [".pdf", ".docx", ".pptx"],
            "irrelevant_extensions": [".exe", ".zip"]
        },
        "time": {
            "active_hours": [8, 23],
            "active_days": [0, 1, 2, 3, 4],
            "typical_interval_hours": 24
        }
    }
}

kernel.register_pulse_module("homework-agent", homework_fingerprint)

from pulse import EscalationDecision

class AgentKernel:
    def _on_pulse_escalation(self, decision: EscalationDecision):
        """
        Called by Pulse when a module's relevance score exceeds threshold.
        
        Responsibility:
        1. Wake the agent with the scoped question
        2. Track the activation for later feedback
        3. Let the agent handle the question
        """
        print(f"\n[PULSE] {decision.module_id} triggered")
        print(f"        Question: {decision.question}")
        print(f"        Confidence: {decision.confidence:.2f}")
        
        # Track this activation (needed for feedback later)
        # Note: The current EscalationDecision doesn't include activation_id,
        # so we'll need to derive it or enhance the API
        activation_id = self._track_activation(decision)
        
        # Wake the agent with the scoped question
        result = self.agent.handle_question(
            question=decision.question,
            context={
                "module_id": decision.module_id,
                "confidence": decision.confidence,
                "events": decision.triggering_events
            }
        )
        
        # Provide feedback based on result
        self._provide_feedback(activation_id, result)
    
    def _track_activation(self, decision: EscalationDecision) -> str:
        """
        Store the activation for later feedback.
        
        In the current architecture, we need to manually create an activation
        record. Future versions may include the activation_id in the
        EscalationDecision.
        """
        # The registry already recorded the activation, but we don't have the ID
        # This is a design limitation - see pulse/registry.py:152
        # For now, generate a synthetic ID based on the question
        activation_id = hash(decision.question)
        self._active_questions[decision.question] = str(activation_id)
        return str(activation_id)
    
    def _provide_feedback(self, activation_id: str, result):
        """
        Provide training feedback based on agent's response.
        """
        # Calculate label based on what the agent did
        if result.action_taken:
            # Agent took action (wrote memory, executed tool, etc.)
            label = 1.0
        elif result.dismissed:
            # Agent explicitly dismissed as irrelevant
            label = 0.0
        else:
            # Agent acknowledged but took no action (maybe informational)
            label = 0.5
        
        # Submit feedback
        self.pulse.record_feedback(activation_id, label)

class AgentKernel:
    def start(self):
        """Start the kernel and Pulse subsystem."""
        # Register the escalation callback
        self.pulse.on_escalation(self._on_pulse_escalation)
        
        # Start Pulse (begins watching filesystem, time ticks, etc.)
        self.pulse.start()
        
        print("✓ Pulse is running")
        print(f"  Watching: {self.pulse._watch_dirs}")
        
        # Start other kernel components...
    
    def stop(self):
        """Gracefully shut down the kernel."""
        print("Shutting down Pulse...")
        
        # Stop Pulse (saves model weights)
        self.pulse.stop()
        
        print("✓ Pulse stopped and models saved")

class Agent:
    def handle_question(self, question: str, context: dict):
        """
        Process a scoped question from Pulse.
        
        Returns:
            Result object with:
            - action_taken: bool
            - dismissed: bool
            - confidence_score: float
        """
        # Use LLM or rule-based logic to answer the question
        response = self.reason(question, context)
        
        # Decide if action is needed
        if self._is_relevant(response):
            # Take action (e.g., store in memory, notify user)
            self.memory.write(f"/pulse/{context['module_id']}/last_seen", {
                "question": question,
                "timestamp": time.time(),
                "response": response
            })
            
            return Result(action_taken=True, dismissed=False, confidence_score=0.9)
        else:
            return Result(action_taken=False, dismissed=True, confidence_score=0.3)