local-pigeon 0.2.0

Local AI agent with Discord/Telegram, Google Workspace, and payments - powered by Ollama

�️ Local Pigeon

A fully local AI agent powered by Ollama (or llama-cpp-python). Your AI assistant that runs entirely on your device, connecting to Discord, Telegram, or a web interface while keeping all LLM inference local and private.

✨ Features

• 🧠 Local LLM Inference - Uses Ollama for on-device model inference
• 🔐 Privacy First - Your conversations never leave your device
• 💬 Multi-Platform - Discord, Telegram, and Web UI support
• 🔧 Extensible Tools - Web search, file operations, and more
• 📧 Google Workspace - Gmail, Calendar, and Drive integration
• 💳 Payment Capabilities - Stripe virtual cards and crypto (USDC/ETH)
• ✅ Human-in-the-Loop - Approval workflow for sensitive operations
• 🚀 Easy Setup - One-command installation

📋 Prerequisites

• Python 3.10+ (Download)
• Ollama (Download) - or Local Pigeon can auto-download models via llama-cpp-python
• A supported LLM model (e.g., gemma3, llama3.2, qwen2.5)

🚀 Quick Start

Option 1: Auto-Installer (Recommended)

Windows (PowerShell):

irm https://raw.githubusercontent.com/tradermichael/local_pigeon/main/install.ps1 | iex

Mac/Linux:

curl -sSL https://raw.githubusercontent.com/tradermichael/local_pigeon/main/install.sh | bash

Option 2: pip Install

pip install local-pigeon

Option 3: From Source

git clone https://github.com/tradermichael/local_pigeon.git
cd local_pigeon
pip install -e .

Option 4: Docker

docker-compose up -d

⚙️ Configuration

1. Set up Ollama (or skip for auto-download)

If you have Ollama installed, make sure it's running:

# Start Ollama (if not running)
ollama serve

# Pull a model
ollama pull gemma3:latest

No Ollama? Local Pigeon will automatically fall back to llama-cpp-python and download a model from HuggingFace on first run.

2. Configure Local Pigeon

Run the setup wizard:

local-pigeon setup

Or manually create a .env file:

# Ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=gemma3:latest

# Discord (optional)
DISCORD_BOT_TOKEN=your_discord_bot_token

# Telegram (optional)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

# Google Workspace (optional)
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

# Payments (optional)
STRIPE_API_KEY=sk_...
PAYMENT_APPROVAL_THRESHOLD=25.00

3. Run Local Pigeon

# Start all enabled platforms
local-pigeon run

# Or run specific platform
local-pigeon run --platform discord
local-pigeon run --platform telegram
local-pigeon run --platform web

💬 Platforms

Discord Bot

1. Create a bot at Discord Developer Portal
2. Enable "Message Content Intent" under Bot settings
3. Copy the bot token to your .env
4. Invite the bot to your server with appropriate permissions

Features:

• Responds to mentions and DMs
• Streaming responses with message edits
• Slash commands: /model, /clear, /status
• Payment approval via DM

Telegram Bot

1. Create a bot via @BotFather
2. Copy the bot token to your .env
3. Optionally set TELEGRAM_ALLOWED_USERS to restrict access

Features:

• Message handling with user whitelist
• Streaming responses
• Commands: /model, /clear, /status
• Inline keyboard for payment approvals

Web UI

Access at http://localhost:7860 when running with --platform web.

Features:

• Chat interface with streaming
• Settings panel
• OAuth setup for Google
• Tool execution display

🧰 Tools

Web Tools

• Web Search - Search using DuckDuckGo
• Web Fetch - Extract content from web pages

Google Workspace

• Gmail - Read, search, and send emails
• Calendar - View and create events
• Drive - List, search, and read files

Payments

• Stripe Card - Virtual card for online payments
• Crypto Wallet - USDC/ETH on Base network

💳 Payment System

Local Pigeon supports both traditional and crypto payments:

Stripe Virtual Cards

• Create virtual cards for online purchases
• Real-time transaction monitoring
• Human-in-the-loop approval for amounts above threshold

Crypto Wallet (CDP)

• USDC and ETH support on Base network
• Send and receive payments
• Approval workflow for security

Approval Workflow

Payments above your configured threshold (default: $25) require approval:

1. Agent requests payment
2. You receive approval request (Discord DM, Telegram message, or Web UI)
3. Approve or deny within 5 minutes
4. Payment proceeds or is cancelled

Configure threshold:

PAYMENT_APPROVAL_THRESHOLD=25.00

🔐 Security

• Local Processing - LLM runs on your device via Ollama
• Encrypted Storage - OAuth tokens encrypted at rest
• Human Approval - Sensitive operations require confirmation
• User Whitelist - Restrict bot access to specific users

📁 Project Structure

local_pigeon/
├── src/
│   └── local_pigeon/
│       ├── core/           # Agent, LLM client, conversation
│       ├── platforms/      # Discord, Telegram adapters
│       ├── tools/          # Web, Google, Payment tools
│       ├── storage/        # Database, credentials
│       ├── ui/             # Gradio web interface
│       ├── config.py       # Configuration management
│       └── cli.py          # Command-line interface
├── config.yaml             # YAML configuration
├── .env.example            # Environment template
├── install.ps1             # Windows installer
├── install.sh              # Mac/Linux installer
├── Dockerfile              # Docker build
└── docker-compose.yml      # Docker orchestration

🛠️ Development

Setup Development Environment

git clone https://github.com/tradermichael/local_pigeon.git
cd local_pigeon
pip install -e ".[dev]"

Run Tests

pytest

Code Style

ruff check .
ruff format .

📝 Commands Reference

# Run the agent
local-pigeon run [--platform discord|telegram|web]

# Interactive setup wizard
local-pigeon setup

# Check system status
local-pigeon status

# List available models
local-pigeon models

# Interactive chat (terminal)
local-pigeon chat

# Show version
local-pigeon version

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Ollama - Local LLM runtime
• discord.py - Discord API wrapper
• aiogram - Telegram Bot framework
• Gradio - Web UI framework
• Stripe - Payment processing
• Coinbase CDP - Crypto infrastructure

---

Made with ❤️ for local-first AI