File size: 3,323 Bytes
4b7bc58 40bb6e9 4b7bc58 40bb6e9 4e0f514 40bb6e9 4e0f514 40bb6e9 4e0f514 40bb6e9 4e0f514 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | ---
title: NexusGraph AI
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
---
# 🧠 NexusGraph AI
> **High Distinction Project**: An advanced "Agentic" Retrieval-Augmented Generation system that uses Graph Theory (LangGraph), Structural Retrieval (SQL), and Self-Correction to answer complex queries.
## 🚀 The "Master's Level" Difference
Unlike basic RAG scripts that just "search and dump," this system acts like a **Consulting Firm**:
1. **Supervisor Agent (Hybrid)**: Uses **Gemini 2.5 Flash Lite** (Fast) to decide *which* tool to use (PDF, Web, or SQL).
2. **Responder Agent (Expert)**: Uses **Gemini 3 Flash Preview** (Smart) to synthesize the final answer.
3. **Self-Correction**: If the answer is bad, the agent *rewrites the query* and tries again.
4. **Hybrid Retrieval**: Combines **Unstructured Data** (PDFs) with **Structured Data** (SQL Database).
5. **Audit System**: calculating Faithfulness and Relevancy scores post-hoc (RAGAS-style).
---
## 🏛️ Architecture
```mermaid
graph TD
User --> Supervisor
Supervisor -->|Policy?| PDF[Librarian: Vectors]
Supervisor -->|Stats?| SQL[Analyst: SQL DB]
Supervisor -->|News?| Web[Journalist: Web Search]
PDF & SQL & Web --> Verifier[Auditor Agent]
Verifier --> Responder[Writer Agent]
Responder -->|Good?| End
Responder -->|Bad?| Supervisor
```
## ✨ New Features
### 1. 📊 Data Analyst (SQL Tool)
The system can now answer quantitative questions like *"Who pays the highest fees?"* or *"What is the average GPA?"* by querying a local SQLite database.
### 2. 🛡️ Resilience (Circuit Breaker)
If the Google Gemini API quota is exceeded (`429`), the system catches the error and returns a graceful "System Busy" message instead of crashing (`500`).
### 3. ⚖️ Hybrid Agent Architecture
Optimized for Speed and Intelligence:
* **Routing**: Handled by lightweight `gemini-2.5-flash-lite`.
* **Reasoning**: Handled by powerful `gemini-3-flash-preview`.
### 4. 🚀 CI/CD Pipeline
Automated deployment from GitHub to Hugging Face using **GitHub Actions**. Commits to `main` are instantly verified and deployed to production.
### 5. 🧪 Automated Testing
Includes a `tests/` suite:
* `test_api.py`: Integrations tests for endpoints.
* `test_rag.py`: Unit tests for retrieval logic.
### 6. 🐳 Dockerized
Fully containerized for "Run Anywhere" capability.
---
## 🛠️ How to Run
### Option A: Local Python
1. **Install**: `pip install -r requirements.txt`
2. **Environment**: Create `.env` with `GEMINI_API_KEY` and `TAVILY_API_KEY`.
3. **Run Service**:
```bash
uvicorn main:app --reload
```
4. **Run Evaluation Audit**:
```bash
python run_evals.py
```
### Option B: Docker (Recommended)
1. **Build**:
```bash
docker-compose build
```
2. **Run**:
```bash
docker-compose up
```
### Option C: Run Tests
```bash
pytest
```
---
## 📊 Evaluation (The Science)
We use an **LLM-as-a-Judge** approach (`run_evals.py`) to measure:
* **Faithfulness**: Is the answer hallucinated?
* **Relevancy**: Did we answer the prompt?
* *Current Benchmarks*: ~0.92 Faithfulness / 0.89 Relevancy.
---
## 📜 Credits
Built by **Vignesh Ladar Vidyananda**.
Powered by FastAPI, LangGraph, FAISS, and Google Gemini.
|