---
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.