[Enhancement] Contextual dua and adhkar recommender sourced from authenticated collections

[zeemscript]

Summary

"What du'a do I read before sleeping?" "Is there an authentic du'a for anxiety?" "What are the morning adhkar?" These are among the most useful, most-repeated requests an Islamic assistant gets — and exactly where a model that half-remembers a du'a, garbles the Arabic, or serves a fabricated supplication does real harm. This issue adds a contextual du'a and adhkar recommender backed by an authenticated collection (e.g. Hisnul Muslim / Fortress of the Muslim, with graded sources): match a user's situation or time of day to the right supplications, and return the Arabic, transliteration, translation, source, and grading — never an invented du'a. This is a concrete capability, not a prompt tweak.

Current state

• There is no du'a/adhkar data or endpoint. main.py exposes /chat, /ping, /chat/{chat_id}; stellar.py adds zakat. No supplication corpus exists in the repo.
• A du'a question today goes straight to chat.send_message (main.py, lines 143–151), so the Arabic text, transliteration, and — critically — the authenticity of the supplication are whatever the model produces, with no source and no grading.
• ISLAMIC_CONTEXT (lines 57–71) asks the model to "Cite sources when possible," but there is no du'a corpus to cite and nothing enforces authenticity for supplications specifically.

What to build

1. An authenticated adhkar corpus — bundle a du'a/adhkar dataset with, per entry: Arabic text, transliteration, translation, category (morning, evening, before sleep, travel, distress, after salah, etc.), source reference, and grading. Prefer a well-known authenticated compilation (e.g. Hisnul Muslim) with documented provenance and licensing; where a du'a is Quranic or from the two Sahihs, mark it accordingly. Reuse the hadith-grading layer from #ai-16 for grading rather than a parallel scheme.
2. A recommender endpoint (e.g. POST /adhkar/recommend) that takes a situation/time/category (and optional free-text like "I'm feeling anxious") and returns the matching supplications with full metadata. Support both category lookup and semantic matching of free-text situations (embedding similarity is fine — coordinate with [Enhancement] Semantic response cache with embedding-similarity matching for repeated questions #27's embedding infra if it lands).
3. Time/context awareness — for morning/evening adhkar, use the Hijri/prayer-time context (coordinate with [Enhancement] Prayer times and Hijri calendar endpoints with selectable calculation methods #28) so "what adhkar now?" resolves correctly.
4. Chat integration — detect du'a/adhkar intent ([Enhancement] Question-understanding pipeline: intent classification, clarifying questions, answer-length calibration, and suggested follow-ups #42) and answer from the corpus, having the model present the authenticated text and source rather than generating a supplication. Explicitly forbid inventing du'as: if nothing authentic matches, say so.
5. Structured, validated output — a typed response so the frontend can render Arabic (RTL), transliteration, and source badges consistently. Coordinate RTL/Arabic display with [Enhancement] First-class Arabic and multilingual support #14.
6. Tests — offline tests asserting category and free-text lookups return the right authenticated entries with complete metadata, and that a no-authentic-match case declines rather than fabricates. No live API calls in CI.

Acceptance criteria

• A bundled authenticated adhkar corpus ships with Arabic, transliteration, translation, category, source, and grading per entry, with documented provenance/licensing.
• POST /adhkar/recommend returns matching supplications by category and by free-text situation, each with full metadata.
• Morning/evening ("now") requests resolve using Hijri/prayer-time context coordinated with [Enhancement] Prayer times and Hijri calendar endpoints with selectable calculation methods #28.
• Chat du'a questions are answered from the corpus; the model never invents a supplication, and a no-match case declines explicitly.
• Grading reuses the #ai-16 hadith-grading layer; RTL/Arabic display coordinates with [Enhancement] First-class Arabic and multilingual support #14 — no parallel schemes.
• Output is typed and validated; tests cover category, free-text, and no-match cases offline; CI stays green.

Pointers

• main.py — router wiring (line 24), /chat handler (lines 118–184), ISLAMIC_CONTEXT (lines 57–71).
• stellar.py — typed router/endpoint pattern (lines 25, 65–81, 106–170) as the template; its DISCLAIMER (lines 50–54) is a good model for a "consult a scholar for specific rulings" note.
• Adjacent issues to compose with: #ai-16 (hadith grading — reuse for du'a authenticity), [Enhancement] Prayer times and Hijri calendar endpoints with selectable calculation methods #28 (prayer times/Hijri — for time-of-day resolution), [Enhancement] Semantic response cache with embedding-similarity matching for repeated questions #27 (embeddings/cache — for free-text matching), [Enhancement] First-class Arabic and multilingual support #14 (Arabic/RTL display), [Enhancement] Question-understanding pipeline: intent classification, clarifying questions, answer-length calibration, and suggested follow-ups #42 (intent).
• CI (.github/workflows/ci.yml) lints/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

Medium — the engineering (typed endpoint, corpus lookup, optional embedding match) is moderate and well-precedented by stellar.py; the real work is sourcing a properly authenticated, well-graded adhkar corpus with clean provenance and wiring the authenticity/display concerns to the issues that own them rather than reinventing them.

---

🏆 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

[Myart352]

Hi! I'd like to work on this issue.

I understand the importance of ensuring that du'a and adhkar responses are sourced from authenticated collections rather than generated by the model. My approach will be to implement a typed recommendation endpoint backed by a verified corpus, returning the Arabic text, transliteration, translation, category, source, and grading for each supplication. I'll integrate it with the chat flow so du'a requests are answered from the authenticated dataset, support both category-based and contextual lookups, reuse the existing hadith grading infrastructure, and coordinate with the related issues where appropriate. I'll also add comprehensive offline tests, keep the implementation well documented, and ensure CI remains green.

Thank you for considering my application!

[grantfox-oss]

🦊 GrantFox — @Myart352 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 #59)
2. Your PR will be reviewed by the Deen-Bridge maintainers

Good luck! Track your progress on GrantFox.