Files

Jordan Ramos ce2c384387 Migrate to Claude Agent SDK framework (v0.2.0)

BREAKING CHANGE: Replaced FastAPI server wrapper with direct Claude Agent SDK integration

## Major Changes

### Architecture
- **OLD:** Bot → FastAPI Server → claude-code-sdk → Claude
- **NEW:** Bot → Claude Agent SDK → Claude (Pro subscription OR API)
- Eliminated HTTP server overhead
- Single-process architecture

### LLM Backend (llm_interface.py)
- Implemented Claude Agent SDK as DEFAULT mode
- Added three-mode architecture:
  - agent-sdk (default) - Uses Pro subscription
  - direct-api - Pay-per-token Anthropic API
  - legacy-server - Backward compat with old setup
- Created async/sync bridge using anyio
- Preserved all existing functionality (17 tools, memory, scheduling)

### Dependencies (requirements.txt)
- Replaced: claude-code-sdk → claude-agent-sdk>=0.1.0
- Added: anyio>=4.0.0 for async bridging
- Removed: fastapi, uvicorn (no longer needed for default mode)

### New Files
- ajarbot.py - Unified launcher with pre-flight checks
- run.bat - Windows one-command launcher (auto-setup)
- pyproject.toml - Python package metadata
- MIGRATION.md - Upgrade guide from old setup
- AGENT_SDK_IMPLEMENTATION.md - Technical documentation
- QUICK_REFERENCE_AGENT_SDK.md - Quick reference card
- test_agent_sdk.py - Comprehensive test suite

### Updated Documentation
- CLAUDE_CODE_SETUP.md - Rewritten for Agent SDK
- README.md - Updated quick start for new default
- .env.example - Added AJARBOT_LLM_MODE configuration

### Deleted Files
- claude_code_server.py - Replaced by agent-sdk integration
- heartbeat.py - Superseded by scheduled_tasks.py
- pulse_brain.py - Unused in production

## Migration Path

Old setup:
1. Start FastAPI server: python claude_code_server.py
2. Start bot: python bot_runner.py
3. Set USE_CLAUDE_CODE_SERVER=true

New setup:
1. Run: run.bat (or python ajarbot.py)
   - That's it! Single command.

## Benefits

✅ Zero API costs (uses Claude Pro subscription)
✅ Simplified deployment (no separate server)
✅ Single-command launch (run.bat)
✅ Faster response times (no HTTP overhead)
✅ All functionality preserved (17 tools, memory, adapters)
✅ Backward compatible (old env vars still work)

## Compatibility

- Python 3.10+ required
- Node.js required (for Claude Code CLI bundled with SDK)
- Windows 11 tested and optimized
- All existing tools, memory system, and adapters unchanged

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-15 10:03:11 -07:00

2.7 KiB

Raw Blame History

Agent SDK Quick Reference Card

🚀 Quick Start

# Install dependencies
pip install -r requirements.txt

# Run bot (Agent SDK is default)
python bot_runner.py

📋 Mode Selection

Agent SDK (Default)

# No config needed - this is the default!
# Or explicitly:
USE_AGENT_SDK=true

✅ Uses Claude Pro subscription (no API costs)

Direct API

USE_DIRECT_API=true
ANTHROPIC_API_KEY=sk-ant-...

✅ Pay-per-token, usage tracking enabled

Legacy Server

USE_CLAUDE_CODE_SERVER=true
CLAUDE_CODE_SERVER_URL=http://localhost:8000

⚠️ Deprecated, not recommended

🔍 Verify Mode

Check startup message:

[LLM] Using Claude Agent SDK (Pro subscription)  ← Agent SDK ✅
[LLM] Using Direct API (pay-per-token)          ← Direct API 💳
[LLM] Using Claude Code server at ...           ← Legacy ⚠️

🧪 Test Installation

python test_agent_sdk.py

Expected: 5/5 tests passed 🎉

🛠️ Troubleshooting

Issue: Fallback to Direct API

pip install claude-agent-sdk anyio

Issue: ModuleNotFoundError

pip install -r requirements.txt

Issue: Still using old mode

# Edit .env and remove conflicting variables
USE_DIRECT_API=false  # or remove line

📊 Priority Order

1. USE_DIRECT_API=true     → Direct API
2. USE_CLAUDE_CODE_SERVER  → Legacy
3. USE_AGENT_SDK (default) → Agent SDK
4. SDK unavailable         → Fallback to Direct API

💰 Cost Comparison

Mode	Cost per 1M tokens
Agent SDK	$0 (Pro subscription)
Direct API (Haiku)	$0.25 - $1.25
Direct API (Sonnet)	$3.00 - $15.00

🎯 Key Files

File	Purpose
`llm_interface.py`	Core implementation
`requirements.txt`	Dependencies
`test_agent_sdk.py`	Test suite
`.env`	Configuration

📚 Documentation

AGENT_SDK_IMPLEMENTATION.md - Full technical details
MIGRATION_GUIDE_AGENT_SDK.md - Step-by-step migration
IMPLEMENTATION_SUMMARY.md - Executive summary
QUICK_REFERENCE_AGENT_SDK.md - This file

✅ Features Preserved

✅ All 17 tools (file ops, Gmail, Calendar) ✅ Scheduled tasks ✅ Memory system ✅ Self-healing system ✅ Telegram adapter ✅ Slack adapter ✅ Model switching (/sonnet, /haiku) ✅ Usage tracking (Direct API mode)

🔄 Rollback

# Quick rollback to Direct API
USE_DIRECT_API=true
ANTHROPIC_API_KEY=sk-ant-...

Restart bot. Done! ✅

📞 Support

Check logs: Look for [LLM] messages
Run tests: python test_agent_sdk.py
Check mode: Verify startup message
Review docs: See files above

Version: 1.0.0 Date: 2026-02-15 Status: ✅ Production Ready

2.7 KiB Raw Blame History