Jordan Ramos
ab3a5afd59
Removed redundant/outdated files: - docs/HEARTBEAT_HOOKS.md (legacy, disabled by default) - docs/QUICK_START_PULSE.md (merged into PULSE_BRAIN.md) - docs/MONITORING_COMPARISON.md (merged into PULSE_BRAIN.md) Consolidated monitoring docs: - Merged 3 monitoring files into comprehensive PULSE_BRAIN.md - Added Quick Start section to PULSE_BRAIN.md - Added "Why Pulse & Brain?" comparison section - Added deprecation notices for Heartbeat system Updated README.md: - Clarified Haiku is default model (12x cheaper) - Added prompt caching info (90% savings on Sonnet) - Removed duplicate setup instructions - Linked to SETUP.md for detailed instructions - Added model switching commands section Simplified WINDOWS_QUICK_REFERENCE.md: - Reduced from 224 lines to ~160 lines - Removed redundant development/deployment sections - Kept essential quick commands - Added model switching commands Updated docs/README.md navigation: - Removed references to deleted files - Added deprecation notice for Heartbeat - Updated learning paths - Cleaned up file organization section Result: - Removed 300+ lines of redundant documentation - Consolidated 3 monitoring files into 1 - Improved accuracy and clarity - Easier navigation and maintenance Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
269 lines
8.1 KiB
Markdown
269 lines
8.1 KiB
Markdown
# Ajarbot Documentation
|
|
|
|
Complete documentation for Ajarbot - a lightweight, cost-effective AI agent framework.
|
|
|
|
## Quick Navigation
|
|
|
|
### Getting Started (Start Here)
|
|
|
|
| Document | Description | Time to Read |
|
|
|----------|-------------|--------------|
|
|
| [Quick Start Guide](QUICKSTART.md) | 30-second setup and basic agent usage | 5 min |
|
|
| [Complete Setup Guide](../SETUP.md) | Comprehensive setup with API keys, config, troubleshooting | 10 min |
|
|
|
|
### Core Systems
|
|
|
|
| Document | Description | Best For |
|
|
|----------|-------------|----------|
|
|
| [Pulse & Brain Architecture](PULSE_BRAIN.md) | Cost-effective monitoring (92% savings) with Quick Start | Production monitoring, homelab |
|
|
| [Memory System](README_MEMORY.md) | SQLite-based memory management | Understanding context/memory |
|
|
| [Scheduled Tasks](SCHEDULED_TASKS.md) | Cron-like task scheduling | Daily briefings, reports |
|
|
|
|
### Platform Integration
|
|
|
|
| Document | Description | Best For |
|
|
|----------|-------------|----------|
|
|
| [Adapters Guide](README_ADAPTERS.md) | Multi-platform messaging (Slack, Telegram) | Running bots on chat platforms |
|
|
| [Skills Integration](SKILLS_INTEGRATION.md) | Claude Code skills from messaging platforms | Advanced bot capabilities |
|
|
|
|
### Configuration
|
|
|
|
| Document | Description | Best For |
|
|
|----------|-------------|----------|
|
|
| [Control & Configuration](CONTROL_AND_CONFIGURATION.md) | Configuration management | Customizing behavior |
|
|
| [Windows Deployment](WINDOWS_DEPLOYMENT.md) | Complete Windows setup guide | Windows users |
|
|
|
|
---
|
|
|
|
> **⚠️ Note on Heartbeat System**: The Heartbeat monitoring system is legacy and disabled by default. Use **Pulse & Brain** instead for 92% cost savings. Heartbeat documentation has been removed - see [PULSE_BRAIN.md](PULSE_BRAIN.md) for the recommended approach.
|
|
|
|
## Learning Paths
|
|
|
|
### Path 1: Simple Agent (10 minutes)
|
|
|
|
Perfect for quick prototypes or single-user use:
|
|
|
|
1. Read [Quick Start Guide](QUICKSTART.md)
|
|
2. Run `example_usage.py`
|
|
3. Explore [Memory System](README_MEMORY.md)
|
|
|
|
**What you'll learn:**
|
|
- Basic agent setup
|
|
- Memory operations
|
|
- Task management
|
|
- Model switching
|
|
|
|
### Path 2: Multi-Platform Bot (20 minutes)
|
|
|
|
For running bots on Slack, Telegram, or both:
|
|
|
|
1. Read [Quick Start Guide](QUICKSTART.md)
|
|
2. Read [Adapters Guide](README_ADAPTERS.md)
|
|
3. Run `bot_runner.py --init`
|
|
4. Configure platforms in `config/adapters.local.yaml`
|
|
5. Run `bot_runner.py`
|
|
|
|
**What you'll learn:**
|
|
- Platform adapter setup
|
|
- Multi-platform message routing
|
|
- User mapping across platforms
|
|
- Custom preprocessors/postprocessors
|
|
|
|
### Path 3: Production Monitoring (20 minutes)
|
|
|
|
For cost-effective production deployments:
|
|
|
|
1. Read [Pulse & Brain Architecture](PULSE_BRAIN.md) - includes Quick Start section
|
|
2. Run `example_bot_with_pulse_brain.py`
|
|
3. Create custom pulse checks
|
|
4. Configure custom brain tasks
|
|
|
|
**What you'll learn:**
|
|
- Pulse checks (zero-cost monitoring)
|
|
- Conditional brain tasks (only when needed)
|
|
- Scheduled brain tasks (daily summaries)
|
|
- Cost optimization (92% savings vs traditional monitoring)
|
|
|
|
### Path 4: Advanced Features (45 minutes)
|
|
|
|
For full-featured production bots:
|
|
|
|
1. Complete Path 2 and Path 3
|
|
2. Read [Scheduled Tasks](SCHEDULED_TASKS.md)
|
|
3. Read [Skills Integration](SKILLS_INTEGRATION.md)
|
|
4. Run `example_bot_with_skills.py`
|
|
5. Create custom skills
|
|
|
|
**What you'll learn:**
|
|
- Task scheduling with cron syntax
|
|
- Skills from messaging platforms
|
|
- Custom skill creation
|
|
- Security best practices
|
|
|
|
## Document Summaries
|
|
|
|
### QUICKSTART.md
|
|
30-second setup guide covering:
|
|
- Installation (pip install)
|
|
- Basic agent usage
|
|
- Memory operations
|
|
- Task tracking
|
|
- Context retrieval
|
|
|
|
**Key takeaway:** Get an agent running with memory in under a minute.
|
|
|
|
### PULSE_BRAIN.md
|
|
Comprehensive guide to the Pulse & Brain architecture:
|
|
- Quick Start section for immediate setup
|
|
- Why continuous polling is expensive ($0.48/day)
|
|
- How Pulse & Brain saves 92% ($0.04/day)
|
|
- Comparison with traditional monitoring (Heartbeat)
|
|
- Default pulse checks and brain tasks
|
|
- Custom configuration examples
|
|
- Real-world use cases (homelab, Docker monitoring)
|
|
|
|
**Key takeaway:** Run proactive monitoring at 1/10th the cost with Quick Start included.
|
|
|
|
### README_ADAPTERS.md
|
|
Multi-platform adapter system:
|
|
- Architecture overview
|
|
- Slack setup (Socket Mode)
|
|
- Telegram setup (polling)
|
|
- User mapping across platforms
|
|
- Adding new adapters
|
|
- Comparison with OpenClaw
|
|
|
|
**Key takeaway:** Run one bot on multiple platforms simultaneously.
|
|
|
|
### SKILLS_INTEGRATION.md
|
|
Claude Code skills in messaging platforms:
|
|
- Architecture overview
|
|
- Enabling skills in bots
|
|
- Creating custom skills
|
|
- Security best practices
|
|
- Skill arguments and metrics
|
|
|
|
**Key takeaway:** Invoke local Claude Code skills from Slack/Telegram.
|
|
|
|
### SCHEDULED_TASKS.md
|
|
Cron-like task scheduling:
|
|
- Task scheduler setup
|
|
- Schedule syntax (daily, weekly, cron)
|
|
- Recurring vs one-time tasks
|
|
- Task callbacks and error handling
|
|
- Multi-platform task routing
|
|
|
|
**Key takeaway:** Schedule recurring bot activities (reports, briefings, etc.).
|
|
|
|
### README_MEMORY.md
|
|
SQLite-based memory system:
|
|
- Memory architecture
|
|
- SOUL (personality) management
|
|
- User preferences
|
|
- Task system
|
|
- Full-text search (FTS5)
|
|
- Conversation history
|
|
|
|
**Key takeaway:** Automatic context loading with fast retrieval.
|
|
|
|
### CONTROL_AND_CONFIGURATION.md
|
|
Configuration management:
|
|
- Configuration file structure
|
|
- Environment variables
|
|
- Adapter configuration
|
|
- Pulse & Brain configuration
|
|
- Security considerations
|
|
|
|
**Key takeaway:** Centralized configuration for all components.
|
|
|
|
## Common Questions
|
|
|
|
### Q: Which monitoring system should I use?
|
|
|
|
**A:** Use **Pulse & Brain** for production. It's 92% cheaper and more flexible.
|
|
|
|
- **Pulse & Brain**: ~$1-2/month (recommended)
|
|
- **Heartbeat**: ~$15/month (legacy, disabled by default)
|
|
|
|
See [PULSE_BRAIN.md](PULSE_BRAIN.md) for details including comparison and migration guide.
|
|
|
|
### Q: Can I run my bot on multiple platforms?
|
|
|
|
**A:** Yes! See [Adapters Guide](README_ADAPTERS.md).
|
|
|
|
Example: Run the same bot on Slack and Telegram simultaneously with unified memory.
|
|
|
|
### Q: How does memory work?
|
|
|
|
**A:** Agent automatically loads:
|
|
1. SOUL.md (personality)
|
|
2. users/{username}.md (user preferences)
|
|
3. Search results (top 3 relevant chunks)
|
|
4. Recent conversation (last 5 messages)
|
|
|
|
See [Memory System](README_MEMORY.md) for details.
|
|
|
|
### Q: How do I schedule recurring tasks?
|
|
|
|
**A:** Use TaskScheduler. See [Scheduled Tasks](SCHEDULED_TASKS.md).
|
|
|
|
```python
|
|
task = ScheduledTask("morning", "Daily brief", schedule="08:00")
|
|
scheduler.add_task(task)
|
|
scheduler.start()
|
|
```
|
|
|
|
### Q: Can I use skills from messaging platforms?
|
|
|
|
**A:** Yes! See [Skills Integration](SKILLS_INTEGRATION.md).
|
|
|
|
From Slack: `@bot /code-review src/agent.py`
|
|
|
|
### Q: Which LLM providers are supported?
|
|
|
|
**A:** Currently:
|
|
- Claude (Anthropic) - Primary
|
|
- GLM (z.ai) - Alternative
|
|
|
|
Model switching: `agent.switch_model("glm")`
|
|
|
|
## File Organization
|
|
|
|
```
|
|
docs/
|
|
├── README.md # This file - navigation hub
|
|
├── QUICKSTART.md # Start here (30 seconds)
|
|
├── PULSE_BRAIN.md # Monitoring guide (includes Quick Start & comparison)
|
|
├── README_ADAPTERS.md # Multi-platform adapters
|
|
├── README_MEMORY.md # Memory system
|
|
├── SKILLS_INTEGRATION.md # Skills from messaging
|
|
├── SCHEDULED_TASKS.md # Task scheduling
|
|
├── CONTROL_AND_CONFIGURATION.md # Configuration guide
|
|
├── WINDOWS_DEPLOYMENT.md # Windows-specific setup
|
|
└── SECURITY_AUDIT_SUMMARY.md # Security audit report
|
|
```
|
|
|
|
## Getting Help
|
|
|
|
If you can't find what you're looking for:
|
|
|
|
1. Check the [main README](../README.md) for overview
|
|
2. Run the examples in the project root
|
|
3. Review test files (`test_*.py`)
|
|
4. Open an issue on GitHub
|
|
|
|
## Contributing to Documentation
|
|
|
|
When adding new documentation:
|
|
|
|
1. Add entry to this index
|
|
2. Update relevant learning paths
|
|
3. Add to common questions if applicable
|
|
4. Follow existing document structure
|
|
5. Include code examples
|
|
6. Add to appropriate section
|
|
|
|
---
|
|
|
|
**Happy building!** Start with the [Quick Start Guide](QUICKSTART.md) and explore from there.
|