# Nexus

> An multiagent project for medical use, it includes Supervisor - workers architecture for macro and ReAct for micro, RAG with Multiple Query and Rerank, Tool Use, MCP, docker and DevContainers

- **Type:** MCP server
- **Install:** `agentstack add mcp-josueperezvalenzuela-nexus`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JosuePerezValenzuela](https://agentstack.voostack.com/s/josueperezvalenzuela)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JosuePerezValenzuela](https://github.com/JosuePerezValenzuela)
- **Source:** https://github.com/JosuePerezValenzuela/Nexus

## Install

```sh
agentstack add mcp-josueperezvalenzuela-nexus
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

---
title: Medical AI Multi-Agent System
emoji: 🏥
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---

# 🏥 Nexus Health AI: Clinical Multi-Agent System

[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://streamlit.io/)
[](https://langchain-ai.github.io/langgraph/)
[](https://www.docker.com/)

> **Thesis Project:** An advanced autonomous multi-agent system designed to assist healthcare professionals by synthesizing patient clinical records (SQL) with medical literature (RAG) in real-time.

## 🚀 Live Demo

**Try it now:**
- 🎨 **Frontend:** [nexus-healthcare.streamlit.app](https://nexus-healthcare.streamlit.app/)

It might be in sleep mode due to the free trial levels.

---

## 🎬 See It In Action

### Simple Query - Medical Guidelines

*chat start greeting*

🔍 View Agent Trace

*LangSmith trace showing*

---

### Complex Query - Patient Analysis + Guidelines

*Retrives patient information, analyzes it, and finally specialist agent synthesizes the final response.*

🔍 View Multi-Agent Orchestration

*Supervisor coordinates*

---

---

## 🧠 The Problem

Traditional LLMs face critical challenges in healthcare:
- ❌ **Hallucinations:** Generate plausible but incorrect medical information
- ❌ **No Private Data Access:** Cannot query patient databases
- ❌ **Context Blindness:** Simple RAG lacks clinical reasoning

**Nexus Health AI solves this** with specialized agents that:
1. 🏥 **Query** private patient databases (SQL)
2. 📚 **Research** medical literature (RAG with 30+ documents)
3. 🧠 **Reason** across both sources for evidence-based insights

---

## 🏗️ System Architecture

The system uses a **Supervisor-Worker** pattern implemented with **LangGraph**. A central LLM router decides which tool to use based on the user's intent.

```mermaid
graph TD
    User[👤 User Query] --> Supervisor{🎯 Supervisor Agent}
    
    Supervisor -->|"Patient Data?"| DataAgent[🏥 Data Agent]
    Supervisor -->|"Medical Theory?"| DocsAgent[📚 Docs Agent]
    Supervisor -->|"Synthesize/Chat"| Specialist[👨‍⚕️ Specialist Agent]
    
    DataAgent -->|SQL Query| DB[(PostgreSQLPatient Records)]
    DocsAgent -->|Vector Search| VectorDB[(pgvector30+ Medical Docs)]
    
    DataAgent --> Specialist
    DocsAgent --> Specialist
    
    Specialist --> SafetyGate[🛡️ Safety Gate]
    SafetyGate -->|Safe Final Response| User
    
    style Supervisor fill:#FF6B6B
    style DataAgent fill:#4ECDC4
    style DocsAgent fill:#95E1D3
    style Specialist fill:#F38181
    style SafetyGate fill:#F9C74F
```

🤖 Agent Roles
| Agent | Model | Function | Tools |
|-------|-------|----------|-------|
| Supervisor | Llama 3.1 8B | Orchestrator/Router | JSON State Parsing |
| Data Agent | Llama 3.1 8B | SQL Analyst | lookup_patient_history |
| Docs Agent | Llama 3.1 8B | Medical Researcher | search_medical_guidelines |
| Specialist | Llama 3.1 8B | Clinical Synthesizer | Context Integration |

---

## 🚀 Key Features

### 🔄 Hybrid Information Retrieval
Seamlessly combines:
- **Structured data:** SQL queries on patient records
- **Unstructured knowledge:** Vector search on medical literature

### 🛡️ Production-Ready
- **Rate limiting:** Token bucket algorithm (slowapi)
- **CORS configured:** Secure cross-origin requests
- **Dockerized:** Reproducible deployments
- **CPU-optimized:** ONNX Runtime for fast embeddings

### 📊 Observable & Debuggable
- LangSmith integration for trace visualization
- Comprehensive logging
- Health check endpoints

---

## 🛠️ Tech Stack

**Backend**
- Python 3.12
- FastAPI (async API)
- LangChain + LangGraph
- PostgreSQL + pgvector
- SQLModel (ORM)

**AI/ML**
- Groq API (Llama 3.1 8B)
- intfloat/multilingual-e5-large
- FlashRank (reranking)
- LangSmith (observability)

**Frontend**
- Streamlit
- Python requests

**Infrastructure**
- Docker + Docker Compose
- HuggingFace Spaces
- Supabase (Database)

---

## 📖 API Documentation

### Interactive Swagger UI

*Auto-generated FastAPI documentation*

### Data Models

*Pydantic schemas for request/response validation*

### Safety Gate (diabetes/prediabetes)
- Guia operativa: [docs/safety-gate-v1.md](docs/safety-gate-v1.md)
- Runbook (config, monitoreo, rollout/rollback): [docs/safety-gate-runbook.md](docs/safety-gate-runbook.md)

---

## ⚡ Quick Start

### Prerequisites
- Docker & Docker Compose
- [uv](https://github.com/astral-sh/uv) (Python package manager)

### 1️⃣ Clone Repository
```bash
git clone https://github.com/JosuePerezValenzuela/Nexus.git
cd Nexus
```

### 2️⃣ Environment Variables
Create `.env` file:
```env
POSTGRES_SERVER=
POSTGRES_PORT=
POSTGRES_USER=
POSTGRES_PASSWORD=
POSTGRES_DB=

LLM_HOST=
VLLM_API_KEY=
LLM_MODEL_NAME=

environment=

# Safety gate (diabetes/prediabetes)
SAFETY_GATE_ENABLED=false
SAFETY_GATE_STRICT_MODE=true
SAFETY_GATE_MAX_REASON_CODES=5
SAFETY_GATE_EXPOSE_METADATA=false
```

### Safety gate quickstart

- Habilitar: setea `SAFETY_GATE_ENABLED=true` y reinicia el backend.
- Deshabilitar: setea `SAFETY_GATE_ENABLED=false` y reinicia el backend.
- Verificacion rapida: revisa logs de `safety_gate_decision` y counters de safety gate.

### 3️⃣ Start Services
```bash
docker compose up --build
```

### 4️⃣ Access
- **Frontend:** http://localhost:8501 (uv run streamlit run frontend/app.py)
- **Backend API:** http://localhost:8000 (uv run dev)
- **API Docs:** http://localhost:8000/docs

## 🧪 Example Scenarios

### 1. Patient Analysis (Data Agent)
**Query:** *"Give me a report on patient ID 1"*

**What happens:**
1. Supervisor routes to **Data Agent**
2. Data Agent queries PostgreSQL
3. Specialist synthesizes clinical summary

**Result:** Complete patient profile with glucose trends, weight evolution, and risk assessment.

---

### 2. Medical Research (Docs Agent)
**Query:** *"What is the recommended treatment for prediabetes?"*

**What happens:**
1. Supervisor routes to **Docs Agent**
2. Docs Agent searches 30+ medical PDFs (WHO, ADA, PAHO)
3. Specialist formats evidence-based recommendations

**Result:** Treatment guidelines with source citations.

---

### 3. Complex Clinical Reasoning (Multi-Agent)
**Query:** *"Is patient Carlos Mamani (ID 1) following treatment targets?"*

**What happens:**
1. Supervisor routes to **both agents**
2. Data Agent: Fetches Carlos's latest glucose (195 mg/dL)
3. Docs Agent: Retrieves target range guidelines (

**⭐ Star this repo if you find it useful!**

Built with ❤️ for healthcare innovation

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JosuePerezValenzuela](https://github.com/JosuePerezValenzuela)
- **Source:** [JosuePerezValenzuela/Nexus](https://github.com/JosuePerezValenzuela/Nexus)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-josueperezvalenzuela-nexus
- Seller: https://agentstack.voostack.com/s/josueperezvalenzuela
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.