Skip to content

README.md

Latest commit

 

History

History
272 lines (220 loc) · 9.19 KB

README.md

File metadata and controls

272 lines (220 loc) · 9.19 KB
Raw

🎯 Chat2Task

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

Python 3.11+ FastAPI License: MIT

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.