ajarbot/MIGRATION.md

# Migration Guide: FastAPI Server to Agent SDK

This guide helps you upgrade from the old FastAPI server setup to the new Claude Agent SDK integration.

## What Changed?

### Old Architecture (Deprecated)
```
Bot → FastAPI Server (localhost:8000) → Claude Code SDK → Claude
```
- Required running `claude_code_server.py` in separate terminal
- Only worked with Pro subscription
- More complex setup with multiple processes

### New Architecture (Current)
```
Bot → Claude Agent SDK → Claude (Pro OR API)
```
- Single process (no separate server)
- Works with Pro subscription OR API key
- Simpler setup and operation
- Same functionality, less complexity

## Migration Steps

### Step 1: Update Dependencies

Pull latest code and reinstall dependencies:

```bash
git pull
pip install -r requirements.txt
```

This installs `claude-agent-sdk` and removes deprecated dependencies.

### Step 2: Update Environment Configuration

Edit your `.env` file:

**Remove these deprecated variables:**
```bash
# DELETE THESE
USE_CLAUDE_CODE_SERVER=true
CLAUDE_CODE_SERVER_URL=http://localhost:8000
```

**Add new mode selection:**
```bash
# ADD THIS
AJARBOT_LLM_MODE=agent-sdk  # Use Pro subscription (default)
# OR
AJARBOT_LLM_MODE=api        # Use pay-per-token API
```

**If using API mode**, ensure you have:
```bash
ANTHROPIC_API_KEY=sk-ant-...
```

**If using agent-sdk mode**, authenticate once:
```bash
claude auth login
```

### Step 3: Stop Old Server

The FastAPI server is no longer needed:

1. Stop any running `claude_code_server.py` processes
2. Remove it from startup scripts/systemd services
3. Optionally archive or delete `claude_code_server.py` (kept for reference)

### Step 4: Use New Launcher

**Old way:**
```bash
# Terminal 1
python claude_code_server.py

# Terminal 2
python bot_runner.py
```

**New way:**
```bash
# Single command
run.bat              # Windows
python ajarbot.py    # Linux/Mac
```

The new launcher:
- Runs pre-flight checks (Node.js, authentication, config)
- Sets sensible defaults (agent-sdk mode)
- Starts bot in single process
- No separate server needed

### Step 5: Test Your Setup

Run health check:
```bash
python ajarbot.py --health
```

Expected output (agent-sdk mode):
```
============================================================
Ajarbot Pre-Flight Checks
============================================================

✓ Python 3.10.x
✓ Node.js found: v18.x.x
✓ Claude CLI authenticated

[Configuration Checks]
✓ Config file found: config/adapters.local.yaml

Pre-flight checks complete!
============================================================
```

### Step 6: Verify Functionality

Test that everything works:

1. **Start the bot:**
   ```bash
   run.bat  # or python ajarbot.py
   ```

2. **Send a test message** via Slack/Telegram

3. **Verify tools work:**
   - Ask bot to read a file
   - Request calendar events
   - Test scheduled tasks

All features are preserved:
- 15 tools (file ops, Gmail, Calendar, Contacts)
- Memory system with hybrid search
- Multi-platform adapters
- Task scheduling

## Mode Comparison

Choose the mode that fits your use case:

| Feature | Agent SDK Mode | API Mode |
|---------|---------------|----------|
| **Cost** | $20/month (Pro) | ~$0.25-$3/M tokens |
| **Setup** | `claude auth login` | API key in `.env` |
| **Requirements** | Node.js + Claude CLI | Just Python |
| **Best For** | Personal heavy use | Light use, production |
| **Rate Limits** | Pro subscription limits | API rate limits |

### Switching Between Modes

You can switch anytime by editing `.env`:

```bash
# Switch to agent-sdk
AJARBOT_LLM_MODE=agent-sdk

# Switch to API
AJARBOT_LLM_MODE=api
ANTHROPIC_API_KEY=sk-ant-...
```

No code changes needed - just restart the bot.

## Troubleshooting

### "Node.js not found" (Agent SDK mode)

**Option 1: Install Node.js**
```bash
# Download from https://nodejs.org
# Or via package manager:
winget install OpenJS.NodeJS  # Windows
brew install node             # Mac
sudo apt install nodejs       # Ubuntu/Debian
```

**Option 2: Switch to API mode**
```bash
# In .env
AJARBOT_LLM_MODE=api
ANTHROPIC_API_KEY=sk-ant-...
```

### "Claude CLI not authenticated"

```bash
# Check status
claude auth status

# Re-authenticate
claude auth logout
claude auth login
```

If Claude CLI isn't installed, download from: https://claude.ai/download

### "Agent SDK not available"

```bash
pip install claude-agent-sdk
```

If installation fails, use API mode instead.

### Old Environment Variables Still Set

Check your `.env` file for deprecated variables:

```bash
# These should NOT be in your .env:
USE_CLAUDE_CODE_SERVER=true
CLAUDE_CODE_SERVER_URL=http://localhost:8000
USE_AGENT_SDK=true
USE_DIRECT_API=true
```

Delete them and use `AJARBOT_LLM_MODE` instead.

### Bot Works But Features Missing

Ensure you have latest code:
```bash
git pull
pip install -r requirements.txt --upgrade
```

All features from the old setup are preserved:
- Tools system (15 tools)
- Memory with hybrid search
- Scheduled tasks
- Google integration
- Multi-platform adapters

### Performance Issues

**Agent SDK mode:**
- May hit Pro subscription rate limits
- Temporary solution: Switch to API mode
- Long-term: Wait for limit reset (usually 24 hours)

**API mode:**
- Check usage with: `python -c "from usage_tracker import UsageTracker; UsageTracker().print_summary()"`
- Costs shown in usage_data.json
- Default Haiku model is very cheap (~$0.04/day moderate use)

## Rollback Plan

If you need to rollback to the old setup:

1. **Restore old .env settings:**
   ```bash
   USE_CLAUDE_CODE_SERVER=true
   CLAUDE_CODE_SERVER_URL=http://localhost:8000
   ```

2. **Start the old server:**
   ```bash
   python claude_code_server.py
   ```

3. **Run bot with old method:**
   ```bash
   python bot_runner.py
   ```

However, the new setup is recommended - same functionality with less complexity.

## What's Backward Compatible?

All existing functionality is preserved:

- Configuration files (`config/adapters.local.yaml`, `config/scheduled_tasks.yaml`)
- Memory database (`memory_workspace/memory.db`)
- User profiles (`memory_workspace/users/`)
- Google OAuth tokens (`config/google_oauth_token.json`)
- Tool definitions and capabilities
- Adapter integrations

You can safely migrate without losing data or functionality.

## Benefits of New Setup

1. **Simpler operation**: Single command to start
2. **Flexible modes**: Choose Pro subscription OR API
3. **Automatic checks**: Pre-flight validation before starting
4. **Better errors**: Clear messages about missing requirements
5. **Less complexity**: No multi-process coordination
6. **Same features**: All 15 tools, adapters, scheduling preserved

## Need Help?

- Review [CLAUDE_CODE_SETUP.md](CLAUDE_CODE_SETUP.md) for detailed mode documentation
- Check [README.md](README.md) for quick start guides
- Run `python ajarbot.py --health` to diagnose issues
- Open an issue if you encounter problems

## Summary

**Before:**
```bash
# Terminal 1
python claude_code_server.py

# Terminal 2
python bot_runner.py
```

**After:**
```bash
# .env
AJARBOT_LLM_MODE=agent-sdk  # or "api"

# Single command
run.bat  # Windows
python ajarbot.py  # Linux/Mac
```

Same features, less complexity, more flexibility.