Metadata-Version: 2.4
Name: dyon
Version: 0.9.0
Summary: Domain-agnostic Python framework for digital twin architectures
Author-email: the Dyon authors <galisamuel97@gmail.com>
License: # PolyForm Noncommercial License 1.0.0
        
        <https://polyformproject.org/licenses/noncommercial/1.0.0>
        
        Required Notice: Copyright © 2026 the Dyon authors
        
        ## Acceptance
        
        In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
        
        ## Copyright License
        
        The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
        
        ## Distribution License
        
        The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
        
        ## Notices
        
        You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
        
        > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
        
        ## Changes and New Works License
        
        The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
        
        ## Patent License
        
        The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
        
        ## Noncommercial Purposes
        
        Any noncommercial purpose is a permitted purpose.
        
        ## Personal Uses
        
        Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
        
        ## Noncommercial Organizations
        
        Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
        
        ## Fair Use
        
        You may have "fair use" rights for the software under the law. These terms do not limit them.
        
        ## No Other Rights
        
        These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
        
        ## Patent Defense
        
        If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
        
        ## Violations
        
        The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
        
        ## No Liability
        
        ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
        
        ## Definitions
        
        The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
        
        **You** refers to the individual or entity agreeing to these terms.
        
        **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
        
        **Your licenses** are all the licenses granted to you for the software under these terms.
        
        **Use** means anything you do with the software requiring one of your licenses.
        
        ---
        
        ## Commercial licensing
        
        *The section below is informational and is not part of the PolyForm Noncommercial
        License 1.0.0 reproduced above.*
        
        The license above permits **noncommercial use only**. Any commercial use — use in
        or for the benefit of a for-profit business, or any use with an anticipated
        commercial application — requires a separate commercial license.
        
        To obtain a commercial license, contact **galisamuel97@gmail.com**.
        
Project-URL: Homepage, https://github.com/lazy-monster/dyon
Project-URL: Repository, https://github.com/lazy-monster/dyon
Project-URL: Documentation, https://github.com/lazy-monster/dyon/tree/master/guide
Project-URL: Issues, https://github.com/lazy-monster/dyon/issues
Keywords: digital-twin,iot,simulation,mqtt,reinforcement-learning,telemetry,autonomous-systems
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paho-mqtt>=2.0
Requires-Dist: influxdb-client>=1.40
Requires-Dist: pymongo>=4.6
Requires-Dist: redis>=5.0
Requires-Dist: minio>=7.2
Requires-Dist: asyncpg>=0.29
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: 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.3,>=2.2
Requires-Dist: gymnasium<0.30,>=0.29
Requires-Dist: imitation<2.0,>=1.0
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"
Provides-Extra: viz
Provides-Extra: forecast
Requires-Dist: prophet>=1.1; extra == "forecast"
Provides-Extra: voice
Requires-Dist: faster-whisper>=1.0; extra == "voice"
Provides-Extra: 3d
Dynamic: license-file

# Dyon

> **Build domain-agnostic digital twins in Python — from raw sensor data to autonomous decision-making.**

[![PyPI version](https://img.shields.io/pypi/v/dyon.svg)](https://pypi.org/project/dyon/)
[![Python versions](https://img.shields.io/pypi/pyversions/dyon.svg)](https://pypi.org/project/dyon/)
[![License: PolyForm Noncommercial 1.0.0](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-orange.svg)](LICENSE)
[![Commercial license available](https://img.shields.io/badge/commercial%20license-available-brightgreen.svg)](mailto:galisamuel97@gmail.com)

Dyon is a domain-agnostic Python framework for building **digital twins** —
live software models of a real-world asset that ingest its sensor data, store and
model it, react to it, reason about it, and act on it. The same framework works
for a pump, a patch of soil, a plant, an HVAC unit, or a manufacturing line,
because nothing in the core knows anything about your domain. You declare what
your asset's sensors look like, write a small amount of asset-specific glue, and
the framework supplies the rest.

You switch on only the capabilities your asset needs — a monitoring-only twin can
be a few lines, and the same twin can grow into a self-managing one without a
rewrite.

## Contents

- [What you can do](#what-you-can-do)
- [The dashboard](#the-dashboard)
- [Installation](#installation)
- [Quick start](#quick-start)
- [CLI reference](#cli-reference)
- [Learn more](#learn-more)
- [License](#license)

## What you can do

With Dyon you can:

- **Ingest live telemetry** off an MQTT broker and store it — time-series,
  documents, cache, and large objects — with an audit trail, no plumbing to write.
- **Clean and score** incoming readings automatically: smoothing, validation, and
  a rolling asset-health score.
- **Model and forecast** the asset — fit a physics model, an ML surrogate, or a
  time-series forecast, and detect drift against it.
- **React without a human in the loop** — thresholds, state machines, and
  closed-loop control that turn readings into actions.
- **Diagnose faults in plain language** — LLM agents that explain *why* something
  is wrong, with a knowledge graph behind them.
- **Act autonomously** — goal-driven decisions, learned control policies, and
  escalation to a person when it matters.
- **Teach a twin by example** — learn a behaviour from demonstrations when it's
  too hard to write down as a rule or reward.
- **Serve and visualise** — a REST + streaming API and an opt-in live dashboard
  (see below).

Each of these is optional and independent: you assemble only what your asset
needs, and you never edit the framework to do it.

## The dashboard

Dyon ships an opt-in, in-browser **dashboard** — the human-facing end of a twin.
It's built from the config you already wrote: pass one flag and you get a modern
app shell whose Home tab foregrounds the asset, a Telemetry tab of KPI tiles,
trend charts, an alarm banner and event log, and an Agents tab that shows the
multi-agent system working — all updating in real time, with nothing more to
author.

```python
app = create_app(config, registry, include_viz=True)   # off by default
```

It reads the same sensor definitions you already declared, streams live updates
to the browser, and wires a chat panel to the twin's diagnostic agent — which can
answer with a chart it draws on the fly (mirrored onto a live agent canvas), or
with speech. For assets you have a 3D model of, a viewport shows the model and
recolours it as the asset's state changes; it checks the viewer's hardware first
and falls back to a 2D schematic where the compute isn't there, so the capability
is available to those who can run it and never a barrier to those who can't. And
when twins combine — a fleet, a composite, a network — one federated dashboard
views them together, drilling into each member's own full view. The client needs
no front-end build step. Chapter 13 of the guide covers it end to end;
`dyon dashboard --api <url>` serves it against a running twin.

## Installation

Dyon requires **Python 3.11+**. The backing services (MQTT broker, databases, and
the optional twin-state and knowledge-graph stores) run in Docker, so you also
need Docker with the Compose plugin.

```bash
pip install dyon
```

That installs the framework and the `dyon` command-line tool. Two optional
dashboard backends install as extras when you want them — `pip install
dyon[forecast]` for the forecasting chart and agent tool, and `pip install
dyon[voice]` for server-side speech (the dashboard otherwise uses the browser's
own voice support). The dashboard itself needs neither.

### Coming from `dt-forge`?

This framework was previously published as **`dt-forge`** (package `dt_forge`,
command `dtforge`). It is now **Dyon**, and existing projects keep working with no
changes: `import dt_forge` and `from dt_forge.… import …` transparently resolve to
`dyon`, and the `dtforge` command still runs. You will see a one-time
`DeprecationWarning` pointing you at the new name. To migrate, replace `dt_forge`
with `dyon` in your imports and `dtforge` with `dyon` on the command line. The
compatibility shim will be removed in a future major release.

## Quick start

### 1. Configure

All configuration comes from environment variables with the `DT_` prefix.
Nested fields use a **double-underscore** delimiter — `DT_MQTT__BROKER`, not
`DT_MQTT_BROKER` (the single-underscore form is silently ignored). Put them in a
`.env` file in your project directory:

```bash
DT_ASSET_ID=pump_001
DT_ASSET_TYPE=centrifugal_pump
DT_ASSET_NAME="Plant A Pump"

DT_MQTT__BROKER=localhost
DT_MQTT__PORT=1883

DT_INFLUX__URL=http://localhost:8086
DT_INFLUX__TOKEN=my-super-secret-token
DT_INFLUX__ORG=digital_twin
DT_INFLUX__BUCKET=asset_telemetry

DT_MONGO__URI=mongodb://admin:password@localhost:27017
DT_REDIS__URL=redis://localhost:6379
DT_DITTO__URL=http://localhost:8080

# Optional — only if you use the LLM diagnostic agent
DT_LLM__PROVIDER=anthropic        # openai | anthropic | ollama
DT_LLM__MODEL=claude-sonnet-4-6
DT_LLM__API_KEY=sk-ant-...
DT_NEO4J__URI=bolt://localhost:7687
```

Every field has a sensible default, so you only set what differs from the defaults.

### 2. Start the infrastructure you need

`dyon infra up` writes a `docker-compose.yml` with exactly the services your twin
needs, then runs `docker compose up -d`:

```bash
# Minimal monitoring twin (MQTT broker + the four data stores):
dyon infra up --layers data,network

# Add the twin-state service and the knowledge graph:
dyon infra up --layers data,network,services,intelligent

# Write the compose file without starting anything:
dyon infra up --layers data,network,services --generate-only
docker compose up -d
```

The command records your selection in a `.dyon-layers` file. Once the containers
are up, verify the twin can reach each one:

```bash
dyon infra check          # reads .dyon-layers automatically
```

Every reachable service prints a `✓`.

### 3. Scaffold a twin

```bash
dyon init \
  --asset-type centrifugal_pump \
  --name "Plant A Pump" \
  --asset-id pump_001
```

That writes two files into the output directory:

| File      | Purpose                                                        |
|-----------|----------------------------------------------------------------|
| `twin.py` | A runnable twin — fill in your sensor fields and run it         |
| `.env`    | Environment configuration, pre-filled with the defaults        |

The generated `twin.py` runs as soon as you fill in your sensor fields, ingesting
telemetry, storing it, scoring health, and raising warning/critical events
automatically. Add modelling, diagnosis, and autonomy as your twin grows.

### 4. Run

```bash
python twin.py            # run the module directly
# or, from the project directory:
dyon run twin          # imports twin.py and drives its lifecycle
```

If you enabled the API, the FastAPI app serves these endpoints:

| Endpoint                     | Returns                                            |
|------------------------------|----------------------------------------------------|
| `GET  /health`               | Liveness — `{asset_id, status}`                    |
| `GET  /api/twin/state`       | Current twin state                                 |
| `GET  /api/twin/telemetry`   | Latest telemetry                                   |
| `GET  /api/twin/health-score`| Current health score                               |
| `GET  /api/twin/events`      | Recent events                                      |
| `POST /api/chat`             | Streamed replies from the LLM diagnostic agent     |

Point a real device (or the bundled simulator) at the twin's telemetry topic and
it starts working immediately.

## CLI reference

```bash
dyon init        --asset-type TYPE --name NAME --asset-id ID [--out DIR]
dyon infra up    --layers ... [--out FILE] [--generate-only]
dyon infra check [--layers ...]              # default: read .dyon-layers
dyon run         [TWIN_MODULE]               # default module: "twin"
dyon train       [--algorithm SAC|TD3|PPO|A2C] [--timesteps N]
                    [--env-module M] [--save NAME]
dyon dashboard   [--api URL] [--port N] [--open/--no-open]   # serve the dashboard
```

Run any command with `--help` for the full flag list.

## Learn more

The `guide/` folder in the source repository is the complete developer manual,
taking you from your first twin to a full worked example and a live dashboard.

## License

Dyon is dual-licensed.

- **Noncommercial use is free** under the
  [PolyForm Noncommercial License 1.0.0](LICENSE). This covers personal projects,
  academic research, teaching, evaluation, and use by nonprofit and government
  organisations. The full terms — including what counts as a permitted purpose —
  are in the [`LICENSE`](LICENSE) file.
- **Commercial use requires a separate commercial license.** Any use in or for
  the benefit of a for-profit business, or any use with an anticipated commercial
  application, needs a paid license. To arrange one, contact
  **[galisamuel97@gmail.com](mailto:galisamuel97@gmail.com)**.

PolyForm Noncommercial is a *source-available* license, not an OSI-approved
open-source license: the source is published and free to read, modify, and use
for noncommercial purposes, but commercial rights are reserved.
