[Enhancement] Faraid and computational-fiqh reasoning engine with verifiable step-by-step working

[zeemscript]

Summary

Some of the most-asked, highest-value Islamic questions are computational: "My father died leaving a wife, two sons, a daughter, and 90,000 — who gets what?" (faraid / inheritance), "I have gold, cash, and business stock — what's my zakat?", "The month started on this date — when is the 27th night?". A general chat model is notoriously bad at exactly this: it slips arithmetic, drops an heir, or misapplies the shares. This issue builds a computational-fiqh reasoning engine that solves these deterministically — real inheritance-share math, real zakat-across-asset-classes math — with verifiable step-by-step working, instead of trusting the LLM's mental arithmetic. The existing zakat endpoint proves the pattern at the smallest scale; this generalizes it into a real capability.

Current state

• The only deterministic calculation in the service is stellar.py's zakat endpoint — a single 2.5%-of-USDC-balance computation (ZAKAT_RATE, line 47; calculate_zakat, lines 117–170). It handles exactly one asset (on-chain USDC), one rate, one nisab. There is no inheritance logic, no multi-asset zakat, no calendar math.
• Everything else is delegated to the LLM via chat.send_message (main.py, lines 143–151), which means any inheritance or multi-asset question is answered by a language model doing arithmetic in its head — the classic failure case.
• ISLAMIC_CONTEXT (lines 57–71) gives no methodology for multi-step problems and the generation config (lines 145–150) is tuned for prose, not reasoning.

What to build

1. A faraid (inheritance) engine — a deterministic module (e.g. faraid.py) that, given the estate value and the set of surviving heirs, computes each heir's share per the rules of the Sunni schools: the fixed shares (furud), residuary (asaba) distribution, the awl (increase) and radd (return) adjustments, and blocking (hajb) rules. Output exact fractions and amounts. Cite the basis for each allocation. Where schools genuinely differ (e.g. treatment of certain cases), surface the difference and coordinate with the madhhab-aware issue ([Enhancement] Madhhab-aware fiqh answers: present the positions of the major schools instead of one flattened ruling #39) rather than hard-coding one school silently.
2. A generalized zakat calculator — extend beyond stellar.py's single-asset case to cash, gold/silver (by weight and current price), and trade goods, with nisab computed from live or configured metal prices (coordinate with [Enhancement] Zakat v2: wire the Stellar zakat endpoint into chat, live nisab pricing, and tests #22 Zakat v2, which already covers live nisab pricing and wiring zakat into chat — build on it, don't fork it).
3. Verifiable working — every result returns structured, auditable steps (which heir got which share and why; how each asset contributed to the zakat base), not just a final number, so users and reviewers can check the logic. Include disclaimers mirroring stellar.py's DISCLAIMER (lines 50–54).
4. Chat routing — detect computational questions in /chat (reuse [Enhancement] Question-understanding pipeline: intent classification, clarifying questions, answer-length calibration, and suggested follow-ups #42 intent), extract the structured parameters (a tool/function call is ideal — coordinate with the function-calling registry [Enhancement] Gemini function-calling framework with a safe tool registry for platform capabilities #25 so this engine is registered as a tool rather than re-implementing extraction), run the deterministic engine, and have the model present the verified result in natural language without altering the numbers.
5. Tests — a substantial offline test suite of worked faraid cases (classic textbook problems: spouse + children, awl cases, radd cases, blocking) with known correct answers, plus multi-asset zakat cases. This is the acceptance backbone — the math must be provably right.

Acceptance criteria

• The faraid engine solves standard inheritance problems (fixed shares, residuary, awl, radd, blocking) with exact fractions/amounts and a cited basis per allocation, matching known textbook answers in the test suite.
• The zakat calculator handles cash, gold/silver by weight, and trade goods with a correctly computed nisab, extending (not forking) [Enhancement] Zakat v2: wire the Stellar zakat endpoint into chat, live nisab pricing, and tests #22's work.
• Every calculation returns structured, auditable working plus a consult-a-scholar disclaimer — no bare final number.
• Computational chat questions are routed to the deterministic engine (ideally via the [Enhancement] Gemini function-calling framework with a safe tool registry for platform capabilities #25 tool registry) and the model presents the verified numbers without changing them.
• School-level differences in faraid are surfaced and coordinated with [Enhancement] Madhhab-aware fiqh answers: present the positions of the major schools instead of one flattened ruling #39, not silently hard-coded.
• A comprehensive offline test suite of worked cases passes; CI stays green.

Pointers

• stellar.py — the entire zakat implementation is the reference pattern: ZAKAT_RATE/nisab (lines 43–48), DISCLAIMER (lines 50–54), typed request/response and endpoint (lines 65–81, 117–170). Generalize this, don't duplicate it.
• main.py — /chat handler (lines 118–184), ISLAMIC_CONTEXT (lines 57–71); register the new router alongside stellar_router (line 24).
• Adjacent issues to compose with: [Enhancement] Zakat v2: wire the Stellar zakat endpoint into chat, live nisab pricing, and tests #22 (Zakat v2 — live nisab + chat wiring, build on it), [Enhancement] Gemini function-calling framework with a safe tool registry for platform capabilities #25 (function-calling registry — register the engine as a tool), [Enhancement] Madhhab-aware fiqh answers: present the positions of the major schools instead of one flattened ruling #39 (madhhab differences), [Enhancement] Question-understanding pipeline: intent classification, clarifying questions, answer-length calibration, and suggested follow-ups #42 (intent routing).
• CI (.github/workflows/ci.yml) has no pytest step — add one; the worked-case suite is the point of this issue. Extend flake8 to new modules.
• PRs target the dev branch (see CONTRIBUTING.md).

Difficulty

High — faraid is an entire discipline; implementing furud, asaba, awl, radd, and hajb correctly (and knowing where the schools diverge) is meticulous work, and generalizing zakat across asset classes with live pricing adds real integration. But because the outputs are deterministic, they are fully testable — which is exactly why this belongs in code, not in the model's head.

---

🏆 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

[Killerjunior]

Hi maintainer, I have read and understood the issue requirements and checked the necessary documentation. I’m confident I can work on this task effectively and deliver a proper solution.

[grantfox-oss]

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

Good luck! Track your progress on GrantFox.