Metadata-Version: 2.4
Name: dt-forge
Version: 0.4.1
Summary: Domain-agnostic Python framework for digital twin architectures
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: paho-mqtt>=2.0
Requires-Dist: influxdb-client>=1.40
Requires-Dist: pymongo>=4.6
Requires-Dist: motor>=3.3
Requires-Dist: redis>=5.0
Requires-Dist: minio>=7.2
Requires-Dist: pydantic>=2.5
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: fastapi>=0.109
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: httpx>=0.26
Requires-Dist: sse-starlette>=2.0
Requires-Dist: scipy>=1.12
Requires-Dist: numpy>=1.26
Requires-Dist: simpy>=4.1
Requires-Dist: onnxruntime>=1.17
Requires-Dist: scikit-learn>=1.4
Requires-Dist: prophet>=1.1
Requires-Dist: transitions>=0.9
Requires-Dist: simple-pid>=2.0
Requires-Dist: neo4j>=5.17
Requires-Dist: vaderSentiment>=3.3
Requires-Dist: langchain>=0.3
Requires-Dist: langchain-classic>=0.1
Requires-Dist: langchain-community>=0.3
Requires-Dist: langchain-openai>=0.2
Requires-Dist: langchain-anthropic>=0.2
Requires-Dist: langchain-ollama>=0.2
Requires-Dist: stable-baselines3>=2.2
Requires-Dist: gymnasium>=0.29
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.1
Requires-Dist: pyserial>=3.5
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.2; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"

# 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

```bash
pip install -e .
```

### 2. Configure

```bash
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:

```bash
# 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):

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

Wait for all services to be ready:

```bash
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

```bash
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

```bash
python twin.py
```

Or via the CLI:

```bash
dtforge run twin
```

## Configuration

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

```bash
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

```bash
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
