coordo

Coordo — Group Chat Coordination Agent

A coordination agent you add to Telegram or Discord groups that turns "we should hang out" into a booked plan without anyone leaving the thread.

What It Does

• Reads context — AI understands your group's conversation to infer event type, preferences, and timing
• Proposes dates — Generates 2-3 concrete date options based on context
• Runs polls — Platform-native polls with 24-hour deadlines
• Books venues — Suggests restaurants and venues based on location and vibe
• Splits bills — Integrates with Selcom Pesa for mobile money payments
• Chases reminders — Escalating nudges for non-voters and non-payers
• Sends calendar invites — Generates .ics files when events are locked

Quick Start

# 1. Clone the repo
git clone https://github.com/Ocdeed/coordo.git
cd coordo

# 2. Set up environment
cp .env.example .env
# Edit .env with your API keys

# 3. Start database
docker-compose up -d

# 4. Install dependencies
pip install -e ".[dev]"

# 5. Run migrations
alembic upgrade head

# 6. Start the Telegram bot
python scripts/run_telegram.py

# 7. Start the API server (for webhooks)
python main.py

How to Use

1. Add @coordobot to your Telegram group
2. @mention it with a planning intent:
   • @coordobot let's get dinner this week
   • @coordobot we should do drinks on Friday
   • @coordobot who's free for a trip next weekend?
3. The bot will propose dates, run a poll, and help coordinate!

Tech Stack

• Backend: Python 3.11+, FastAPI, SQLAlchemy
• AI: OpenAI GPT-4o
• Database: PostgreSQL with Alembic migrations
• Telegram: python-telegram-bot
• Discord: discord.py
• Payments: Selcom Pesa (Tanzania mobile money)
• Scheduler: APScheduler for background reminders

Project Structure

coordo/
├── core/           # App entry, config, models, schemas
├── ai/             # GPT-4o engine, intents, prompts
├── coordinator/    # State machine, polls, calendar
├── platforms/      # Telegram + Discord adapters
├── payments/       # Selcom Pesa integration
├── scheduler/      # Background reminders
├── db/             # Database engine, migrations
├── tests/          # Unit and integration tests
└── scripts/        # Platform runner scripts

Environment Variables

License

MIT