ajarbot/docs/MONITORING_COMPARISON.md

# Monitoring Systems Comparison

Ajarbot now has **three different monitoring systems**. Here's how to choose the right one.

## 📊 Quick Comparison

| 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 | Simple setups |

## 🏆 Recommended: Pulse & Brain

**Use this for production monitoring.**

### How It Works

```
Pulse (60s intervals, pure Python):
  ├─ Check disk space       $0
  ├─ Check log errors       $0
  ├─ Check stale tasks      $0
  ├─ Check server health    $0
  └─ ... (add more)

Brain (Agent/SDK, only when triggered):
  ├─ Condition: disk > 90%        → Invoke agent ($0.01)
  ├─ Condition: errors found      → Invoke agent ($0.01)
  ├─ Scheduled: 8:00 AM briefing  → Invoke agent ($0.01)
  └─ Scheduled: 6:00 PM summary   → Invoke agent ($0.01)
```

### Example Setup

```python
from pulse_brain import PulseBrain

pb = PulseBrain(agent, pulse_interval=60)
pb.add_adapter("slack", slack_adapter)
pb.start()
```

### Cost Breakdown

**Pulse checks:** 1,440/day (every 60s) = **$0**
**Brain invocations:** ~4/day (only when needed) = **~$0.04/day**

**Total: ~$1.20/month** 💰

### When to Use

✅ Production monitoring
✅ Server health checks
✅ Log analysis
✅ Resource alerts
✅ Daily briefings
✅ Cost-conscious deployments

## 🎯 Alternative: TaskScheduler

**Use this for content generation only.**

### How It Works

```
Every task runs on schedule (always uses Agent):
  ├─ 08:00 Weather report      → Agent ($0.01)
  ├─ 12:00 Midday standup      → Agent ($0.01)
  ├─ 18:00 Evening summary     → Agent ($0.01)
  └─ Fri 17:00 Weekly review   → Agent ($0.02)
```

### Example Setup

```python
from scheduled_tasks import TaskScheduler

scheduler = TaskScheduler(agent)
scheduler.add_adapter("slack", slack_adapter)
scheduler.start()
```

### Cost Breakdown

**If you have:**
- 2 daily tasks (morning/evening) = 60 calls/month = ~$6/month
- 1 weekly task (Friday summary) = 4 calls/month = ~$0.80/month

**Total: ~$6.80/month**

### When to Use

✅ Scheduled content generation
✅ Weather reports
✅ Daily summaries
✅ Weekly newsletters
✅ Team standups
❌ Real-time monitoring (use Pulse & Brain instead)

## 💡 Hybrid Approach (Best of Both)

**Recommended for most users:**

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

# TaskScheduler ONLY for specific content tasks
scheduler = TaskScheduler(agent)
# Enable only tasks that generate unique content
# (Don't duplicate with Pulse & Brain briefings)
scheduler.start()
```

### Example Hybrid Config

**Pulse & Brain handles:**
- Health monitoring (disk, logs, tasks)
- Morning briefing with system status
- Evening summary
- Error alerts

**TaskScheduler handles:**
- Weekly newsletter (Friday 5pm)
- Monthly metrics report (1st of month)
- Custom scheduled reports

**Cost: ~$2-3/month** (vs $15/month with old heartbeat)

## 🔧 Configuration Examples

### Minimal Monitoring (Cheapest)

**Just Pulse & Brain, no scheduled content:**

```python
pb = PulseBrain(agent, pulse_interval=60)
# Only conditional tasks (error alerts)
# Remove scheduled briefings
pb.start()
```

**Cost: ~$0.20/month** (only when errors occur)

### Full Monitoring + Content (Balanced)

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

# TaskScheduler for weekly/monthly content only
scheduler = TaskScheduler(agent)
scheduler.tasks = [weekly_newsletter, monthly_report]  # Only specific tasks
scheduler.start()
```

**Cost: ~$2-4/month**

### Maximum Features (Still Efficient)

```python
# Pulse & Brain with custom checks
pb = PulseBrain(agent, pulse_interval=60)
apply_custom_config(pb)  # Homelab, Docker, GPU, etc.
pb.start()

# TaskScheduler for all content
scheduler = TaskScheduler(agent)
scheduler.start()
```

**Cost: ~$5-8/month**

## 📈 Real-World Examples

### Example 1: Personal Homelab

**Goal:** Monitor servers, get daily briefings

**Solution:**
```python
pb = PulseBrain(agent, pulse_interval=120)  # Check every 2 minutes
# Pulse checks: Plex, UniFi, Docker, disk, GPU
# Brain tasks: Morning briefing, error alerts
```

**Cost: ~$1-2/month**

### Example 2: Development Team Bot

**Goal:** Daily standups, build notifications

**Solution:**
```python
# Pulse & Brain for build failures
pb = PulseBrain(agent, pulse_interval=60)
# Conditional: CI/CD failures

# TaskScheduler for standups
scheduler = TaskScheduler(agent)
# Daily 9am standup reminder
# Daily 5pm build summary
```

**Cost: ~$4-6/month**

### Example 3: Solo Developer

**Goal:** Track tasks, get weekly summaries

**Solution:**
```python
# Just Pulse & Brain
pb = PulseBrain(agent, pulse_interval=300)  # Every 5 minutes
# Pulse: Check pending tasks
# Brain: Friday evening weekly review
```

**Cost: ~$0.50-1/month**

## 🎓 Decision Tree

```
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 → Use old Heartbeat (or upgrade to Pulse & Brain)

Most users should: Use Pulse & Brain (+ optionally TaskScheduler for content)
```

## 💰 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
   ```

## 🚀 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 (hourly checks)

## 📝 Summary

| Your Need | Use This | Monthly Cost |
|-----------|----------|--------------|
| **Monitoring only** | Pulse & Brain | ~$1-2 |
| **Content only** | TaskScheduler | ~$4-8 |
| **Monitoring + Content** | Both | ~$3-6 |
| **Simple checks** | Old Heartbeat | ~$15 |

**Winner:** Pulse & Brain for 99% of use cases 🏆

**Files:**
- `pulse_brain.py` - Main system
- `config/pulse_brain_config.py` - Custom checks
- `example_bot_with_pulse_brain.py` - Full example
- `PULSE_BRAIN.md` - Complete documentation