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