OpenThyroid v2.0.0 - OpenMedicine Platform

OpenThyroid is a comprehensive digital twin platform for thyroid endocrine simulation and visualization, built on the OpenMedicine Platform. It provides real-time simulation of the Hypothalamic-Pituitary-Thyroid (HPT) axis, 3D anatomical visualization, AI agent-assisted treatment planning, and comprehensive telemetry monitoring.

Features

Endocrine Simulation

• HPT Axis Modeling: Complete simulation of thyroid hormone regulation
• Pharmacology Engine: Medication absorption, distribution, and effects
• Binding Protein Dynamics: Thyroid hormone binding and transport
• Real-time Simulation: Continuous endocrine state updates

AI Agent System

• Treatment Planning: AI-assisted scenario planning and execution
• Clinical Decision Support: Evidence-based treatment recommendations
• Outcome Prediction: Simulation-based treatment outcome forecasting
• Multi-step Execution: Complex treatment protocol automation

3D Visualization

• Anatomical Models: High-fidelity thyroid 3D representations
• GLTF 2.0 Support: Industry-standard 3D model format
• Interactive Scenes: Three.js-powered 3D visualization
• Model Variants: Healthy, diseased, and treatment state models

Real-time Telemetry

• Live Monitoring: Continuous endocrine state streaming
• WebSocket Integration: Real-time frontend updates
• Historical Data: Comprehensive telemetry history
• Performance Metrics: System and simulation performance tracking

Enterprise Features

• Prometheus Metrics: Production-ready observability
• Docker Deployment: Containerized deployment support
• Native Deployment: Direct system installation
• Backup & Recovery: Automated backup and restoration
• Health Monitoring: Comprehensive system health checks

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │   Deployment    │
│   (React +      │◄──►│   (FastAPI +    │◄──►│   (Docker +     │
│   Three.js)     │    │   Pydantic)     │    │   Compose)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  3D Scene       │    │  Simulation     │    │  Monitoring     │
│  Components     │    │  Models         │    │  & Metrics      │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• Git

Development Setup

# Clone repository
git clone https://github.com/openthyroid/openthyroid.git
cd openthyroid

# Setup development environment
./scripts/ob.sh setup

# Start development servers
./scripts/ob.sh dev

Production Deployment

Docker Compose (Recommended)

# Deploy with Docker
./scripts/ob.sh deploy

# Check status
./scripts/ob.sh status

Native Deployment

# Setup production environment
./scripts/bootstrap-native.sh setup

# Start services
./scripts/bootstrap-native.sh start

API Documentation

Once running, access the interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI Spec: http://localhost:8000/openapi.json

Core Components

Backend Models

HPT Axis Simulation

from app.models.hpt_axis import HPTAxis

# Create HPT axis simulation
hpt = HPTAxis()
state = hpt.initialize_state()
result = hpt.step(state, duration_hours=1)

Pharmacology Engine

from app.models.pharmacology import PharmacologyModel

# Model medication effects
pharm = PharmacologyModel()
effects = pharm.calculate_medication_effects(
    medication="levothyroxine",
    dose_mcg=100,
    frequency="daily"
)

Binding Protein Dynamics

from app.models.binding import BindingModel

# Calculate hormone binding
binding = BindingModel()
free_fraction = binding.calculate_free_fraction(
    total_t4=120,
    binding_proteins={"TBG": 1.2, "TTR": 0.8}
)

Frontend Components

3D Thyroid Scene

import { ThyroidScene } from './components/ThyroidScene';

function App() {
  return (
    <div className="thyroid-scene">
      <ThyroidScene 
        modelVariant="healthy"
        enableInteractions={true}
        showLabels={true}
      />
    </div>
  );
}

Telemetry Panel

import { TelemetryPanel } from './components/TelemetryPanel';

function App() {
  return (
    <TelemetryPanel 
      updateInterval={1000}
      showHistory={true}
      enableAlerts={true}
    />
  );
}

Configuration

Environment Variables

Create a .env file in the project root:

# OpenAI Configuration
OPENAI_API_KEY=<your-openai-api-key>
OPENAI_BASE_URL=https://api.openai.com/v1

# Simulation Parameters
SIMULATION_DURATION_DAYS=30
SIMULATION_STEP_HOURS=1
ENABLE_REAL_TIME_TELEMETRY=true

# Hormone Bounds
TSH_MIN=0.4
TSH_MAX=4.0
FT4_MIN=0.8
FT4_MAX=1.8

Simulation Parameters

The system supports extensive customization of endocrine simulation parameters:

• Hormone Ranges: Physiological bounds for TSH, FT4, FT3
• Dosing Limits: Maximum safe medication doses
• Physiological Constants: Body weight, surface area, blood volume
• Telemetry Settings: Update frequency, history retention

Development

Project Structure

openthyroid/
├── backend/                 # Python FastAPI backend
│   ├── app/
│   │   ├── models/         # Simulation models
│   │   ├── schemas/        # Pydantic schemas
│   │   ├── services/       # Business logic
│   │   └── agents.py       # AI agent system
│   ├── tests/              # Backend tests
│   └── requirements.txt     # Python dependencies
├── web/                    # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── stores/         # Zustand state management
│   │   └── hooks/          # Custom React hooks
│   ├── package.json        # Node.js dependencies
│   └── vite.config.ts      # Vite configuration
├── deploy/                 # Deployment configuration
│   ├── compose.yml         # Docker Compose
│   ├── prometheus.yml      # Prometheus config
│   └── litellm.config.yaml # LiteLLM configuration
├── scripts/                # Management scripts
│   ├── ob.sh              # Main bootstrap script
│   └── bootstrap-native.sh # Native deployment
├── ops/                    # Operations scripts
│   └── backup.sh          # Backup and restore
└── docs/                   # Documentation
    └── PRODUCTION.md       # Production guide

Running Tests

# Backend tests
cd backend
source venv/bin/activate
python -m pytest tests/ -v

# Frontend tests
cd web
npm run test

Code Quality

The project follows strict coding standards:

• Python: Black formatting, flake8 linting, mypy type checking
• TypeScript: ESLint, Prettier, strict type checking
• Testing: Comprehensive unit and integration tests
• Documentation: Inline code documentation and API specs

Deployment

Docker Compose

The recommended deployment method uses Docker Compose:

services:
  api:
    build: ../backend
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
  
  web:
    build: ../web
    ports:
      - "5173:80"
    depends_on:
      - api

Native Deployment

For production environments without Docker:

# Setup system services
sudo ./scripts/bootstrap-native.sh setup

# Start services
sudo ./scripts/bootstrap-native.sh start

# Check status
./scripts/bootstrap-native.sh status

Monitoring

Prometheus Metrics

The system exposes comprehensive metrics at /metrics:

• Request Metrics: Count, duration, status codes
• Simulation Metrics: Runs, errors, performance
• WebSocket Metrics: Connections, messages
• System Metrics: Memory, CPU, disk usage

Health Checks

# Check system health
./scripts/ob.sh status

# Check specific services
curl http://localhost:8000/healthz
curl http://localhost:8000/metrics

Backup and Recovery

Automated Backups

# Create backup
./ops/backup.sh backup

# List backups
./ops/backup.sh list

# Restore backup
./ops/backup.sh restore backup_file.tar.gz

Backup Schedule

• Full backup: Daily at 2:00 AM
• Configuration backup: Weekly
• Database backup: Every 4 hours
• Retention: 30 days for daily, 90 days for weekly

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/<short-feature-name>)
3. Commit your changes (git commit -m 'feat: add <short-feature-description>')
4. Push to the branch (git push origin feature/<short-feature-name>)
5. Open a Pull Request with context and test evidence

Development Guidelines

• Follow established code style and conventions
• Add comprehensive tests for new functionality
• Update documentation for API changes
• Ensure all tests and builds pass before submitting PRs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Documentation

• API Docs: http://localhost:8000/docs (when running)
• Production Guide: docs/PRODUCTION.md
• Code Documentation: See inline comments

Getting Help

• GitHub Issues: https://github.com/openthyroid/openthyroid/issues
• Discussions: https://github.com/openthyroid/openthyroid/discussions
• Documentation: https://github.com/openthyroid/openthyroid/wiki

Acknowledgments

• OpenMedicine Platform: Foundation for medical AI systems
• FastAPI: High-performance Python web framework
• React + Three.js: Modern frontend and 3D visualization
• Pydantic: Data validation and settings management
• Prometheus: Metrics collection and monitoring

Roadmap

v2.1.0

• Enhanced agent tools and planning UX
• Expanded 3D model variants and educational overlays
• Collaboration primitives for session sharing
• Responsive layout refinements

v2.2.0

• Multi-patient simulation management
• Advanced analytics dashboard and reporting
• EMR integration adapters (read-only)
• Clinical decision support API (pilot)

v3.0.0

• Multi-organ endocrine simulations
• Advanced AI reasoning chains
• Privacy-preserving learning support
• Enterprise security enhancements

Author: Nik Jois
Version: 2.0.0
Platform: OpenMedicine Platform
License: MIT

For more information, visit OpenMedicine Platform.