TheMahdiAI

Advanced The Ahmadi Religion of Peace and Light (AROPL) Knowledge Assistant powered by AI & RAG

---

🌟 Overview

TheMahdiAI is an open-source, production-ready Telegram Bot designed to provide accurate, context-aware Islamic knowledge. It leverages a modern AI stack with RAG (Retrieval-Augmented Generation) and a robust 3-level failover gateway to ensure reliable and high-quality responses.

Built for the community, it integrates Quranic texts, authentic Hadiths, and scholarly references into a seamless, interactive chat experience.

✨ Key Features

• 🧠 Google NotebookLM Integration: Direct API integration via notebooklm-py and Playwright for authenticating and querying Google's powerful RAG engine directly from Telegram.
• 🛡️ 3-Level AI Failover Gateway: Automatic fallback between OpenAI, Anthropic, and Groq using LiteLLM and Circuit Breakers.
• ⚡ Parallel Processing & Streaming: Concurrent message handling with progressive response delivery for a low-latency feel.
• 🔒 Smart Quota & Rate Limiting: Built-in protection with Redis-based limits (minutely/daily) and persistent Database Fallback.
• 📊 Premium Admin Dashboard: Modern Next.js dashboard to manage Notebooks, configure fallback chains, monitor real-time sessions, and audit detailed chat histories on dedicated pages.
• 🌐 Global Multi-lingual Support: Native support for 15+ priority languages with manual custom entry.
• 🛠️ Dynamic Orchestration: Hot-reload system prompts, Telegram bot menus, and fallback chains via the dashboard.

🚀 Getting Started

Prerequisites

• Python 3.9+
• PostgreSQL & Redis
• uv (Highly recommended for package management)
• Docker & Docker Compose (Optional, for easy infra setup)

Installation

1. Clone the repository:

   git clone https://github.com/TheHashemCode/TheMahdiAI.git
   cd TheMahdiAI

2. Setup Environment:

   cp .env.example .env
   # Edit .env with your API keys and database credentials

3. Install Dependencies:

   pip install uv
   uv pip install -r requirements.txt

4. Initialize Database:

   alembic upgrade head

5. Run API (Backend):

   python -m uvicorn app.main:app --reload

6. Run Dashboard (Frontend):

   cd dashboard
   npm run dev

   Dashboard will be available at http://localhost:10313

🏗️ Technical Stack

• Framework: FastAPI
• ORM: SQLModel (SQLAlchemy + Pydantic)
• AI Gateway: LiteLLM
• Knowledge Engine: Google NotebookLM (notebooklm-py + Playwright)
• Migrations: Alembic
• Vector DB: Qdrant (Planned)

📂 Project Structure

• app/: Core application logic (Bot handlers, AI Gateway, Models).
• docs/: Technical documentation and flowcharts.
• contexts/: Knowledge base for AI Agents and development best practices.
• alembic/: Database migration scripts.
• assets/: Project images and branding.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feat/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feat/AmazingFeature)
5. Open a Pull Request

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

Developed by Wau Hashem & The Hashem Code Projects