[Enhancement] Hadith authenticity: grade references by sanad strength and refuse to present weak or fabricated narrations as authentic

[zeemscript]

Summary

For an Islamic assistant, presenting a weak (da'if) or fabricated (mawdu') narration as if it were authentic is one of the most serious failure modes there is — it puts words in the Prophet's ﷺ mouth that the scholars of hadith rejected. Right now the service has no notion of hadith authenticity at all: the model is simply told to use "Quran and Hadith" and left to its own training data, which is riddled with popular-but-unauthenticated narrations. This issue makes the assistant grading-aware: when it references a hadith, it must attach the collection, the grading (sahih / hasan / da'if / mawdu'), and the grader where known, refuse to present ungraded or weak narrations as evidence for rulings, and clearly separate "this is an authentic hadith" from "this is a popular saying with no reliable chain."

Current state

• ISLAMIC_CONTEXT (main.py, lines 57–71) mentions "authentic Islamic sources (Quran and Hadith)" and "Be clear about what is from authentic sources vs. scholarly opinion" but gives the model no methodology: no instruction to name the collection, state the grade, or refuse weak narrations. Authenticity is left entirely to the model's discretion.
• There is no hadith data of any kind in the repo — no collection index, no grading table, nothing. The service is main.py + stellar.py only (see requirements.txt: fastapi, google-generativeai, pydantic, stellar-sdk).
• The /chat handler (main.py, lines 118–184) sends the raw prompt to chat.send_message (lines 143–151) with no post-processing, so whatever the model asserts about a hadith's authenticity reaches the user unchecked.
• The structured-citations issue ([Enhancement] Return structured Quran/Hadith citations alongside answers #15) defines the shape of a citation and [Enhancement] Citation verification: check quoted Quran text against a bundled corpus and flag unverifiable references #40 verifies Quran text against a bundled corpus — neither touches hadith grading. This issue owns authenticity grading for hadith specifically.

What to build

1. A hadith grading knowledge layer — bundle a curated dataset (or integrate a source such as Sunnah.com's grading data where licensing permits) covering the major collections (Bukhari, Muslim, the four Sunan, Muwatta, etc.) that maps a normalized reference (collection + book/number) to its grade and, where available, the grading authority (e.g. al-Albani, the collection's own tashih). Ship it as a versioned local resource with a documented provenance and update process. If a full corpus is out of scope for one PR, define the schema and seed a defensible starter set, and make the lookup pluggable.
2. A grading lookup + reference normalizer — a module (e.g. hadith.py) that parses hadith references out of a model answer, normalizes them (collection aliases, transliteration variants, "Sahih al-Bukhari 1" ≡ "Bukhari [Enhancement] AI service responds slowly with no streaming or caching #1"), and returns a grade or unknown.
3. Grading policy enforcement — post-generation, annotate each referenced hadith with its grade; downgrade or flag any answer that leans on a da'if/mawdu' narration as evidence for a ruling; force ungraded references to be labeled "grading unverified" rather than implied authentic. Weak narrations may still be mentioned for encouragement (targhib/tarhib) contexts if explicitly labeled weak — encode that nuance.
4. Prompt guidance — extend the Islamic context with explicit hadith-adab rules: always name the collection, state the grade when known, never cite a hadith you cannot attribute, and prefer the two Sahihs for evidentiary claims.
5. Response metadata — an optional hadith_references: [{raw, collection, grade, grader, verified}] block on ChatResponse so the frontend can render authenticity badges. Keep it optional and additive.
6. Tests — offline unit tests for the normalizer and grading lookup (alias handling, unknown references), plus handler tests with a mocked Gemini client asserting the grading annotations and that a weak-hadith-as-evidence answer is flagged.

Acceptance criteria

• Hadith references in an answer are parsed and normalized across common spelling/numbering variants and matched against the bundled grading data.
• Each referenced hadith is annotated with its grade and grader where known; unknown references are labeled "grading unverified", never implied authentic.
• An answer that uses a known-weak or fabricated narration as evidence for a ruling is flagged (and the policy for weak-but-labeled targhib/tarhib usage is documented and enforced).
• The prompt guidance instructs the model to name the collection and state the grade for every hadith it cites.
• ChatResponse carries the optional hadith_references block; existing clients are unaffected.
• The grading dataset ships with documented provenance and an update process; the lookup is pluggable.
• Unit and handler tests run offline with a mocked client; CI stays green.

Pointers

• main.py — ISLAMIC_CONTEXT (lines 57–71), ChatResponse (lines 85–88), /chat handler and send_message (lines 118–184).
• requirements.txt — no data/NLP deps today; justify anything added.
• Adjacent issues to compose with, not absorb: [Enhancement] Return structured Quran/Hadith citations alongside answers #15 (citation shape), [Enhancement] Citation verification: check quoted Quran text against a bundled corpus and flag unverifiable references #40 (Quran text verification against a bundled corpus — mirror its bundling/provenance approach for hadith), [Enhancement] Retrieval-augmented generation over authenticated Quran and Hadith sources #24 (RAG retrieval — if it lands, the grading layer should annotate whatever hadith RAG returns; keep hadith.py importable so RAG can reuse it), [Enhancement] Madhhab-aware fiqh answers: present the positions of the major schools instead of one flattened ruling #39 (madhhab-aware answers rely on graded evidence — coordinate).
• CI (.github/workflows/ci.yml) lints and compiles only main.py and has no pytest step — extend flake8 to new modules and add a pytest step.
• PRs target the dev branch (see CONTRIBUTING.md).

Difficulty

High — hadith grading is a specialist domain with real data-sourcing and licensing questions, reference-parsing is genuinely fuzzy (many spellings and numbering schemes), and the policy layer must encode subtle scholarly conventions (weak-but-labeled targhib usage) without over-refusing. Getting this wrong is worse than doing nothing, so correctness and provenance matter.

---

🏆 GrantFox OSS — Official Campaign | FWC26. Apply for this issue through the GrantFox campaign page. The maintainer assigns one contributor before work starts; unassigned PRs may not be reviewed. PRs target the dev branch. Quality bar: CI must stay green.

💬 Questions or need help? Reach the maintainers and other contributors on the DeenBridge Telegram: https://t.me/+nst9lXNj1wc4ZDE0

[Tijesunimi004]

I am familiar with Open SOurce and would love to work on this project

[grantfox-oss]

🦊 GrantFox — @Tijesunimi004 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #53)
2. Your PR will be reviewed by the Deen-Bridge maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@Tijesunimi004's PR #63 was approved and merged by @zeemscript.

🏆 @Tijesunimi004: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (414 total points). Track your full progress on GrantFox.

👏 Great work, @Tijesunimi004! Keep contributing to Deen-Bridge.