jramos/ajarbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation cleanup and consolidation

Browse Source 
Removed redundant/outdated files:
- docs/HEARTBEAT_HOOKS.md (legacy, disabled by default)
- docs/QUICK_START_PULSE.md (merged into PULSE_BRAIN.md)
- docs/MONITORING_COMPARISON.md (merged into PULSE_BRAIN.md)

Consolidated monitoring docs:
- Merged 3 monitoring files into comprehensive PULSE_BRAIN.md
- Added Quick Start section to PULSE_BRAIN.md
- Added "Why Pulse & Brain?" comparison section
- Added deprecation notices for Heartbeat system

Updated README.md:
- Clarified Haiku is default model (12x cheaper)
- Added prompt caching info (90% savings on Sonnet)
- Removed duplicate setup instructions
- Linked to SETUP.md for detailed instructions
- Added model switching commands section

Simplified WINDOWS_QUICK_REFERENCE.md:
- Reduced from 224 lines to ~160 lines
- Removed redundant development/deployment sections
- Kept essential quick commands
- Added model switching commands

Updated docs/README.md navigation:
- Removed references to deleted files
- Added deprecation notice for Heartbeat
- Updated learning paths
- Cleaned up file organization section

Result:
- Removed 300+ lines of redundant documentation
- Consolidated 3 monitoring files into 1
- Improved accuracy and clarity
- Easier navigation and maintenance

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jordan Ramos
2026-02-13 21:06:15 -07:00
parent a99799bf3d
commit ab3a5afd59
7 changed files with 404 additions and 882 deletions
Download Patch File Download Diff File Expand all files Collapse all files

386
docs/PULSE_BRAIN.md
View File

@@ -1,6 +1,86 @@
# Pulse & Brain Architecture
The **most efficient** way to run an agent with proactive monitoring.
⭐ **The most efficient way to run an agent with proactive monitoring.**
> **Note:** The old Heartbeat system is now **legacy** and disabled by default. Use Pulse & Brain for all new deployments.
---
## 🚀 Quick Start
Copy-paste ready setup in under 50 lines:
### Basic Monitoring (Zero-cost pulse, conditional agent)
```python
from agent import Agent
from pulse_brain import PulseBrain
# Initialize agent (disable old heartbeat)
agent = Agent(provider="claude", enable_heartbeat=False)
# Create Pulse & Brain with 60-second pulse interval
pb = PulseBrain(agent, pulse_interval=60)
# Start monitoring
pb.start()
```
### With Slack/Telegram Integration
```python
from adapters.runtime import AdapterRuntime
from adapters.slack.adapter import SlackAdapter
from pulse_brain import PulseBrain
agent = Agent(provider="claude", enable_heartbeat=False)
# Set up messaging adapters
slack = SlackAdapter(bot_token="xoxb-...", channel="C_MONITORING")
runtime = AdapterRuntime(agent)
runtime.add_adapter(slack)
# Create Pulse & Brain with adapter support
pb = PulseBrain(agent, pulse_interval=60)
pb.add_adapter("slack", slack)
# Start both systems
await runtime.start()
pb.start()
```
### Custom Pulse Check (Zero Cost)
```python
from pulse_brain import PulseCheck, BrainTask, CheckType
def check_my_server():
"""Pure Python check - no agent, no cost."""
import requests
try:
r = requests.get("http://localhost:8000/health", timeout=5)
return {"status": "ok" if r.status_code == 200 else "error"}
except:
return {"status": "error", "message": "Server down"}
# Add to Pulse & Brain
pb = PulseBrain(agent)
pb.add_pulse_check(PulseCheck("my-server", check_my_server, interval_seconds=60))
# Only invoke agent when server is down
pb.add_brain_task(BrainTask(
name="server-fixer",
check_type=CheckType.CONDITIONAL,
prompt_template="Server is down! What should I check?",
condition_func=lambda data: data.get("status") == "error"
))
pb.start()
```
**That's it!** Your agent now monitors your system 24/7 at ~$1-2/month.
---
## 🎯 The Problem
@@ -75,6 +155,8 @@ while True:
**Savings: 92%** 💰
---
## 🏗️ Architecture
```
@@ -110,41 +192,7 @@ while True:
└─────────────────────┘
```
## 🔧 Usage
### Basic Setup
```python
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
```python
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
@@ -165,6 +213,8 @@ pb.start()
| `morning-briefing` | Scheduled | Daily at 8:00 AM |
| `evening-summary` | Scheduled | Daily at 6:00 PM |
---
## 🎨 Custom Configuration
Create `config/pulse_brain_config.py`:
@@ -198,6 +248,8 @@ CUSTOM_BRAIN_TASKS = [
]
```
---
## 🌟 Real-World Examples
### Example 1: Homelab Monitoring (from Gemini)
@@ -294,13 +346,198 @@ BRAIN_TASK = BrainTask(
**Pulse runs every 60s:** $0
**Brain only when unhealthy:** ~$0.01 per incident
---
## 💡 Why Pulse & Brain?
### The Evolution of Monitoring
Ajarbot has had **three different monitoring systems**. Here's how they compare:
| Feature | Pulse & Brain ⭐ | TaskScheduler | Old Heartbeat ⚠️ |
|---------|-----------------|---------------|------------------|
| **Cost per day** | ~$0.04 | ~$0.10-0.30 | ~$0.48 |
| **Cost per month** | ~$1.20 | ~$3-9 | ~$14.40 |
| **Agent usage** | Only when needed | Every scheduled task | Every interval |
| **Scheduling** | Cron + Conditional | Cron only | Interval only |
| **Monitoring** | ✅ Zero-cost pulse | ❌ None | ❌ Uses agent |
| **Messaging** | ✅ Slack/Telegram | ✅ Slack/Telegram | ❌ None |
| **Best for** | Production monitoring | Content generation | ⚠️ Legacy (deprecated) |
| **Status** | ✅ Recommended | ✅ Active | ⚠️ Disabled by default |
### Why Pulse & Brain Wins
**1. Zero-Cost Monitoring**
```python
# Pulse checks run constantly at zero cost
Pulse (60s intervals, pure Python):
├─ Check disk space $0
├─ Check log errors $0
├─ Check stale tasks $0
├─ Check server health $0
└─ ... (add infinite checks, still $0)
# Brain only invoked when needed
Brain (Agent/SDK):
├─ Condition: disk > 90% → $0.01 (only if triggered)
├─ Condition: errors found → $0.01 (only if triggered)
├─ Scheduled: 8:00 AM briefing → $0.01 (once per day)
└─ Scheduled: 6:00 PM summary → $0.01 (once per day)
```
**2. Smarter Than TaskScheduler**
TaskScheduler always invokes the agent, even if there's nothing to report:
```python
# ❌ TaskScheduler: Always uses agent
- 08:00 Weather report → Agent ($0.01) even if no change
- 12:00 Midday standup → Agent ($0.01) even if no updates
- 18:00 Evening summary → Agent ($0.01) even if nothing happened
# ✅ Pulse & Brain: Conditional intelligence
- Pulse checks for changes → Python ($0)
- Brain only if updates → Agent ($0.01) only when needed
```
**3. More Flexible Than Old Heartbeat**
Old Heartbeat was simple but wasteful:
```python
# ❌ Old Heartbeat: Every 30 minutes, always uses agent
while True:
agent.chat("Check everything") # ~$0.01
time.sleep(1800) # 48 calls/day = $0.48/day
# ✅ Pulse & Brain: Smart triggers
while True:
# 1,440 pulse checks/day (pure Python) = $0
# Only 4 brain calls/day (when needed) = $0.04/day
```
### Decision Tree: Which System to Use?
```
Start here:
↓
Do you need real-time monitoring? (disk, logs, health checks)
├─ YES → Use Pulse & Brain ⭐
└─ NO → Go to next question
↓
Do you need scheduled content? (weather, summaries, reports)
├─ YES → Use TaskScheduler
└─ NO → Go to next question
↓
Do you need simple periodic checks?
└─ YES → Migrate from old Heartbeat to Pulse & Brain
Most users should: Use Pulse & Brain (+ optionally TaskScheduler for content)
```
### Hybrid Approach (Best of Both)
For maximum efficiency:
```python
# Pulse & Brain handles:
# - Health monitoring (disk, logs, tasks)
# - Morning briefing with system status
# - Evening summary
# - Error alerts
pb = PulseBrain(agent, pulse_interval=60)
pb.start()
# TaskScheduler handles ONLY:
# - Weekly newsletter (Friday 5pm)
# - Monthly metrics report (1st of month)
# - Custom scheduled content (unique reports)
scheduler = TaskScheduler(agent)
scheduler.tasks = [weekly_newsletter, monthly_report]
scheduler.start()
```
**Cost: ~$2-3/month** (vs $15/month with old heartbeat) 💰
### Real-World Cost Examples
| Use Case | System | Monthly Cost |
|----------|--------|--------------|
| **Homelab monitoring** | Pulse & Brain only | ~$1-2 |
| **Dev team bot** | Pulse & Brain + TaskScheduler | ~$4-6 |
| **Solo developer** | Pulse & Brain only | ~$0.50-1 |
| **Content bot** | TaskScheduler only | ~$4-8 |
| **Old heartbeat** | ⚠️ Legacy system | ~$15 |
### Migration Guide
**From Old Heartbeat → Pulse & Brain**
```python
# Old (heartbeat.py) ❌
agent = Agent(enable_heartbeat=True)
# New (pulse_brain.py) ✅
agent = Agent(enable_heartbeat=False)
pb = PulseBrain(agent)
pb.start()
```
**Benefit:** 92% cost reduction
**From TaskScheduler → Pulse & Brain**
If your "scheduled tasks" are really monitoring checks:
```python
# Old (scheduled_tasks.yaml) ❌
- name: health-check
schedule: "hourly"
prompt: "Check system health"
# New (pulse_brain.py) ✅
def check_health(): # Pure Python, zero cost
return {"status": "ok", "message": "Healthy"}
PulseCheck("health", check_health, interval_seconds=3600)
```
**Benefit:** 96% cost reduction
### Why Not Just Use TaskScheduler?
TaskScheduler is great for **content generation**, but wasteful for monitoring:
```python
# Example: Check disk space every hour with TaskScheduler
# Cost: 24 calls/day × 30 days = 720 calls/month = ~$7/month
# Same with Pulse & Brain:
# Pulse checks: Unlimited ($0)
# Brain only if disk > 90%: ~2 calls/month = ~$0.02/month
# Savings: $6.98/month (99.7% reduction)
```
### Why Not Just Use Old Heartbeat?
Old Heartbeat was the original system, but it's:
- **Expensive**: Uses agent for every check
- **Inflexible**: Only interval-based, no conditionals
- **Limited**: No messaging platform integration
- **Deprecated**: Disabled by default, legacy code
**Pulse & Brain replaces it entirely with 92% cost savings.**
---
## 🎯 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 |
| **Old Heartbeat** | ⚠️ Legacy (don't use) | ~$15/month |
### Recommended Stack
@@ -317,6 +554,8 @@ scheduler = TaskScheduler(agent)
scheduler.start()
```
---
## 📊 Monitoring Your Costs
```python
@@ -334,6 +573,44 @@ cost = total_tokens * 0.000003 # Claude Sonnet pricing
print(f"Estimated cost: ${cost:.4f}")
```
---
## 💰 Cost Optimization Tips
1. **Increase pulse interval** if checks don't need to be frequent
```python
pb = PulseBrain(agent, pulse_interval=300) # Every 5 min instead of 60s
```
2. **Use conditional brain tasks** instead of scheduled
```python
# ❌ Expensive: Always runs
BrainTask(schedule="daily 08:00", ...)
# ✅ Cheap: Only if there's news
BrainTask(condition=lambda: has_updates(), ...)
```
3. **Batch briefings** instead of multiple schedules
```python
# ❌ Expensive: 3 calls/day
- morning-briefing (08:00)
- midday-update (12:00)
- evening-summary (18:00)
# ✅ Cheaper: 2 calls/day
- morning-briefing (08:00)
- evening-summary (18:00)
```
4. **Make pulse checks do more** before invoking brain
```python
# Pulse checks can filter, aggregate, and pre-process
# Brain only gets invoked with actionable data
```
---
## 🚀 Getting Started
1. **Edit** `config/pulse_brain_config.py` with your checks
@@ -342,6 +619,8 @@ print(f"Estimated cost: ${cost:.4f}")
4. **Run** `python -m pulse_brain`
5. **Monitor** brain invocation count
---
## 🔥 Pro Tips
1. **Make pulse checks fast** (<1 second each)
@@ -350,6 +629,39 @@ print(f"Estimated cost: ${cost:.4f}")
4. **Test pulse checks** without brain first
5. **Monitor brain invocations** to track costs
---
## ⚠️ Legacy System Notice
### Old Heartbeat (Deprecated)
The original Heartbeat system is now **disabled by default**. It has been superseded by Pulse & Brain.
**Why it's deprecated:**
- Uses agent for every check (expensive)
- No conditional logic (always runs)
- No messaging platform integration
- Replaced entirely by Pulse & Brain
**If you're still using it:**
```python
# Old (don't use) ❌
agent = Agent(enable_heartbeat=True)
# New (migrate to this) ✅
agent = Agent(enable_heartbeat=False)
pb = PulseBrain(agent)
pb.start()
```
**Migration benefits:**
- 92% cost reduction
- Conditional intelligence
- Messaging platform support
- More flexible scheduling
---
## 🎉 Summary
**Pulse & Brain is the most cost-effective way to run a proactive agent:**