Meetup Organizer Agent

Built for ETHGlobal Cannes -- designed for any event.

An AI agent that turns events into self-organizing learning networks. Instead of people randomly networking, the agent understands participant intent, matches complementary profiles, and coordinates real-world interactions.

AI should not replace human interaction -- it should coordinate it.

---

The Problem

At hackathons and conferences:

• People want to learn specific things
• Many are willing to teach or share
• But discovery is inefficient, coordination is manual, and opportunities are missed

Result: massive unused potential.

The Solution

An AI agent that:

• Chats with users via Telegram (DMs and group chats)
• Onboards participants with a quick survey to understand motivations and skills
• Extracts structured intent: what you want to learn, what you can teach
• Matches complementary profiles across the community
• Proposes learning sessions and notifies participants
• Iterates via conversation -- accept, reject, reschedule

---

Core Features

Conversational Agent

Users interact through natural language:

• "I want to learn Zama FHE"
• "I can teach Uniswap v4 hooks"

The agent extracts structured data and maintains context per user.

Matching Engine

• In-memory profile registry with learn/teach topics
• Community-wide matching: 1:1 mentorship, 1:N sessions, group discussions
• Proposals generated by the coordination agent based on the full registry

Coordination Layer

The agent proposes sessions with:

• Participants (teacher + students)
• Topic and summary
• Per-user notifications delivered in Telegram

Handles accept/reject flows and re-matching.

Onboarding Survey

6-question intake via Telegram (/start):

1. Motivation for attending
2. Interest in learning (yes/no)
3. Thoughts on meetup format
4. What you want to learn
5. Interest in speaking (yes/no)
6. What you can teach

Resumes from where you left off if interrupted. On completion, syncs your profile to the matching registry.

---

Architecture

Stack

Component	Role
FastAPI (src/api/)	REST API + SSE streaming for the LangGraph agent
Telegram bot (src/telegram_bot/)	Onboarding survey, DM conversations, group chat (@mention)
Streamlit (src/chatbot_ui/)	Local test UI
PostgreSQL 16	LangGraph checkpoints + onboarding survey storage
Qdrant	Vector DB (available for future embedding-based matching)
LiteLLM + Instructor	LLM routing -- supports OpenRouter and direct OpenAI

Agent Graph (LangGraph)

START --> coordinator_agent
            |                   |
    profile_intake_agent   meetup_coordination_agent
            |                   |
        [tools]             [tools]
            |                   |
            +--> coordinator_agent --> END

Node	Role
coordinator_agent	Routes to profile intake or meetup coordination. Handles small talk directly.
profile_intake_agent	Captures learn/teach intent, saves to registry.
meetup_coordination_agent	Reads community registry, proposes sessions, notifies participants.

API Endpoints

Method	Path	Purpose
POST	/rag/	Stream agent response (SSE)
GET	/rag/meetup-pending-notifications	Pop queued notifications for a user
POST	/submit_feedback/	Feedback for LangSmith traces
GET	/admin/meetup-context	Full registry snapshot (password-protected)
GET	/health	Liveness check

See docs/API.md for the full reference.

---

Quick Start

Prerequisites

• Docker and Docker Compose
• API key: OpenRouter (OPENROUTER_API_KEY) and/or OpenAI (OPENAI_API_KEY)
• Telegram bot token from @BotFather

1. Configure

cp env.example .env
# Edit .env -- set OPENROUTER_API_KEY (or OPENAI_API_KEY) and TELEGRAM_BOT_TOKEN

2. Run

docker compose up --build -d

This starts 5 services: api (8000), telegram-bot, streamlit-app (8501), postgres, qdrant.

3. Verify

docker compose ps                        # all services "Up"
docker compose logs -f telegram-bot      # check bot logs
curl http://localhost:8000/health         # {"status": "ok"}

Then /start your bot on Telegram.

Local Development (without Docker for Python)

Use this when iterating on Python code. You still need Postgres for LangGraph checkpoints.

1. Install dependencies:

   uv sync

2. Start Postgres only:

   docker compose up -d postgres

3. Set .env with at least your API key, bot token, and local checkpoint URL:

   OPENROUTER_API_KEY=sk-or-v1-...
   LANGGRAPH_POSTGRES_URI=postgresql://langgraph_user:langgraph_password@127.0.0.1:5434/langgraph_db
   TELEGRAM_API_URL=http://127.0.0.1:8000

4. Terminal 1 -- API:

   PYTHONPATH=src uv run --env-file .env uvicorn api.app:app --reload --host 127.0.0.1 --port 8000

5. Terminal 2 -- Telegram bot:

   PYTHONPATH=src uv run --env-file .env python -m telegram_bot.telegram_main

---

Environment Variables

See env.example for the full list.

Variable	Required	Description
OPENROUTER_API_KEY	Yes*	OpenRouter API key. If set, agents route through OpenRouter.
OPENAI_API_KEY	Yes*	Direct OpenAI key. Used if OPENROUTER_API_KEY is not set.
TELEGRAM_BOT_TOKEN	Yes	From @BotFather.
MEETUP_ADMIN_PASSWORD	No	Password for /admin/meetup-context (default: humansftw).
MEETUP_STATE_FILE	No	JSON persistence path. Docker sets this automatically.
DATABASE_URL	No	PostgreSQL connection string. Docker sets this automatically.
LANGGRAPH_POSTGRES_URI	No	Checkpoint DB. Default: postgres:5432 (Docker). Set for local dev.
LANGSMITH_API_KEY	No	Enable LangSmith tracing.

*At least one of OPENROUTER_API_KEY or OPENAI_API_KEY is required.

---

Project Structure

src/
  api/                          # FastAPI backend
    agent/                      # LangGraph agents, tools, prompts
      agents.py                 # Agent functions (coordinator, profile intake, meetup coordination, group chat)
      graph.py                  # LangGraph workflow definition
      meetup_context.py         # In-memory registry + JSON persistence
      meetup_tools.py           # Agent tools (profile save, registry read, proposal creation)
      prompts/                  # YAML prompt templates per agent
    api/                        # FastAPI routes, models, middleware
    core/                       # Config (pydantic-settings)
  telegram_bot/                 # Telegram bot client
    telegram_bot.py             # Bot handlers, onboarding survey
    survey_db.py                # PostgreSQL access layer for surveys
  chatbot_ui/                   # Streamlit test UI
sql/                            # Database schemas
docker-compose.yml              # All services
Dockerfile.{fastapi,telegram,streamlit}

Tests

uv sync --group dev
uv run pytest src/telegram_bot/test_telegram_bot.py -q

---

Documentation

Doc	Content
docs/ARCHITECTURE.md	System overview, data flow, DB schema, agent tools
docs/API.md	Full API endpoint reference with examples
docs/DEPLOYMENT.md	Production deployment (Coolify/Hetzner, backups, troubleshooting)

---

Vision

This project explores a broader idea: AI-coordinated human interaction.

Built for ETHGlobal Cannes, but designed to work at any event where people gather to learn and share -- hackathons, conferences, coworking spaces, online communities bridging to IRL.

Turn communities into self-organizing networks where knowledge exchange is fluid, incentivized, and coordinated by AI.

---

Team

Made by Shelly Chang, Victor Xu, Helena Gebhart, Samir Touinssi, and Antoine E.

ETHGlobal Cannes 2026