ajarbot/docs/QUICK_START_PULSE.md

# 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.