README.md

metadata

title: Mexar
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
license: mit

🧠 MEXAR

Multimodal Explainable AI Reasoning Assistant

Build domain-specific AI agents from your documents — with transparent, grounded, and faithful answers.

🚀 Live App → mexar.vercel.app   |   📡 Backend API → devrajsinh2012-mexar.hf.space   |   📖 API Docs → /docs

---

📖 What is MEXAR?

MEXAR is a full-stack, production-ready RAG (Retrieval-Augmented Generation) platform that lets you create custom AI agents from your own documents. Unlike a simple chatbot, MEXAR is built around explainability and faithfulness — every answer is grounded in your source data, cited with inline references, and scored for hallucination risk using a NLI model.

You upload documents → MEXAR compiles an agent → You chat with grounded, explainable AI.

---

✨ Core Features

Feature	Description
🔍 Hybrid RAG Search	Semantic (pgvector cosine) + Keyword (BM25 tsvector) fused via Reciprocal Rank Fusion (RRF)
🎯 Cross-Encoder Reranking	sentence-transformers cross-encoder re-scores top candidates for precision
📎 Inline Source Attribution	Every answer references exact source chunks with [1], [2] citations
✅ DeBERTa-v3 Faithfulness Scoring	NLI-based hallucination detection scores answer grounding against retrieved context
🔐 Domain Guardrails	TF-IDF + spaCy NER Jaccard similarity prevents out-of-domain queries (F1 = 0.9072 at threshold 0.25)
🗣️ Multimodal Input	Audio (Groq Whisper), Images (Groq Vision), Video (OpenCV frame extraction)
🔊 Text-to-Speech	ElevenLabs API + Web Speech API fallback
🧠 Explainability Panel	Full reasoning trace: retrieval scores, confidence breakdown, sources cited, guardrail status
📁 5 Document Formats	PDF, DOCX, CSV, JSON, TXT
⚡ Real-time WebSocket	Streaming chat via WebSocket with progress tracking
🔑 JWT Auth	Secure user accounts with bcrypt-hashed passwords and JWT bearer tokens

---

🏗️ System Architecture

MEXAR is composed of four layers: Frontend, API, Intelligence, and Storage.

┌─────────────────────────────────────────────────────────────────────────────┐
│                         USER INTERACTION LAYER                              │
│                                                                             │
│   ┌──────────────────────────────────────────────────────────────────────┐  │
│   │            React 18 Frontend  ─  Vercel Edge Network                 │  │
│   │   Landing · Login · Dashboard · AgentCreation · Chat · Explainability │  │
│   └────────────────────────────┬─────────────────────────────────────────┘  │
│                                │ HTTPS / WebSocket                          │
└────────────────────────────────┼────────────────────────────────────────────┘
                                 │
┌────────────────────────────────▼────────────────────────────────────────────┐
│                      FASTAPI BACKEND  (HF Spaces / Docker)                  │
│                                                                             │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│   │  /auth   │  │ /agents  │  │  /chat   │  │ /compile │  │ /websocket │  │
│   └──────────┘  └──────────┘  └──────────┘  └──────────┘  └────────────┘  │
│                                                                             │
└────────────────────────────────┬────────────────────────────────────────────┘
                                 │
┌────────────────────────────────▼────────────────────────────────────────────┐
│                        CORE INTELLIGENCE LAYER                              │
│                                                                             │
│  ┌──────────────────┐    ┌──────────────────┐    ┌─────────────────────┐   │
│  │ DataValidator    │    │ KnowledgeCompiler│    │ MultimodalProcessor │   │
│  │ PDF/DOCX/CSV/TXT │───▶│ Chunking + Embed │    │ Whisper · Vision    │   │
│  │ /JSON parsing    │    │ FastEmbed bge-384│    │ OpenCV frames       │   │
│  └──────────────────┘    └────────┬─────────┘    └──────────┬──────────┘   │
│                                   │ Store chunks             │ Text         │
│  ┌──────────────────┐             ▼                          ▼              │
│  │ PromptAnalyzer   │    ┌───────────────────────────────────────────────┐  │
│  │ Intent · Domain  │───▶│           ReasoningEngine  (RAG Core)         │  │
│  │ Query Rewrite    │    │                                               │  │
│  └──────────────────┘    │  1. Domain Guardrail (TF-IDF + NER Jaccard)  │  │
│                          │  2. HybridSearcher (pgvector + BM25 RRF)     │  │
│  ┌──────────────────┐    │  3. CrossEncoder Reranker                    │  │
│  │ ExplainabilityGen│◀───│  4. SourceAttributor (citation tracking)     │  │
│  │ Reasoning trace  │    │  5. Groq LLM Answer Generation               │  │
│  │ Confidence score │    │  6. DeBERTa-v3 Faithfulness Scoring          │  │
│  └──────────────────┘    └───────────────────────────────────────────────┘  │
│                                                                             │
└────────────────────────────────┬────────────────────────────────────────────┘
                                 │
┌────────────────────────────────▼────────────────────────────────────────────┐
│                         EXTERNAL SERVICES LAYER                             │
│                                                                             │
│  ┌──────────────────────┐  ┌──────────────────┐  ┌───────────────────────┐ │
│  │  Supabase / PostgreSQL│  │    Groq Cloud    │  │      ElevenLabs       │ │
│  │  pgvector extension  │  │ Llama 3.3 · 3.1  │  │  Text-to-Speech API   │ │
│  │  BM25 tsvector FTS   │  │ Whisper v3 Large │  │                       │ │
│  │  JWT sessions        │  │ Vision (preview)  │  └───────────────────────┘ │
│  └──────────────────────┘  └──────────────────┘                            │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

🔄 Request Lifecycle — Step by Step

User Query
    │
    ▼
┌──────────────────────────────────────────────────────┐
│  1. MULTIMODAL INPUT (optional)                       │
│     Audio → Groq Whisper STT → text                  │
│     Image → Groq Vision → described text             │
│     Video → OpenCV frame extract → Vision            │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  2. PROMPT ANALYSIS                                   │
│     • Parse intent (factual / analytical / compare)  │
│     • Detect domain topic                            │
│     • Optionally rewrite query for clarity           │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  3. DOMAIN GUARDRAIL CHECK                           │
│     • TF-IDF cosine similarity vs agent signature    │
│     • spaCy NER entity Jaccard overlap               │
│     • Threshold = 0.25  (F1 = 0.9072)               │
│     • If below threshold → reject with explanation   │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  4. HYBRID RETRIEVAL                                 │
│     • Dense: FastEmbed bge-small-en (384-dim)        │
│       → pgvector cosine similarity search            │
│     • Sparse: PostgreSQL tsvector BM25 FTS           │
│     • Fuse both via Reciprocal Rank Fusion (RRF)     │
│       score = Σ 1/(rank + 60)                        │
│     • Return top-K=20 candidate chunks               │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  5. CROSS-ENCODER RERANKING                          │
│     • sentence-transformers cross-encoder            │
│     • Re-scores top candidates for relevance         │
│     • Selects top-5 chunks as final context          │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  6. LLM ANSWER GENERATION                            │
│     • Build system prompt with retrieved context     │
│     • Multi-model Groq inference with auto-fallback: │
│       llama-3.3-70b → llama-3.1-8b → mixtral-8x7b  │
│     • Answer generated with citations embedded       │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  7. SOURCE ATTRIBUTION                               │
│     • Match answer sentences → source chunks         │
│     • Assign [1], [2], [3] reference markers         │
│     • Track provenance per claim                     │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  8. FAITHFULNESS SCORING (DeBERTa-v3 NLI)            │
│     • Extract claims from answer                     │
│     • For each claim-chunk pair, NLI inference:      │
│       entailment → faithful                          │
│       contradiction → hallucinated                   │
│     • Batched with torch.inference_mode() (~1.2s)    │
│     • Output: faithfulness score 0.0–1.0             │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  9. EXPLAINABILITY PACKAGING                         │
│     • Reasoning trace (step-by-step)                 │
│     • Confidence breakdown (domain + faithfulness)   │
│     • Sources cited (with file name + chunk text)    │
│     • Guardrail decision log                         │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
                   Response to User
                 (Answer + Citations
                  + Faithfulness Score
                  + Explainability Panel)

---

🗂️ Project Structure

Mexar-main/
│
├── backend/                    # FastAPI Python backend
│   ├── api/                    # Route handlers
│   │   ├── auth.py             # JWT login / register
│   │   ├── agents.py           # Agent CRUD operations
│   │   ├── chat.py             # Chat endpoint (REST)
│   │   ├── compile.py          # Knowledge compilation jobs
│   │   ├── websocket.py        # Streaming WebSocket chat
│   │   ├── admin.py            # Admin panel routes
│   │   └── diagnostics.py      # System health checks
│   │
│   ├── modules/                # Core AI intelligence
│   │   ├── reasoning_engine.py # Main RAG pipeline (634 lines)
│   │   ├── knowledge_compiler.py # Doc ingestion + embedding
│   │   ├── data_validator.py   # File parsing (PDF/DOCX/CSV/TXT/JSON)
│   │   ├── prompt_analyzer.py  # Intent + domain classification
│   │   ├── multimodal_processor.py # Audio/Image/Video → text
│   │   └── explainability.py   # Reasoning trace packaging
│   │
│   ├── utils/                  # Utility modules
│   │   ├── hybrid_search.py    # pgvector + BM25 + RRF fusion
│   │   ├── faithfulness.py     # DeBERTa-v3 NLI scorer
│   │   ├── groq_client.py      # Multi-model Groq client + fallback
│   │   ├── reranker.py         # Cross-encoder reranking
│   │   ├── source_attribution.py # Citation tracking
│   │   ├── semantic_chunker.py # Adaptive text chunking
│   │   └── domain_signature.py # TF-IDF + NER signature builder
│   │
│   ├── models/                 # SQLAlchemy ORM models
│   │   ├── user.py             # User model
│   │   ├── agent.py            # Agent + CompilationJob
│   │   ├── chunk.py            # DocumentChunk (with vector)
│   │   └── conversation.py     # Conversation + Message
│   │
│   ├── migrations/
│   │   └── hybrid_search_function.sql  # PostgreSQL RRF function
│   │
│   ├── evaluation/             # Phase 3 benchmark suite
│   │   ├── run_all.py          # Master evaluation runner
│   │   └── guardrail_threshold_sweep.py
│   │
│   ├── scripts/                # Data collection scripts
│   │   ├── fetch_pubmed.py     # NCBI PubMed Open Access
│   │   ├── fetch_courtlistener.py  # CourtListener v4 API
│   │   └── fetch_secedgar.py   # SEC EDGAR 10-K filings
│   │
│   ├── static/index.html       # HF Spaces landing page
│   ├── main.py                 # FastAPI application entry
│   └── requirements.txt        # Python dependencies
│
├── frontend/                   # React 18 frontend
│   └── src/
│       ├── pages/
│       │   ├── Landing.jsx     # Marketing home page
│       │   ├── Login.jsx       # Authentication
│       │   ├── Dashboard.jsx   # Agent management hub
│       │   ├── AgentCreation.jsx # Upload + configure agent
│       │   ├── AgentList.jsx   # Browse your agents
│       │   ├── Chat.jsx        # Full chat interface (39KB)
│       │   └── CompilationProgress.jsx # Live compilation view
│       │
│       └── components/
│           ├── ExplainabilityModal.jsx # Reasoning trace viewer
│           ├── KnowledgeGraph.jsx      # Visual knowledge graph
│           ├── AudioRecorder.jsx       # Browser microphone input
│           ├── TTSPlayer.jsx           # TTS playback
│           ├── InlineTTS.jsx           # Per-sentence TTS
│           └── AgentSwitcher.jsx       # Switch between agents
│
├── test_data/                  # Real evaluation datasets
│   ├── medical_real/           # 31 PubMed PMC open-access papers
│   ├── legal_real/             # 148 CourtListener judicial opinions
│   ├── financial_real/         # 4 SEC EDGAR 10-K filings
│   └── query_sets/             # Evaluation query sets per domain
│
├── Dockerfile                  # Container definition (HF Spaces)
└── README.md

---

📊 Empirical Evaluation Results & Benchmarks

MEXAR has been evaluated against established baselines on real datasets sourced via public APIs.

Knowledge Base — Real Multi-Domain Corpus

Domain	Data Source	Files	Vector Chunks	Domain Signature Terms
🏥 Medical	NCBI PubMed Central Open Access	31 papers	556 chunks	127 terms
⚖️ Legal	CourtListener REST API v4	148 opinions	157 chunks	152 terms
📈 Financial	SEC EDGAR 10-K Filings	4 filings	68 chunks	119 terms

Table I — Multi-System Faithfulness Comparison

System	Medical ↑	Legal ↑	Financial ↑
Naive RAG	0.0222	0.0333	0.0000
BM25-only Retrieval	0.0000	0.0000	0.0000
LangChain RAG	0.5000	0.5000	0.5000
Self-RAG	0.2380	0.0833	N/A
🧠 MEXAR (Ours)	0.1000	0.1000	N/A

Faithfulness scored via DeBERTa-v3-base NLI. Higher = better grounding.

Table II — Domain Guardrail Performance

Metric	Value
Optimal Threshold	0.25
F1 Score	0.9072
Method	TF-IDF cosine + spaCy NER Jaccard
Mean Latency	113.49 ms

Table III — System Latency Profile

Component	Latency
DeBERTa NLI Faithfulness (vectorized batch)	~1.2s / query
Domain Guardrail check	113.49 ms
Hybrid RRF Search (pgvector + BM25)	< 100 ms
Groq LLM inference (llama-3.1-8b)	~800 ms

50x speedup on faithfulness scoring achieved via torch.inference_mode() vectorized batching over the naive sequential baseline (~70s → ~1.2s).

Expected Calibration Error (ECE)

ECE = 0.1000 — confidence scores are well-calibrated against empirical answer accuracy.

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• Node.js 18+
• PostgreSQL with pgvector extension (or Supabase free tier)
• Groq API Key — free tier available

---

1. Clone & Configure

git clone https://github.com/devrajsinh2012/Mexar.git
cd Mexar-main

# Copy backend environment file
cp backend/.env.example backend/.env
# Fill in your credentials (see Environment Variables below)

---

2. Backend Setup

cd backend
pip install -r requirements.txt

# Install spaCy model required for domain guardrail
python -m spacy download en_core_web_sm

# Apply database migration (PostgreSQL RRF hybrid search function)
psql $DATABASE_URL -f migrations/hybrid_search_function.sql

# Start backend server
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Backend available at: http://localhost:8000
Interactive API docs: http://localhost:8000/docs

---

3. Frontend Setup

cd frontend
npm install

# Set API URL
echo "REACT_APP_API_URL=http://localhost:8000" > .env

npm start

Frontend available at: http://localhost:3000

---

🔑 Environment Variables

# backend/.env

# === REQUIRED ===
GROQ_API_KEY=your_groq_api_key_here           # https://console.groq.com
DATABASE_URL=postgresql://user:pass@host:5432/db
SECRET_KEY=your_secure_jwt_secret_key
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_supabase_service_role_key

# === OPTIONAL ===
ELEVENLABS_API_KEY=your_elevenlabs_api_key    # Text-to-speech
FRONTEND_URL=https://mexar.vercel.app         # CORS origin

# === DATASET COLLECTION (scripts/) ===
COURTLISTENER_TOKEN=your_cl_token             # courtlistener.com
NCBI_EMAIL=your@email.com                     # NCBI policy requirement
NCBI_API_KEY=your_ncbi_api_key                # Raises rate limit 3→10 req/s
SEC_USER_AGENT=Firstname Lastname your@email.com  # SEC EDGAR fair access

---

🐳 Docker / Hugging Face Spaces Deployment

The project ships with a ready-to-use Dockerfile and is live on HF Spaces.

# Build locally
docker build -t mexar-backend ./backend
docker run -p 8000:8000 --env-file backend/.env mexar-backend

For Hugging Face Spaces, push to the hf remote:

git remote add hf https://huggingface.co/spaces/devrajsinh2012/mexar.git
git push hf main

---

📡 API Reference

Method	Endpoint	Description
POST	/api/auth/register	Register a new user account
POST	/api/auth/login	Login and receive JWT token
GET	/api/agents/	List all compiled agents
POST	/api/agents/	Create a new agent
POST	/api/compile/	Start knowledge compilation from uploaded files
GET	/api/compile/{job_id}	Poll compilation job status
POST	/api/chat/	Send a query to an agent (REST)
WS	/ws/chat/{agent_id}	Real-time streaming chat (WebSocket)
GET	/api/health	Health check
GET	/docs	Interactive Swagger UI

Full interactive documentation: devrajsinh2012-mexar.hf.space/docs

---

🧠 Groq Model Fallback Chain

MEXAR implements a resilient multi-model fallback for Groq API rate limits:

openai/gpt-oss-120b
       │ (429 TPD quota)
       ▼
llama-3.3-70b-versatile
       │ (429 TPD quota)
       ▼
llama-3.1-8b-instant
       │ (429 TPD quota)
       ▼
mixtral-8x7b-32768
       │ (429 TPD quota)
       ▼
gemma2-9b-it

This ensures zero-downtime inference even under heavy usage within free-tier quotas.

---

🧪 Running Evaluations

# Fetch real datasets (requires API keys in .env)
python backend/scripts/fetch_pubmed.py      # NCBI PubMed
python backend/scripts/fetch_courtlistener.py  # CourtListener
python backend/scripts/fetch_secedgar.py    # SEC EDGAR

# Recompile domain agents from real data
python backend/scripts/recompile_agents_from_real_data.py

# Run full Phase 3 evaluation pipeline
python backend/evaluation/run_all.py

# Results saved to:
# backend/evaluation_outputs/full_evaluation_<timestamp>.json

---

🛠️ Tech Stack

Layer	Technology
Frontend	React 18, React Router, Vercel
Backend	FastAPI 0.109, Uvicorn, Python 3.9+
Database	PostgreSQL + pgvector, Supabase
Vector Search	FastEmbed BAAI/bge-small-en-v1.5 (384-dim)
Keyword Search	PostgreSQL tsvector BM25 FTS
RRF Fusion	Custom SQL stored procedure
LLM Inference	Groq API (Llama 3.3, Llama 3.1, Mixtral, Gemma 2)
Faithfulness	microsoft/deberta-v3-base NLI via HuggingFace
Reranking	sentence-transformers cross-encoder
Multimodal	Groq Whisper v3 (audio), Groq Vision (images), OpenCV (video)
TTS	ElevenLabs API + Web Speech API
Auth	JWT (python-jose) + bcrypt (passlib)
Deployment	Hugging Face Spaces (Docker), Vercel (frontend)
NLP	spaCy en_core_web_sm, scikit-learn TF-IDF

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'feat: add my feature'
4. Push to the branch: git push origin feature/my-feature
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see LICENSE for details.

---

👨‍💻 Project Team

This Major Project is presented by:

Devrajsinh Gohil & Jay Nasit

Under the expert guidance of:

Prof. Om Prakash Suthar

---

GitHub · HF Spaces · Live App