🤲 Islamic AI Companion

Guided by Wisdom.
Powered by AI.

A spiritually-grounded conversational API. Tone detection, journey tracking, multilingual support (Arabic, Urdu, English) and Quranic references — all in one.

🔄 3-Model Fallback

🎭 13 Tone Modes

📊 Journey Tracking

🌍 Multilingual

📿 Quranic Refs

📱 Flutter Ready

API Endpoints

GET /health Status & model info ▾

Returns API status, active models and configuration.

        {
          "status": "OK",
          "mode": "HF Router API (Free Tier)",
          "models": ["Llama-3-8B-Instruct", "Llama-3.1-8B-Instruct", "Llama-3.2-1B-Instruct"],
          "token_configured": true
        }
                  

POST /chat Main conversation endpoint ▾

Core chat endpoint with Llama-3 fallback. Detects tone, language and intent. Supports journey flow, MCQ submissions, and general conversation.

Field	Type	Description
messagerequired	string	User's message (max 1000 chars)
user_idrequired	string	Unique user identifier (display name)
categoryoptional	string	Journey category (default: "General")
previous_summaryoptional	object	Previous session context
answersoptional	array	MCQ answers array for submission

        // Request body
        {
          "message": "What is the meaning of patience in Islam?",
          "user_id": "Abdullah123",
          "category": "Religious Self"
        }
        
        // Response
        {
          "status": "insight_only",
          "voice_answer": "Sabr (patience) in Islam is...",
          "middle_section": "Detailed Notes: ...",
          "middle_label": "Detailed Notes",
          "follow_up": "Which aspect of sabr do you find most challenging?",
          "references": "Quran 2:153 — Indeed, Allah is with those who are patient.",
          "model_used": "Llama-3-8B-Instruct",
          "next_action_guidance": { /* guidance object */ }
        }
                  

GET /journey/{user_id} User progress & stats ▾

Returns a user's journey progress, cumulative summary, loopholes and recent activity.

Parameter	Type	Description
user_idpath	string	User identifier
categoryoptional	string	Category filter (default: "General")

GET /categories Available MCQ categories ▾

Returns all available journey categories with question counts.

        {
          "categories": ["Religious Self", "Emotional Self", "General", /* ... */],
          "total_questions": { "Religious Self": 12, /* ... */ },
          "description": "Categories for spiritual and personal development journeys"
        }
                  

POST /reset-journey/{user_id} Reset journey in category ▾

Resets a user's journey progress in a specific category. Fresh start, insha'Allah.

Parameter	Type	Description
user_idpath	string	User to reset
categoryquery	string	Category to reset (default: "General")

Live API Tester

User ID

Guided by Wisdom. Powered by AI.

Guided by Wisdom.
Powered by AI.