🎯 Chat2Task

Turn messy Telegram chats into reminders, summaries, and ready-to-send drafts.

---

Chat2Task is a Telegram-first task copilot. Send it a messy message like "besok ingetin saya bayar listrik, rangkum meeting ini, terus bikin draft WA ke tim" and it parses it into structured actions — reminders, summaries, and drafts — then lets you approve and execute each one.

✨ Features

Feature	Description
Multi-action parsing	Extracts multiple actions from a single message
Approval-first workflow	Nothing executes without your confirmation
Smart reminders	One-time and recurring, with snooze and timezone support
Summaries	Concise, structured text summaries on demand
Draft generation	Ready-to-send messages for WhatsApp, email, etc.
🎙 Voice messages	Send a voice note — it gets transcribed and parsed automatically
🤖 Multi-turn clarification	Bot asks follow-up questions for ambiguous requests
📅 Google Calendar sync	Approved reminders auto-create Google Calendar events
📓 Notion sync	Approved tasks auto-create pages in your Notion database
👥 Group chat support	Add bot to groups — responds only when @mentioned or replied to
📊 Web dashboard	Dark-themed dashboard at /dashboard to view & filter tasks
Multilingual	Works in English, Indonesian, and other languages
Daily digest	Morning summary of your tasks and reminders
REST API	Task inbox accessible via API alongside Telegram
Provider-agnostic LLM	Works with any OpenAI-compatible API (NVIDIA NIM, OpenRouter, local models)
Persistent scheduling	Reminders survive restarts

🗂 Architecture

app/
├── main.py              # FastAPI entrypoint & lifespan
├── config.py            # Pydantic settings from .env
├── database.py          # SQLAlchemy engine & session
├── models/              # DB models (User, Task, Reminder, ActionLog)
├── schemas/             # Pydantic schemas (actions, tasks, users)
├── llm/
│   ├── provider.py      # Abstract LLM interface
│   ├── openai_compat.py # OpenAI-compatible client (default)
│   ├── parser.py        # Task extraction engine
│   ├── summarizer.py    # Summary generation
│   ├── drafter.py       # Draft generation
│   └── prompts.py       # Prompt templates
├── services/
│   ├── task_service.py      # Task lifecycle management
│   ├── reminder_service.py  # Reminder scheduling
│   ├── user_service.py      # User CRUD & preferences
│   ├── digest_service.py    # Daily digest builder
│   ├── voice_service.py     # 🎙 Voice transcription (Whisper API)
│   ├── conversation.py      # 🤖 Multi-turn state manager
│   ├── gcal_service.py      # 📅 Google Calendar integration
│   └── notion_service.py    # 📓 Notion integration
├── scheduler/           # APScheduler engine & reminder jobs
├── telegram/
│   ├── bot.py           # Bot & Dispatcher factory
│   ├── handlers/        # Command, message, voice, callback handlers
│   ├── keyboards.py     # Inline keyboard builders
│   └── formatting.py    # Message formatting helpers
├── routers/             # FastAPI routes (webhook, tasks API, health)
│   └── dashboard.py     # 📊 Web dashboard routes
└── templates/           # Jinja2 HTML templates (dashboard UI)

🚀 Quick Start

Prerequisites

• Python 3.11+
• A Telegram bot token (from @BotFather)
• An OpenAI-compatible API key (OpenAI, NVIDIA NIM, OpenRouter, etc.)

1. Clone & Install

git clone https://github.com/your-username/chat2task.git
cd chat2task
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure

cp .env.example .env
# Edit .env with your tokens:
#   TELEGRAM_BOT_TOKEN=your-bot-token
#   LLM_API_KEY=your-api-key
#   LLM_BASE_URL=https://integrate.api.nvidia.com/v1  (or any OpenAI-compatible endpoint)
#   LLM_MODEL=meta/llama-3.1-8b-instruct

3. Run

# Local development (long polling mode — no webhook needed)
make dev
# Or directly:
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

4. Use

Open your bot in Telegram and send a message:

Besok ingetin saya bayar listrik jam 10, rangkum meeting ini, terus bikin draft WA ke tim

The bot will respond with detected actions and approval buttons.

Docker

cp .env.example .env
# Edit .env
docker compose up --build

💬 Example Conversations

Single Reminder

You: Remind me to call the dentist tomorrow at 3pm

Chat2Task: 🎯 Detected Actions

⏰ #1 — Call the dentist Type: reminder 🟢 📅 2025-01-15 15:00

[✅ Approve] [❌ Cancel]

Multiple Actions

You: besok ingetin saya bayar listrik, rangkum meeting ini, terus bikin draft WA ke tim

Chat2Task: 🎯 Detected Actions

⏰ #1 — Bayar listrik Type: reminder 🟢 📅 2025-01-15

📝 #2 — Rangkum meeting Type: summary 🟡

✉️ #3 — Draft WA ke tim Type: draft 🟡 📨 To: Tim (WhatsApp)

[✅ Approve All] [✅ #1] [❌ #1] [✅ #2] [❌ #2] [✅ #3] [❌ #3] [🗑 Ignore All]

Reminder Fires

Chat2Task: ⏰ Reminder

📌 Bayar listrik

What would you like to do?

[✅ Done] [⏰ 10m] [⏰ 1h] [📅 Tomorrow]

🔧 Configuration

Variable	Default	Description
TELEGRAM_BOT_TOKEN	—	Your Telegram bot token (required)
WEBHOOK_URL	—	Webhook URL (leave empty for polling mode)
WEBHOOK_SECRET	change-me	Secret for webhook verification
LLM_BASE_URL	https://integrate.api.nvidia.com/v1	OpenAI-compatible API base URL
LLM_API_KEY	—	API key for the LLM provider
LLM_MODEL	meta/llama-3.1-8b-instruct	Model identifier
LLM_TIMEOUT	30	Request timeout in seconds
LLM_TEMPERATURE	0.1	LLM temperature for parsing
DATABASE_URL	sqlite:///./chat2task.db	Database connection string
DEFAULT_TIMEZONE	Asia/Jakarta	Fallback timezone
DEFAULT_REMINDER_HOUR	9	Default hour for reminders without time
STT_BASE_URL	—	Whisper-compatible STT endpoint (blank = use LLM_BASE_URL)
STT_API_KEY	—	STT API key (blank = use LLM_API_KEY)
STT_MODEL	whisper-1	STT model name
GOOGLE_CALENDAR_ENABLED	false	Enable Google Calendar sync
GOOGLE_CREDENTIALS_FILE	credentials.json	Path to Google OAuth credentials
GOOGLE_TOKEN_FILE	token.json	Path to cached Google auth token
NOTION_ENABLED	false	Enable Notion sync
NOTION_API_KEY	—	Notion integration API key
NOTION_DATABASE_ID	—	Target Notion database ID

📡 REST API

The app exposes a lightweight REST API alongside the Telegram interface:

• GET /health — Health check
• GET /api/tasks/?telegram_id=123 — List user tasks
• GET /api/tasks/{id} — Get task details
• PATCH /api/tasks/{id} — Update task
• POST /api/tasks/{id}/approve — Approve task
• POST /api/tasks/{id}/cancel — Cancel task
• GET /docs — Interactive API docs (Swagger UI)
• GET /dashboard — Web dashboard (task overview & stats)
• GET /dashboard/tasks — Task list with status filter

🧪 Testing

make test
# Or:
pytest tests/ -v

🛠 Extending

Add a new LLM provider

1. Implement app/llm/provider.py::LLMProvider interface
2. Create your provider class (e.g., app/llm/anthropic.py)
3. Update the provider instantiation in message handlers

Switch to PostgreSQL

1. Install psycopg2-binary
2. Update DATABASE_URL in .env:

   DATABASE_URL=postgresql+psycopg2://user:pass@localhost:5432/chat2task
   

3. Uncomment the PostgreSQL service in docker-compose.yml

Add new action types

1. Add the type to ActionType enum in app/schemas/action.py
2. Update the LLM prompt in app/llm/prompts.py
3. Add execution logic in app/telegram/handlers/callback.py::_execute_task

🗺 Roadmap

• Multi-turn clarification & settings state machine
• Google Calendar sync
• Notion integration
• Voice message transcription → action extraction
• Group chat support with @mention parsing
• Web dashboard for task management
• Alembic migrations for production schema management
• Todoist / CalDAV integration
• Rate limiting and usage quotas
• Multi-model fallback chain
• Docker production-ready image
• Webhook mode with HTTPS reverse proxy guide

📄 License

MIT — see LICENSE.

---

Built with ❤️ for people who think faster than they can organize.