amankhan1009/daily-hadith-ai-agent repository overview

⁠Daily Hadith AI Agent

A production-grade, fail-closed AI system and publicly accessible Telegram bot delivering verified daily Hadith notifications to subscribers, orchestrated with LangGraph, verified deterministically with Pydantic, persisted on Neon PostgreSQL, and powered by Groq.

⁠Core Problem & Engineering Philosophy

Generative AI models are probabilistic by nature—they hallucinate, paraphrase without permission, and confabulate citations. When building software around sacred or canonical domain texts (such as Hadith literature, legal statutes, or clinical guidelines), probabilistic generation without deterministic boundaries is unacceptable.

A naive implementation might ask an LLM to "send a daily Hadith from Sahih al-Bukhari". This frequently results in invented chains of narration (Isnad), paraphrased translations, or fabricated references.

Daily Hadith AI Agent solves this through architectural rigor:

• Canonical texts are never generated or modified by AI. The English translation is retrieved directly from an approved primary source (HadeethEnc⁠) via its official API and preserved with byte-for-byte fidelity.
• Deterministic verification gates run before any LLM is invoked. If references, metadata, or English/Arabic cross-matching fail, the pipeline terminates immediately (fail-closed).
• Generative AI is strictly isolated to supplementary educational reflections, clearly demarcated as non-canonical commentary.

⁠System Architecture

flowchart TD
    subgraph Ingestion ["1. Deterministic Ingestion Pipeline"]
        API["HadeethEnc API (GET)"] --> Fetch["Candidate Ingestion (EN + AR)"]
        Fetch --> Match["Metadata Cross-Match & Provenance"]
        Match --> Gate{"Passes Deterministic Gate?"}
        Gate -- "No" --> Abort["Persist Audit Log & Abort"]
        Gate -- "Yes" --> DB[("Neon PostgreSQL Candidate Queue")]
    end

    subgraph Webhook ["2. Inbound Webhook & Multi-User Router"]
        Users["Public Telegram Users"] -->|"/start, /today, /stop, /help"| WH["FastAPI POST /telegram/webhook"]
        WH --> Sec{"Verify Secret Token"}
        Sec -- "Invalid" --> Reject["403 Forbidden"]
        Sec -- "Valid" --> Router["Command Router"]
        Router -->|"/start (Idempotent)"| SubDB[("Telegram Subscribers")]
        Router -->|"/today"| InstantSend["Dispatch Today's Hadith"]
        Router -->|"/stop"| Deact["Deactivate (is_active = false)"]
    end

    subgraph Daily ["3. Daily Orchestration & Fan-Out Broadcast"]
        Sched["Daily Trigger: 10:00 AM IST"] --> LG["LangGraph Daily StateGraph"]
        LG --> Idemp{"Idempotency Check"}
        Idemp -- "Already Sent" --> Skip["Skip Execution"]
        Idemp -- "Fresh Run" --> LLM["Groq LLM Reflection (Segregated)"]
        LLM --> Guard{"Guardrails AI Gate"}
        Guard -- "Violation" --> Fallback["Omit Reflection (Fail-Safe)"]
        Guard -- "Valid" --> Format["Format Canonical Notification"]
        Fallback --> Format
        Format --> Broadcaster["Multi-User Fan-Out Broadcaster"]
        SubDB -->|"Active Subscribers"| Broadcaster
        Broadcaster -->|"30 msg/sec Throttling"| TG["Telegram Bot API"]
        TG -->|"403 Blocked"| AutoDeact["Auto-Deactivate Blocked User"]
        TG -->|"Delivered"| Record["Record Per-Subscriber Delivery Log"]
    end

⁠Repository Structure & Package Guides

Every folder in this codebase includes its own dedicated README guide:

⁠Key Reliability Principles

1. Deterministic Content Gates: Every candidate record undergoes Pydantic schema validation, reference consistency checks, and English/Arabic pair matching.
2. Fail-Closed Safety: If external APIs are unresponsive, references are ambiguous, or metadata is incomplete, the system rejects the candidate rather than dispatching unverified religious material.
3. Exact Source Attribution: Every notification includes the authentic collection title, verified reference number, canonical HadeethEnc URL, and translation-version metadata.
4. Physical Idempotency: Neon PostgreSQL enforces a UNIQUE constraint on DailyDeliveryLog.scheduled_date, ensuring at most one delivery per calendar day.
5. Clear AI Separation: Any LLM-generated reflection is explicitly labeled: AI-generated reflection — not part of the original Hadith.
6. No Web Scraping: Only official REST API endpoints are utilized.

⁠Project Status & Roadmap

The project is actively developed following a 20-milestone engineering roadmap:

For the complete 20-milestone breakdown, see docs/PROJECT_ROADMAP.md⁠.

⁠Local Development Setup

⁠Prerequisites

• Python 3.14 or 3.13
• Git

⁠Installation

# Clone the repository
git clone https://github.com/Amankhan1009/daily-hadith-ai-agent.git
cd daily-hadith-ai-agent

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

⁠Running the Test Suite

.venv/bin/pytest -v

⁠License & Attribution

• Source Code: MIT License.
• Hadith Content: Retrieved from HadeethEnc⁠ and attributed under their open non-commercial educational reuse guidelines.