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.

• 🗓️ 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

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

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

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

• 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)

python main.py

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

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

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.

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

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

• 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.

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

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

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.]

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