Warning

This project is an active research prototype and is not production-ready. Features, APIs, and clinical data may change without notice. Do not use in live clinical environments without physician oversight and your own validation. See Section 2 — Clinical Responsibility Statement before use.

Sentra SideLab · Clinical AI Division ferdiiskandar.com

Sentra Artificial Intelligence SIDELAB — Sentra Laboratory for Clinical AI Research SideLab is the free Mini edition of Sentra's larger Clinical Decision Support System (CDSS) roadmap. It is released as a lightweight research and community-access prototype, not as the full production CDSS platform. SideLab helps frontline physicians reason more consistently, detect red flags earlier, retrieve local clinical references, and produce structured clinical decision-support output — while preserving physician responsibility as the final clinical authority.

---

Live Terminal Motion Preview

_{Demo: Clinician types symptoms in the terminal. SideLab surfaces red flags, differential diagnosis, working diagnosis, and initial management steps in structured format.}

This preview shows SideLab in practice: the clinician types a complaint, the system processes clinical context, then outputs differential diagnosis, working diagnosis, investigations, and initial recommendations in a structured, reviewable format.

---

Quick Start — Windows

git clone https://github.com/drcodie/sidelab.git
cd sidelab
copy .env.example .env

Open .env and fill in at least one API key — example for DeepSeek:

SIDELAB_DEFAULT_BACKEND=deepseek
DEEPSEEK_API_KEY=sk-...

Then run:

SIDELAB.bat

First-time setup runs automatically (Python, dependencies, Desktop shortcut). Run SIDELAB.bat again any time after that.

Ollama is not required when using a cloud backend (DeepSeek, OpenAI, NVIDIA, etc.). Ollama is only needed for offline-local mode (SIDELAB_DEFAULT_BACKEND=local).

---

1. What SideLab Is

SIDELAB (Sentra Laboratory for Clinical AI Research) is the free Mini edition of Sentra's broader Clinical Decision Support System (CDSS) initiative. It is provided as a lightweight, offline-first research prototype for Indonesian primary-care physicians working in FKTP / Puskesmas settings.

This repository does not represent the complete Sentra CDSS platform. It is a focused public/research build intended for learning, testing, demonstration, and community-oriented clinical-AI exploration.

It combines:

• local clinical retrieval,
• deterministic red-flag detection,
• Indonesian clinical reference anchors,
• FORNAS-aware pharmacotherapy guidance,
• local drug-stock awareness,
• ICD-10 Indonesia lookup,
• multi-backend LLM routing,
• and structured clinical output through the AUDREY Protocol v1.

The goal is not to replace clinicians. The goal is to make clinical reasoning more structured, safer, auditable, and locally usable.

---

2. Clinical Responsibility Statement

SideLab is a physician-assistive research prototype, not a physician and not an approved medical device.

All diagnostic conclusions, treatment suggestions, referral suggestions, drug recommendations, and risk assessments generated by SideLab are advisory. They must be reviewed by a licensed physician before any clinical action.

Principle	Meaning
Physician remains accountable	The attending physician is responsible for diagnosis, prescription, referral, and care decisions.
AI output must be reviewed	Model output may contain errors, omissions, outdated assumptions, or hallucinations.
Red flags are assistive	Emergency warnings support clinical vigilance; they do not replace examination or triage.
Input quality matters	SideLab cannot account for missing history, physical examination, labs, imaging, or local context not entered by the user.
No autonomous care	SideLab must not be used for unsupervised diagnosis, treatment, or patient-facing automation.

---

3. Operating Doctrine

SideLab is designed around one conservative clinical-AI doctrine:

Retrieve first.
Detect red flags early.
Structure the answer.
Show the boundary.
Let the physician decide.

Non-Negotiables

• No diagnosis without physician review.
• No emergency signal hidden behind LLM generation.
• No medication suggestion without formulary and stock context where available.
• No clinical output without structure.
• No patient-data transmission unless explicitly designed, approved, and governed.
• No production or medical-device claim without proper validation and regulatory pathway.

---

4. System Overview

Layer	Capability	Purpose
Clinical Intelligence Engine	RAG v4, semantic retrieval, certainty calibration	Builds structured clinical context from local references.
Red Flag Detector	Rule-based pre-LLM emergency scan	Surfaces time-sensitive risk before model generation.
AUDREY Protocol v1	Eight-section clinical response	Keeps output predictable, reviewable, and clinically useful.
Drug Stock Integration	FORNAS + local Puskesmas inventory	Reduces unavailable or inappropriate medication suggestions.
Multi-Backend Router	12 LLM providers	Supports offline, cloud, and fallback deployment modes.
Textual TUI v2	Rich terminal interface	Provides usable local UX without heavy infrastructure.
ICD-10 Indonesia Lookup	Local code search	Supports standardized diagnostic coding.
Session Management	Bounded consultation context	Preserves continuity while controlling prompt growth.
Telegram Notification	Consultation alert gateway	Enables asynchronous clinical collaboration.
CI/CD Pipeline	Black, isort, Ruff, pytest	Maintains quality gates and regression protection.

---

5. Architecture

CLINICAL QUERY
    │
    ▼
RED FLAG DETECTION                         ← deterministic, runs before LLM
    │   emergency pattern scan · unmistakable warning panel if triggered
    ▼
LOCAL RETRIEVAL                            ← hybrid scoring pipeline
    │   query profile extraction (tokenize · body-system hints · abbreviation expansion)
    │   TF-IDF + semantic vector scoring · top-3 disease candidates
    │   pharmacotherapy context (FORNAS 2023 · first/second line)
    │   drug stock lookup (local Puskesmas inventory · prefix matching)
    │   red flag context injection
    ▼
PROMPT AUGMENTATION
    │   clinical reference block + stock notes + patient data injected into prompt
    ▼
LLM STREAMING
    │   selected backend · AUDREY Protocol v1 system prompt
    ▼
SAFETY POST-PROCESSING
    │   pharma deduplication · minimum drug floor enforcement
    │   insufficient-data guard · diagnostic frame injection for red flags
    ▼
STRUCTURED CDSS OUTPUT
    │   differential · working diagnosis · investigation · management
    │   pharmacotherapy · patient education · referral · prognosis
    ▼
PHYSICIAN REVIEW

---

6. Core Technical Stack

Component	Technology	Role
Language	Python 3.12+	Core application and package modules.
Terminal UI	Rich + Textual	Panels, sidebar, rendering, and TUI interaction.
Data Layer	JSON flat files	Disease, drug, stock, mapping, vector, and clinical-chain data.
Retrieval	TF-IDF + semantic vectors	Local disease matching and reference context building.
LLM Runtime	Multi-backend router	Ollama, DeepSeek, OpenAI, NVIDIA, Kimi, Qwen, Zhipu, Yi, Baichuan, Ernie, Spark, Gemini.
Clinical Coding	ICD-10 Indonesia module	Local ICD lookup and REPL support.
Notifications	Telegram gateway	Structured consultation alerts.
Testing	pytest	Clinical, LLM, ICD, notification, installer, and regression tests.
CI/CD	GitHub Actions	Black, isort, Ruff, pytest on Python 3.12.

---

7. Project Structure

sidelab/
├── sidelab_tui.py                     # Main Textual TUI launcher
├── sidelab.py                         # Legacy clinical core during TUI migration
├── sidelab/                           # Python package modules
│   ├── intelligence.py                # RAG, chains, vectors, certainty
│   ├── tui.py                         # Textual TUI v2
│   ├── console_bridge.py              # Thread-safe RichLog bridge
│   ├── icd/                           # ICD-10 Indonesia lookup
│   ├── llm/                           # LLM provider router
│   └── notify/                        # Telegram notification sender
├── data/                              # Local clinical databases
│   ├── penyakit.json                  # KKI-classified diseases
│   ├── 144_penyakit_puskesmas.json    # Puskesmas diseases + FORNAS 2023
│   ├── clinical-chains.json           # Symptom-to-disease chains
│   ├── clinical-patches.json          # Edge-case clinical patches
│   ├── penyakit-vectors.json          # Semantic vectors
│   ├── stok_obat.json                 # Local drug inventory
│   ├── obat_data.json                 # Supplementary drug data
│   └── drug_mapping.json              # Generic-to-alias-to-stock mapping
├── tests/                             # pytest suite
├── sessions/                          # Saved consultation histories
├── installer/                         # Windows installer assets
├── build/ / dist/                     # Build artifacts
├── .github/workflows/                 # CI/CD workflows
├── SIDELAB.bat                        # Satu-satunya launcher — auto-setup + jalankan TUI
├── tools/
│   ├── diagnose.bat                   # Diagnostic tool
│   └── run_perf.bat                   # Performance test runner
└── requirements.txt                   # Runtime dependencies

---

8. Clinical Data Layer

SideLab uses local JSON references to support offline-first operation.

File	Purpose
penyakit.json	KKI-classified diseases with symptoms, signs, red flags, and management context.
144_penyakit_puskesmas.json	Common Puskesmas conditions with FORNAS 2023 pharmacotherapy references.
clinical-chains.json	Symptom-to-disease prediction chains.
clinical-patches.json	Clinical edge-case adjustments.
penyakit-vectors.json	Semantic disease vectors for fuzzy matching.
stok_obat.json	Local drug inventory: name, strength, quantity, unit.
drug_mapping.json	Generic name, alias, and local stock mapping.

Reference anchors include SKDI, PPK IDI, and FORNAS 2023.

---

9. Red Flag Detector

The red-flag layer runs before LLM inference. Its role is to detect high-risk clinical patterns deterministically so that emergency signals are not dependent only on probabilistic generation.

Representative conditions include:

Risk Pattern	Example Trigger Context	Severity
Bacterial meningitis	Fever + headache + neck stiffness / nuchal rigidity	Critical
Subarachnoid hemorrhage	Sudden severe headache	Critical
Stroke	Hemiplegia, aphasia, facial drooping	Critical
ACS / STEMI	Chest pain + cold sweat / dyspnea	Critical
Traumatic brain injury	Head trauma, loss of consciousness, amnesia	Emergent
Sepsis	High fever / rigors + tachycardia / hypotension	Critical
Aortic dissection	Tearing chest pain + blood-pressure discrepancy	Critical
Pulmonary embolism	Sudden dyspnea + pleuritic chest pain + DVT risk	Critical

Red-flag output must be interpreted by a physician and integrated with direct examination, vital signs, local protocol, and referral availability.

---

10. AUDREY Protocol v1

Every clinical response is constrained into eight sections:

#	Section	Purpose
1	Differential Diagnosis	At least three alternatives with reasoning and ICD-10 context where available.
2	Working Diagnosis	Primary diagnosis with justification.
3	Recommended Investigations	Suggested investigations and expected findings.
4	Management	Non-pharmacological and clinical management plan.
5	Pharmacotherapy	FORNAS-aware drug recommendations with dose, interaction, and contraindication context.
6	Patient Education	Patient and family education points.
7	Referral Criteria	Emergency, urgent, or elective referral threshold.
8	Prognosis	Outcome determinants and risk context.

Pharmacotherapy format:

[Drug Name]
Dose: [dose]; Route: [route]; Frequency: [freq]; Duration: [duration]
DDI: [drug interactions]
CI: [contraindications]
Stock: [available / limited / unavailable / unknown]

---

11. Installation

Requirements

Component	Minimum	Recommended
OS	Windows 10/11	Windows 11
Python	3.12+	3.12+
RAM	4 GB	8 GB+
Storage	10 GB	20 GB SSD
Local LLM	Ollama 0.4+	Ollama 0.5+
GPU	Optional	NVIDIA RTX 3060+

Standard Setup

REM 1. Clone repository
git clone https://github.com/drcodie/sidelab.git
cd sidelab

REM 2. Create configuration file
copy .env.example .env
REM   Open .env, set SIDELAB_DEFAULT_BACKEND and the API key for your chosen provider

REM 3. Run — first-time setup runs automatically
SIDELAB.bat

Ollama is only required for SIDELAB_DEFAULT_BACKEND=local (offline mode). For cloud backends (DeepSeek, OpenAI, NVIDIA, etc.), just fill in the matching API key.

Prebuilt Binary

REM Run installer if available
dist\SIDELAB-SETUP.exe

REM Or use the Desktop shortcut, or run directly:
SIDELAB.bat

---

12. Basic Usage

SIDELAB.bat

DOCTOR INPUT › Male 55yo, crushing chest pain radiating to left arm,
               cold sweat, dyspnea. Hypertension and DM. BP 160/90, HR 110.

Available commands:

Command	Description
/pasien nama=X umur=Y jk=L	Set active patient data (name, age, sex, allergies, comorbidities)
/provider	Switch LLM provider / model
/next	New case, reset session
/save	Save session to file
/copy	Copy last response to clipboard
/help	Show command list
/exit	Exit SIDELAB

Keyboard shortcuts:

Shortcut	Action
Ctrl+B	Select backend / model
Ctrl+N	New case
Ctrl+P	Set patient data
Ctrl+S	Save session
Ctrl+Y	Copy response to clipboard
Ctrl+Q	Quit

---

13. Quality Gates

Before claiming a change is complete, run the smallest meaningful verification set.

# Format and lint
black .
isort .
ruff check .

# Test collection
python -m pytest --co -q

# Full test suite
python -m pytest

Current reported test scope: 581 tests across clinical logic, retrieval, LLM routing, ICD lookup, notification, installer, and regression domains.

---

14. Validation Boundary

The original prototype dossier reports strong internal validation metrics, including red-flag sensitivity, specificity, diagnosis accuracy, FORNAS compliance, stock match rate, backend support, and user-satisfaction findings.

These figures must be treated as internal prototype validation unless accompanied by:

• published protocol,
• dataset description,
• sampling method,
• external evaluator description,
• prospective clinical setting,
• statistical analysis plan,
• and independent clinical review.

SideLab should therefore be presented as a research prototype, not a validated autonomous clinical system.

---

15. Known Limitations

Limitation	Risk	Current Mitigation
LLM hallucination	Incorrect or fabricated output	Retrieval context, structured prompt, physician review.
Incomplete clinical input	Wrong prioritization	Encourage structured case input and SOAP-style details.
Limited red-flag coverage	Rare emergencies may be missed	Expand deterministic rules and regression cases.
Local data staleness	Outdated treatment or stock context	Versioned updates and periodic review.
Prefix-based stock matching	False positives in drug matching	Improve normalization and fuzzy matching.
Backend variability	Inconsistent latency and response quality	Router, fallback, and backend-specific testing.
Monolithic legacy core	Maintenance difficulty	Continue modularization into package submodules.
No strict type checking	Type-related defects	Planned mypy/pyright adoption.

---

16. Roadmap

Near-Term Engineering

• Complete TUI-first extraction of sidelab.py into package modules.
• Add pre-commit hooks.
• Add pytest-cov coverage tracking.
• Add strict type checking with mypy or pyright.
• Improve drug normalization and stock matching.
• Strengthen red-flag regression tests.

Clinical Safety

• Expand red-flag rules for SAH, PE, aortic dissection, eclampsia, anaphylaxis, severe dehydration, and pediatric danger signs.
• Add structured uncertainty handling.
• Improve physician-review prompts.
• Define clinical governance protocol.

Deployment & Integration

• Improve Windows installer reliability.
• Add EHR / SIMRS integration pathway.
• Add real-time drug inventory API connection.
• Explore voice input through Whisper or VOSK.
• Prepare controlled field-trial workflow for Puskesmas settings.

---

17. Contributor & Agent Rules

SideLab should be modified conservatively.

Think before coding.
Do not assume silently.
Prefer the smallest safe change.
Preserve clinical safety boundaries.
Run relevant tests.
Document what changed and why.

Recommended workflow:

Read context → Identify risk → Propose plan → Make small change → Verify → Summarize handoff

When present, read these governance files before making non-trivial changes:

• AGENTS.md
• PLANS.md
• USER.md
• .agent/CONTEXT.md
• .agent/PROGRESS.md
• .agent/HANDOFF.md
• .agent/DECISIONS.md

---

18. References

Indonesian Clinical Standards

1. Konsil Kedokteran Indonesia — SKDI: Standar Kompetensi Dokter Indonesia.
2. Ikatan Dokter Indonesia — PPK IDI: Panduan Penyelenggaraan Pelayanan Kesehatan.
3. Kementerian Kesehatan Republik Indonesia — FORNAS 2023: Formularium Nasional.

Algorithms & AI

4. Manning, Raghavan & Schütze — Introduction to Information Retrieval.
5. Vaswani et al. — Attention Is All You Need.
6. Devlin et al. — BERT: Pre-training of Deep Bidirectional Transformers.

Clinical Decision Support

7. Musen et al. — Clinical Decision-Support Systems.
8. Shortliffe & Sepúlveda — Clinical Decision Support in the Era of Artificial Intelligence.
9. Kawamoto et al. — Improving Clinical Practice Using Clinical Decision Support Systems.

Tools

10. Ollama — Local LLM runtime.
11. Textualize Rich — Terminal formatting library.
12. Textualize Textual — Python TUI framework.
13. FAISS — Efficient similarity search.

---

Let's Connect

Station Stacks

---

❤️ for Alde, Aimee, Audrey & Del

From Indonesia, for a more equitable world of healthcare.
_{Offline. Trusted. Sovereign.}

ferdiiskandar.com