aDOs - Personal AI Assistant with Telegram UI

A production-ready personal AI assistant with Telegram interface, powered by GPT-5, featuring project management, memory system, calendar integration, and file processing capabilities.

🚀 Features

Core AI Capabilities

• GPT-5 Integration with tool calling and fallback support
• Semantic Memory System with 1536-dimensional vector embeddings
• Context-Aware Responses with conversation history retrieval
• Multi-Modal Processing (text, images, audio, PDFs, URLs)

Project Management

• Projects & Tasks with priority and status tracking
• Time Tracking with automatic minute calculation
• Notes System for project documentation
• Today's Tasks with timezone awareness

Calendar Integration

• Google Calendar OAuth2 authentication
• Free Slot Detection algorithm
• Event Scheduling and rescheduling
• Timezone-Aware operations (Australia/Melbourne)

File Processing

• URL Content Extraction with BeautifulSoup
• PDF Processing with OCR fallback
• Image OCR with Tesseract
• Audio Transcription with OpenAI Whisper
• Supabase Storage integration

🏗️ Architecture

• Backend: FastAPI with uvicorn
• AI: OpenAI GPT-5 with text-embedding-3-small
• Database: PostgreSQL with pgvector extension
• Storage: Supabase Storage
• UI: Telegram Bot API
• Deployment: Docker + Railway (recommended)

📁 Project Structure

├── main.py                 # FastAPI application
├── config.py               # Environment config & database clients
├── openai_client.py        # OpenAI integration with tool calling
├── models.py               # Pydantic schemas
├── util.py                 # Utility functions
├── telegram_api.py         # Telegram Bot API helpers
├── tools_pm.py             # Project management tools
├── tools_memory.py         # Memory system & embeddings
├── tools_calendar.py       # Google Calendar integration
├── tools_ingest.py         # File processing (URL/PDF/Image/Audio)
├── sql/
│   └── init.sql           # Database schema with pgvector
├── Dockerfile             # Container configuration
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variables template
└── README.md             # This file

🗄️ Database Schema

Core Tables

• projects: Project management with status tracking
• tasks: Task management with priority and time tracking
• time_entries: Time tracking with automatic minute calculation
• notes: Project notes and profile information

Memory System

• messages: Conversation history with vector embeddings
• docs: Document chunks with semantic search
• memory_events: System events and decisions

Vector Search

• 1536-dimensional embeddings using text-embedding-3-small
• IVFFlat indexes for efficient similarity search
• Cosine similarity for semantic retrieval

🚀 Quick Start

Prerequisites

• Python 3.11+
• Docker
• PostgreSQL with pgvector extension
• Supabase account
• OpenAI API key
• Telegram Bot token
• Google Cloud credentials

1. Environment Setup

# Copy environment template
cp .env.example .env

# Edit .env with your credentials
nano .env

2. Database Setup

# Apply database schema
psql "$DATABASE_URL" -f sql/init.sql

3. Local Development

# Build and run with Docker
docker build -t ai-assistant .
docker run --rm -p 8080:8080 --env-file .env \
  -v $(pwd)/credentials.json:/app/credentials.json \
  -v $(pwd)/token.json:/app/token.json \
  ai-assistant

4. Production Deployment (Railway)

1. Push code to GitHub
2. Connect Railway to your GitHub repo
3. Deploy pgvector template for database with vector extension
4. Set environment variables in Railway dashboard
5. Initialize database schema via /init-db endpoint
6. Set up Telegram webhook
7. Deploy automatically

🔧 Environment Variables

# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_MODEL=gpt-5
FALLBACK_MODEL=gpt-5-mini

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=123456789:ABC-DEF1234ghIkl-zyx57W2v1u123456789
TELEGRAM_WEBHOOK_SECRET=your-random-secret-token-here
TELEGRAM_ALLOWED_CHAT_ID=123456789

# Database Configuration
DATABASE_URL=postgresql://user:password@host:port/database?sslmode=require

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Google Calendar Configuration
GOOGLE_CREDENTIALS_PATH=/app/credentials.json
GOOGLE_CALENDAR_ID=primary

# Timezone Configuration
TZ=Australia/Melbourne

🤖 Telegram Setup

1. Create Bot

1. Message @BotFather on Telegram
2. Create new bot with /newbot
3. Get bot token and set in environment

2. Set Webhook

# For local development (with ngrok)
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://YOUR_PUBLIC_URL/telegram/webhook","secret_token":"'$TELEGRAM_WEBHOOK_SECRET'"}' 

# For Railway deployment (PowerShell)
Invoke-RestMethod -Uri "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" -Method POST -Body @{url='https://YOUR_RAILWAY_URL/telegram/webhook'; secret_token='$TELEGRAM_WEBHOOK_SECRET'} -ContentType 'application/x-www-form-urlencoded'

# For Railway deployment (Bash)
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "url=https://YOUR_RAILWAY_URL/telegram/webhook&secret_token=$TELEGRAM_WEBHOOK_SECRET"

📅 Google Calendar Setup

1. Create Credentials

1. Go to Google Cloud Console
2. Create new project or select existing
3. Enable Google Calendar API
4. Create OAuth2 credentials
5. Download JSON file as credentials.json

2. Generate Token

# Run OAuth flow to generate token.json
python -c "
from tools_calendar import _load_creds
from google.auth.transport.requests import Request
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/calendar']
flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
creds = flow.run_local_server(port=0)
with open('token.json', 'w') as token:
    token.write(creds.to_json())
"

🛠️ Available Tools

The AI assistant has access to 14 tools:

Project Management

• get_projects - List all projects
• create_project - Create new project
• get_tasks - List tasks with filters
• create_task - Create new task
• update_task - Update task properties
• add_time_entry - Log time spent
• add_note - Add project notes
• list_today - Get today's tasks

Memory System

• search_memory - Semantic search conversations
• show_profile - Get user profile
• update_profile - Update user profile

Calendar Integration

• find_free_slot - Find available time
• schedule_event - Create calendar event
• reschedule_event - Move existing event

🔒 Security Features

• Input Validation with message length limits
• Chat Whitelisting via TELEGRAM_ALLOWED_CHAT_ID
• Webhook Secret validation
• Non-root Docker user
• Environment Variable protection
• Error Handling without information leakage

📊 Monitoring

• Health Check endpoint at /health
• Debug Endpoint at /debug for environment verification
• Vector Test endpoint at /test-vector for database validation
• Database Init endpoint at /init-db for schema setup
• Structured Logging with error tracking
• Database Connection monitoring
• OpenAI API fallback handling

🚀 Deployment Options

Railway (Recommended)

• Free tier available
• Automatic HTTPS
• Easy environment management
• GitHub integration

Railway Deployment Steps

1. Create Railway Account and connect GitHub
2. Deploy pgvector Template:
   • Go to Railway Extensions
   • Deploy "pgvector-pg17" template
   • Note the new DATABASE_URL
3. Deploy Main App:
   • Connect your GitHub repository
   • Set environment variables
   • Deploy automatically
4. Initialize Database:
   • Call /init-db endpoint to set up schema
   • Verify with /test-vector endpoint
5. Configure Telegram:
   • Set webhook using PowerShell command
   • Test bot functionality

Docker

• Production-ready container
• Health checks included
• Security best practices
• Multi-platform support

Local Development

• Hot reload with uvicorn
• Environment file support
• Database connection pooling

🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Make changes
4. Test thoroughly
5. Submit pull request

📝 License

This project is for personal use. Please respect OpenAI's usage policies and terms of service.

🆘 Troubleshooting

Common Issues

Database Connection Errors

• Verify DATABASE_URL format
• Ensure pgvector extension is installed (use Railway pgvector template)
• Check database permissions
• Test vector extension with /test-vector endpoint
• Initialize schema with /init-db endpoint

OpenAI API Errors

• Verify API key is valid
• Check rate limits
• Ensure sufficient credits

Telegram Webhook Issues

• Verify webhook URL is accessible
• Check secret token matches
• Ensure bot token is correct
• Test webhook with proper PowerShell syntax
• Check TELEGRAM_ALLOWED_CHAT_ID is set correctly

Calendar Integration Issues

• Verify credentials.json exists
• Check token.json is valid
• Ensure calendar API is enabled

Vector Search Issues

• Ensure pgvector extension is properly installed
• Check vector dimension matches (1536 for text-embedding-3-small)
• Verify SQL query uses proper type casting (::vector)
• Test with /test-vector endpoint

Support

For issues and questions:

1. Check the logs for error details
2. Verify all environment variables
3. Test individual components
4. Check API service status

---

Built with ❤️ for personal productivity and AI assistance.