Skip to content

README.md

Latest commit

 

History

History
146 lines (108 loc) · 4.83 KB

README.md

File metadata and controls

146 lines (108 loc) · 4.83 KB

TheMahdiAI Logo

TheMahdiAI

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

FastAPI Python PostgreSQL LiteLLM Telegram

🌟 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

✅ Testing

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
make test

You can pass custom test args (without editing Makefile):

make test ARGS="-q -k quota"

CI

Every push and pull request runs:

make test

The workflow uses Python 3.11 on GitHub Actions.

🤝 Contributing

  • See CONTRIBUTING.md for contribution workflow.
  • Use clear, small PRs with focused scope and tests.
  • Keep secrets out of repository history (.env*, API keys, tokens).

Development checklist

  • Use make test before pushing.
  • Update docs when behavior changes.
  • Include or update unit tests for logic changes.

🏗️ 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.md: Contributor guide.

📜 License

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

Developed by Wau Hashem & The Hashem Code Projects