🌐 Acali — Agentic Telegram Google Calendar Assistant

---

🧠 Overview

Acali is a lightweight agentic orchestration system that connects a Telegram bot to Google Calendar, powered by LangGraph, Vertex AI (Gemini), and FastAPI.
It enables natural-language scheduling, conflict resolution, and persistent user memory — forming a foundation for extendable Google Workspace automation.

---

✨ Key Features

• 🗓️ Natural-language event creation (Gemini / Vertex AI)
• ⚙️ Agentic orchestration with LangGraph
• ⚡ Conflict detection & auto-rescheduling (agent_flow/features_conflict.py)
• 🔐 Secure Google OAuth2 with encrypted tokens (oauth_flow/agent.py)
• 🧠 Per-user contextual memory (memory/manager.py)
• 🌐 FastAPI webhook integration with Telegram
• 🧩 Modular design — extendable to Gmail, Docs, Sheets, Drive

---

🗂️ Architecture Overview

Telegram Bot  <──>  FastAPI  <──>  LangGraph Agent  <──>  Vertex AI (Gemini)
       │                     │
       │                     └── OAuth Flow + Storage
       │                           ├── oauth_flow/agent.py
       │                           ├── oauth_flow/routes.py
       │                           ├── oauth_flow/storage.py
       │                           └── oauth_flow/db.py
       │
       └───> Telegram UX Layer
               ├── telegram_ux/ui.py
               └── telegram_ux/handlers.py

Memory Manager (persistent JSON)
 └── memory/manager.py, memory/store.py, memory/schema.py

Scheduling & Conflict Logic
 └── agent_flow/features_schedule.py, agent_flow/features_conflict.py

📁 Project Structure

acali/
├── main.py                          # Entry point - FastAPI + Telegram bot
├── requirements.txt                 # Python dependencies
├── readme.md                        # This file
│
├── web/                             # FastAPI web layer
│   └── api.py                       # FastAPI app factory + webhook endpoints
│
├── telegram_ux/                     # Telegram bot interface
│   ├── handlers.py                  # Command and message handlers
│   └── ui.py                        # UI helpers and OAuth callback HTML
│
├── oauth_flow/                      # Google OAuth & Calendar integration
│   ├── agent.py                     # OAuth agent (authorize, callback, revoke)
│   ├── db.py                        # Sync SQLite token storage (encrypted)
│   ├── storage.py                   # Async SQLAlchemy storage (optional)
│   ├── google_calendar.py           # Calendar API CRUD operations
│   ├── models.py                    # SQLAlchemy models
│   ├── routes.py                    # OAuth routes (if using FastAPI router)
│   ├── service.py                   # OAuth service helpers
│   └── utils.py                     # Utility functions
│
├── agent_flow/                      # LangGraph agent orchestration
│   ├── core.py                      # LLM setup (Vertex AI/Gemini)
│   ├── calendar_agent.py            # Main calendar agent
│   ├── calendar_chat_agent.py       # Context-aware chat agent
│   ├── chat_agent.py                # General chat + routing
│   ├── calendar_graph.py            # LangGraph workflow (if using)
│   ├── intent.py                    # Intent classification
│   ├── features_schedule.py         # Event scheduling logic
│   ├── features_conflict.py         # Conflict detection & resolution
│   ├── features_memory.py           # Event memory management
│   └── features_utils.py            # Shared utilities
│
└── memory/                          # Persistent user memory
    ├── manager.py                   # High-level memory API
    ├── store.py                     # JSON file storage
    └── schema.py                    # Pydantic models

---

🧩 Core Modules

Module	Purpose
main.py	Entry point — runs FastAPI and Telegram bot
web/api.py	FastAPI + Telegram integration (create_fastapi_app)
oauth_flow/agent.py	OAuth orchestration and token logic
oauth_flow/storage.py	Async SQLAlchemy + Fernet encrypted storage
oauth_flow/db.py	Sync SQLite token storage with encryption
telegram_ux/handlers.py	Telegram bot commands (register)
telegram_ux/ui.py	Telegram UI helpers and OAuth callback HTML
agent_flow/calendar_agent.py	Main calendar agent with LLM-driven scheduling
agent_flow/calendar_chat_agent.py	Context-aware calendar chat agent
agent_flow/chat_agent.py	General chat agent and routing orchestrator
agent_flow/features_schedule.py	Event scheduling and creation logic
agent_flow/features_conflict.py	Conflict detection and alternative time finding
agent_flow/features_memory.py	Event memory management for deletions
agent_flow/core.py	Core LLM setup (Vertex AI/Gemini) and state definitions
agent_flow/intent.py	Intent classification and timezone helpers
memory/manager.py	Per-user memory management
memory/store.py	JSON-based persistent storage
memory/schema.py	Pydantic models for memory structure
oauth_flow/google_calendar.py	Calendar API adapter (CRUD operations)

---

⚙️ Installation

git clone <repo-url> acali
cd acali

python -m venv venv
# On Windows:
venv\Scripts\activate
# On Linux/Mac:
source venv/bin/activate

pip install -r requirements.txt

---

🔧 Configuration — .env

Variable	Description
BOT_TOKEN	Telegram bot token (required)
WEBHOOK_URL	Public HTTPS URL for Telegram webhook (optional, for webhook mode)
FERNET_KEY / ENCRYPTION_KEY	Symmetric key for encrypted tokens (required)
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET	Google OAuth credentials (required)
GOOGLE_REDIRECT_BASE	Redirect base URL (default: http://localhost:8000)
DB_PATH	SQLite file path for OAuth tokens (default: .data/tokens.db)
DATABASE_URL	Async SQLAlchemy database URL (default: sqlite+aiosqlite:///./oauth_flow.db)
GCP_PROJECT_ID	Google Cloud Project ID for Vertex AI (required)
LOCATION	Vertex AI location (default: us-central1)
GEMINI_MODEL	Gemini model name (default: gemini-2.5-flash)
GEMINI_TEMPERATURE	LLM temperature (default: 0.3)
DEFAULT_TIMEZONE	Default user timezone (default: Asia/Kolkata)

---

🧱 Database Setup

• Sync SQLite (oauth_flow/db.py) initializes automatically on import via ensure_connection().
• Async SQLAlchemy (oauth_flow/storage.py) requires explicit initialization in main.py startup event (already configured).

The application uses two database systems:

1. SQLite (oauth_flow/db.py) - For encrypted OAuth token storage (sync)
2. Async SQLAlchemy (oauth_flow/storage.py) - For OAuth session management (optional, if using PKCE flow)

---

🚀 Running Locally

python main.py

• Runs FastAPI and Telegram Bot.
• If using webhooks, set WEBHOOK_URL and expose via ngrok for testing.

---

🔑 OAuth Flow

• /connect command triggers Google OAuth authorization.
• Redirect + token storage handled by:
  • oauth_flow/routes.py
  • web/api.py
• Tokens are encrypted and stored securely.

---

🧠 LangGraph + Vertex AI

Acali uses LangGraph to orchestrate the agent’s reasoning chain — managing natural-language interpretation, conflict resolution, and contextual scheduling.

• LangGraph: Controls multi-step reasoning and dialogue flow.
• Vertex AI: Executes semantic tasks (intent detection, date extraction, conflict explanation).
• Memory Layer: Stores user context persistently to refine scheduling over time.

---

🔄 Extendability — Google Workspace Integration

Acali’s modular design allows effortless extension to other Google tools:

Extension	Example Use
Docs	Generate meeting summaries
Sheets	Visualize schedule metrics
Gmail	Send confirmation emails
Drive	Store contextual data or logs

Each extension can plug into the LangGraph workflow as a reasoning node.

---

🛡️ Development Notes

• Keep .env and encryption keys private.
• For local testing, stub LLM responses to reduce latency.
• Each subsystem (OAuth, Telegram, FastAPI, Memory) is self-contained and testable.

---

🔧 Troubleshooting

Common Issues

1. "ENCRYPTION_KEY not set" error

   • Generate a key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
   • Add to .env: ENCRYPTION_KEY=<generated_key>

2. "GCP_PROJECT_ID not set" error

   • Ensure you have a Google Cloud Project with Vertex AI enabled
   • Add to .env: GCP_PROJECT_ID=your-project-id

3. OAuth callback fails

   • Verify GOOGLE_REDIRECT_BASE matches your server URL
   • Ensure redirect URI is configured in Google Cloud Console
   • Check that WEBHOOK_URL (if using webhooks) is publicly accessible

4. Database initialization errors

   • Ensure DB_PATH directory exists or is writable
   • Check that DATABASE_URL is correct for async SQLAlchemy
   • Verify FERNET_KEY is set correctly

5. Import errors

   • Ensure all dependencies are installed: pip install -r requirements.txt
   • Check that virtual environment is activated
   • Verify Python version is 3.9+

6. Telegram bot not responding

   • Verify BOT_TOKEN is correct
   • Check if using webhook mode, ensure WEBHOOK_URL is set
   • Check logs for connection errors

7. LLM/Vertex AI errors

   • Verify Google Cloud credentials are set up
   • Check that Vertex AI API is enabled in your GCP project
   • Ensure billing is enabled for the project
   • Verify model name (GEMINI_MODEL) is valid

---

🤝 Contributing

MIT-licensed.
Contributions via issues or pull requests are welcome!

---

📜 License

MIT License
Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

[Full license included in LICENSE file.]

---

🧭 Future Vision

Acali can evolve into a unified personal agentic framework —
bridging conversational interfaces (Telegram, WhatsApp, web) with
Google Workspace and Vertex AI reasoning, forming the base for
next-generation productivity agents