Muḥāwir | محاور

Bilingual agentic knowledge assistant

Arabic + English · LangGraph · Hybrid RAG · Evaluations · Guardrails

Quick start · Architecture · Evaluation · Source

At a glance

Muḥāwir is an Arabic/English agentic knowledge assistant built around retrievers, rerankers, contextual conversation, and measurable answer quality. It is a source-code project for experimenting with production-oriented AI architecture, not a claim of a hosted commercial service.

Related MCP server: DocAgent-MCP

Architecture

flowchart TD
    U["Arabic / English question"] --> API["FastAPI + SSE"]
    API --> G["Input guardrails"]
    G --> L["Language detection + conversation context"]
    L --> R{"Query complexity"}
    R -->|Simple| S["Single-hop retrieval"]
    R -->|Complex| M["LangGraph multi-hop planning"]
    M --> S
    S --> H["BM25 + Qdrant vectors"]
    H --> F["RRF fusion + neural reranker"]
    F --> A["LLM via OpenAI-compatible vLLM endpoint"]
    A --> Q["Output checks + evaluation"]
    Q --> U2["Answer with citations"]
    U2 -.-> O["Langfuse / Prometheus / MLflow"]

The diagram summarizes the intended request path. Some services depend on separately deployed model infrastructure and configured credentials.

Quick start

Requirements: Python 3.11+, Docker and Docker Compose for infrastructure, and an OpenAI-compatible model server for generation.

git clone https://github.com/FaizanAKhan786/muhawir.git
cd muhawir
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env

Security: Generate a strong random API key and set API_KEY in .env (for example, python -c "import secrets; print(secrets.token_urlsafe(32))"). There is no usable default key. Chat, evaluation, session history and memory routes now require the X-API-Key header. An API key protects this reference service, but is not per-user authentication or tenant isolation.

Configure .env for your vLLM endpoint (VLLM_BASE_URL defaults to port 8001), Qdrant, Redis, and optional tracing credentials. Then start the dependencies and API:

docker compose up -d qdrant redis postgres langfuse
uvicorn src.api.main:app --reload --port 8000

Open API docs locally. Initial model downloads and inference capacity depend on your machine. A working Qdrant container is not a substitute for a running LLM endpoint.

For corpus preparation, see the ingestion script and sample documents. The Makefile provides shortcuts such as make ingest, make docker-up, and make eval.

Evaluation and tests

pytest tests/ -v
ruff check .
python scripts/run_eval.py --golden-set data/golden_sets/golden_v1.0.json

Evaluation code lives in src/evaluation/ and sample benchmark data in data/golden_sets/. Evaluation integrity: The shipped golden-set script performs fixture-based proxy diagnostics when no real retriever and generator are supplied. It does not fabricate rank-1 retrieval hits: MRR/NDCG/Recall remain not evaluated, and quality gates fail rather than claiming production readiness. See Evaluation Integrity. Configure a genuine retriever, model, and evaluation dataset before publishing benchmark claims.

Repository map

Scope and limitations

This repo showcases an engineering implementation and reference architecture. Running all paths requires appropriate inference compute, model assets, external service configuration and evaluation data. No real government data or proprietary deployment is included.

Verification & benchmark protocol

Read the reproducible test and evaluation guide. It documents the current automated checks, commands for model-dependent evaluations, and what results do not establish.

Issues · GitHub profile