dt-forge 0.4.1

Domain-agnostic Python framework for digital twin architectures

DT-Forge

A domain-agnostic Python framework for building digital twins of any physical asset.

DT-Forge implements a six-layer Digital Twin architecture — Data, Simulation & Model, Services, Reactive, Intelligent, and Autonomous — along with a Connector subsystem for inter-twin communication and four collection-twin patterns.

Architecture

┌─────────────────────────────────────────────┐
│              AUTONOMOUS LAYER               │
│  OODA loop · Goal planner · RL policies     │
├─────────────────────────────────────────────┤
│          INTELLIGENT LAYER (MAS)            │
│  LangChain agents · Neo4j knowledge graph   │
├─────────────────────────────────────────────┤
│              REACTIVE LAYER                 │
│  Threshold FSM · PID controllers            │
├─────────────────────────────────────────────┤
│              SERVICES LAYER                 │
│  Eclipse Ditto sync · FastAPI REST/SSE      │
├─────────────────────────────────────────────┤
│         SIMULATION & MODEL LAYER            │
│  ODE · ONNX surrogate · SimPy · Prophet     │
├─────────────────────────────────────────────┤
│               DATA LAYER                    │
│  InfluxDB · MongoDB · Redis · MinIO         │
├─────────────────────────────────────────────┤
│            DT NETWORK LAYER                 │
│  MQTT ingestion · Pydantic validation       │
└─────────────────────────────────────────────┘

Collection patterns

Pattern	Use case
AggregateDT	Fleet of identical assets — fused state, shared control
CollectionDT	Batch monitoring, outlier detection, statistical comparison
CompositeDT	Hierarchical systems with boundary condition exchange
NetworkDT	Graph-topology systems, cascade risk, bottleneck detection

Quick start

1. Install

pip install -e .

2. Configure

cp .env.example .env   # then edit .env with your asset ID, LLM key, etc.

3. Start infrastructure

Generate a docker-compose.yml for the layers you need and bring them up in a single step:

# Minimal (data + MQTT + Ditto):
dtforge infra up --layers data,network,services

# Full stack (adds Neo4j for the intelligent layer):
dtforge infra up --layers data,network,services,intelligent

dtforge infra up writes the compose file and runs docker compose up -d. Pass --generate-only if you only want the file written (e.g. to commit it):

dtforge infra up --layers data,network,services --generate-only
docker compose up -d

Wait for all services to be ready:

dtforge infra check --layers data,network,services,intelligent

Every service shows ✓ when the twin can connect to it.

What gets started:

Service	Port	Purpose
Mosquitto	1883	MQTT message broker
InfluxDB	8086	Time-series sensor readings
MongoDB	27017	Events, audit log
Redis	6379	Session cache, FSM state
MinIO	9000	Trained models, file objects
Eclipse Ditto	8080	Canonical twin state
Neo4j	7687	Knowledge graph (intelligent layer)
Grafana	3000	Observability dashboard (optional)

Pre-built implementations (e.g. implementations/sdt/) ship with a ready-made docker-compose.yml tuned for their specific configuration. Use that instead of generating one from scratch.

4. Scaffold a new twin

dtforge init --asset-type centrifugal_pump --name "Plant A Pump" --asset-id pump_001

This creates:

• twin.py — twin class scaffold (edit build_layers() to wire your logic)
• .env — environment configuration

5. Run

python twin.py

Or via the CLI:

dtforge run twin

Configuration

All settings are driven by environment variables with the DT_ prefix.
Nested fields use double-underscore as a delimiter:

DT_ASSET_ID=pump_001
DT_MQTT__BROKER=192.168.1.10
DT_INFLUX__TOKEN=my-token
DT_LLM__PROVIDER=anthropic
DT_LLM__MODEL=claude-sonnet-4-6
DT_LLM__API_KEY=sk-ant-...

See .env.example for a full reference.

Extending the framework

Extension point	Mechanism
New storage backend	Implement TimeSeriesStore / DocumentStore protocol
New physics model	Subclass ODEModel or implement TwinModel protocol
New ML surrogate	Implement TwinModel with ONNX/sklearn
Custom reactive rule	Implement Rule protocol
New agent	Implement TwinAgent protocol
New LLM provider	Swap build_llm() in intelligent/agent.py
Custom connector	Implement ConnectorProtocol
New collection pattern	Subclass AbstractCollectionTwin
Custom RL reward	Pass reward_fn to GenericTwinEnv

Technology stack

Concern	Technology
Messaging	Eclipse Mosquitto / paho-mqtt
Time-series	InfluxDB 2
Documents	MongoDB
Cache / pub-sub	Redis
Object storage	MinIO
Twin state	Eclipse Ditto
Knowledge graph	Neo4j
Agents	LangChain + OpenAI / Anthropic / Ollama
RL	Stable-Baselines3 + Gymnasium
API	FastAPI + Uvicorn
Validation	Pydantic v2
State machine	transitions
PID control	simple-pid
Physics solver	SciPy (solve_ivp)
Discrete event	SimPy
Forecasting	Prophet

CLI reference

dtforge init        # scaffold a new twin project
dtforge infra up    # generate docker-compose.yml
dtforge infra check # check infrastructure readiness
dtforge run         # run the twin
dtforge train       # train an RL policy

License

MIT