ajarbot/docs/PULSE_BRAIN.md

Pulse & Brain Architecture

The most efficient way to run an agent with proactive monitoring.

🎯 The Problem

Running an agent in a loop is expensive:

# ❌ EXPENSIVE: Agent asks "What should I do?" every loop
while True:
    response = agent.chat("What should I do?")  # Costs tokens!
    time.sleep(60)

Cost: If you check every minute for 24 hours:

• 1,440 API calls/day
• ~50,000 tokens/day
• ~$0.50/day just to ask "nothing to do"

✅ The Solution: Pulse & Brain

Think of it like a security guard:

• Pulse (Guard): Walks the perimeter every 60 seconds. Checks doors (pure Python). Cost: $0
• Brain (Manager): Only called when guard sees a problem or it's time for the morning report. Cost: Only when needed

# ✅ EFFICIENT: Agent only invoked when needed
while True:
    # Pulse: Pure Python checks (zero cost)
    disk_check = check_disk_space()        # $0
    log_check = check_for_errors()         # $0
    task_check = check_stale_tasks()       # $0

    # Brain: Only if something needs attention
    if disk_check.status == "error":
        agent.chat("Disk space critical!")  # Costs tokens (but only when needed)

    if current_time == "08:00":
        agent.chat("Morning briefing")      # Costs tokens (scheduled)

    time.sleep(60)

📊 Cost Comparison

Old Heartbeat System (Always Uses Agent)

# Every 30 minutes, agent processes checklist
while True:
    response = agent.chat(checklist)  # ~1000 tokens
    time.sleep(1800)  # 30 min

Cost per day:

• 48 checks/day
• ~48,000 tokens/day
• ~$0.48/day

Pulse & Brain (Conditional Agent)

# Every 60 seconds, pure Python checks (zero cost)
# Agent only invoked when:
# 1. Error detected (~2x/day)
# 2. Scheduled briefings (2x/day)
# = ~4 agent calls/day

Cost per day:

• 1,440 pulse checks (pure Python) = $0
• 4 brain invocations (~4,000 tokens) = $0.04/day

Savings: 92% 💰

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   PULSE LOOP                        │
│              (Pure Python, $0 cost)                 │
│                                                     │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐      │
│  │ Disk Space│  │ Log Errors│  │ Tasks     │      │
│  │ Check     │  │ Check     │  │ Check     │ ...  │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘      │
│        │              │              │             │
│        └──────────────┼──────────────┘             │
│                       │                             │
│               ┌───────▼───────┐                     │
│               │  Conditions?  │                     │
│               └───────┬───────┘                     │
│                       │                             │
│        ┌──────────────┴──────────────┐              │
│        │                             │              │
│   ┌────▼────┐                  ┌────▼────┐         │
│   │ Error?  │                  │ 8:00 AM?│         │
│   └────┬────┘                  └────┬────┘         │
│        │ YES                         │ YES          │
└────────┼─────────────────────────────┼──────────────┘
         │                             │
         └──────────┬──────────────────┘
                    │
         ┌──────────▼──────────┐
         │       BRAIN         │
         │   (Agent/SDK)       │
         │   COSTS TOKENS      │
         └─────────────────────┘

🔧 Usage

Basic Setup

from agent import Agent
from pulse_brain import PulseBrain

agent = Agent(provider="claude", enable_heartbeat=False)

# Create Pulse & Brain
pb = PulseBrain(agent, pulse_interval=60)  # Pulse every 60 seconds

# Start
pb.start()

With Messaging Platforms

from adapters.runtime import AdapterRuntime
from pulse_brain import PulseBrain

# Set up runtime with adapters
runtime = AdapterRuntime(agent)
runtime.add_adapter(slack_adapter)

# Create Pulse & Brain
pb = PulseBrain(agent)
pb.add_adapter("slack", slack_adapter)

# Start both
await runtime.start()
pb.start()

📝 Default Checks

Pulse Checks (Zero Cost)

Check	Interval	What It Does
disk-space	5 min	Checks disk usage, warns >80%
memory-tasks	10 min	Counts pending tasks
log-errors	1 min	Scans logs for errors

Brain Tasks (Uses Tokens)

Task	Type	Trigger
disk-space-advisor	Conditional	Disk >90% used
error-analyst	Conditional	Errors found in logs
morning-briefing	Scheduled	Daily at 8:00 AM
evening-summary	Scheduled	Daily at 6:00 PM

🎨 Custom Configuration

Create config/pulse_brain_config.py:

from pulse_brain import PulseCheck, BrainTask, CheckType

def check_my_server() -> dict:
    """Pure Python check (zero cost)."""
    import requests
    try:
        r = requests.get("http://localhost:8000/health")
        return {
            "status": "ok" if r.status_code == 200 else "error",
            "message": f"Server: {r.status_code}"
        }
    except:
        return {"status": "error", "message": "Server down"}

CUSTOM_PULSE_CHECKS = [
    PulseCheck("my-server", check_my_server, interval_seconds=60)
]

CUSTOM_BRAIN_TASKS = [
    BrainTask(
        name="server-medic",
        check_type=CheckType.CONDITIONAL,
        prompt_template="Server is down! {message}\n\nWhat should I check?",
        condition_func=lambda data: data.get("status") == "error"
    )
]

🌟 Real-World Examples

Example 1: Homelab Monitoring (from Gemini)

The "Morning Briefing" (Scheduled Brain):

BrainTask(
    name="homelab-morning",
    check_type=CheckType.SCHEDULED,
    schedule_time="08:00",
    prompt_template="""Good morning Jordan!

Overnight summary:
- Plex: {plex_status}
- Star Citizen: {game_status}
- UniFi: {network_status}

Any restarts or patches detected?""",
    send_to_platform="slack",
    send_to_channel="C_HOMELAB"
)

Cost: 1 API call/day = ~$0.01

The "Medic" (Conditional Brain):

def check_logs():
    """Pure Python log scanner."""
    with open("/var/log/syslog") as f:
        recent = f.readlines()[-100:]
        errors = [line for line in recent if "ERROR" in line]
        return {
            "status": "error" if errors else "ok",
            "error_lines": errors
        }

BrainTask(
    name="error-medic",
    check_type=CheckType.CONDITIONAL,
    prompt_template="""Errors detected in logs:
{error_lines}

What does this mean and should I fix it?""",
    condition_func=lambda data: data.get("status") == "error"
)

Cost: Only when errors found = ~$0.01 per error

The "Resource Manager" (Conditional Brain):

BrainTask(
    name="disk-cleanup",
    check_type=CheckType.CONDITIONAL,
    prompt_template="""Disk space is low: {gb_free:.1f} GB free.

Please:
1. Scan temp folders
2. Recommend what to delete (>7 days old)
3. Provide cleanup commands""",
    condition_func=lambda data: data.get("gb_free", 100) < 10
)

Cost: Only when disk < 10GB = ~$0.02 per trigger

Example 2: Docker Monitoring

def check_docker():
    import subprocess
    result = subprocess.run(
        ["docker", "ps", "--format", "{{.Status}}"],
        capture_output=True, text=True
    )
    unhealthy = sum(1 for line in result.stdout.split("\n")
                   if "unhealthy" in line)
    return {
        "status": "error" if unhealthy > 0 else "ok",
        "unhealthy_count": unhealthy
    }

PULSE_CHECK = PulseCheck("docker", check_docker, interval_seconds=60)

BRAIN_TASK = BrainTask(
    name="docker-fixer",
    check_type=CheckType.CONDITIONAL,
    prompt_template="{unhealthy_count} containers unhealthy. What should I do?",
    condition_func=lambda data: data.get("unhealthy_count", 0) > 0
)

Pulse runs every 60s: $0 Brain only when unhealthy: ~$0.01 per incident

🎯 When to Use What

System	Best For	Cost
Pulse & Brain	Production monitoring	~$1-2/month
TaskScheduler	Scheduled content	~$3-5/month
Old Heartbeat	Simple health checks	~$15/month

Recommended Stack

For maximum efficiency:

# Pulse & Brain for monitoring (cheapest)
pb = PulseBrain(agent, pulse_interval=60)
pb.start()

# TaskScheduler for scheduled content only
scheduler = TaskScheduler(agent)
# Only enable specific scheduled tasks
scheduler.start()

📊 Monitoring Your Costs

pb = PulseBrain(agent)
pb.start()

# After running for a while
status = pb.get_status()
print(f"Brain invoked {status['brain_invocations']} times")

# Estimate cost
tokens_per_invocation = 1000  # Average
total_tokens = status['brain_invocations'] * tokens_per_invocation
cost = total_tokens * 0.000003  # Claude Sonnet pricing
print(f"Estimated cost: ${cost:.4f}")

🚀 Getting Started

1. Edit config/pulse_brain_config.py with your checks
2. Test your pulse checks (they should return {"status": "ok|warn|error"})
3. Configure brain tasks (conditional or scheduled)
4. Run python -m pulse_brain
5. Monitor brain invocation count

🔥 Pro Tips

1. Make pulse checks fast (<1 second each)
2. Use conditional brain tasks for errors/warnings
3. Use scheduled brain tasks for daily summaries
4. Test pulse checks without brain first
5. Monitor brain invocations to track costs

🎉 Summary

Pulse & Brain is the most cost-effective way to run a proactive agent:

✅ Pulse runs constantly - Zero cost ✅ Brain only when needed - Pay for value ✅ 92% cost savings vs always-on agent ✅ Smart monitoring - Python checks + Agent analysis ✅ Scalable - Add more checks without increasing cost

Perfect for:

• Homelab monitoring
• Server health checks
• Log analysis
• Resource management
• Scheduled briefings

Result: An agent that's always watching but only speaks when it has something important to say. 🫀🧠