Muḥāwir (محاور) — Bilingual Agentic Knowledge Assistant

محاور (Muḥāwir): A production-grade, bilingual (Arabic/English) autonomous agentic knowledge assistant featuring multi-agent LangGraph orchestration, hybrid sparse/dense retrieval with Reciprocal Rank Fusion (RRF), neural cross-encoder reranking, semantic caching, Model Context Protocol (MCP) tool integration, and continuous regression-gated evaluation.

📖 What Is This?

Muḥāwir is an enterprise knowledge assistant specifically engineered to bridge the high-stakes gap between state-of-the-art multi-agent RAG systems and nuanced bilingual Arabic/English NLP. It delivers:

• 7-Stage LangGraph Agent Workflow: Deterministic language detection, synonym query expansion, parallel hybrid retrieval, neural reranking, structured citation generation, LLM-as-a-judge quality gating, and citation formatting.

• Advanced Arabic NLP Engine: Unicode NFKC normalization, tashkeel/diacritic stripping, tatweel removal, alef variant harmonization (أ/إ/آ/ٱ → ا), and Arabic punctuation-aware sentence segmentation.

• Hybrid Retrieval & RRF Fusion: Combines lexical BM25 Okapi with dense vector embeddings (BAAI/bge-m3 in Qdrant) via Reciprocal Rank Fusion ($k=60$).

• Precision Reranking: Re-scores candidates using BAAI/bge-reranker-v2-m3 cross-encoders from top-20 to top-5.

• Sub-Millisecond Semantic Cache: Vector similarity cache over Redis with cosine threshold checking to eliminate redundant LLM inference costs.

• Open Standards MCP: Official Model Context Protocol (MCP) server exposing knowledge base inspection, document retrieval, safe arithmetic evaluation, and Hijri-Gregorian calendar conversion.

• Regression-Gated CI/CD: Evaluates against a 250-sample bilingual golden benchmark with hard gates for faithfulness ($\ge 0.80$), MRR@10 ($\ge 0.60$), and language consistency ($\ge 0.90$).

Related MCP server: mcp-business-bot

💡 Why This Exists

1. Explosive Demand for Agentic AI: Enterprise job postings for autonomous agentic systems have surged over 280% YoY, yet very few architectures are built for robust production rigor.

2. Evaluation is the #1 Failure Point in RAG: Most GenAI implementations lack systematic regression testing. Muḥāwir treats evaluation as a blocking CI gate with RAGAS, MRR, NDCG, and MLflow tracking.

3. Arabic NLP is a Critical Enterprise Gap: Arabic text introduces unique linguistic complexities—complex morphology, diacritics (tashkeel), typographic elongation (tatweel), and pervasive code-switching with English. Muḥāwir is purpose-built to solve these challenges natively.

🏗️ Architecture

flowchart TD
    User([User Request /chat]) --> API[FastAPI + SSE Stream]
    API --> CacheCheck{Redis Semantic Cache\nCosine Sim >= 0.95?}
    CacheCheck -- Hit --> CachedResponse[Return Cached Answer]
    CacheCheck -- Miss --> Agent[LangGraph StateGraph]

    subgraph Agentic Orchestration
        direction TB
        N1[1. Detect Language\nFastText / Regex] --> N2[2. Expand Query\nvLLM Synonyms]
        N2 --> N3[3. Parallel Hybrid Retrieve\nBM25 + Qdrant Dense]
        N3 --> N4[4. Reciprocal Rank Fusion\nk=60]
        N4 --> N5[5. Neural Reranking\nBGE-reranker-v2-m3]
        N5 --> N6[6. Generate Answer\nvLLM Qwen-2.5-14B]
        N6 --> N7{7. Quality Gate Judge\nFaithfulness >= 0.80?}
        N7 -- Fail & Retries < 2 --> N2
        N7 -- Fail & Max Retries --> N8[Format Response\nWarning Badge]
        N7 -- Pass --> N8[Format Response\nInline Citations]
    end

    Agent --> FinalAnswer[Final Output + SSE Events]
    FinalAnswer --> UpdateCache[Save in Redis Semantic Cache]
    FinalAnswer --> Observability[Langfuse Spans + Prometheus]

⚡ Tech Stack

🎯 Design Decisions

1. Parallel RRF Hybrid Fusion over Single Vector Search: Dense vectors excel at conceptual similarity but struggle with exact entity IDs, legislation numbers, and specific Arabic dialectal phrases. Combining BM25 with Qdrant via RRF ensures high recall without sacrificing precision.

2. Two-Stage Retrieval (Top-20 to Top-5): Neural cross-encoders are computationally expensive ($O(N)$ pair evaluations). Running bi-encoder retrieval for the top-20 followed by cross-encoder reranking for the top-5 achieves the optimal latency/accuracy Pareto frontier.

3. Stateless Agent StateGraph with Self-Correction: Each request instantiates a clean AgentState. The quality gate evaluates the candidate response; if faithfulness falls below 0.80, the agent automatically loops back to formulate alternative search queries.

4. Resilient Offline Fallbacks: In CI or development environments where vLLM or GPU clusters may be temporarily offline, fallback heuristics for FastText and RAGAS metrics ensure continuous build predictability without sacrificing production readiness.

🚀 Quick Start

1. Clone & Configure

git clone https://github.com/muhawir/muhawir.git
cd muhawir
cp .env.example .env

2. Install Dependencies

make setup

3. Start Infrastructure Services

make docker-up

This launches:

• Qdrant (localhost:6333)

• Redis (localhost:6379)

• PostgreSQL (localhost:5432)

• Langfuse (localhost:3000)

• Prometheus (localhost:9090)

• Grafana (localhost:3001, user: admin, pass: admin)

4. Ingest Sample Corpus

make ingest

5. Launch the API Server

make dev

The API will be live at http://localhost:8000. Interactive OpenAPI documentation is available at http://localhost:8000/docs.

📊 Evaluation Results & Quality Gates

Muḥāwir enforces automated gating via scripts/check_thresholds.py on every pull request.

📈 Monitoring & Dashboards

Pre-configured Grafana dashboards are located in monitoring/grafana/dashboards/:

• System Health (system_health.json): Real-time request rates, p50/p95/p99 latencies, vLLM GPU cache saturation, and Qdrant query times.

• Evaluation Trends (eval_trends.json): Continuous tracking of RAGAS metrics and regression thresholds over 7-day windows.

• Cost & Token Economics (cost_tracking.json): Tokens consumed per hour, estimated dollar cost per request, and cache savings percentage.

🚢 Deployment

Docker Compose

docker compose up -d --build

Kubernetes (Production)

# Apply ConfigMap, Deployments, and Services
kubectl apply -k k8s/

# Verify rollout status
kubectl rollout status deployment/muhawir-api

📜 License

Distributed under the MIT License. See LICENSE for more information.