🕌 Deen Bridge — AI Service

The FastAPI service behind Deen Bridge's Islamic-knowledge AI assistant, powered by Google Gemini.

Live API · Web App · Report a Bug · Contribute

About

This service powers the AI assistant inside Deen Bridge, a platform for authentic Islamic education built on the Stellar network — courses and books are purchased with USDC, and creators are paid directly to their own Stellar wallets. The assistant wraps Google's Gemini model with an Islamic-knowledge system prompt, content safety filters, and per-session conversation history, exposing a simple chat API consumed by the web app.

Stellar-aware chat supports wallet USDC zakat estimates, factual answers about the signed-in user's Stellar purchases, and exact USDC/stroop and user-specified percentage calculations. Calculations are informational; the AI service never signs or submits a Stellar transaction.

The platform is composed of three services:

✨ Features

• 🤖 Islamic context-aware responses grounded in a curated system prompt
• 🌍 Multilingual support — Arabic, English, Urdu, Malay, French, and more; always quotes Quran in Arabic script with translation
• 🧵 Conversation history per chat session
• 🛡️ Content safety filters on model output
• 🎚️ Confidence-aware answers — abstains or hedges instead of guessing, and routes doubtful religious answers to a scholar
• 🧠 Per-user long-term memory — user profiles (knowledge level, madhhab, topics studied, remembered facts) extracted from conversations and injected across sessions; privacy controls with GET/DELETE endpoints and remember opt-out per request
• 📋 Conversation summarization — compaction API ready for token-budget-triggered eviction; merges and recompresses summaries when history exceeds budget
• 📖 Tafsir-grounded ayah explanations — retrieved from named classical works, never paraphrased from model memory
• 🕵️ Hadith Research Agent — retrieval, isnad chain analysis, rijal (narrator) cross-referencing, grading justification, and variant alignment across ten major collections
• 📚 Structured citations — Quran and Hadith references returned as validated, typed objects on every answer, bounds-checked against the 114-surah index
• ⚡ FastAPI with automatic OpenAPI docs at /docs

🔗 API

All chat endpoints require an X-API-Key header (see Authentication & Rate Limiting).

🔐 Authentication & Rate Limiting

Authentication

Protected endpoints (including /chat and /chat/stream) require an X-API-Key request header whose value matches the server's SERVICE_API_KEY. Requests with a missing or invalid key are rejected with 401. For local development you can bypass authentication entirely by setting AUTH_DISABLED=true (never do this in production — SERVICE_API_KEY is mandatory when ENVIRONMENT=production).

Rate Limiting

The service enforces three independent limits. All of them are in-process (non-persistent) and therefore reset on restart and are scoped to a single instance — a shared Redis backend would be required for multi-instance deployments.

How a client is identified for the request-rate limit. The slowapi limiter keys each caller by, in order of preference: the X-API-Key header (so limits are enforced per API key when authenticated), otherwise the first address in X-Forwarded-For (the app runs behind a proxy on Render), otherwise the direct remote address. The hourly token quota is keyed by the request's user_id when one is supplied, falling back to the same client key.

Response headers — no X-RateLimit-*

Note: This service does not emit X-RateLimit-Limit, X-RateLimit-Remaining, or X-RateLimit-Reset headers. The slowapi limiter is created as Limiter(key_func=...) without headers_enabled=True, so those informational headers are never added. Do not build clients that depend on them.

The only rate-limit header you can rely on is Retry-After (an integer number of seconds), which is set on:

• 429 responses from /chat and /chat/stream (request-rate limit), and
• the 429 returned by the /chat hourly token-quota check.

The /feedback 429 does not include a Retry-After header; its 60-second window is described in the JSON hint field instead.

429 response shape

All three limits return HTTP 429 with a JSON body containing a detail message and a human-readable hint, for example:

// POST /chat or /chat/stream — request-rate limit exceeded
// (also carries a `Retry-After: <seconds>` header)
{
  "detail": "Rate limit exceeded: 60 per 1 minute",
  "hint": "Too many requests sent. Please wait 60 seconds before retrying."
}

// POST /chat — hourly token quota exceeded
// (also carries a `Retry-After: <seconds>` header)
{
  "detail": "Token quota