Ether - Hybrid Brain Tumor Detection Support System
A Clinical Decision Support System (CDSS) prototype that combines classical radiomics and deep learning to give an AI-assisted second opinion on brain MRI scans, aimed at radiologists in resource-limited environments.
Hackathon prototype, not a medical device. It has not been validated on clinical data and must not be used to make clinical decisions. It is designed to support a specialist, never to replace one.
📌 Project status
Reviewed on 2026-10-29. This table says what exists today, not what is planned.
| Area | Works today | Not built yet |
|---|
| ML engine | JPG/PNG loader, image quality gate, 45 radiomic features (GLCM, LBP, wavelet, intensity), frozen EfficientNet-B0 embeddings, a training pipeline (cross-validation, calibration, report) and a serving pipeline. All tested on synthetic data | A model trained on the real dataset (the dataset is not in this repository), so there are no accuracy figures yet. Grad-CAM explanations. DICOM input |
| Backend | FastAPI service with a /health endpoint and API docs, hexagonal structure, PostgreSQL schema managed with Alembic, a client for the Meta Model API (Muse Spark) that is not yet connected to any endpoint | Study upload and classification endpoints, report and chat endpoints, de-identification. /health reports model_loaded: true because the service still uses a fake classifier |
| Frontend | Landing page and the "how we built it" page, deployed on Vercel | The clinician portal, the MRI viewer (Cornerstone3D is installed but no viewer exists), the results panel and the chat |
| Infrastructure | CI on GitHub Actions (tests, type checks, commit format). Frontend on Vercel, backend on Google Cloud Run, database on Supabase | Automatic database migrations on deploy |
Live frontend: https://ether-self-five.vercel.app
🏗 Architecture
Three independent components:
- Backend (
app/backend): FastAPI with a hexagonal (ports and adapters) structure.
- ML engine (
app/ml_engine): a standalone package with the hybrid pipeline (radiomics + CNN).
- Frontend (
app/frontend): Next.js web app.
Planned request flow (the backend does not implement it yet):
Clinician Backend (FastAPI) ML engine Muse Spark API
│ │ │ │
├─ Upload MRI ─────────>│ │ │
│ ├─ Classify ─────────────>│ │
│ │<─ Prediction ───────────│ │
│ ├─ Draft report ─────────────────────────────────>│
│<─ Result + report ────│<────────────────────────────────────────────────│
See CLAUDE.md for the architecture rules and docs/ml-engine/status.md for how the ML pieces fit together.
🚀 Quick start
Prerequisites: Python 3.11+, Node.js 18+ and Docker (only for the local database).
Backend
docker compose up -d postgres # PostgreSQL on localhost:5432
cd app/backend
pip install -e ".[dev]"
cp .env.example .env
alembic upgrade head # create the schema
uvicorn main:app --reload # http://localhost:8000, docs at /docs
pytest # integration tests need a reachable PostgreSQL
If port 5432 is already taken by a local PostgreSQL, change the host port in docker-compose.yml and in DATABASE_URL.
Do not run the whole stack with docker compose up yet. The compose file still defines Redis, MinIO and a Celery worker that the backend no longer uses, and the worker points to a module that does not exist.
ML engine
cd app/ml_engine
pip install -r requirements.lock
pytest src/tests
Exporting the backbone weights, training and serving are described in app/ml_engine/README.md.
Frontend
cd app/frontend
npm install
npm run dev # http://localhost:3000
📁 Project structure
Ether/
├── app/
│ ├── backend/ # FastAPI service
│ │ ├── adapters/ # inbound HTTP and outbound (database, LLM, storage, classifier)
│ │ ├── application/ # use cases
│ │ ├── domain/ # entities and domain errors
│ │ ├── ports/ # interfaces the adapters implement
│ │ ├── migrations/ # Alembic migrations
│ │ ├── tests/
│ │ ├── main.py # application factory
│ │ └── settings.py
│ │
│ ├── ml_engine/ # standalone ML package
│ │ └── src/
│ │ ├── preprocessing/ # loader, quality gate, skull stripping, deduplication
│ │ ├── classical/ # radiomic extractors
│ │ ├── deep_learning/ # frozen CNN extractor and weight bundles
│ │ ├── pipelines/ # serving pipeline
│ │ ├── training/ # training, selection, calibration, artifacts
│ │ └── tests/
│ │
│ └── frontend/ # Next.js app
│ └── src/
│ ├── app/ # pages and routes
│ ├── features/ # landing and story sections
│ └── hooks/
│
├── docs/ # deployment plan and ML engine documentation
├── openspec/ # specification changes
├── docker-compose.yml # local services
├── CONTRIBUTING.md # contribution guidelines
├── CLAUDE.md # team guidelines and architecture rules
└── LICENSE
📚 Documentation
🛠 Technologies
- Backend: FastAPI, SQLAlchemy (async) with asyncpg, Alembic, Pydantic, httpx
- ML engine: PyTorch, torchvision, scikit-learn, scikit-image, PyWavelets, OpenCV, joblib
- Frontend: Next.js 14, React 18, TypeScript, Recharts
- Data: PostgreSQL (Supabase in the cloud)
- Deployment: Vercel, Google Cloud Run, Supabase
- Tooling: GitHub Actions for CI, Azure Boards for work items
🤝 Contributing
Read CONTRIBUTING.md. In short:
git checkout develop && git pull
git checkout -b AB-88-your-feature # AB-{work item id}-{description}
git commit -m "AB-88: feat(backend): your description"
git push -u origin AB-88-your-feature # then open a pull request against develop
Pull requests target develop (QA). Changes reach main only through a promotion from develop. Work items live in a private Azure Boards project; use GitHub issues for questions.
⚠️ Important notes
- Ether is a Clinical Decision Support System prototype: it is meant to augment a specialist's evaluation, never to replace it, and it is not validated on clinical data.
- No real patient data is processed or stored today. Only JPG and PNG images are supported. De-identification and DICOM support are planned, not implemented.
- Explanations such as Grad-CAM heatmaps are planned, not implemented.
📜 Third-party assets and licenses
The code in this repository is released under the MIT License. That license does not cover the third-party assets below, which keep their own terms.
Ether is a hackathon prototype. These are the external assets it depends on and what is known about their terms. "Not verified" means nobody on the team has checked them yet, not that they are permissive.
| Asset | Used for | Status |
|---|
EfficientNet-B0 weights pretrained on ImageNet-1K, from torchvision (IMAGENET1K_V1) | Frozen CNN feature extractor | Terms not verified. They are never committed to git. The ImageNet terms of access limit the dataset to non-commercial research and education, and whether trained weights inherit that is unresolved. Check before any commercial use |
| Brain Tumor MRI Dataset (Masoud Nickparvar, Kaggle) | Training and evaluation | License not confirmed. A secondary source lists it as CC0, but we have not checked the Kaggle page, and the dataset combines three public datasets (figshare, SARTAJ and Br35H) whose own terms also matter. The team decided to commit it to app/ml_engine to track preprocessing steps, despite the license still being unconfirmed |
| Meta Model API (Muse Spark) | Clinical report and chat | Used through the API with a key from an environment variable. Subject to Meta's terms. While free credits are in use, Meta may use the content sent for product improvement, so only public dataset images and invented notes are sent (see app/backend/README.md) |
| Python and JavaScript dependencies | Everything | Open-source packages pinned in app/ml_engine/requirements.lock and the backend and frontend manifests. Their licenses were not audited |
Drawn skull and surgical instrument illustrations (app/frontend/public/portal-skull.png, portal-instrument.png) | Fixed background behind the study list | Owned by the team; cleared for use in this repository |
Drawn skeletal hand, torso and bird illustrations (app/frontend/public/portal-brain.png, portal-heart.png, portal-web.png) | Fixed background behind each analysis tab | Owned by the team; cleared for use in this repository |
Drawn skeleton back and IV drip stand illustrations (app/frontend/public/story-skeleton-back.png, ) |
Every model artifact records where its weights came from (backbone_provenance in its manifest.json). Details are in docs/ml-engine/decisions.md (D9, D14).
