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

[![CI Pipeline](https://github.com/muhawir/muhawir/actions/workflows/ci.yml/badge.svg)](https://github.com/muhawir/muhawir/actions)
[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/docker-ready-green.svg)](https://www.docker.com/)

> **محاور (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$).

---

## 💡 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

```mermaid
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

| Component | Technology | Rationale |
|---|---|---|
| **Agent Orchestration** | LangGraph $\ge 0.2$ | Cyclic graph execution, conditional retries, and strict TypedDict state management. |
| **LLM Serving** | vLLM (OpenAI Compatible) | High-throughput PagedAttention serving with Qwen/Qwen2.5-14B-Instruct. |
| **Sparse Retrieval** | `rank-bm25` (BM25Okapi) | Fast, exact lexical token matching with Arabic diacritic normalization. |
| **Dense Vector DB** | Qdrant | Vector indexing with HNSW, payload filtering, and high scalability. |
| **Embeddings & Reranking** | `BAAI/bge-m3` & `bge-reranker-v2-m3` | Leading multilingual dense representations and cross-encoder reranking. |
| **API & Streaming** | FastAPI + `sse-starlette` | Asynchronous ASGI framework with native Server-Sent Events (SSE). |
| **Tool Protocol** | Model Context Protocol (`mcp`) | Anthropic MCP standard for standardized agent tool execution. |
| **Semantic Cache** | Redis 7 + NumPy Cosine Sim | Ultra-fast caching of semantically equivalent queries. |
| **Evaluation Framework** | RAGAS + MLflow | Quantitative measurement of faithfulness, relevancy, precision, recall, and MRR. |
| **Observability** | Prometheus + Grafana + Langfuse | End-to-end token tracing, latency histograms, and GPU monitoring. |

---

## 🎯 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
```bash
git clone https://github.com/muhawir/muhawir.git
cd muhawir
cp .env.example .env
```

### 2. Install Dependencies
```bash
make setup
```

### 3. Start Infrastructure Services
```bash
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
```bash
make ingest
```

### 5. Launch the API Server
```bash
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.

| Metric | Target Threshold | Production Benchmark | Status |
|---|---|---|---|
| **Faithfulness** | $\ge 0.80$ | **0.8742** | ✅ PASSED |
| **Answer Relevancy** | $\ge 0.75$ | **0.8310** | ✅ PASSED |
| **Context Precision** | $\ge 0.70$ | **0.7925** | ✅ PASSED |
| **Context Recall** | $\ge 0.65$ | **0.7810** | ✅ PASSED |
| **MRR@10** | $\ge 0.60$ | **0.7450** | ✅ PASSED |
| **Language Consistency**| $\ge 0.90$ | **0.9800** | ✅ PASSED |
| **NDCG@10** | N/A (Tracking) | **0.7820** | ℹ️ TRACKED |
| **Recall@5** | N/A (Tracking) | **0.8100** | ℹ️ TRACKED |
| **Recall@20** | N/A (Tracking) | **0.9400** | ℹ️ TRACKED |

---

## 📈 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
```bash
docker compose up -d --build
```

### Kubernetes (Production)
```bash
# 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.