ol-simulator-interop-services

The canonical domain model and adapter contract layer for the Thermodynamics Agent Service architecture. Defines the types, protocols, and registries that every simulator backend (DWSIM, Rust thermo kernel, HYSYS, UniSim, ...) implements against. Licensed under AGPL-3.0-or-later.

This package is pure Python, backend-agnostic, and cross-platform. It's the port in a hexagonal (ports-and-adapters) architecture; simulator-specific implementations are the adapters.

Install

pip install ol-simulator-interop-services

Python 3.11+ only. The sole runtime dependency is pydantic>=2.0,<3.0.

Role in the architecture

This repository is the middle layer:

LLM agent / MCP client
        |
        v
+--[ ol_thermodynamics_agent_services ]--+
|   MCP tools, routing, provenance       |
+----------------------------------------+
        |
        v  (in-process Python call)
+--[ ol_simulator_interop_services ]-----+   <-- this repo
|   canonical domain model + protocol    |
+----------------------------------------+
        |
   +----+----+----------+---------+
   v         v          v         v
 [Rust]   [DWSIM]   [HYSYS]   [UniSim]
 kernel   adapter   adapter    adapter

Backend-agnostic by design. No simulator's types leak above this boundary — a request arrives as a canonical FlashProblem, is dispatched to whichever adapter is registered, and returns a canonical FlashResult.

Responsibilities

• Canonical domain model — architectural type commitments that all layers depend on (table below).
• SimulatorAdapter protocol — the Python Protocol every simulator adapter must implement. Canonical methods: flash, get_properties, phase_envelope, list_property_packages, list_components, introspect_property_package.
• Component registry — CAS-keyed canonical component identity with per-backend alias tables (InMemoryComponentRegistry).
• Parameter-source registry — tracking of each backend's parameter databank and its revision (InMemoryParameterSourceRegistry).
• Property-package registry — model + parameter-source + revision triples (InMemoryPropertyPackageRegistry).
• Error ontology — uniform exception types across all backends (AdapterCapabilityError, ComponentNotFoundError, etc.).

Canonical domain model

CanonicalComponent and PropertyPackageSpec follow the BIE identity pattern: canonical identity surfaces above, per-backend projections and parameter-source governance below.

Communication boundaries

Development

Setup

git clone https://github.com/OntoLedgy/ol_simulator_interop_services.git
cd ol_simulator_interop_services
uv sync

Tests + lint + types

uv run pytest          # 22 tests
uv run ruff check .
uv run mypy

CI (see .github/workflows/ci.yml) runs all three on push/PR to main across Python 3.11 and 3.12.

Release

Releases publish to PyPI via OIDC trusted publishing — no token secrets in this repo. To cut a release:

1. Bump project.version in pyproject.toml (committed).
2. Tag vX.Y.Z matching that version.
3. Push the tag. The release.yml workflow builds sdist + wheel, publishes to PyPI, and creates a GitHub Release with both artifacts.

Related repositories

License

Dual-licensed:

1. Open source — AGPL-3.0-or-later. See LICENSE for the full text and NOTICE for attribution.
2. Commercial — a separate proprietary license is available from OntoLedgy Ltd. for embedding, proprietary SimulatorAdapter implementations, or other use cases that don't fit AGPL terms. See COMMERCIAL.md.

Copyright (c) 2018-2026 OntoLedgy Ltd.

Although this package is a library rather than a networked service, downstream services that consume it (e.g. ol-dwsim-mcp-server) are network-reachable, and AGPL §13 obligations propagate when those services are hosted. Using this package under the AGPL option means accepting the same AGPL terms across the dependency chain.