Initial commit: Ajarbot with optimizations

Features: - Multi-platform bot (Slack, Telegram) - Memory system with SQLite FTS - Tool use capabilities (file ops, commands) - Scheduled tasks system - Dynamic model switching (/sonnet, /haiku) - Prompt caching for cost optimization Optimizations: - Default to Haiku 4.5 (12x cheaper) - Reduced context: 3 messages, 2 memory results - Optimized SOUL.md (48% smaller) - Automatic caching when using Sonnet (90% savings) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-13 19:06:28 -07:00
commit a99799bf3d
58 changed files with 11434 additions and 0 deletions
--- a/docs/MONITORING_COMPARISON.md
+++ b/docs/MONITORING_COMPARISON.md
@@ -0,0 +1,331 @@
+# 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