README.md

metadata

title: BioOps Twin
emoji: ⚙️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: true
license: mit
short_description: AI Digital Twin for Lab Centrifuge Calibration

⚙️ BioOps Twin — AI-Powered Digital Twin for Laboratory Centrifuge Calibration

Enterprise-grade digital twin that uses Gemini 3.1 Pro to autonomously calibrate laboratory centrifuge hardware through natural language, real-time telemetry, and physics-based simulation — with full audit traceability and human-in-the-loop governance.

---

🎯 Problem Statement

Biochemical laboratories rely on centrifuges calibrated manually, a process that is:

• Error-prone — human operators misconfigure RPM/RCF parameters for sample weights
• Undocumented — calibration decisions lack audit trails for regulatory compliance (FDA 21 CFR Part 11, EU GMP Annex 11)
• Reactive — failures are detected after sample damage, not prevented proactively

BioOps Twin solves this by creating an AI copilot that reads calibration manuals, simulates centrifuge physics, and recommends safe parameters — all through a conversational interface.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                  Operator (Gradio Dashboard)             │
│  Chat Console │ Telemetry Plots │ 3D Model │ Audit Log  │
└──────┬────────────────┬─────────────────┬───────────────┘
       │                │                 │
       ▼                ▼                 ▼
┌─────────────┐ ┌──────────────┐ ┌────────────────┐
│ LLM Engine  │ │  Simulation  │ │ Industrial Edge│
│ Gemini 3.1  │ │   Core       │ │ MQTT Telemetry │
│ Pro + Tools │ │ Physics+FSM  │ │ Z-Score Anomaly│
└──────┬──────┘ └──────┬───────┘ └────────┬───────┘
       │                │                  │
       ▼                ▼                  ▼
┌─────────────┐ ┌──────────────┐ ┌────────────────┐
│ RAG Memory  │ │  Security    │ │  Audit Logger  │
│ ChromaDB    │ │  Sanitizer   │ │  JSONL Immut.  │
│ Hybrid BM25 │ │  Zero-PHI    │ │  FDA-ready     │
└─────────────┘ └──────────────┘ └────────────────┘

Modules

Module	Purpose
simulation_core/	Centrifuge physics engine (RPM → vibration → RCF), finite state machine, command pattern
llm_engine/	Gemini 3.1 Pro agent with structured function calling, Shadow Mode (HITL)
rag_memory/	Hybrid search (dense + BM25) with parent-child chunking on calibration manuals
industrial_edge/	MQTT telemetry publisher + statistical anomaly detection (Z-Score)
security/	Input sanitization (Zero-PHI), immutable JSONL audit logging
simulation_ui/	Gradio Blocks industrial dashboard with real-time plots and 3D viewer

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• (Optional) GEMINI_API_KEY for live AI mode — runs in MOCK mode without it

Installation

git clone https://github.com/maximolopezchenlo-lab/bioops-twin.git
cd bioops-twin
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run

python main.py

Open http://localhost:7860 in your browser.

Try These Commands

• "Set the centrifuge to 3000 RPM"
• "What is the maximum RPM for a 50g load?"
• "Stop" / "Reset"

---

🛡️ Enterprise Features

Shadow Mode (Human-in-the-Loop)

When enabled, all AI-generated commands are intercepted and require explicit operator approval before execution — critical for regulatory compliance.

Immutable Audit Trail

Every agent decision, operator command, and state transition is logged to an append-only JSONL file with ISO 8601 timestamps, source attribution, and severity levels.

MQTT Edge Connectivity

Real-time telemetry is published to a configurable MQTT broker (broker.hivemq.com for demo), enabling integration with industrial SCADA/HMI systems and external monitoring tools like MQTT Explorer.

Statistical Anomaly Detection

A rolling Z-Score algorithm (window = 20 ticks) continuously monitors vibration data. When Z > 3σ, the system triggers visual alerts and injects a SYSTEM_ALERT into the LLM context to force recalibration.

---

📁 Project Structure

bioops-twin/
├── main.py                    # Application entry point
├── app.py                     # Hugging Face Spaces entry point
├── requirements.txt
├── assets/
│   └── centrifuge_v3.glb      # 3D centrifuge model
├── data/
│   └── manuals/               # Calibration manual sources for RAG
├── bioops/
│   ├── simulation_core/       # Physics engine + FSM + commands
│   ├── llm_engine/            # Gemini agent + tools + prompts
│   ├── rag_memory/            # ChromaDB hybrid retrieval
│   ├── industrial_edge/       # MQTT + anomaly detection
│   ├── security/              # Audit logger + sanitizer
│   └── simulation_ui/         # Gradio dashboard + callbacks
└── docs/                      # Technical architecture papers

---

📖 Technical Documentation

Document	Description
Technical Architecture	System design, patterns, and component interactions
Gemini 3.1 Integration	LLM configuration, function calling, and prompt engineering
RAG Architecture	Hybrid search, parent-child chunking, and retrieval pipeline
Governance & Security	Veea Lobster Trap proxy, Zero-PHI, audit compliance

---

🔧 Environment Variables

Variable	Required	Description
GEMINI_API_KEY	No	Google Gemini API key. Without it, the agent runs in MOCK mode
MQTT_BROKER	No	MQTT broker host (default: broker.hivemq.com)
MQTT_PORT	No	MQTT broker port (default: 1883)

---

📜 License

This project was built for the lablab.ai Transforming Enterprise Through AI Hackathon (May 2026).

---

Built with ❤️ using Google Gemini 3.1 Pro · Veea Lobster Trap · Gradio