Hidayah AI: The Royal Divine Library 🕌

Hidayah AI is a premium Ramadan Research Companion designed for deep Quranic immersion. Beyond a simple reader, it is a sophisticated AI-orchestrated environment that transforms scholarly study into a world-class, aesthetic experience.

---

🏛️ The "Royal Divine" Experience

Hidayah AI is built on a unique design philosophy that prioritizes Visual Authority and Linguistic Depth:

• Glassmorphism 2.0: A semi-transparent "Divine" interface using frosted-glass headers, grain-textured panels, and multi-layered shadows.
• Sharp Design Tokens: A technical 2px radius aesthetic that provides a sharp, modern, and authoritative feel compared to generic rounded apps.
• Midnight & Gold Palette: A curated contrast between Deep Midnight backgrounds (#0F172A) and vibrant Royal Gold accents (#D4AF37).
• Linguistic Trilingualism: Seamless native support for Arabic, English, and Urdu across both text and audio orchestration.

---

🧠 Advanced AI Orchestration

Hidayah AI leverages the latest in Generative AI to provide unprecedented scholarly depth:

• Multimodal Intent Routing: Uses Gemini 2.5 Flash to instantaneously classify user queries into Verse Lookup, Scholarly Research, or Document Analysis.
• Deep Scholarly RAG: A robust "Retrieval-Augmented Generation" pipeline using FAISS Vector Search and Gemini Embeddings to query scholarly PDF documents with high precision.
• Trilingual Audio Engine: A unique synchronized playback system that orchestrates recitation (e.g., Mishary Rashid) followed by translation-accurate audio (Ibrahim Walk or Shamshad Ali Khan).
• Graceful Quota Management: Professional, brand-aligned error masking that replaces technical API jargon with a "Scholar is Resting" status for service interruptions.

---

📱 Mobile-First Architecture

Engineered for use during specialized Ramadan study sessions, Hidayah AI features:

• Mobile-Responsive Verse Stacking: Intelligent CSS Grid transitions that stack language panes (Arabic → English → Urdu) for optimal vertical flow on touch devices.
• Scroll-Locked AI Overlay: A sophisticated full-width mobile overlay for the Scholar Agent that locks background scrolling to maintain architectural focus.
• Slide-Up Interaction: Native-feeling animations and a dedicated touch-friendly "✕" close button for seamless scholarly navigation.

---

🛠️ Technical Foundation

• Framework: Streamlit (Python)
• Primary LLM: Google Gemini 2.5 Flash
• Knowledge Retrieval: Tavily Search & FAISS Vector Store
• Data Protocols: AlQuran.cloud API Orchestration
• Typography: Amiri (Quranic), Inter (Technical), Playfair Display (Headers)

---

📥 Getting Started

1. Clone & Install:

   git clone https://github.com/mohammadali-14/Hidayah-AI.git
   pip install -r requirements.txt

2. Configure Environment: Populate your .env with GEMINI_API_KEY and TAVILY_API_KEY.
3. Launch:

   streamlit run app.py

---

Developed with devotion by the Hidayah AI Team.