Spaces:

devrajsinh2012
/

Mexar

Sleeping

App Files Files Community

devrajsinh2012 commited on 22 days ago

Commit

b576b71

verified ·

1 Parent(s): 39d6f5a

Upload folder using huggingface_hub

Browse files

Files changed (5) hide show

README.md +575 -564
backend/api/chat.py +509 -511
backend/modules/reasoning_engine.py +6 -6
backend/requirements.txt +68 -67
backend/workers/compilation_worker.py +213 -210

README.md CHANGED Viewed

@@ -1,564 +1,575 @@
----
-title: Mexar
-emoji: 🧠
-colorFrom: blue
-colorTo: indigo
-sdk: docker
-pinned: false
-license: mit
----
-<div align="center">
-# 🧠 MEXAR
-### **M**ultimodal **E**xplainable **A**I **R**easoning Assistant
-*Build domain-specific AI agents from your documents — with transparent, grounded, and faithful answers.*
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg?style=for-the-badge&logo=python)](https://www.python.org/)
-[![FastAPI](https://img.shields.io/badge/FastAPI-0.109-009688.svg?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com/)
-[![React 18](https://img.shields.io/badge/React-18-61dafb.svg?style=for-the-badge&logo=react)](https://reactjs.org/)
-[![Groq](https://img.shields.io/badge/Groq-LLM-f54e42.svg?style=for-the-badge)](https://groq.com/)
-[![Supabase](https://img.shields.io/badge/Supabase-pgvector-3ECF8E?style=for-the-badge&logo=supabase)](https://supabase.com/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
-<br/>
-**🚀 Live App** → [mexar.vercel.app](https://mexar.vercel.app) &nbsp;&nbsp;|&nbsp;&nbsp; **📡 Backend API** → [devrajsinh2012-mexar.hf.space](https://devrajsinh2012-mexar.hf.space) &nbsp;&nbsp;|&nbsp;&nbsp; **📖 API Docs** → [/docs](https://devrajsinh2012-mexar.hf.space/docs)
-</div>
----
-## 📖 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](https://supabase.com) free tier)
-- [Groq API Key](https://console.groq.com) — free tier available
----
-### 1. Clone & Configure
-```bash
-git clone https://github.com/devrajsinh2012/Mexar.git
-cd Mexar-main
-```
-```bash
-# Copy backend environment file
-cp backend/.env.example backend/.env
-# Fill in your credentials (see Environment Variables below)
-```
----
-### 2. Backend Setup
-```bash
-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
-```bash
-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
-```bash
-# 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.
-```bash
-# 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:
-```bash
-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](https://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
-```bash
-# 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](LICENSE) for details.
----
-<div align="center">
-Built with ❤️ by **Devrajsinh Gohil**
-[GitHub](https://github.com/devrajsinh2012/Mexar) · [HF Spaces](https://huggingface.co/spaces/devrajsinh2012/mexar) · [Live App](https://mexar.vercel.app)
-</div>

+---
+title: Mexar
+emoji: 🧠
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+license: mit
+---
+<div align="center">
+# 🧠 MEXAR
+### **M**ultimodal **E**xplainable **A**I **R**easoning Assistant
+*Build domain-specific AI agents from your documents — with transparent, grounded, and faithful answers.*
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg?style=for-the-badge&logo=python)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.109-009688.svg?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com/)
+[![React 18](https://img.shields.io/badge/React-18-61dafb.svg?style=for-the-badge&logo=react)](https://reactjs.org/)
+[![Groq](https://img.shields.io/badge/Groq-LLM-f54e42.svg?style=for-the-badge)](https://groq.com/)
+[![Supabase](https://img.shields.io/badge/Supabase-pgvector-3ECF8E?style=for-the-badge&logo=supabase)](https://supabase.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
+<br/>
+**🚀 Live App** → [mexar.vercel.app](https://mexar.vercel.app) &nbsp;&nbsp;|&nbsp;&nbsp; **📡 Backend API** → [devrajsinh2012-mexar.hf.space](https://devrajsinh2012-mexar.hf.space) &nbsp;&nbsp;|&nbsp;&nbsp; **📖 API Docs** → [/docs](https://devrajsinh2012-mexar.hf.space/docs)
+</div>
+---
+## 📖 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](https://supabase.com) free tier)
+- [Groq API Key](https://console.groq.com) — free tier available
+---
+### 1. Clone & Configure
+```bash
+git clone https://github.com/devrajsinh2012/Mexar.git
+cd Mexar-main
+```
+```bash
+# Copy backend environment file
+cp backend/.env.example backend/.env
+# Fill in your credentials (see Environment Variables below)
+```
+---
+### 2. Backend Setup
+```bash
+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
+```bash
+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
+```bash
+# 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.
+```bash
+# 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:
+```bash
+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](https://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
+```bash
+# 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](LICENSE) for details.
+---
+<div align="center">
+## 👨‍💻 Project Team
+This Major Project is presented by:
+**Devrajsinh Gohil** & **Jay Nasit**
+Under the expert guidance of:
+**Prof. Om Prakash Suthar**
+---
+[GitHub](https://github.com/devrajsinh2012/Mexar) · [HF Spaces](https://huggingface.co/spaces/devrajsinh2012/mexar) · [Live App](https://mexar.vercel.app)
+</div>

backend/api/chat.py CHANGED Viewed

@@ -1,511 +1,509 @@
-"""
-MEXAR Chat API - Phase 2
-Handles all chat interactions with agents.
-"""
-from typing import Optional
-from pathlib import Path
-import shutil
-import uuid
-import logging
-from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Form
-from fastapi.responses import FileResponse
-from sqlalchemy.orm import Session
-from pydantic import BaseModel
-from core.database import get_db
-from services.agent_service import agent_service
-from services.tts_service import get_tts_service
-from services.storage_service import storage_service
-from services.conversation_service import conversation_service
-from api.deps import get_current_user
-from models.user import User
-from modules.reasoning_engine import create_reasoning_engine
-from modules.explainability import create_explainability_generator
-logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api/chat", tags=["chat"])
-# Pydantic models for JSON requests
-class ChatRequest(BaseModel):
-    agent_name: str
-    message: str
-    include_explainability: bool = True
-    include_tts: bool = False
-    tts_provider: str = "elevenlabs"  # "elevenlabs" or "web_speech"
-class MultimodalChatRequest(BaseModel):
-    agent_name: str
-    message: str = ""
-class TTSRequest(BaseModel):
-    text: str
-    provider: str = "elevenlabs"  # "elevenlabs" or "web_speech"
-    voice_id: Optional[str] = None
-# ===== MAIN CHAT ENDPOINT (JSON) =====
-@router.post("")
-@router.post("/")
-async def chat_json(
-    request: ChatRequest,
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
-):
-    """
-    Chat with an agent using JSON body.
-    This is the primary endpoint used by the frontend.
-    """
-    # Get agent with ownership check
-    agent = agent_service.get_agent(db, current_user, request.agent_name)
-    if not agent:
-        raise HTTPException(status_code=404, detail=f"Agent '{request.agent_name}' not found")
-    if agent.status != "ready":
-        raise HTTPException(
-            status_code=400,
-            detail=f"Agent is not ready. Current status: {agent.status}"
-        )
-    # Get/Create conversation
-    conversation = conversation_service.get_or_create_conversation(
-        db, agent.id, current_user.id
-    )
-    # Log USER message
-    conversation_service.add_message(
-        db, conversation.id, "user", request.message
-    )
-    try:
-        # Use agent's storage path for reasoning engine
-        storage_path = Path(agent.storage_path).parent
-        engine = create_reasoning_engine(str(storage_path))
-        result = engine.reason(
-            agent_name=agent.name,
-            query=request.message
-        )
-        response = {
-            "success": True,
-            "answer": result["answer"],
-            "confidence": result["confidence"],
-            "in_domain": result["in_domain"]
-        }
-        if request.include_explainability:
-            try:
-                explainer = create_explainability_generator()
-                response["explainability"] = explainer.generate(result)
-            except Exception as e:
-                logger.warning(f"Explainability generation failed: {e}")
-                response["explainability"] = result.get("explainability")
-        # Log ASSISTANT message
-        conversation_service.add_message(
-            db,
-            conversation.id,
-            "assistant",
-            result["answer"],
-            explainability_data=response.get("explainability"),
-            confidence=result["confidence"]
-        )
-        # Generate TTS if requested
-        if request.include_tts:
-            try:
-                tts_service = get_tts_service()
-                tts_result = tts_service.generate_speech(
-                    text=result["answer"],
-                    provider=request.tts_provider
-                )
-                response["tts"] = tts_result
-            except Exception as e:
-                logger.warning(f"TTS generation failed: {e}")
-                response["tts"] = {"success": False, "error": str(e)}
-        return response
-    except Exception as e:
-        logger.error(f"Chat error: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-# ===== MULTIMODAL CHAT ENDPOINT =====
-@router.post("/multimodal")
-async def chat_multimodal(
-    agent_name: str = Form(...),
-    message: str = Form(""),
-    audio: UploadFile = File(None),
-    image: UploadFile = File(None),
-    include_explainability: bool = Form(True),
-    include_tts: bool = Form(False),
-    tts_provider: str = Form("elevenlabs"),
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
-):
-    """
-    Chat with an agent using multimodal inputs (audio/image).
-    Uses multipart form data.
-    """
-    from modules.multimodal_processor import create_multimodal_processor
-    # Get agent with ownership check
-    agent = agent_service.get_agent(db, current_user, agent_name)
-    if not agent:
-        raise HTTPException(status_code=404, detail=f"Agent '{agent_name}' not found")
-    if agent.status != "ready":
-        raise HTTPException(
-            status_code=400,
-            detail=f"Agent is not ready. Current status: {agent.status}"
-        )
-    # Get/Create conversation
-    conversation = conversation_service.get_or_create_conversation(
-        db, agent.id, current_user.id
-    )
-    try:
-        multimodal_context = ""
-        audio_url = None
-        image_url = None
-        # Process audio if provided
-        if audio and audio.filename:
-            # Upload to Supabase Storage
-            upload_result = await storage_service.upload_file(
-                file=audio,
-                bucket="chat-media",
-                folder=f"audio/{agent.id}"
-            )
-            audio_url = upload_result["url"]
-            # Save temporarily for processing
-            temp_dir = Path("data/temp")
-            temp_dir.mkdir(parents=True, exist_ok=True)
-            temp_path = temp_dir / f"{uuid.uuid4()}{Path(audio.filename).suffix}"
-            with open(temp_path, "wb") as buffer:
-                await audio.seek(0)  # Reset file pointer
-                shutil.copyfileobj(audio.file, buffer)
-            processor = create_multimodal_processor()
-            audio_text = processor.process_audio(str(temp_path))
-            if audio_text:
-                multimodal_context += f"\n[AUDIO TRANSCRIPTION]: {audio_text}"
-            # Clean up temp file
-            try:
-                temp_path.unlink()
-            except:
-                pass
-        # Process image if provided
-        if image and image.filename:
-            # Upload to Supabase Storage
-            upload_result = await storage_service.upload_file(
-                file=image,
-                bucket="chat-media",
-                folder=f"images/{agent.id}"
-            )
-            image_url = upload_result["url"]
-            logger.info(f"[MULTIMODAL] Image uploaded to Supabase: {image_url}")
-            # Save temporarily for processing
-            temp_dir = Path("data/temp")
-            temp_dir.mkdir(parents=True, exist_ok=True)
-            temp_path = temp_dir / f"{uuid.uuid4()}{Path(image.filename).suffix}"
-            logger.info(f"[MULTIMODAL] Saving temp file: {temp_path}")
-            with open(temp_path, "wb") as buffer:
-                await image.seek(0)  # Reset file pointer
-                shutil.copyfileobj(image.file, buffer)
-            file_size = temp_path.stat().st_size
-            logger.info(f"[MULTIMODAL] Temp file saved, size: {file_size} bytes")
-            try:
-                logger.info(f"[MULTIMODAL] Starting image analysis with Groq Vision...")
-                processor = create_multimodal_processor()
-                image_result = processor.process_image(str(temp_path))
-                logger.info(f"[MULTIMODAL] Image processing result: {image_result.get('success')}")
-                if image_result.get("success"):
-                    image_desc = image_result.get("description", "")
-                    if image_desc:
-                        logger.info(f"[MULTIMODAL] ✓ Image analyzed successfully, description length: {len(image_desc)} chars")
-                        logger.info(f"[MULTIMODAL] Description preview: {image_desc[:150]}...")
-                        multimodal_context += f"\n[IMAGE DESCRIPTION]: {image_desc}"
-                    else:
-                        logger.warning(f"[MULTIMODAL] Image analysis returned success but empty description")
-                        multimodal_context += f"\n[IMAGE]: User uploaded an image named {image.filename}"
-                else:
-                    # Log error but don't fail - provide basic context
-                    error_msg = image_result.get('error', 'Unknown error')
-                    error_type = image_result.get('error_type', 'Unknown')
-                    logger.warning(f"[MULTIMODAL] Image analysis failed - {error_type}: {error_msg}")
-                    multimodal_context += f"\n[IMAGE]: User uploaded an image named {image.filename}"
-            except Exception as e:
-                logger.error(f"[MULTIMODAL] Image processing exception: {type(e).__name__}: {str(e)}")
-                import traceback
-                logger.error(f"[MULTIMODAL] Traceback: {traceback.format_exc()}")
-                multimodal_context += f"\n[IMAGE]: User uploaded an image named {image.filename}"
-            # Clean up temp file
-            try:
-                temp_path.unlink()
-                logger.info(f"[MULTIMODAL] Temp file cleaned up")
-            except:
-                pass
-        # Run reasoning
-        storage_path = Path(agent.storage_path).parent
-        engine = create_reasoning_engine(str(storage_path))
-        result = engine.reason(
-            agent_name=agent.name,
-            query=message,
-            multimodal_context=multimodal_context
-        )
-        # Log USER message with attachments
-        conversation_service.add_message(
-            db,
-            conversation.id,
-            "user",
-            message,
-            multimodal_data={
-                "audio_url": audio_url,
-                "image_url": image_url
-            }
-        )
-        response = {
-            "success": True,
-            "answer": result["answer"],
-            "confidence": result["confidence"],
-            "in_domain": result["in_domain"],
-            "audio_url": audio_url,
-            "image_url": image_url
-        }
-        if include_explainability:
-            try:
-                explainer = create_explainability_generator()
-                response["explainability"] = explainer.generate(result)
-            except Exception:
-                response["explainability"] = result.get("explainability")
-        # Log ASSISTANT message
-        conversation_service.add_message(
-            db,
-            conversation.id,
-            "assistant",
-            result["answer"],
-            explainability_data=response.get("explainability"),
-            confidence=result["confidence"]
-        )
-        # Generate TTS if requested
-        if include_tts:
-            try:
-                tts_service = get_tts_service()
-                tts_result = tts_service.generate_speech(
-                    text=result["answer"],
-                    provider=tts_provider
-                )
-                response["tts"] = tts_result
-            except Exception as e:
-                logger.warning(f"TTS generation failed: {e}")
-                response["tts"] = {"success": False, "error": str(e)}
-        return response
-    except Exception as e:
-        logger.error(f"Multimodal chat error: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-# ===== HISTORY ENDPOINTS =====
-@router.get("/{agent_name}/history")
-def get_chat_history(
-    agent_name: str,
-    limit: int = 50,
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
-):
-    """Get conversation history with an agent."""
-    from services.conversation_service import conversation_service
-    agent = agent_service.get_agent(db, current_user, agent_name)
-    if not agent:
-        raise HTTPException(status_code=404, detail="Agent not found")
-    history = conversation_service.get_conversation_history(
-        db, agent.id, current_user.id, limit
-    )
-    return {"messages": history}
-@router.delete("/{agent_name}/history")
-def clear_chat_history(
-    agent_name: str,
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
-):
-    """Clear conversation history with an agent."""
-    from models.conversation import Conversation
-    agent = agent_service.get_agent(db, current_user, agent_name)
-    if not agent:
-        raise HTTPException(status_code=404, detail="Agent not found")
-    conversation = db.query(Conversation).filter(
-        Conversation.agent_id == agent.id,
-        Conversation.user_id == current_user.id
-    ).first()
-    if conversation:
-        db.delete(conversation)
-        db.commit()
-    return {"message": "Chat history cleared"}
-# ===== TEXT-TO-SPEECH ENDPOINTS =====
-@router.post("/tts/generate")
-async def generate_tts(
-    request: TTSRequest,
-    current_user: User = Depends(get_current_user)
-):
-    """Generate text-to-speech audio."""
-    try:
-        tts_service = get_tts_service()
-        result = tts_service.generate_speech(
-            text=request.text,
-            provider=request.provider,
-            voice_id=request.voice_id
-        )
-        return result
-    except Exception as e:
-        logger.error(f"TTS generation error: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-@router.get("/tts/audio/{filename}")
-async def serve_tts_audio(filename: str):
-    """Serve cached TTS audio files."""
-    audio_path = Path("data/tts_cache") / filename
-    if not audio_path.exists():
-        raise HTTPException(status_code=404, detail="Audio file not found")
-    return FileResponse(
-        path=audio_path,
-        media_type="audio/mpeg",
-        filename=filename
-    )
-@router.get("/tts/voices")
-async def get_tts_voices(
-    provider: str = "elevenlabs",
-    current_user: User = Depends(get_current_user)
-):
-    """Get available TTS voices for a provider."""
-    try:
-        tts_service = get_tts_service()
-        voices = tts_service.get_available_voices(provider)
-        return {"provider": provider, "voices": voices}
-    except Exception as e:
-        logger.error(f"Failed to fetch voices: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-@router.get("/tts/quota")
-async def get_tts_quota(current_user: User = Depends(get_current_user)):
-    """Check TTS quota for ElevenLabs."""
-    try:
-        tts_service = get_tts_service()
-        quota = tts_service.check_quota()
-        return quota
-    except Exception as e:
-        logger.error(f"Failed to check quota: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-# ===== LIVE AUDIO TRANSCRIPTION =====
-@router.post("/transcribe")
-async def transcribe_audio(
-    audio: UploadFile = File(...),
-    language: str = Form("en"),
-    current_user: User = Depends(get_current_user)
-):
-    """Transcribe uploaded audio (for live recording)."""
-    from modules.multimodal_processor import create_multimodal_processor
-    try:
-        # Save audio temporarily
-        temp_dir = Path("data/temp")
-        temp_dir.mkdir(parents=True, exist_ok=True)
-        temp_path = temp_dir / f"{uuid.uuid4()}{Path(audio.filename).suffix}"
-        with open(temp_path, "wb") as buffer:
-            shutil.copyfileobj(audio.file, buffer)
-        # Transcribe
-        processor = create_multimodal_processor()
-        result = processor.process_audio(str(temp_path), language)
-        # Clean up
-        try:
-            temp_path.unlink()
-        except:
-            pass
-        if result.get("success"):
-            return {
-                "success": True,
-                "transcript": result.get("transcript", ""),
-                "language": language,
-                "word_count": result.get("word_count", 0)
-            }
-        else:
-            raise HTTPException(status_code=500, detail=result.get("error", "Transcription failed"))
-    except Exception as e:
-        logger.error(f"Audio transcription error: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
-# ===== UTILITY FUNCTIONS =====
-async def save_upload(file: UploadFile, base_path: str, subfolder: str) -> str:
-    """Save an uploaded file and return its path."""
-    upload_dir = Path(base_path) / subfolder
-    upload_dir.mkdir(parents=True, exist_ok=True)
-    ext = Path(file.filename).suffix
-    filename = f"{uuid.uuid4()}{ext}"
-    file_path = upload_dir / filename
-    with open(file_path, "wb") as buffer:
-        shutil.copyfileobj(file.file, buffer)
-    return str(file_path)

+"""
+MEXAR Chat API - Phase 2
+Handles all chat interactions with agents.
+"""
+from typing import Optional
+from pathlib import Path
+import shutil
+import uuid
+import logging
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Form
+from fastapi.responses import FileResponse
+from sqlalchemy.orm import Session
+from pydantic import BaseModel
+from core.database import get_db
+from services.agent_service import agent_service
+from services.tts_service import get_tts_service
+from services.storage_service import storage_service
+from services.conversation_service import conversation_service
+from api.deps import get_current_user
+from models.user import User
+from modules.reasoning_engine import create_reasoning_engine
+from modules.explainability import create_explainability_generator
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/chat", tags=["chat"])
+# Pydantic models for JSON requests
+class ChatRequest(BaseModel):
+    agent_name: str
+    message: str
+    include_explainability: bool = True
+    include_tts: bool = False
+    tts_provider: str = "elevenlabs"  # "elevenlabs" or "web_speech"
+class MultimodalChatRequest(BaseModel):
+    agent_name: str
+    message: str = ""
+class TTSRequest(BaseModel):
+    text: str
+    provider: str = "elevenlabs"  # "elevenlabs" or "web_speech"
+    voice_id: Optional[str] = None
+# ===== MAIN CHAT ENDPOINT (JSON) =====
+@router.post("")
+@router.post("/")
+async def chat_json(
+    request: ChatRequest,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Chat with an agent using JSON body.
+    This is the primary endpoint used by the frontend.
+    """
+    # Get agent with ownership check
+    agent = agent_service.get_agent(db, current_user, request.agent_name)
+    if not agent:
+        raise HTTPException(status_code=404, detail=f"Agent '{request.agent_name}' not found")
+    if agent.status != "ready":
+        raise HTTPException(
+            status_code=400,
+            detail=f"Agent is not ready. Current status: {agent.status}"
+        )
+    # Get/Create conversation
+    conversation = conversation_service.get_or_create_conversation(
+        db, agent.id, current_user.id
+    )
+    # Log USER message
+    conversation_service.add_message(
+        db, conversation.id, "user", request.message
+    )
+    try:
+        # Use agent's storage path for reasoning engine
+        engine = create_reasoning_engine(str(agent.storage_path))
+        result = engine.reason(
+            agent_name=agent.name,
+            query=request.message
+        )
+        response = {
+            "success": True,
+            "answer": result["answer"],
+            "confidence": result["confidence"],
+            "in_domain": result["in_domain"]
+        }
+        if request.include_explainability:
+            try:
+                explainer = create_explainability_generator()
+                response["explainability"] = explainer.generate(result)
+            except Exception as e:
+                logger.warning(f"Explainability generation failed: {e}")
+                response["explainability"] = result.get("explainability")
+        # Log ASSISTANT message
+        conversation_service.add_message(
+            db,
+            conversation.id,
+            "assistant",
+            result["answer"],
+            explainability_data=response.get("explainability"),
+            confidence=result["confidence"]
+        )
+        # Generate TTS if requested
+        if request.include_tts:
+            try:
+                tts_service = get_tts_service()
+                tts_result = tts_service.generate_speech(
+                    text=result["answer"],
+                    provider=request.tts_provider
+                )
+                response["tts"] = tts_result
+            except Exception as e:
+                logger.warning(f"TTS generation failed: {e}")
+                response["tts"] = {"success": False, "error": str(e)}
+        return response
+    except Exception as e:
+        logger.error(f"Chat error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+# ===== MULTIMODAL CHAT ENDPOINT =====
+@router.post("/multimodal")
+async def chat_multimodal(
+    agent_name: str = Form(...),
+    message: str = Form(""),
+    audio: UploadFile = File(None),
+    image: UploadFile = File(None),
+    include_explainability: bool = Form(True),
+    include_tts: bool = Form(False),
+    tts_provider: str = Form("elevenlabs"),
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Chat with an agent using multimodal inputs (audio/image).
+    Uses multipart form data.
+    """
+    from modules.multimodal_processor import create_multimodal_processor
+    # Get agent with ownership check
+    agent = agent_service.get_agent(db, current_user, agent_name)
+    if not agent:
+        raise HTTPException(status_code=404, detail=f"Agent '{agent_name}' not found")
+    if agent.status != "ready":
+        raise HTTPException(
+            status_code=400,
+            detail=f"Agent is not ready. Current status: {agent.status}"
+        )
+    # Get/Create conversation
+    conversation = conversation_service.get_or_create_conversation(
+        db, agent.id, current_user.id
+    )
+    try:
+        multimodal_context = ""
+        audio_url = None
+        image_url = None
+        # Process audio if provided
+        if audio and audio.filename:
+            # Upload to Supabase Storage
+            upload_result = await storage_service.upload_file(
+                file=audio,
+                bucket="chat-media",
+                folder=f"audio/{agent.id}"
+            )
+            audio_url = upload_result["url"]
+            # Save temporarily for processing
+            temp_dir = Path("data/temp")
+            temp_dir.mkdir(parents=True, exist_ok=True)
+            temp_path = temp_dir / f"{uuid.uuid4()}{Path(audio.filename).suffix}"
+            with open(temp_path, "wb") as buffer:
+                await audio.seek(0)  # Reset file pointer
+                shutil.copyfileobj(audio.file, buffer)
+            processor = create_multimodal_processor()
+            audio_text = processor.process_audio(str(temp_path))
+            if audio_text:
+                multimodal_context += f"\n[AUDIO TRANSCRIPTION]: {audio_text}"
+            # Clean up temp file
+            try:
+                temp_path.unlink()
+            except:
+                pass
+        # Process image if provided
+        if image and image.filename:
+            # Upload to Supabase Storage
+            upload_result = await storage_service.upload_file(
+                file=image,
+                bucket="chat-media",
+                folder=f"images/{agent.id}"
+            )
+            image_url = upload_result["url"]
+            logger.info(f"[MULTIMODAL] Image uploaded to Supabase: {image_url}")
+            # Save temporarily for processing
+            temp_dir = Path("data/temp")
+            temp_dir.mkdir(parents=True, exist_ok=True)
+            temp_path = temp_dir / f"{uuid.uuid4()}{Path(image.filename).suffix}"
+            logger.info(f"[MULTIMODAL] Saving temp file: {temp_path}")
+            with open(temp_path, "wb") as buffer:
+                await image.seek(0)  # Reset file pointer
+                shutil.copyfileobj(image.file, buffer)
+            file_size = temp_path.stat().st_size
+            logger.info(f"[MULTIMODAL] Temp file saved, size: {file_size} bytes")
+            try:
+                logger.info(f"[MULTIMODAL] Starting image analysis with Groq Vision...")
+                processor = create_multimodal_processor()
+                image_result = processor.process_image(str(temp_path))
+                logger.info(f"[MULTIMODAL] Image processing result: {image_result.get('success')}")
+                if image_result.get("success"):
+                    image_desc = image_result.get("description", "")
+                    if image_desc:
+                        logger.info(f"[MULTIMODAL] ✓ Image analyzed successfully, description length: {len(image_desc)} chars")
+                        logger.info(f"[MULTIMODAL] Description preview: {image_desc[:150]}...")
+                        multimodal_context += f"\n[IMAGE DESCRIPTION]: {image_desc}"
+                    else:
+                        logger.warning(f"[MULTIMODAL] Image analysis returned success but empty description")
+                        multimodal_context += f"\n[IMAGE]: User uploaded an image named {image.filename}"
+                else:
+                    # Log error but don't fail - provide basic context
+                    error_msg = image_result.get('error', 'Unknown error')
+                    error_type = image_result.get('error_type', 'Unknown')
+                    logger.warning(f"[MULTIMODAL] Image analysis failed - {error_type}: {error_msg}")
+                    multimodal_context += f"\n[IMAGE]: User uploaded an image named {image.filename}"
+            except Exception as e:
+                logger.error(f"[MULTIMODAL] Image processing exception: {type(e).__name__}: {str(e)}")
+                import traceback
+                logger.error(f"[MULTIMODAL] Traceback: {traceback.format_exc()}")
+                multimodal_context += f"\n[IMAGE]: User uploaded an image named {image.filename}"
+            # Clean up temp file
+            try:
+                temp_path.unlink()
+                logger.info(f"[MULTIMODAL] Temp file cleaned up")
+            except:
+                pass
+        # Run reasoning
+        engine = create_reasoning_engine(str(agent.storage_path))
+        result = engine.reason(
+            agent_name=agent.name,
+            query=message,
+            multimodal_context=multimodal_context
+        )
+        # Log USER message with attachments
+        conversation_service.add_message(
+            db,
+            conversation.id,
+            "user",
+            message,
+            multimodal_data={
+                "audio_url": audio_url,
+                "image_url": image_url
+            }
+        )
+        response = {
+            "success": True,
+            "answer": result["answer"],
+            "confidence": result["confidence"],
+            "in_domain": result["in_domain"],
+            "audio_url": audio_url,
+            "image_url": image_url
+        }
+        if include_explainability:
+            try:
+                explainer = create_explainability_generator()
+                response["explainability"] = explainer.generate(result)
+            except Exception:
+                response["explainability"] = result.get("explainability")
+        # Log ASSISTANT message
+        conversation_service.add_message(
+            db,
+            conversation.id,
+            "assistant",
+            result["answer"],
+            explainability_data=response.get("explainability"),
+            confidence=result["confidence"]
+        )
+        # Generate TTS if requested
+        if include_tts:
+            try:
+                tts_service = get_tts_service()
+                tts_result = tts_service.generate_speech(
+                    text=result["answer"],
+                    provider=tts_provider
+                )
+                response["tts"] = tts_result
+            except Exception as e:
+                logger.warning(f"TTS generation failed: {e}")
+                response["tts"] = {"success": False, "error": str(e)}
+        return response
+    except Exception as e:
+        logger.error(f"Multimodal chat error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+# ===== HISTORY ENDPOINTS =====
+@router.get("/{agent_name}/history")
+def get_chat_history(
+    agent_name: str,
+    limit: int = 50,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Get conversation history with an agent."""
+    from services.conversation_service import conversation_service
+    agent = agent_service.get_agent(db, current_user, agent_name)
+    if not agent:
+        raise HTTPException(status_code=404, detail="Agent not found")
+    history = conversation_service.get_conversation_history(
+        db, agent.id, current_user.id, limit
+    )
+    return {"messages": history}
+@router.delete("/{agent_name}/history")
+def clear_chat_history(
+    agent_name: str,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Clear conversation history with an agent."""
+    from models.conversation import Conversation
+    agent = agent_service.get_agent(db, current_user, agent_name)
+    if not agent:
+        raise HTTPException(status_code=404, detail="Agent not found")
+    conversation = db.query(Conversation).filter(
+        Conversation.agent_id == agent.id,
+        Conversation.user_id == current_user.id
+    ).first()
+    if conversation:
+        db.delete(conversation)
+        db.commit()
+    return {"message": "Chat history cleared"}
+# ===== TEXT-TO-SPEECH ENDPOINTS =====
+@router.post("/tts/generate")
+async def generate_tts(
+    request: TTSRequest,
+    current_user: User = Depends(get_current_user)
+):
+    """Generate text-to-speech audio."""
+    try:
+        tts_service = get_tts_service()
+        result = tts_service.generate_speech(
+            text=request.text,
+            provider=request.provider,
+            voice_id=request.voice_id
+        )
+        return result
+    except Exception as e:
+        logger.error(f"TTS generation error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+@router.get("/tts/audio/{filename}")
+async def serve_tts_audio(filename: str):
+    """Serve cached TTS audio files."""
+    audio_path = Path("data/tts_cache") / filename
+    if not audio_path.exists():
+        raise HTTPException(status_code=404, detail="Audio file not found")
+    return FileResponse(
+        path=audio_path,
+        media_type="audio/mpeg",
+        filename=filename
+    )
+@router.get("/tts/voices")
+async def get_tts_voices(
+    provider: str = "elevenlabs",
+    current_user: User = Depends(get_current_user)
+):
+    """Get available TTS voices for a provider."""
+    try:
+        tts_service = get_tts_service()
+        voices = tts_service.get_available_voices(provider)
+        return {"provider": provider, "voices": voices}
+    except Exception as e:
+        logger.error(f"Failed to fetch voices: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+@router.get("/tts/quota")
+async def get_tts_quota(current_user: User = Depends(get_current_user)):
+    """Check TTS quota for ElevenLabs."""
+    try:
+        tts_service = get_tts_service()
+        quota = tts_service.check_quota()
+        return quota
+    except Exception as e:
+        logger.error(f"Failed to check quota: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+# ===== LIVE AUDIO TRANSCRIPTION =====
+@router.post("/transcribe")
+async def transcribe_audio(
+    audio: UploadFile = File(...),
+    language: str = Form("en"),
+    current_user: User = Depends(get_current_user)
+):
+    """Transcribe uploaded audio (for live recording)."""
+    from modules.multimodal_processor import create_multimodal_processor
+    try:
+        # Save audio temporarily
+        temp_dir = Path("data/temp")
+        temp_dir.mkdir(parents=True, exist_ok=True)
+        temp_path = temp_dir / f"{uuid.uuid4()}{Path(audio.filename).suffix}"
+        with open(temp_path, "wb") as buffer:
+            shutil.copyfileobj(audio.file, buffer)
+        # Transcribe
+        processor = create_multimodal_processor()
+        result = processor.process_audio(str(temp_path), language)
+        # Clean up
+        try:
+            temp_path.unlink()
+        except:
+            pass
+        if result.get("success"):
+            return {
+                "success": True,
+                "transcript": result.get("transcript", ""),
+                "language": language,
+                "word_count": result.get("word_count", 0)
+            }
+        else:
+            raise HTTPException(status_code=500, detail=result.get("error", "Transcription failed"))
+    except Exception as e:
+        logger.error(f"Audio transcription error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+# ===== UTILITY FUNCTIONS =====
+async def save_upload(file: UploadFile, base_path: str, subfolder: str) -> str:
+    """Save an uploaded file and return its path."""
+    upload_dir = Path(base_path) / subfolder
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    ext = Path(file.filename).suffix
+    filename = f"{uuid.uuid4()}{ext}"
+    file_path = upload_dir / filename
+    with open(file_path, "wb") as buffer:
+        shutil.copyfileobj(file.file, buffer)
+    return str(file_path)

backend/modules/reasoning_engine.py CHANGED Viewed

@@ -123,7 +123,7 @@ class ReasoningEngine:
             timings["total_ms"] = round((time.perf_counter() - t0) * 1000, 1)
             resp = self._create_out_of_domain_response(
                 query=query,
-                domain=agent["prompt_analysis"].get("domain", "unknown"),
                 domain_score=domain_score
             )
             resp["timings"] = timings
@@ -248,11 +248,11 @@ class ReasoningEngine:
             agent = db.query(Agent).filter(Agent.name == agent_name).first()
             if not agent:
-                clean_name = agent_name.replace("_agent", "").replace("agent", "").strip()
                 agent = db.query(Agent).filter(Agent.domain.ilike(f"%{clean_name}%")).first()
-            if not agent:
-                agent = db.query(Agent).filter(Agent.name.ilike(f"%{clean_name}%")).first()
             if not agent:
                 agent = db.query(Agent).first()
@@ -274,9 +274,9 @@ class ReasoningEngine:
                     "id": agent.id,
                     "name": agent.name,
                     "system_prompt": agent.system_prompt,
-                    "domain": agent.domain,
                     "domain_signature": agent.domain_signature or [],
-                    "prompt_analysis": agent.prompt_analysis or {},
                     "knowledge_graph": agent.knowledge_graph_json or {},
                     "chunk_count": agent.chunk_count or 0
                 }

             timings["total_ms"] = round((time.perf_counter() - t0) * 1000, 1)
             resp = self._create_out_of_domain_response(
                 query=query,
+                domain=agent.get("domain") or agent["prompt_analysis"].get("domain", "general"),
                 domain_score=domain_score
             )
             resp["timings"] = timings
             agent = db.query(Agent).filter(Agent.name == agent_name).first()
             if not agent:
+                clean_name = agent_name.replace("_agent", "").replace("agent", "").strip() or agent_name
                 agent = db.query(Agent).filter(Agent.domain.ilike(f"%{clean_name}%")).first()
+                if not agent:
+                    agent = db.query(Agent).filter(Agent.name.ilike(f"%{clean_name}%")).first()
             if not agent:
                 agent = db.query(Agent).first()
                     "id": agent.id,
                     "name": agent.name,
                     "system_prompt": agent.system_prompt,
+                    "domain": agent.domain or "general",
                     "domain_signature": agent.domain_signature or [],
+                    "prompt_analysis": agent.prompt_analysis or {"domain": agent.domain or "general"},
                     "knowledge_graph": agent.knowledge_graph_json or {},
                     "chunk_count": agent.chunk_count or 0
                 }

backend/requirements.txt CHANGED Viewed

@@ -1,67 +1,68 @@
-# MEXAR Phase 1 - Backend Dependencies
-# Domain Guardrail (Section III-A: TF-IDF + NER + Jaccard)
-scikit-learn>=1.4.0
-spacy>=3.7.0,<3.8.0
-thinc>=8.2.0,<8.3.0
-# Web Framework
-fastapi==0.109.0
-uvicorn[standard]==0.27.0
-# Groq API
-groq==0.4.2
-httpx==0.27.0  # Pin to compatible version for groq SDK
-# Knowledge Graph
-networkx==3.2.1
-# Data Processing
-pandas==2.1.4
-PyPDF2==3.0.1
-python-docx==1.1.0
-# File Upload
-python-multipart==0.0.6
-# Video Processing
-opencv-python==4.9.0.80
-# Environment
-python-dotenv==1.0.0
-# JSON handling
-orjson==3.9.10
-# Async support
-aiofiles==23.2.1
-# Database (Supabase/PostgreSQL)
-SQLAlchemy==2.0.25
-psycopg2-binary==2.9.9
-# Authentication & Security
-passlib[bcrypt]==1.7.4
-python-jose[cryptography]==3.3.0
-bcrypt==4.1.2
-email-validator==2.1.0
-# Supabase Client
-supabase==2.24.0
-# Vector Support
-fastembed>=0.7.0  # Updated from 0.2.0 (was yanked)
-pgvector==0.2.4
-# RAG Components (NEW)
-sentence-transformers>=2.2.0  # Cross-encoder reranking
-numpy>=1.24.0  # Vector operations
-transformers>=4.38.0
-torch>=2.0.0
-# Evaluation & Baselines (Phase 3)
-langchain>=0.1.0
-langchain-community>=0.0.20
-langchain-groq>=0.1.0
-chromadb>=0.4.20

+# MEXAR Phase 1 - Backend Dependencies
+# Domain Guardrail (Section III-A: TF-IDF + NER + Jaccard)
+scikit-learn>=1.4.0
+spacy>=3.7.0,<3.8.0
+thinc>=8.2.0,<8.3.0
+# Web Framework
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+# Groq API
+groq==0.4.2
+httpx==0.27.0  # Pin to compatible version for groq SDK
+# Knowledge Graph
+networkx==3.2.1
+# Data Processing
+pandas==2.1.4
+PyPDF2==3.0.1
+python-docx==1.1.0
+# File Upload
+python-multipart==0.0.6
+# Video Processing
+opencv-python==4.9.0.80
+# Environment
+python-dotenv==1.0.0
+# JSON handling
+orjson==3.9.10
+# Async support
+aiofiles==23.2.1
+# Database (Supabase/PostgreSQL)
+SQLAlchemy==2.0.25
+psycopg2-binary==2.9.9
+# Authentication & Security
+passlib[bcrypt]==1.7.4
+python-jose[cryptography]==3.3.0
+bcrypt==4.1.2
+email-validator==2.1.0
+# Supabase Client
+supabase==2.24.0
+# Vector Support
+fastembed>=0.7.0  # Updated from 0.2.0 (was yanked)
+pgvector==0.2.4
+# RAG Components (NEW)
+sentence-transformers>=2.2.0  # Cross-encoder reranking
+numpy>=1.24.0  # Vector operations
+transformers>=4.38.0
+torch>=2.0.0
+# Evaluation & Baselines (Phase 3)
+langchain>=0.1.0
+langchain-community>=0.0.20
+langchain-groq>=0.1.0
+# chromadb>=0.4.20  # Optional (Requires C++ Build Tools on Python 3.12)

backend/workers/compilation_worker.py CHANGED Viewed

@@ -1,210 +1,213 @@
-import threading
-from pathlib import Path
-from typing import Optional, Callable
-from datetime import datetime
-from sqlalchemy.orm import Session
-import logging
-from models.agent import Agent, CompilationJob
-from modules.knowledge_compiler import KnowledgeCompiler, create_knowledge_compiler
-from modules.prompt_analyzer import PromptAnalyzer, create_prompt_analyzer
-logger = logging.getLogger(__name__)
-def _run_compilation_thread(
-    agent_id: int,
-    job_id: int,
-    storage_path: str,
-    system_prompt: str,
-    files_data: list
-):
-    """Execute the compilation process in a separate thread."""
-    from core.database import SessionLocal
-    db = SessionLocal()
-    job = None
-    agent = None
-    try:
-        job = db.query(CompilationJob).filter(CompilationJob.id == job_id).first()
-        agent = db.query(Agent).filter(Agent.id == agent_id).first()
-        if not job or not agent:
-            logger.error(f"Job or agent not found: job_id={job_id}, agent_id={agent_id}")
-            return
-        logger.info(f"Starting compilation for agent {agent.name}")
-        # Step 1: Analyze prompt (10%)
-        _update_progress(db, job, 10, "Analyzing system prompt")
-        analyzer = create_prompt_analyzer()
-        prompt_analysis = analyzer.analyze_prompt(system_prompt)
-        logger.info(f"Prompt analysis complete: domain={prompt_analysis.get('domain')}")
-        # Step 2: Initialize compiler (20%)
-        _update_progress(db, job, 20, "Initializing knowledge compiler")
-        compiler = create_knowledge_compiler(str(Path(storage_path).parent))
-        # Step 3: Compile knowledge (20-80%)
-        _update_progress(db, job, 30, "Compiling knowledge base")
-        logger.info(f"Starting compilation with {len(files_data)} files")
-        # Parse files into the expected format
-        parsed_data = []
-        for file_info in files_data:
-            content = file_info.get("content", "")
-            filename = file_info.get("filename", "unknown")
-            parsed_data.append({
-                "source": filename,
-                "content": content,
-                "type": "text",
-                "records": content.split("\n") if content else []
-            })
-        # Run compilation with error handling
-        try:
-            result = compiler.compile(
-                agent_name=agent.name,
-                parsed_data=parsed_data,
-                system_prompt=system_prompt,
-                prompt_analysis=prompt_analysis
-            )
-            logger.info(f"Compilation complete: {result.get('stats', {})}")
-        except Exception as compile_error:
-            logger.error(f"Compilation error (continuing): {compile_error}", exc_info=True)
-            # Continue even if compilation has issues - embeddings may still be created
-            result = {"stats": {}, "domain_signature": []}
-        _update_progress(db, job, 80, "Saving to vector store")
-        # Step 4: Update agent metadata (90%)
-        _update_progress(db, job, 90, "Updating agent metadata")
-        agent.status = "ready"
-        agent.domain = prompt_analysis.get("domain", "general")
-        agent.domain_keywords = prompt_analysis.get("domain_keywords", [])
-        agent.entity_count = result.get("stats", {}).get("total_entries", 0)
-        # Step 5: Complete (100%)
-        job.status = "completed"
-        job.progress = 100
-        job.current_step = "Compilation complete"
-        job.completed_at = datetime.utcnow()
-        db.commit()
-        logger.info(f"Agent {agent.name} compilation completed successfully")
-    except Exception as e:
-        logger.error(f"Compilation failed for job {job_id}: {str(e)}", exc_info=True)
-        # CRITICAL: Always update job and agent status on error
-        try:
-            if not job:
-                job = db.query(CompilationJob).filter(CompilationJob.id == job_id).first()
-            if not agent:
-                agent = db.query(Agent).filter(Agent.id == agent_id).first()
-            if job:
-                job.status = "failed"
-                job.error_message = str(e)[:500]  # Limit error message length
-                job.completed_at = datetime.utcnow()
-                logger.error(f"Job {job_id} marked as failed")
-            if agent:
-                agent.status = "failed"
-                logger.error(f"Agent {agent_id} marked as failed")
-            db.commit()
-        except Exception as update_error:
-            logger.error(f"Failed to update error status: {update_error}")
-            db.rollback()
-    finally:
-        # CRITICAL: Ensure database connection is closed
-        try:
-            db.close()
-            logger.info(f"Database connection closed for job {job_id}")
-        except Exception as close_error:
-            logger.error(f"Error closing database: {close_error}")
-def _update_progress(db: Session, job: CompilationJob, progress: int, step: str):
-    """Update job progress."""
-    job.progress = progress
-    job.current_step = step
-    db.commit()
-    logger.info(f"Job {job.id} progress: {progress}% - {step}")
-class CompilationWorker:
-    """
-    Background worker for compiling agent knowledge bases.
-    Uses threading for reliable async execution on Windows.
-    """
-    def __init__(self):
-        self.active_jobs = {}  # agent_id -> job_info
-    def start_compilation(
-        self,
-        db: Session,
-        agent: Agent,
-        files_data: list,
-        progress_callback: Optional[Callable] = None
-    ) -> CompilationJob:
-        """Start a background compilation job using threading."""
-        # Create compilation job record
-        job = CompilationJob(
-            agent_id=agent.id,
-            status="in_progress",
-            progress=0,
-            current_step="Initializing"
-        )
-        db.add(job)
-        db.commit()
-        db.refresh(job)
-        logger.info(f"Created compilation job {job.id} for agent {agent.name}")
-        # Start background thread
-        thread = threading.Thread(
-            target=_run_compilation_thread,
-            args=(agent.id, job.id, agent.storage_path, agent.system_prompt, files_data),
-            daemon=True
-        )
-        thread.start()
-        self.active_jobs[agent.id] = {
-            "job_id": job.id,
-            "thread": thread,
-            "status": "in_progress"
-        }
-        logger.info(f"Started compilation thread for agent {agent.name}")
-        return job
-    def get_job_status(self, db: Session, agent_id: int) -> Optional[dict]:
-        """Get the latest job status for an agent."""
-        job = db.query(CompilationJob).filter(
-            CompilationJob.agent_id == agent_id
-        ).order_by(CompilationJob.created_at.desc()).first()
-        if not job:
-            return None
-        return {
-            "id": job.id,
-            "status": job.status,
-            "progress": job.progress,
-            "current_step": job.current_step,
-            "error_message": job.error_message,
-            "created_at": job.created_at,
-            "completed_at": job.completed_at
-        }
-# Singleton instance
-compilation_worker = CompilationWorker()

+import threading
+from pathlib import Path
+from typing import Optional, Callable
+from datetime import datetime
+from sqlalchemy.orm import Session
+import logging
+from models.agent import Agent, CompilationJob
+from modules.knowledge_compiler import KnowledgeCompiler, create_knowledge_compiler
+from modules.prompt_analyzer import PromptAnalyzer, create_prompt_analyzer
+logger = logging.getLogger(__name__)
+def _run_compilation_thread(
+    agent_id: int,
+    job_id: int,
+    storage_path: str,
+    system_prompt: str,
+    files_data: list
+):
+    """Execute the compilation process in a separate thread."""
+    from core.database import SessionLocal
+    db = SessionLocal()
+    job = None
+    agent = None
+    try:
+        job = db.query(CompilationJob).filter(CompilationJob.id == job_id).first()
+        agent = db.query(Agent).filter(Agent.id == agent_id).first()
+        if not job or not agent:
+            logger.error(f"Job or agent not found: job_id={job_id}, agent_id={agent_id}")
+            return
+        logger.info(f"Starting compilation for agent {agent.name}")
+        # Step 1: Analyze prompt (10%)
+        _update_progress(db, job, 10, "Analyzing system prompt")
+        analyzer = create_prompt_analyzer()
+        prompt_analysis = analyzer.analyze_prompt(system_prompt)
+        logger.info(f"Prompt analysis complete: domain={prompt_analysis.get('domain')}")
+        # Step 2: Initialize compiler (20%)
+        _update_progress(db, job, 20, "Initializing knowledge compiler")
+        compiler = create_knowledge_compiler(str(Path(storage_path).parent))
+        # Step 3: Compile knowledge (20-80%)
+        _update_progress(db, job, 30, "Compiling knowledge base")
+        logger.info(f"Starting compilation with {len(files_data)} files")
+        # Parse files into the expected format
+        parsed_data = []
+        for file_info in files_data:
+            content = file_info.get("content", "")
+            filename = file_info.get("filename", "unknown")
+            parsed_data.append({
+                "source": filename,
+                "content": content,
+                "type": "text",
+                "records": content.split("\n") if content else []
+            })
+        # Run compilation with error handling
+        try:
+            result = compiler.compile(
+                agent_name=agent.name,
+                parsed_data=parsed_data,
+                system_prompt=system_prompt,
+                prompt_analysis=prompt_analysis
+            )
+            logger.info(f"Compilation complete: {result.get('stats', {})}")
+        except Exception as compile_error:
+            logger.error(f"Compilation error (continuing): {compile_error}", exc_info=True)
+            # Continue even if compilation has issues - embeddings may still be created
+            result = {"stats": {}, "domain_signature": []}
+        _update_progress(db, job, 80, "Saving to vector store")
+        # Step 4: Update agent metadata (90%)
+        _update_progress(db, job, 90, "Updating agent metadata")
+        agent.status = "ready"
+        agent.domain = prompt_analysis.get("domain", "general")
+        agent.domain_keywords = prompt_analysis.get("domain_keywords", [])
+        agent.prompt_analysis = prompt_analysis
+        agent.domain_signature = result.get("domain_signature", [])
+        agent.compilation_stats = result.get("stats", {})
+        agent.entity_count = result.get("stats", {}).get("total_entries", 0)
+        # Step 5: Complete (100%)
+        job.status = "completed"
+        job.progress = 100
+        job.current_step = "Compilation complete"
+        job.completed_at = datetime.utcnow()
+        db.commit()
+        logger.info(f"Agent {agent.name} compilation completed successfully")
+    except Exception as e:
+        logger.error(f"Compilation failed for job {job_id}: {str(e)}", exc_info=True)
+        # CRITICAL: Always update job and agent status on error
+        try:
+            if not job:
+                job = db.query(CompilationJob).filter(CompilationJob.id == job_id).first()
+            if not agent:
+                agent = db.query(Agent).filter(Agent.id == agent_id).first()
+            if job:
+                job.status = "failed"
+                job.error_message = str(e)[:500]  # Limit error message length
+                job.completed_at = datetime.utcnow()
+                logger.error(f"Job {job_id} marked as failed")
+            if agent:
+                agent.status = "failed"
+                logger.error(f"Agent {agent_id} marked as failed")
+            db.commit()
+        except Exception as update_error:
+            logger.error(f"Failed to update error status: {update_error}")
+            db.rollback()
+    finally:
+        # CRITICAL: Ensure database connection is closed
+        try:
+            db.close()
+            logger.info(f"Database connection closed for job {job_id}")
+        except Exception as close_error:
+            logger.error(f"Error closing database: {close_error}")
+def _update_progress(db: Session, job: CompilationJob, progress: int, step: str):
+    """Update job progress."""
+    job.progress = progress
+    job.current_step = step
+    db.commit()
+    logger.info(f"Job {job.id} progress: {progress}% - {step}")
+class CompilationWorker:
+    """
+    Background worker for compiling agent knowledge bases.
+    Uses threading for reliable async execution on Windows.
+    """
+    def __init__(self):
+        self.active_jobs = {}  # agent_id -> job_info
+    def start_compilation(
+        self,
+        db: Session,
+        agent: Agent,
+        files_data: list,
+        progress_callback: Optional[Callable] = None
+    ) -> CompilationJob:
+        """Start a background compilation job using threading."""
+        # Create compilation job record
+        job = CompilationJob(
+            agent_id=agent.id,
+            status="in_progress",
+            progress=0,
+            current_step="Initializing"
+        )
+        db.add(job)
+        db.commit()
+        db.refresh(job)
+        logger.info(f"Created compilation job {job.id} for agent {agent.name}")
+        # Start background thread
+        thread = threading.Thread(
+            target=_run_compilation_thread,
+            args=(agent.id, job.id, agent.storage_path, agent.system_prompt, files_data),
+            daemon=True
+        )
+        thread.start()
+        self.active_jobs[agent.id] = {
+            "job_id": job.id,
+            "thread": thread,
+            "status": "in_progress"
+        }
+        logger.info(f"Started compilation thread for agent {agent.name}")
+        return job
+    def get_job_status(self, db: Session, agent_id: int) -> Optional[dict]:
+        """Get the latest job status for an agent."""
+        job = db.query(CompilationJob).filter(
+            CompilationJob.agent_id == agent_id
+        ).order_by(CompilationJob.created_at.desc()).first()
+        if not job:
+            return None
+        return {
+            "id": job.id,
+            "status": job.status,
+            "progress": job.progress,
+            "current_step": job.current_step,
+            "error_message": job.error_message,
+            "created_at": job.created_at,
+            "completed_at": job.completed_at
+        }
+# Singleton instance
+compilation_worker = CompilationWorker()