A production-grade clinical AI platform that transforms natural language symptom descriptions
into structured, RAG-grounded health assessments with personalized risk stratification.
Overview · Architecture · Getting Started · API Docs · Comparison
|
Patients struggle to articulate clinical symptoms accurately — relying on vague Google searches or fragmented symptom-checker forms that yield generic, anxiety-inducing results (e.g., "headache = brain tumor"). On the other side, healthcare providers lack time to manually parse chaotic, emotionally driven patient histories before an appointment. Equinox bridges this gap by acting as an intelligent clinical triage layer. It accepts raw, unstructured text — exactly how a patient speaks — and translates it into a structured clinical differential. What makes Equinox fundamentally different from standard "AI doctors" is its staunch anti-hallucination architecture. General-purpose LLMs are notoriously dangerous in medical contexts because they confidently fabricate. Equinox avoids this by entirely decoupling knowledge retrieval from reasoning. It relies on a highly sophisticated RAG pipeline powered by Patients interface via a dynamic React frontend. As they describe symptoms, an autonomous agentic loop takes over — asking one targeted clinical question per turn based on what data is missing from the differential (e.g., "Does the pain radiate to your jaw?"). It incorporates the user's longitudinal health profile and prior visit memory. Once the AI has sufficient data — or detects a critical red flag — it autonomously terminates the interview, generates a clinician-ready PDF handover report, and dynamically routes high-risk profiles to care. |
|
|
Free-Text Clinical Intake Natural language processing of raw patient narratives into structured clinical entities (Site, Onset, Character, Radiation, etc.) via the SOCRATES framework. Dynamic NLP Interviewing Sovereign AI agent that drives the assessment, autonomously asking targeted follow-up questions to narrow down the differential diagnosis without human intervention. RAG-Grounded Medical Knowledge
Retrieval-Augmented Generation using HDBSCAN Semantic Clustering Advanced topological data analysis to cluster medical transcriptions and map symptoms efficiently, drastically improving retrieval speed and contextual accuracy. Personalized Risk Stratification
Programmatic cross-referencing of current symptoms with the user's stored health profile (medications, allergies, past conditions) to assign a calibrated risk tier: |
Automated Clinical Handover PCRs Generation of comprehensive, physician-centric PDF reports using ReportLab, fully structured with differentials, vital heuristics, and red flag tracking. Autonomous Emergency Detection
Built-in heuristic safeguards combined with LLM analysis that immediately force-terminate an assessment and escalate to Voice Interactivity
Integration with Emotional Distress Tone Analysis Automatic detection of patient panic, frustration, or anxiety based on syntactic input, dynamically triggering warm wellness nudges and shifting the AI tone. Memory & Context Continuity Longitudinal session tracking that natively injects past patient medical visits into the live Llama 3 context window for continuity of care. |
Patient Dashboard Central hub showing active sessions, recent assessments, and health snapshot at a glance. |
Clinical Intake & Agentic Interview Real-time agentic loop driving the symptom intake with targeted follow-up questions. |
Risk Stratification Output Differential diagnosis with calibrated risk tier, red flags, and recommended care pathway. |
Clinician Handover PDF Auto-generated PCR report structured for direct clinical handover — no reformatting needed. |
Clinical Analyses Panel Longitudinal symptom trends, session telemetry, and aggregated health signal visualizations. |
Visit History & Memory Persistent longitudinal record of all past assessments, injected into future AI context windows. |
Patient Health Profile Stored medications, allergies, and chronic conditions that personalize every risk assessment. |
Care Routing Map Geo-aware emergency routing that surfaces nearby care facilities based on assessed risk tier. |
Population-Level Insights Aggregate epidemiological view across the platform — symptom clusters, regional trends, and more. |
| Feature / Aspect | Equinox | Ada Health | Healthify Me | WebMD | K Health |
|---|---|---|---|---|---|
| AI Model Type | Llama 3.3 70B + PubMedBERT |
Proprietary Bayesian | Basic ML / Rules | Heuristic Tree | Text-based ML |
| Data Source | Kaggle Transcripts + Guidelines | Internal Curated DB | Nutrition/Fitness DB | Static Articles | Mayo Clinic Data |
| Personalization | High (Longitudinal Memory) | Moderate | Moderate (Fitness) | Low | Moderate |
| Offline Capability | Limited (requires API) | Unknown | Limited | Yes (basic) | Limited |
| Open-Source | Yes | No | No | No | No |
| Cost | Free | Freemium | Paid | Free (ad-supported) | Paid per visit |
| RAG / Retrieval | Yes (ChromaDB vector search) |
No | No | No | No |
| Clinical Accuracy Focus | RAG-Bounded Generation | Very High (validated) | Low (non-clinical) | Moderate | High |
| NLP Depth | Semantic Clustering (HDBSCAN) |
Keyword / Probabilistic | Basic intent | Keyword matching | Keyword / Intent |
| Agentic Interview Loop | Yes | No | No | No | No |
| PDF Clinical Reports | Yes | No | No | No | No |
| Voice Interactivity | Yes (Vapi + Edge TTS) | No | No | No | No |
graph TD
A[React SPA / Vite] -->|REST API| B[FastAPI Backend :8000]
A -->|Auth| Firebase[Firebase OAuth]
B -->|SQLite / SQLAlchemy| C[(Primary Database)]
B -->|Routes Request| D[ML Microservice :8001]
D -->|User Query| E{RAG Router}
E -->|Embed Query| F[PubMedBERT sentence-transformers]
F -->|Cosine Similarity| G[(ChromaDB Vector Store)]
G -->|Retrieve Top K Context| H[Prompt Builder]
H -->|Inject Profile & History| I[Groq Client]
I -->|Agentic Loop| J[Llama 3.3 70B via Groq API]
J -->|Strict JSON| K{Is Final Assessment?}
K -- No --> L[Return Follow-up Question]
K -- Yes --> M[Generate Differential & Risk Score]
L --> A
M --> N[Report Builder PDF]
M --> A
N --> A
subgraph Data Pipeline
Z[Kaggle mtsamples.csv] --> Y[Pandas Cleaning]
Y --> X[Sentence Embeddings]
X --> W[UMAP Reduction]
W --> V[HDBSCAN Clustering]
V --> G
end
| Layer | Description |
|---|---|
| Frontend | React 18 SPA built with Vite. State managed by Zustand. Animations via Framer Motion and Three.js (react-three-fiber) — particle backgrounds and fluid cursors. Communicates with the backend over Axios at /api. |
| Backend | FastAPI on Python 3.11, port 8000. Handles authentication (PyJWT + Firebase OAuth), session management, appointments, and feedback. Persistence via SQLite + SQLAlchemy ORM, validated through Pydantic. |
| ML Microservice | Secondary FastAPI service on port 8001. Runs the full RAG pipeline: query embedding → ChromaDB retrieval → prompt construction → Groq agentic call → structured JSON extraction. |
| Vector Store | ChromaDB as the persistent semantic layer. Documents embedded via NeuML/pubmedbert-base-embeddings. Stores chunked JSON guidelines covering differential diagnoses, risk factors, and recommended actions. |
| Data Pipeline | mtsamples.csv from Kaggle is cleaned via pandas, embedded with PubMedBERT, reduced to 2D using UMAP, and topologically clustered using HDBSCAN to identify natural symptom syndromes before insertion into ChromaDB. |
| Agentic Loop | The LLM controls its own termination. By setting "is_final": true in its strictly enforced JSON schema, the model transitions app state from "Interviewing" to "Assessment Complete" — acting as a state machine controller. |
| Technology | Category | Why It's Used |
|---|---|---|
React 18 + Vite |
Frontend | Fast HMR, SPA routing, component architecture |
Zustand |
State Management | Lightweight, boilerplate-free global state |
Framer Motion + Three.js |
UI / Animations | Premium fluid animations and 3D particle scenes |
FastAPI |
Backend Framework | Async Python server with automatic OpenAPI docs |
SQLAlchemy + SQLite |
ORM / Database | Simple, file-based relational persistence |
Pydantic |
Validation | Runtime type safety for all API contracts |
PyJWT + Firebase OAuth |
Auth | Stateless JWT session + Google sign-in |
Groq API |
LLM Inference | Ultra-fast Llama 3.3 70B inference (sub-second) |
Llama 3.3 70B |
Language Model | High-reasoning open model for clinical differential |
PubMedBERT (NeuML) |
Embedding Model | Fine-tuned on biomedical text; superior medical NLP |
ChromaDB |
Vector Database | Local-first persistent vector store for RAG |
HDBSCAN |
Clustering | Density-based; handles medical transcript noise well |
UMAP |
Dimensionality Reduction | Topology-preserving 2D projection for clustering |
sentence-transformers |
Embedding Framework | Loads and runs PubMedBERT in the pipeline |
pandas |
Data Processing | Cleans and preprocesses Kaggle CSV transcripts |
ReportLab |
PDF Generation | Programmatic clinical PDF report rendering |
Vapi |
Voice AI | AI voice agent infrastructure for spoken intake |
Edge TTS |
Text-to-Speech | Real-time synthesized speech output |
Axios |
HTTP Client | Frontend-to-backend REST communication |
git clone https://github.com/quirky-sharan/equinox.git
cd equinoxcd frontend
npm installCreate frontend/.env:
VITE_FIREBASE_API_KEY=your_key_here
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_API_BASE_URL=http://localhost:8000cd ../backend
pip install -r requirements.txtCreate backend/.env:
DATABASE_URL=sqlite:///./meowmeow.db
JWT_SECRET=super-secret-production-key-change-me
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440
ML_SERVICE_URL=http://localhost:8001
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_API_KEY=your_key
FRONTEND_URL=http://localhost:5173
GROQ_API_KEY=gsk_your_groq_api_key_here
VAPI_API_KEY=your_vapi_key
VAPI_PHONE_NUMBER_ID=your_vapi_phone_idcd ../ml
pip install -r requirements.txtImportant: Run the ingestion script once to build your local ChromaDB vector index from the medical knowledge base.
python -m knowledge_base.ingestOn first run,
SentenceTransformerandPubMedBERTweights will be downloaded automatically. This may take a few minutes.
From the root directory, run the initialization script:
start_all.batThis boots all three services in parallel:
| Service | URL |
|---|---|
| Frontend UI (Vite / React) | http://localhost:5173 |
| Backend API (FastAPI) | http://localhost:8000 |
| ML Engine (FastAPI) | http://localhost:8001 |
- Open
http://localhost:5173— you should see the Equinox landing page. - Navigate to
/api/docs(port 8000) for the auto-generated FastAPI Swagger UI. - Navigate to
http://localhost:8001/docsfor the ML service API docs. - Sign in with Google, start a new session, and describe a symptom to confirm the agentic loop is responding.
equinox/
│
├── backend/ # Primary FastAPI application (port 8000)
│ ├── .env # Backend environment secrets (DB, JWT, Firebase)
│ ├── auth.py # PyJWT issuance and validation logic
│ ├── config.py # Pydantic BaseSettings mapping .env to runtime config
│ ├── database.py # SQLAlchemy engine initialization and session factory
│ ├── main.py # Application entrypoint & CORS middleware setup
│ ├── requirements.txt # Python dependencies for the backend
│ ├── models/ # SQLAlchemy ORM models (users, sessions, telemetry)
│ ├── routes/ # Route handlers mapping URL paths to modules
│ └── schemas/ # Pydantic serializers for request/response validation
│
├── frontend/ # React 18 SPA (Vite, port 5173)
│ ├── package.json # NPM dependency registry
│ ├── vite.config.js # HMR server + /api reverse proxy config
│ └── src/
│ ├── App.jsx # Root component and React Router orchestrator
│ ├── main.jsx # HTML entry point attaching the React tree
│ ├── index.css # Global token and styling definitions
│ ├── api/ # Axios sub-clients for FastAPI communication
│ ├── components/ # Isolated UI parts (Navbars, Cursors, 3D elements)
│ ├── config/ # Frontend environment and key config
│ ├── hooks/ # Custom hooks (cursor state, session, etc.)
│ ├── pages/ # Full-screen route targets (individual pages)
│ ├── store/ # Zustand global state configuration
│ └── utils/ # Extracted helper and utility scripts
│
├── medical_system/ # Clinical data aggregation workflow
│ ├── data_pipeline.py # Pandas driver for cleaning Kaggle datasets
│ ├── main.py # Executor triggering pipeline flow and DB insertion
│ ├── pdf_report_generator.py # ReportLab script rendering clinical PDF summaries
│ └── rag_engine.py # HDBSCAN clustering engine for embedding topologies
│
├── ml/ # AI/ML inference microservice (port 8001)
│ ├── groq_client.py # Agentic loop managing Llama 3 context and termination
│ ├── ml_api.py # FastAPI routes for chat generation and TTS streams
│ ├── prompt_builder.py # Combines RAG context, profile, and SOCRATES format
│ ├── report_generator.py # Connects ML outputs to PDF builders
│ ├── session_manager.py # In-memory conversation history dictionary
│ ├── user_memory_injector.py # Maps SQL user history into live LLM context
│ ├── chroma_db/ # ChromaDB persistent vector store files
│ └── knowledge_base/
│ ├── ingest.py # SentenceTransformer embedding push to ChromaDB
│ ├── retriever.py # Query embedding and nearest-neighbor retrieval
│ └── medical_knowledge*.json# Static structured condition definitions for differential matching
│
├── screenshots/ # Application screenshots for documentation
│ ├── landing_page.png # Hero / landing page
│ ├── dashboard.png # Patient dashboard
│ ├── inference.png # Clinical intake & agentic interview
│ ├── assesment.png # Risk stratification output
│ ├── pdf.png # Clinician handover PDF
│ ├── analyses.png # Analytics panel
│ ├── history.png # Visit history
│ ├── profile.png # Patient health profile
│ ├── map.png # Care routing map
│ ├── population.png # Population-level insights
│ └── logo.png # Application logo
│
├── README.md # This file
└── start_all.bat # Sequential boot script for all services
| Method | Endpoint | Description |
|---|---|---|
 |
/api/session/new |
Instantiate a new patient encounter session |
 |
/api/history |
Return all past user assessment logs |
|
/api/auth/verify |
Validate Firebase OAuth tokens and issue JWT |
| Method | Endpoint | Description |
|---|---|---|
|
/ml/chat |
Main RAG pipeline — triggers Groq call, returns risk tiers and follow-up or final differential |
|
/ml/report/pdf |
Generate the post-assessment clinician PCR Handover PDF |
|
/ml/speak |
Stream Edge TTS voice synthesis audio data |
Full interactive API docs are auto-generated by FastAPI and available at
/docson both ports when the servers are running.
|
The primary training and retrieval corpus. Contains thousands of real de-identified medical transcription samples across specialties. Used in the data pipeline to:
Source: Kaggle — Medical Transcriptions |
A curated set of These are embedded alongside the Kaggle transcripts and serve as the authoritative clinical ground truth for the retrieval layer. Format: Chunked JSON — each document represents a condition cluster with associated symptoms, red flags, and differential guidance. |
|
Sharan AI / ML Pipeline · NLP Engineering · Frontend Architecture |
Devatman Frontend UI/UX · Backend APIs · Three.js · Database |
Varun Agentic Call Base · Agent Autonomy · Frontend Features |
- PubMedBERT by NeuML — biomedical embedding model
- Groq — ultra-fast LLM inference infrastructure
- ChromaDB — open-source vector database
- Kaggle — Medical Transcriptions — primary clinical corpus
- Vapi — voice AI infrastructure
- ReportLab — PDF generation library
Medical Disclaimer: Equinox is an AI research tool strictly intended for educational demonstration purposes. It is not a diagnostic medical device and its outputs must never supersede professional clinical judgment.
Made with precision by the Equinox team.