🤖 R2D2 Bot

OpenClaw-like Personal Assistant with Low Operational Cost

R2D2 is an autonomous personal assistant bot inspired by OpenClaw, designed to run on your own infrastructure with minimal operational costs. Unlike cloud-based AI assistants, R2D2 gives you full control over your data and can be deployed anywhere.

---

🌟 Key Features

💰 Low Cost Operation

• Free LLM Options: Supports Google Gemini (15 RPM free tier)
• Affordable Alternatives: GLM 4.7 ($1/M tokens), Kimi k2.5 ($0.60/M tokens)
• Smart Routing: Automatically routes to cheaper models first
• Self-Hosted: No subscription fees, run on your own server

🛠️ Real Web Scraping Tools

• Search Engines: Brave, Google, Yandex (Playwright-based)
• Travel: Google Flights & Hotels scraping
• Local Business: Google Maps & Reviews extraction
• Communication: WhatsApp CLI integration

🧠 Autonomous Capabilities

• Self-Healing: Automatic retry with exponential backoff
• Self-Improvement: Learns from failures using ChromaDB
• External Validation: Fact-checks responses with web search
• Context Management: Smart conversation history with sliding window

🔄 OpenClaw-like Architecture

• Tool-Based: Modular tool system with automatic registration
• Function Calling: Native LLM function calling support
• Multi-Provider: Seamless fallback between LLM providers
• Memory: Semantic search (ChromaDB) + SQL history

---

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• At least 1 LLM API key (Gemini recommended for free tier)
• Telegram Bot Token (get from @BotFather)

Installation

1. Clone the repository

git clone https://github.com/helioneto144/r2d2_bot.git
cd r2d2_bot

2. Configure environment

cp .env.template .env
nano .env  # Add your API keys

3. Start with Docker

docker compose up -d

4. Check logs

docker logs telegram-bot --tail 50

---

📊 Architecture

Components

r2d2_bot/
├── core/                  # Core orchestration
│   ├── orchestrator.py    # Main coordinator
│   ├── context_manager.py # Conversation context
│   └── config_loader.py   # Settings management
├── llm_router/            # LLM provider routing
│   ├── router.py          # Smart routing logic
│   └── providers/         # LLM implementations
│       ├── gemini.py      # Google Gemini
│       ├── moonshot.py    # Kimi (Moonshot)
│       └── zai.py         # GLM (Z.AI)
├── memory/                # Persistence layer
│   ├── semantic_search.py # ChromaDB integration
│   └── conversation_store.py # SQLite history
├── tools/                 # Tool system
│   ├── registry.py        # Auto-discovery
│   └── built_in/          # Built-in tools
│       ├── google_search.py
│       ├── google_flights.py
│       ├── google_hotels.py
│       └── ...
├── self_heal/             # Autonomous features
│   ├── auto_repair.py     # Retry & fallback
│   ├── self_improve.py    # Learning from errors
│   └── external_validator.py # Fact-checking
└── interfaces/            # User interfaces
    └── telegram_bot.py    # Telegram integration

LLM Routing Strategy

User Query → Router
              ↓
        ┌─────┴─────┐
        │   GLM 4.7  │ ($1.00/M) - Fastest, cheapest
        │   (Z.AI)   │
        └─────┬─────┘
              ↓ (if fails)
        ┌─────┴─────┐
        │  Kimi k2.5 │ ($0.60/M) - Balanced
        │ (Moonshot) │
        └─────┬─────┘
              ↓ (if fails)
        ┌─────┴─────┐
        │  Gemini 3  │ (FREE 15 RPM) - Fallback
        │   Flash    │
        └───────────┘

---

🔧 Available Tools

🔍 Web Search

Tool	Technology	Cost
brave_search	Brave API	$5/month (1M queries)
google_search	Playwright scraping	Free
yandex_search	Playwright scraping	Free

✈️ Travel

Tool	Technology	Cost
google_flights	Playwright scraping	Free
google_hotels	Playwright scraping	Free

📍 Location & Reviews

Tool	Technology	Cost
google_maps_scraper	Docker (gosom/google-maps-scraper)	Free
google_reviews	Playwright scraping	Free

💬 Communication

Tool	Technology	Cost
whatsapp_cli	Go binary (vicentereig/whatsapp-cli)	Free

---

💡 Usage Examples

Telegram Commands

/start    - Start conversation
/help     - Show help
/new      - Clear context, start fresh
/tools    - List available tools
/status   - Show system status

Natural Language Queries

"busque voos de GRU para GIG amanhã"
→ Uses google_flights tool with Playwright

"procure hotéis em São Paulo"
→ Uses google_hotels tool

"o que você pode fazer?"
→ Lists real capabilities (no hallucinated features)

---

🎯 Why R2D2 vs Commercial Alternatives?

Feature	R2D2	ChatGPT Plus	Claude Pro
Monthly Cost	~$5-10	$20	$20
Data Privacy	✅ Self-hosted	❌ Cloud	❌ Cloud
Custom Tools	✅ Easy to add	❌ Limited	❌ Limited
LLM Choice	✅ Multi-provider	❌ OpenAI only	❌ Anthropic only
Rate Limits	✅ Configurable	⚠️ Fixed	⚠️ Fixed
Open Source	✅ MIT License	❌ Proprietary	❌ Proprietary

---

🧩 Adding Custom Tools

1. Create a new tool file in tools/built_in/:

from tools.base import BaseTool, ToolParam

class MyCustomTool(BaseTool):
    name = "my_custom_tool"
    description = "Does something useful"

    parameters = [
        ToolParam(
            name="query",
            type="string",
            description="What to search for",
            required=True
        )
    ]

    def execute(self, query: str) -> dict:
        # Your logic here
        return {
            "success": True,
            "data": {"result": "..."}
        }

2. That's it! The tool will be auto-discovered and available to the LLM.

---

🔐 Security Best Practices

1. Never commit credentials

   • Use .env file (already in .gitignore)
   • Use environment variables in production

2. API Key rotation

   • Rotate keys periodically
   • Use separate keys for dev/prod

3. Rate limiting

   • Configure per-provider limits in llm_router/rate_limiter.py
   • Prevents API abuse and cost overruns

4. Input validation

   • All tools validate inputs
   • SQL injection protection in conversation store

---

📈 Cost Estimation

Minimal Setup (Free Tier)

Gemini 3 Flash: FREE (15 RPM)
Hosting: $5/month (VPS)
Total: $5/month

Recommended Setup

GLM 4.7 (primary): ~$3/month (moderate use)
Gemini 3 Flash (fallback): FREE
Hosting: $10/month (better VPS)
Total: $13/month

Power User

GLM 4.7 + Kimi k2.5: ~$10/month
Brave Search API: $5/month
Hosting: $15/month (high-performance)
Total: $30/month

Still 33% cheaper than ChatGPT Plus!

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium

# Run tests
pytest

---

📝 Roadmap

• Web dashboard (FastAPI + React)
• Voice interface (Whisper integration)
• Mobile app (React Native)
• More LLM providers (OpenAI, Anthropic, Cohere)
• Tool marketplace (community-contributed tools)
• Multi-user support
• Conversation sharing & export

---

🐛 Troubleshooting

Bot not responding

# Check if container is running
docker ps

# View logs
docker logs telegram-bot --tail 100

# Restart bot
docker compose restart telegram_bot

Playwright errors

# Reinstall Playwright inside container
docker exec telegram-bot playwright install chromium

LLM API errors

• Check API key validity
• Verify rate limits not exceeded
• Try fallback provider

---

📜 License

MIT License - feel free to use for personal or commercial projects.

---

🙏 Acknowledgments

• Inspired by OpenClaw architecture
• Built with Playwright for web scraping
• Uses ChromaDB for semantic memory
• Telegram integration via python-telegram-bot

---

📧 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Author: @helioneto144

---

Made with ❤️ for the open source community

_{If you find this project useful, please consider giving it a ⭐️ on GitHub!}