Asclepius

Clinical Intelligence Engine — Brain tumor detection, longitudinal tracking, and clinical decision support.

---

Overview

Asclepius is a production-grade clinical AI platform that detects brain tumors from MRI scans and provides full longitudinal clinical intelligence. The system chains a CNN classifier through a multi-engine cognition pipeline — perception, world modeling, temporal reasoning, and prognosis — to deliver survival predictions, therapy recommendations, risk stratification, and AI-generated clinical summaries.

The platform ships as a Next.js 14 frontend with a FastAPI backend, backed by PostgreSQL for structured data and MongoDB Atlas for vector intelligence (similarity search, RAG, TCE memory).

---

Architecture

frontend/                  Next.js 14 application (port 3000)
  src/
    app/                   Pages (dashboard, analysis, timeline, prognosis, etc.)
    components/            UI components (brain-3d, similar-cases, providers)
    layouts/               Command Center layout (topbar, sidebar, workspace)
    lib/                   API client, utilities, auth store

backend/                   FastAPI application (port 8080)
  api/                     Route modules (auth, patients, scans, analysis, etc.)
  auth/                    JWT + bcrypt authentication
  database/                SQLAlchemy async models + session management
  infrastructure/          MongoDB client, vector intelligence
  schemas/                 Pydantic request/response schemas
  services/                Business logic services

asclepius/                 Core ML + clinical intelligence package
  config/                  Configuration and settings
  core/                    Exceptions, logging, performance, regulatory compliance
  data_collector/          Multi-agent data collection pipeline
    agents/                Validation agents (quality, anomaly, duplicate, etc.)
    connectors/            Data source connectors (Kaggle, filesystem)
    pipelines/             Normalization, cleaning, encoding
    validators/            Schema, range, distribution checks
    schemas/               Pydantic data models
    database/              PostgreSQL storage and lineage tracking
  engine/                  ML engines (perception, multimodal, world model, temporal, prognosis)
  models/                  Classifier, research backbones (Swin-UNETR, Meta-nnUNet, GNN)
  pipelines/               Inference, preprocessing, data flow orchestrator
  services/                Authentication, patient records, report generation, chatbot, email
  synthetic/               Synthetic data generation
  tce/                     Temporal Cognition Engine (4-layer architecture)
    storage/               Timeline, embedding, event, causal stores
    representation/        Temporal encoding, sequence building, delta analysis
    reasoning/             Pattern detection, anomaly detection, progression, causality
    api/                   High-level timeline, memory, reasoning, trajectory APIs
  world_model/             Latent state, transitions, estimator, decoder

federated/                 Federated learning (server, client, aggregation, encryption)
pretraining/               Self-supervised pretraining (MAE 3D, SimCLR 3D)
models/                    Model artifacts (.h5 files)
data/                      Training data (raw, master, production)
scripts/                   Dataset build, balance, validate, and training utilities
regulatory/                FDA/EU MDR compliance templates
tests/                     44 test files across 4 suites
  asclepius/               Core ML tests (15 files)
  backend/                 API tests (9 files)
  tce/                     Temporal Cognition Engine tests (4 files)
  data_collector/          Data pipeline tests (9 files)
docs/                      Project documentation

---

Tech Stack

Layer	Technologies
Frontend	Next.js 14.2, React 18.3, TypeScript, Tailwind CSS, Framer Motion, Recharts, Three.js
Backend	FastAPI, Uvicorn, SQLAlchemy (async), Pydantic
Databases	PostgreSQL 14+ (primary), MongoDB Atlas (vector search, optional)
ML	TensorFlow/Keras (CNN classifier), custom engines (perception, world model, temporal, prognosis)
Auth	JWT (python-jose), bcrypt
AI	Google Gemini 2.5 Flash (clinical assistant + summaries)

---

Requirements

• Python 3.10+
• Node.js 18+
• PostgreSQL 14+
• MongoDB Atlas (optional — system degrades gracefully without it)
• TensorFlow / Keras

---

Setup

# Clone the repository
git clone https://github.com/ReservedSnow/asclepius.git
cd asclepius

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Install frontend dependencies
cd frontend && npm install && cd ..

# Copy environment template and configure
cp .env.example .env

---

Environment Variables

Variable	Purpose	Default
DATABASE_URL	PostgreSQL connection string	postgresql+asyncpg://asclepius:asclepius@localhost:5432/asclepius
MONGODB_URI	MongoDB Atlas connection string	—
ASCLEPIUS_MODEL_PATH	Path to Keras HDF5 model file	models/brain_tumor_model.h5
GOOGLE_API_KEY	Google Gemini API key	—
ASCLEPIUS_GEMINI_MODEL	Gemini model identifier	gemini-2.5-flash
JWT_SECRET_KEY	Secret key for JWT token signing	—
ASCLEPIUS_WEBHOOK_URL	n8n webhook URL for email delivery	—
KAGGLE_USERNAME	Kaggle API username	—
KAGGLE_KEY	Kaggle API key	—

---

Usage

Start the backend

uvicorn backend.main:app --host 0.0.0.0 --port 8080 --reload

Start the frontend

cd frontend
npm run dev

Data Collector

# Run a full collection pipeline
python -m asclepius.data_collector.orchestrator --source kaggle

# Build and balance datasets
python scripts/build_master_dataset.py
python scripts/balance_dataset.py
python scripts/validate_dataset.py

---

API Endpoints

22+ REST endpoints across 10 route modules:

Module	Prefix	Key Endpoints
Auth	/api/auth	POST /login, POST /register, GET /me
Patients	/api/patients	GET /, POST /, GET /{id}, PATCH /{id}
Scans	/api/scans	POST /upload, GET /{id}, GET /patient/{id}
Analysis	/api/analysis	POST /run
Timeline	/api/timeline	GET /{id}, POST /{id}/events, POST /{id}/treatments
Prognosis	/api/prognosis	GET /{id}
Knowledge Graph	/api/knowledge-graph	GET /{id}, POST /{id}/nodes
Chat	/api/chat	POST /
Vector	/api/vector	GET /health, POST /similar-cases, POST /rag-context
Reports	/api/reports	GET /, GET /{scan_id}/download

---

Development

# Run tests
make test

# Lint
make lint

# Format
make format

# Type check
make typecheck

# Run all checks
make check

# Build frontend
cd frontend && npm run build

---

Documentation

Document	Description
System Architecture	Core architecture, TCE layers, data flow
System Architecture (Updated)	Current stack, API structure, database design
ML Pipeline	Two-tier inference pipeline (standard + cognition)
API Reference	REST API + core module APIs
Model Data Contract	Input schema, label structure, constraints
Database Design	PostgreSQL schema, indexes, lineage tracking
MongoDB Architecture	Vector search, collections, embedding design
Data Collector Architecture	Multi-agent pipeline, connectors, validators
Data Governance	Data quality, compliance, and governance policies
TCE Cognition	Temporal Cognition Engine design
World Model	Latent state management and transitions
Clinical Pipeline	End-to-end clinical workflow
RAG Pipeline	Retrieval-augmented generation design
Vector Search Design	Embedding and similarity search architecture
Design System	Visual design tokens
Contribution Policy	Guidelines for contributors

---

License

MIT

---

Copyright (c) 2026 Tanvir Singh Sandhu. All rights reserved.