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/QUICK_START_PULSE.md
+++ b/docs/QUICK_START_PULSE.md
@@ -0,0 +1,221 @@
+# Pulse & Brain Quick Start
+
+## ❓ Will the agent arbitrarily pick tasks to monitor?
+
+**NO.** You have complete control. Here are your options:
+
+## 🎯 Three Ways to Use Pulse & Brain
+
+### Option 1: Start with Examples (Easiest)
+
+```python
+from pulse_brain import PulseBrain
+
+pb = PulseBrain(agent)  # Loads example checks
+pb.start()
+```
+
+**What this monitors:**
+- Disk space (every 5 min)
+- Memory tasks (every 10 min)
+- Log errors (every 1 min)
+- Morning briefing (8:00 AM)
+- Evening summary (6:00 PM)
+
+**Remove what you don't want:**
+```python
+pb = PulseBrain(agent)
+
+# Remove specific checks
+pb.pulse_checks = [c for c in pb.pulse_checks if c.name != "log-errors"]
+pb.brain_tasks = [t for t in pb.brain_tasks if t.name != "morning-briefing"]
+
+pb.start()
+```
+
+### Option 2: Start Clean (Recommended)
+
+```python
+from pulse_brain import PulseBrain
+
+# NO default checks loaded
+pb = PulseBrain(agent, enable_defaults=False)
+
+# Now add ONLY what YOU want
+from pulse_brain import PulseCheck
+
+def my_check():
+    return {"status": "ok", "message": "All good"}
+
+pb.pulse_checks.append(
+    PulseCheck("my-check", my_check, interval_seconds=60)
+)
+
+pb.start()
+```
+
+**What this monitors:**
+- ONLY what you explicitly add
+- Nothing else
+
+### Option 3: No Automation (Pure Chat Bot)
+
+```python
+from agent import Agent
+
+agent = Agent(provider="claude")
+
+# Don't use Pulse & Brain at all
+# Agent only responds to messages you send
+
+response = agent.chat("Check the server for me")
+```
+
+**What this monitors:**
+- Nothing automatically
+- Only responds when you message it
+
+## 📋 Quick Reference
+
+### Add a Pulse Check (Zero Cost)
+
+```python
+def check_something():
+    """Pure Python check - no agent, no tokens."""
+    # Your check logic here
+    return {
+        "status": "ok",  # or "warn" or "error"
+        "message": "Status message",
+        "data": "any data you want"
+    }
+
+pb.pulse_checks.append(
+    PulseCheck(
+        name="my-check",
+        check_func=check_something,
+        interval_seconds=300  # Every 5 minutes
+    )
+)
+```
+
+### Add a Conditional Brain Task (Uses Agent When Condition Met)
+
+```python
+from pulse_brain import BrainTask, CheckType
+
+pb.brain_tasks.append(
+    BrainTask(
+        name="my-alert",
+        check_type=CheckType.CONDITIONAL,
+        prompt_template="Something went wrong: {message}. What should I do?",
+        condition_func=lambda data: data.get("status") == "error"
+    )
+)
+```
+
+### Add a Scheduled Brain Task (Uses Agent at Specific Time)
+
+```python
+pb.brain_tasks.append(
+    BrainTask(
+        name="daily-briefing",
+        check_type=CheckType.SCHEDULED,
+        schedule_time="08:00",
+        prompt_template="Good morning! Summary please: {message}",
+        send_to_platform="slack",
+        send_to_channel="C12345"
+    )
+)
+```
+
+## 🔍 Check What Will Run BEFORE Starting
+
+```python
+pb = PulseBrain(agent)
+
+# Review before starting
+print("Pulse checks:")
+for c in pb.pulse_checks:
+    print(f"  - {c.name} (every {c.interval_seconds}s)")
+
+print("\nBrain tasks:")
+for t in pb.brain_tasks:
+    print(f"  - {t.name}")
+
+# Modify if needed
+pb.pulse_checks = []  # Clear all
+pb.brain_tasks = []   # Clear all
+
+# Add only what you want
+# ...
+
+pb.start()
+```
+
+## 💡 Recommended Setup
+
+```python
+from agent import Agent
+from pulse_brain import PulseBrain, PulseCheck, BrainTask, CheckType
+
+agent = Agent(provider="claude")
+
+# Start with ZERO automation
+pb = PulseBrain(agent, enable_defaults=False)
+
+print(f"Pulse checks: {len(pb.pulse_checks)}")  # 0
+print(f"Brain tasks: {len(pb.brain_tasks)}")     # 0
+
+# Now YOU decide what to add
+# Example: Monitor one specific thing
+def check_my_server():
+    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"}
+
+pb.pulse_checks.append(
+    PulseCheck("server", check_my_server, 60)
+)
+
+pb.brain_tasks.append(
+    BrainTask(
+        name="server-alert",
+        check_type=CheckType.CONDITIONAL,
+        prompt_template="Server is down! What should I check?",
+        condition_func=lambda d: d["status"] == "error"
+    )
+)
+
+print(f"\nNow monitoring: {[c.name for c in pb.pulse_checks]}")
+print(f"Brain tasks: {[t.name for t in pb.brain_tasks]}")
+
+pb.start()
+```
+
+## ✅ Key Takeaways
+
+1. **You control everything** - Agent doesn't pick tasks
+2. **Use `enable_defaults=False`** to start clean
+3. **Add checks explicitly** - Nothing happens automatically
+4. **Review before starting** - Print pulse_checks and brain_tasks
+5. **Agent only analyzes** - Doesn't decide what to monitor
+
+## 🎯 Answer to Your Question
+
+> "It won't arbitrarily pick tasks though right? Only tasks that I specifically ask the agent to monitor?"
+
+**Correct!**
+
+- ✅ Agent only monitors what YOU add to `pulse_checks`
+- ✅ Agent only invokes when YOUR conditions are met
+- ✅ Agent only uses prompts YOU write
+- ❌ Agent CANNOT add new monitors
+- ❌ Agent CANNOT change conditions
+- ❌ Agent CANNOT pick tasks arbitrarily
+
+**You are in complete control.** 🎛️
+
+See **[CONTROL_AND_CONFIGURATION.md](CONTROL_AND_CONFIGURATION.md)** for detailed examples.