physlink 0.1.2__tar.gz

physlink-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Hamon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

physlink-0.1.2/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: physlink
+Version: 0.1.2
+Summary: Backend-agnostic adapter library for physical simulation ML
+License: MIT
+Project-URL: Homepage, https://Denis-hamon.github.io/physlink/
+Project-URL: Documentation, https://Denis-hamon.github.io/physlink/
+Project-URL: Repository, https://github.com/Denis-hamon/physlink
+Project-URL: Bug Tracker, https://github.com/Denis-hamon/physlink/issues
+Project-URL: Changelog, https://github.com/Denis-hamon/physlink/blob/main/CHANGELOG.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: rich>=13.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: safetensors>=0.4
+Requires-Dist: Pillow>=9.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.9; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: torch; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
+Requires-Dist: mike>=2.1; extra == "docs"
+Provides-Extra: notebook
+Requires-Dist: nbconvert>=7.0; extra == "notebook"
+Requires-Dist: nbformat>=5.9; extra == "notebook"
+Dynamic: license-file
+
+# PhysLink
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Denis-hamon/physlink/actions/workflows/ci.yml/badge.svg)](https://github.com/Denis-hamon/physlink/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://Denis-hamon.github.io/physlink/)
+[![PyPI](https://img.shields.io/pypi/v/physlink.svg)](https://pypi.org/project/physlink/)
+[![Python](https://img.shields.io/pypi/pyversions/physlink.svg)](https://pypi.org/project/physlink/)
+[![arXiv](https://img.shields.io/badge/arXiv-coming%20soon-b31b1b.svg)](https://arxiv.org/abs/PLACEHOLDER)
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Denis-hamon/physlink/blob/main/notebooks/quickstart.ipynb)
+
+<p align="center">
+  <a href="https://colab.research.google.com/github/Denis-hamon/physlink/blob/main/notebooks/quickstart.ipynb"><strong>Quick Start →</strong></a>
+  &nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="https://Denis-hamon.github.io/physlink/lab-adoption-guide/"><strong>Evaluate for your lab →</strong></a>
+  &nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="https://Denis-hamon.github.io/physlink/domain-scientists/"><strong>For Domain Scientists →</strong></a>
+</p>
+
+---
+
+**PhysLink bridges physical simulators and deep RL adapters in one `pip install`.**
+
+Plug your robot trajectories into [DreamerV3](https://github.com/danijar/dreamerv3) (and future backends) without writing boilerplate space definitions, checkpoint logic, or compliance checks. PhysLink handles the plumbing — you keep the science.
+
+## Why PhysLink
+
+| Without PhysLink | With PhysLink |
+|-----------------|---------------|
+| Hand-write observation/action space mappings per framework | `ObservationSpace.from_proprioception(joints=7)` |
+| Debug silent OOM on Colab at step 8 000 | `physlink.doctor()` catches it before you start |
+| Lose 3h of T4 training on session disconnect | Auto-checkpoint every N steps, resume on reconnect |
+| Manually verify energy conservation after adaptation | `register_invariant` + `compliance_report()` |
+| Stare at loss curves to diagnose model drift | Triptych GIF — Imagination / Real / Difference in one call |
+
+## Install
+
+```bash
+pip install physlink
+```
+
+Works on Google Colab out of the box. No CUDA required for diagnostics and space definitions.
+
+## Quick example
+
+```python
+import physlink
+
+# 1. Verify your environment (< 15 s)
+physlink.doctor()
+
+# 2. Define spaces from your robot config
+obs = physlink.ObservationSpace.from_proprioception(joints=7, include_velocity=True)
+act = physlink.ActionSpace.continuous(dims=7, bounds=(-1.0, 1.0))
+
+# 3. Adapt
+adapter = physlink.DreamerV3Adapter(obs, act)
+adapter.fit(trajectories, steps=10_000)
+
+# 4. Validate physics compliance
+physlink.register_invariant(adapter, "energy", fn=energy_fn, tolerance=0.05)
+report = adapter.compliance_report()
+report.plot()
+
+# 5. Visualise
+adapter.visualize(trajectories)   # → triptych GIF
+adapter.export("./run-01/")
+```
+
+## Documentation
+
+Full docs at **[Denis-hamon.github.io/physlink](https://Denis-hamon.github.io/physlink/)** — includes API reference, lab adoption guide, and domain-scientist quickstart.
+
+## Status
+
+`v0.1.x` — public API stable across minor versions (see [CHANGELOG](CHANGELOG.md)).  
+`test-cpu` CI passes on every PR. GPU benchmarks run on release tags.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome — use the provided templates.

physlink-0.1.2/README.md

@@ -0,0 +1,81 @@
+# PhysLink
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Denis-hamon/physlink/actions/workflows/ci.yml/badge.svg)](https://github.com/Denis-hamon/physlink/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://Denis-hamon.github.io/physlink/)
+[![PyPI](https://img.shields.io/pypi/v/physlink.svg)](https://pypi.org/project/physlink/)
+[![Python](https://img.shields.io/pypi/pyversions/physlink.svg)](https://pypi.org/project/physlink/)
+[![arXiv](https://img.shields.io/badge/arXiv-coming%20soon-b31b1b.svg)](https://arxiv.org/abs/PLACEHOLDER)
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Denis-hamon/physlink/blob/main/notebooks/quickstart.ipynb)
+
+<p align="center">
+  <a href="https://colab.research.google.com/github/Denis-hamon/physlink/blob/main/notebooks/quickstart.ipynb"><strong>Quick Start →</strong></a>
+  &nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="https://Denis-hamon.github.io/physlink/lab-adoption-guide/"><strong>Evaluate for your lab →</strong></a>
+  &nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="https://Denis-hamon.github.io/physlink/domain-scientists/"><strong>For Domain Scientists →</strong></a>
+</p>
+
+---
+
+**PhysLink bridges physical simulators and deep RL adapters in one `pip install`.**
+
+Plug your robot trajectories into [DreamerV3](https://github.com/danijar/dreamerv3) (and future backends) without writing boilerplate space definitions, checkpoint logic, or compliance checks. PhysLink handles the plumbing — you keep the science.
+
+## Why PhysLink
+
+| Without PhysLink | With PhysLink |
+|-----------------|---------------|
+| Hand-write observation/action space mappings per framework | `ObservationSpace.from_proprioception(joints=7)` |
+| Debug silent OOM on Colab at step 8 000 | `physlink.doctor()` catches it before you start |
+| Lose 3h of T4 training on session disconnect | Auto-checkpoint every N steps, resume on reconnect |
+| Manually verify energy conservation after adaptation | `register_invariant` + `compliance_report()` |
+| Stare at loss curves to diagnose model drift | Triptych GIF — Imagination / Real / Difference in one call |
+
+## Install
+
+```bash
+pip install physlink
+```
+
+Works on Google Colab out of the box. No CUDA required for diagnostics and space definitions.
+
+## Quick example
+
+```python
+import physlink
+
+# 1. Verify your environment (< 15 s)
+physlink.doctor()
+
+# 2. Define spaces from your robot config
+obs = physlink.ObservationSpace.from_proprioception(joints=7, include_velocity=True)
+act = physlink.ActionSpace.continuous(dims=7, bounds=(-1.0, 1.0))
+
+# 3. Adapt
+adapter = physlink.DreamerV3Adapter(obs, act)
+adapter.fit(trajectories, steps=10_000)
+
+# 4. Validate physics compliance
+physlink.register_invariant(adapter, "energy", fn=energy_fn, tolerance=0.05)
+report = adapter.compliance_report()
+report.plot()
+
+# 5. Visualise
+adapter.visualize(trajectories)   # → triptych GIF
+adapter.export("./run-01/")
+```
+
+## Documentation
+
+Full docs at **[Denis-hamon.github.io/physlink](https://Denis-hamon.github.io/physlink/)** — includes API reference, lab adoption guide, and domain-scientist quickstart.
+
+## Status
+
+`v0.1.x` — public API stable across minor versions (see [CHANGELOG](CHANGELOG.md)).  
+`test-cpu` CI passes on every PR. GPU benchmarks run on release tags.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome — use the provided templates.

physlink-0.1.2/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "physlink"
+version = "0.1.2"
+description = "Backend-agnostic adapter library for physical simulation ML"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.24",
+    "rich>=13.0",
+    "matplotlib>=3.7",
+    "pyyaml>=6.0",
+    "safetensors>=0.4",
+    "Pillow>=9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.4",
+    "mypy>=1.9",
+    "pytest>=8.0",
+    "pytest-benchmark>=4.0",
+    "pre-commit>=3.7",
+    "build>=1.2",
+    "torch",  # for adapters/ testing; excluded from core/ strict check
+]
+docs = [
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.25",
+    "mike>=2.1",
+]
+notebook = [
+    "nbconvert>=7.0",
+    "nbformat>=5.9",
+]
+
+[project.urls]
+Homepage = "https://Denis-hamon.github.io/physlink/"
+Documentation = "https://Denis-hamon.github.io/physlink/"
+Repository = "https://github.com/Denis-hamon/physlink"
+"Bug Tracker" = "https://github.com/Denis-hamon/physlink/issues"
+Changelog = "https://github.com/Denis-hamon/physlink/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src"]
+exclude = [".agents", ".claude", "_bmad", "_bmad-output", ".venv", "dist", "build"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "ANN", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[[tool.mypy.overrides]]
+module = "physlink.adapters.*"
+ignore_missing_imports = true
+strict = false  # PyTorch stubs incomplete — ADR-002 defers to v0.3.0
+
+[[tool.mypy.overrides]]
+module = "physlink.utils.*"
+ignore_missing_imports = true
+# utils/ may import matplotlib/PIL which have partial stubs
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "gpu: requires CUDA GPU — excluded from test-cpu CI job (deselect with '-m not gpu')",
+    "notebook_execution: executes the Colab notebook via nbconvert — run separately with '-m notebook_execution'",
+]

physlink-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

physlink-0.1.2/src/physlink/__init__.py

@@ -0,0 +1,19 @@
+"""PhysLink — backend-agnostic adapter library for physical simulation ML."""
+
+__version__ = "0.1.2"
+
+from physlink.adapters.dreamer import DreamerV3Adapter  # Story 3.1
+from physlink.core.exceptions import PhysLinkError
+from physlink.core.spaces import ActionSpace, ObservationSpace  # Story 2.6
+from physlink.core.validation import ComplianceReport, register_invariant  # Story 4.3 + 4.4
+from physlink.utils.diagnostics import doctor
+
+__all__ = [
+    "ActionSpace",
+    "ComplianceReport",
+    "DreamerV3Adapter",
+    "ObservationSpace",
+    "PhysLinkError",
+    "doctor",
+    "register_invariant",
+]