BioScan-intelligence

Doctor-assistive clinical decision support platform powered by a 6-agent LLM orchestration pipeline

Comment

🩺 BioScan Intelligence

Doctor-Assistive Multi-Modal AI Clinical Decision Support Platform

React 19 Vite FastAPI Groq LPU Python 3.12 License: MIT

BioScan Intelligence replaces single-prompt LLM black-boxes with a 6-Agent Orchestrated Clinical Team. Powered by high-capacity open reasoning models (openai/gpt-oss-120b), BioScan ingests medical imaging (Chest X-Rays), comprehensive lab values (CBC, CMP, Lipid), and cancer risk data — transforming them into structured, review-ready clinical reports with real-time SSE reasoning transparency.

Key Features • Agent Architecture • Quick Start • API Reference

🌟 Key Features

  • 🏥 Multi-Modal Clinical Suite: Supports Radiographic (X-Ray), Hematologic (Blood Panel), and Oncology (Cancer Risk) diagnostic inputs.
  • ⚡ 6-Agent Orchestrated Pipeline: Modular DAG architecture mimicking real hospital multidisciplinary team (MDT) workflows.
  • 🚀 High-Capacity Open Inference: Standardized on high-performance open weights models (openai/gpt-oss-120b) hosted on high-throughput LPUs.
  • 🔀 Parallel Agent Reasoning: Diagnostic reasoning and test planning run concurrently to minimize clinical latency.
  • 🛡️ Autonomous Safety Guardrails: Dedicated Safety Agent inspects reasoning outputs for hallucinations, contradictions, and unsafe suggestions before final report synthesis.
  • 📡 Real-Time SSE Streaming: Live event-driven UI updates showing agent activity, active LLM model, execution timings, and intermediate clinical thoughts.
  • 📊 Lab Reference Range Engine: Standardizes and normalizes 24+ biomarker lab values (CBC, CMP, Lipid, Thyroid) with automatic out-of-range flagging.
  • 📄 Review-Ready Clinical Reports: Generates structured, exportable clinical summaries ready for physician confirmation.

🏗️ 6-Agentic Clinical Team Architecture

BioScan divides complex medical interpretation into specialized, narrow-scope tasks. This multi-agent decomposition dramatically reduces hallucinations compared to single monolithic LLMs.

flowchart TD
    classDef inputNode fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#ffffff,rx:8px,ry:8px;
    classDef stage1 fill:#0f172a,stroke:#60a5fa,stroke-width:2px,color:#ffffff,rx:8px,ry:8px;
    classDef stage2 fill:#1e1b4b,stroke:#a78bfa,stroke-width:2px,color:#ffffff,rx:8px,ry:8px;
    classDef stage3 fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#ffffff,rx:8px,ry:8px;
    classDef reportNode fill:#047857,stroke:#10b981,stroke-width:3px,color:#ffffff,rx:10px,ry:10px;

    A["Patient Data / Image / Lab Values"]:::inputNode --> B

    subgraph SG1 ["Stage 1: Triage and Evidence Extraction"]
        B["Agent 1: Triage Specialist (openai/gpt-oss-120b)"]:::stage1
        C["Agent 2: Evidence Extractor (openai/gpt-oss-120b)"]:::stage1
        B -->|"Urgency & Category"| C
    end

    subgraph SG2 ["Stage 2: Concurrent Reasoning (Parallel)"]
        D1["Agent 3: Differential Diagnostician (openai/gpt-oss-120b)"]:::stage2
        D2["Agent 4: Test & Interventions Planner (openai/gpt-oss-120b)"]:::stage2
    end

    C -->|"Normalized Facts"| D1
    C -->|"Normalized Facts"| D2

    subgraph SG3 ["Stage 3: Verification & Synthesis"]
        E["Agent 5: Safety Reviewer (openai/gpt-oss-120b)"]:::stage3
        F["Agent 6: Report Synthesizer (openai/gpt-oss-120b)"]:::stage3
        E -->|"Validated Audit Trace"| F
    end

    D1 -->|"Diagnoses & Rationale"| E
    D2 -->|"Workup Plan"| E

    F --> G["Final Structured Clinical Report"]:::reportNode

Agent Specialization Breakdown

# Agent Name Clinical Role Primary AI Engine Execution Mode Role & Focus
0 Vision Preprocessor Radiographic Descriptor google/gemma-4-26b-a4b-it:free Sequential (Images) Extracts visual features & anatomical findings from X-rays.
1 Triage Specialist Urgency & Classification openai/gpt-oss-120b Sequential Assigns triage priority (Emergency, Urgent, Routine) and risk category.
2 Evidence Extractor Data Normalization openai/gpt-oss-120b Sequential Normalizes raw patient data, flags abnormal lab ranges & findings.
3 Differential Diagnostician Clinical Reasoning openai/gpt-oss-120b Parallel Generates differential diagnoses with confidence scores & rationale.
4 Test Planner Diagnostic Workup openai/gpt-oss-120b Parallel Recommends follow-up labs, imaging, and specialist consultations.
5 Safety Reviewer Hallucination Guard openai/gpt-oss-120b Sequential Cross-checks outputs for unsupported claims, conflicts, or risks.
6 Report Synthesizer Summary Generator openai/gpt-oss-120b Sequential Composes the final physician-facing structured clinical report.

🔄 Real-Time SSE Streaming Sequence

sequenceDiagram
    autonumber
    actor Clinician as Clinician (UI)
    participant Backend as FastAPI Backend
    participant Orchestrator as Clinical Orchestrator
    participant AI as Groq / OpenRouter (GPT-OSS-120B)

    Clinician->>Backend: POST /api/{module}/analyze/stream
    Backend-->>Clinician: HTTP 200 OK (text/event-stream)
    Backend->>Orchestrator: Run Pipeline Stream

    Note over Clinician, AI: Stage 1 — Clinical Triage & Fact Extraction
    Orchestrator->>AI: Agent 1 (Triage) Query
    AI-->>Orchestrator: Urgency Score & Triage Category
    Orchestrator-->>Clinician: SSE Event: Agent 1 Complete

    Orchestrator->>AI: Agent 2 (Evidence Extractor) Query
    AI-->>Orchestrator: Normalized Findings & Abnormal Values
    Orchestrator-->>Clinician: SSE Event: Agent 2 Complete

    Note over Clinician, AI: Stage 2 — Concurrent Clinical Reasoning (Parallel Branching)
    par Differential Diagnosis Branch
        Orchestrator->>AI: Agent 3 (Diagnosis) Query
        AI-->>Orchestrator: Differential Diagnoses & Confidence
    and Diagnostic Workup Branch
        Orchestrator->>AI: Agent 4 (Test Planner) Query
        AI-->>Orchestrator: Recommended Labs & Referrals
    end
    Orchestrator-->>Clinician: SSE Event: Agents 3 & 4 Complete

    Note over Clinician, AI: Stage 3 — Autonomous Verification & Report Synthesis
    Orchestrator->>AI: Agent 5 (Safety Reviewer) Query
    AI-->>Orchestrator: Safety Audit & Hallucination Guard Check
    Orchestrator-->>Clinician: SSE Event: Agent 5 Complete

    Orchestrator->>AI: Agent 6 (Report Synthesizer) Query
    AI-->>Orchestrator: Final JSON Clinical Report
    Orchestrator-->>Clinician: SSE Event: Complete (Final Payload)

💻 Tech Stack Overview

Frontend

  • Framework: React 19 + Vite 6
  • Styling: Vanilla CSS3 + Modern Design System (Glassmorphism, Dark Mode Palette, Responsive Flex/Grid)
  • Icons: Lucide React
  • Routing & State: React Hooks & Custom useClinicalPipeline SSE Hook

Backend

AI & Inference Infrastructure

  • Primary LPUs: Groq API (openai/gpt-oss-120b)
  • Vision Models: OpenRouter API (google/gemma-4-26b-a4b-it:free)

📁 Repository Structure

BioScan Intelligence/
├── backend/
│   ├── services/
│   │   ├── __init__.py
│   │   ├── blood.py           # Blood panel reference ranges & anomaly normalization
│   │   └── orchestration.py   # 6-Agent DAG orchestrator, Groq/OpenRouter client & SSE emitter
│   ├── __init__.py
│   └── main.py                # FastAPI app, endpoints, CORS middleware, report store
├── public/                    # Static assets & favicon
├── src/
│   ├── hooks/
│   │   └── useClinicalPipeline.js  # React hook managing SSE connection & agent state
│   ├── App.jsx                # Main application UI, multi-modal forms & live pipeline view
│   ├── ClinicalReport.jsx     # Render component for final structured clinical report
│   ├── judge-polish.css       # Fine-grained styling for report visual cards
│   ├── main.jsx               # React application entry point
│   ├── mockReports.js         # Pre-configured medical demo cases (X-Ray, Blood, Cancer)
│   ├── report.css             # Report-specific layout & typography
│   ├── style1.css             # Comprehensive design tokens & visual components
│   ├── styles.css             # App-wide utility styles & layout variables
│   └── types.js               # Clinical data schemas & type definitions
├── .env.example               # Template for environment key setup
├── .gitignore                 # Git ignore configuration for Node, Python & logs
├── index.html                 # HTML shell
├── package.json               # Frontend dependencies & run scripts
├── requirements.txt           # Python backend dependencies
└── vite.config.js             # Vite configuration

🚀 Quick Start Guide

Prerequisites

  • Node.js: v18.0.0 or higher
  • Python: 3.10, 3.11, or 3.12
  • Groq API Key: Free key available at console.groq.com

Step 1: Clone Repository

git clone https://github.com/sumit-sh2009/BioScan-intelligence.git
cd BioScan-intelligence

Step 2: Environment Setup

Create .env file from .env.example:

cp .env.example .env

Open .env and add your Groq API Key:

GROQ_API_KEY=gsk_your_actual_groq_api_key_here

Step 3: Install Backend & Dependencies

# Create virtual environment (optional but recommended)
python -m venv .venv

# Activate virtual environment
# On Windows PowerShell:
.venv\Scripts\Activate.ps1
# On Linux / macOS:
source .venv/bin/activate

# Install Python requirements
pip install -r requirements.txt

Step 4: Install Frontend Dependencies

npm install

Step 5: Run BioScan Locally

Dual Terminal Execution

Terminal 1 (Backend API):

npm run api
# Or directly: python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

Terminal 2 (Frontend App):

npm run dev

Open your browser at <http://127.0.0.1:5173>.

📡 API Reference

HTTP Method Endpoint Description Response Type
GET /api/health Service health status & active model configuration application/json
POST /api/xray/analyze/stream Multi-agent analysis of Chest X-Ray image text/event-stream (SSE)
POST /api/blood/analyze/stream Multi-agent analysis of 24+ Blood Lab markers text/event-stream (SSE)
POST /api/cancer/analyze/stream Multi-agent analysis of Cancer Risk parameters text/event-stream (SSE)
POST /api/xray/analyze Synchronous X-Ray analysis application/json
POST /api/blood/analyze Synchronous Blood Lab analysis application/json
POST /api/cancer/analyze Synchronous Cancer Risk analysis application/json
GET /api/reports/{id} Retrieve saved clinical report by UUID application/json

⚡ SSE Event Payload Schema

When consuming streaming endpoints, the server emits named events:

// Event: "agent"
interface AgentEvent {
  agent_index: number;      // 0 to 6
  agent_name: string;       // e.g., "Differential Diagnostician"
  model: string;            // e.g., "openai/gpt-oss-120b"
  status: "running" | "complete" | "error";
  thought: string;          // Intermediate clinical rationale
  data?: Record<string, any>; // Partial agent outputs
  timestamp: string;
}

// Event: "complete"
interface CompleteEvent {
  report_id: string;
  report: ClinicalReport;
}

🩺 Diagnostic Suites Supported

1. 🫁 Chest Radiography Suite

  • Ingests image files (PNG/JPEG) or standard base64 payloads.
  • Evaluates opacity, consolidations, cardiomegaly, pleural effusions, pneumothorax, and pulmonary vascularity.

2. 🩸 Blood Hematology & Metabolic Suite

  • Accepts CBC, CMP, Lipid, Thyroid, and Cardiac biomarker inputs.
  • Automatically compares patient values against standardized reference boundaries:
Biomarker Reference Range Units Key Significance
Hemoglobin 12.0 - 17.5 g/dL Oxygen-carrying capacity, Anemia indicator
White Blood Cells (WBC) 4.5 - 11.0 x10^3/µL Infection & immune response
Platelets 150 - 450 x10^3/µL Hemostasis & clotting ability
Glucose (Fasting) 70 - 99 mg/dL Glycemic control & Metabolic health
Creatinine 0.6 - 1.2 mg/dL Renal clearance & kidney function
TSH 0.45 - 4.5 mIU/L Thyroid regulatory status

3. 🎗️ Multi-Organ Cancer Risk Suite

  • Stratifies clinical risk profiles across early warning indicators.
  • Correlates symptoms, risk factors, and tumor markers to guide targeted secondary screening.

🔬 Clinical Safety & Design Principles

[!IMPORTANT] Translucent AI over Black-Box Models BioScan does not issue automated diagnoses. It functions as an interactive clinical reasoning assistant. By exposing every step of the 6-agent thought chain in real-time, clinicians can inspect, verify, or question the underlying logic before making patient care decisions.

[!WARNING] Medical Disclaimer & Compliance Notice BioScan Intelligence is intended for research, demonstration, and clinical decision support purposes only. It does not constitute independent medical advice or diagnosis. All recommendations must be confirmed by a licensed medical practitioner.

🛠️ Verification & Build Commands

To verify project integrity before deployment:

# Check Python backend syntax
python -m py_compile backend/main.py backend/services/orchestration.py backend/services/blood.py

# Test frontend production build
npm run build

📜 License

Distributed under the MIT License. See LICENSE for more information.

Share this project:

Updates