pytpg 0.5.0__tar.gz

pytpg-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install package and test dependencies
+        run: python -m pip install -e ".[dev,gymnasium]"
+      - name: Test (including installed distribution)
+        run: python -m pytest
+
+  quality-release-check:
+    name: Quality and release checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          cache: pip
+      - name: Install package and development dependencies
+        run: python -m pip install -e ".[dev,gymnasium]"
+      - name: Lint
+        run: python -m ruff check .
+      - name: Type check
+        run: python -m pyright
+      - name: Test (including installed distribution)
+        run: python -m pytest
+      - name: Build source distribution and wheel
+        run: python -m build
+      - name: Check distribution metadata
+        run: python -m twine check dist/*

pytpg-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+name: Publish pyTPG
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - name: Install build
+        run: python -m pip install build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Store distributions
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch'
+    needs:
+      - build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/pytpg
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs:
+      - build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pytpg
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pytpg-0.5.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.venv/
+build/
+dist/
+htmlcov/
+

pytpg-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+pyTPG is specification-first research software. A change to algorithm behavior
+must update the relevant document under `docs/specification/` in the same pull
+request. Tests should assert semantics, not only benchmark performance.
+
+Core dependencies must point inward:
+
+```text
+application/environment -> adapter -> training/evolution -> core -> runtime
+```
+
+The core and runtime must not import environment integrations. Optional
+integrations must not become required package dependencies.
+
+Before submitting a change, run:
+
+```bash
+ruff check .
+pyright
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+Install development dependencies with `python -m pip install -e ".[dev]"`.
+The distribution test also requires pip and builds an installed-wheel smoke test.
+See [release preparation](docs/release.md) for compatibility and licensing.
+
+Milestone 7 intentionally uses a fixed synchronous agent roster. Independent
+controllers isolate live episode state; centralized shared control concatenates
+observations and uses a mixed-radix scalar joint action. Dynamic or turn-based
+rosters, per-agent early termination, PettingZoo integration, partial
+observations, continuous/composite actions, coevolution, credit assignment,
+centralized-training/decentralized-execution, parallel evaluation, persistent
+genealogy, custom-operator schema registration, and serialization migrations
+remain outside this milestone.

pytpg-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pyTPG contributors
+
+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.

pytpg-0.5.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: pytpg
+Version: 0.5.0
+Summary: A modular research framework for Tangled Program Graphs
+Project-URL: Homepage, https://github.com/ramsayxiaoshao/pyTPG
+Project-URL: Repository, https://github.com/ramsayxiaoshao/pyTPG
+Project-URL: Documentation, https://github.com/ramsayxiaoshao/pyTPG/tree/main/docs
+Project-URL: Issues, https://github.com/ramsayxiaoshao/pyTPG/issues
+Author: pyTPG contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: evolutionary-computation,reinforcement-learning,tangled-program-graphs
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hatchling>=1.26; extra == 'dev'
+Requires-Dist: pyright[nodejs]>=1.1.380; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=6.1; extra == 'dev'
+Provides-Extra: gymnasium
+Requires-Dist: gymnasium<2,>=1.0; extra == 'gymnasium'
+Description-Content-Type: text/markdown
+
+# pyTPG
+
+## What is TPG?
+
+pyTPG is a modular research framework for Tangled Program Graphs
+(TPG). The project is being developed specification-first so that algorithmic
+choices are explicit, testable, and reproducible.
+
+The repository currently contains **Milestone 7**: deterministic runtime and
+evolution, reproducible research infrastructure, optional Gymnasium integration,
+episode-scoped stateful TPG, and deterministic multi-agent composition.
+
+## Installation
+
+Requires Python 3.10 or newer. After the first public release, install with:
+
+```bash
+pip install pytpg
+```
+
+For development from a checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Install the optional Gymnasium integration with:
+
+```bash
+python -m pip install "pytpg[gymnasium]"
+```
+
+The PyPI distribution and Python import namespace are both `pytpg`.
+The GitHub project name is pyTPG.
+
+Code using the previous `tpg` namespace must update imports to `pytpg`;
+no compatibility alias is provided. See [release notes](docs/release.md).
+
+## Minimal example
+
+The following manually constructs and executes a one-team TPG graph:
+
+```python
+from pytpg.core import (
+    ActionID,
+    AtomicAction,
+    ConstantOperand,
+    InputIndex,
+    InputOperand,
+    Instruction,
+    Learner,
+    LearnerID,
+    OperatorName,
+    Program,
+    ProgramID,
+    RegisterIndex,
+    Team,
+    TeamID,
+    TPGGraph,
+)
+
+instruction = Instruction(
+    operator=OperatorName("multiply"),
+    destination=RegisterIndex(0),
+    operands=(InputOperand(InputIndex(0)), ConstantOperand(2.0)),
+)
+program = Program(ProgramID(0), (instruction,))
+learner = Learner(LearnerID(0), program, AtomicAction(ActionID(0)))
+team = Team(TeamID(0), (learner,))
+graph = TPGGraph((team,), (team.id,))
+
+action = graph.act((0.75,))
+assert action == ActionID(0)
+```
+
+For recorded experiments, pass an explicit `GraphRuntime(RuntimeConfig(...))`
+rather than relying on the shape inference provided by `graph.act`.
+
+## Main features
+
+- Explicit core concepts rather than trainer-owned dictionaries.
+- Immutable value objects and typed identifiers.
+- Environment-independent core architecture.
+- Extensible operator registry with protected deterministic arithmetic.
+- Strict observation, register, instruction, and operator validation.
+- Stable raw-bid selection with deterministic tie-breaking.
+- Validated Team-reference traversal with cycle and step-limit safety.
+- Graph diagnostics, traversal traces, and structural summaries.
+- Explicit NumPy RNG ownership and fixed-seed reproducibility.
+- Valid connected population initialization and finite scalar evaluation.
+- Stable tournament selection, elitism, and mutation-only reproduction.
+- Eight focused clone-on-write mutation operators with invariant validation.
+- Inspectable parent and mutation records for each offspring generation.
+- Canonical experiment configuration digests and named RNG streams.
+- Structured lifecycle callbacks, standard logging, and generation statistics.
+- Recorded Python/NumPy/package/platform experiment metadata.
+- Versioned JSON graph serialization and evaluated-boundary checkpoints.
+- Exact deterministic continuation without re-evaluating saved fitness.
+- Lazy optional Gymnasium integration with no environment dependency in core.
+- Reproducible multi-episode fitness with common seeds and a hard rollout bound.
+- Strict modern `terminated`/`truncated` handling and Discrete action mapping.
+- Explicit memory reset, snapshot, restore, and atomic update contracts.
+- Null, fixed-register, and oldest-to-newest observation-history memory.
+- Stateful traversal by observation augmentation without duplicated graph logic.
+- Independent and heterogeneous controllers with transactional joint steps.
+- Safe immutable-graph parameter sharing with per-agent episode state.
+- Centralized shared control with mixed-radix heterogeneous joint actions.
+
+## Documentation
+
+- [Architecture](docs/architecture.md)
+- [Specification index](docs/specification/README.md)
+- [Open algorithmic questions](docs/specification/open-questions.md)
+
+## Examples
+
+Run the manual deterministic-team example with:
+
+```bash
+python examples/manual_team.py
+```
+
+Run the cyclic graph traversal example with:
+
+```bash
+python examples/manual_graph.py
+```
+
+Run a fixed-seed toy evolution with:
+
+```bash
+python examples/evolve_bandit.py
+```
+
+Run, save, load, and resume a reproducible experiment with:
+
+```bash
+python examples/reproducible_experiment.py
+```
+
+After installing the Gymnasium extra, run the small CartPole evolution with:
+
+```bash
+python examples/evolve_cartpole.py
+```
+
+Run the three-step delayed-signal memory example with:
+
+```bash
+python examples/stateful_delayed_signal.py
+```
+
+Run heterogeneous independent and centralized shared control with:
+
+```bash
+python examples/multiagent_control.py
+```
+
+## Development status
+
+Current version: `0.5.0` (Milestone 7, multi-agent TPG, pre-alpha).
+
+Run the local checks with:
+
+```bash
+ruff check .
+pyright
+pytest
+python -m build
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development boundaries.
+
+## License
+
+MIT licensed. Copyright (c) 2026 pyTPG contributors. See [LICENSE](LICENSE).

pytpg-0.5.0/README.md

@@ -0,0 +1,176 @@
+# pyTPG
+
+## What is TPG?
+
+pyTPG is a modular research framework for Tangled Program Graphs
+(TPG). The project is being developed specification-first so that algorithmic
+choices are explicit, testable, and reproducible.
+
+The repository currently contains **Milestone 7**: deterministic runtime and
+evolution, reproducible research infrastructure, optional Gymnasium integration,
+episode-scoped stateful TPG, and deterministic multi-agent composition.
+
+## Installation
+
+Requires Python 3.10 or newer. After the first public release, install with:
+
+```bash
+pip install pytpg
+```
+
+For development from a checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Install the optional Gymnasium integration with:
+
+```bash
+python -m pip install "pytpg[gymnasium]"
+```
+
+The PyPI distribution and Python import namespace are both `pytpg`.
+The GitHub project name is pyTPG.
+
+Code using the previous `tpg` namespace must update imports to `pytpg`;
+no compatibility alias is provided. See [release notes](docs/release.md).
+
+## Minimal example
+
+The following manually constructs and executes a one-team TPG graph:
+
+```python
+from pytpg.core import (
+    ActionID,
+    AtomicAction,
+    ConstantOperand,
+    InputIndex,
+    InputOperand,
+    Instruction,
+    Learner,
+    LearnerID,
+    OperatorName,
+    Program,
+    ProgramID,
+    RegisterIndex,
+    Team,
+    TeamID,
+    TPGGraph,
+)
+
+instruction = Instruction(
+    operator=OperatorName("multiply"),
+    destination=RegisterIndex(0),
+    operands=(InputOperand(InputIndex(0)), ConstantOperand(2.0)),
+)
+program = Program(ProgramID(0), (instruction,))
+learner = Learner(LearnerID(0), program, AtomicAction(ActionID(0)))
+team = Team(TeamID(0), (learner,))
+graph = TPGGraph((team,), (team.id,))
+
+action = graph.act((0.75,))
+assert action == ActionID(0)
+```
+
+For recorded experiments, pass an explicit `GraphRuntime(RuntimeConfig(...))`
+rather than relying on the shape inference provided by `graph.act`.
+
+## Main features
+
+- Explicit core concepts rather than trainer-owned dictionaries.
+- Immutable value objects and typed identifiers.
+- Environment-independent core architecture.
+- Extensible operator registry with protected deterministic arithmetic.
+- Strict observation, register, instruction, and operator validation.
+- Stable raw-bid selection with deterministic tie-breaking.
+- Validated Team-reference traversal with cycle and step-limit safety.
+- Graph diagnostics, traversal traces, and structural summaries.
+- Explicit NumPy RNG ownership and fixed-seed reproducibility.
+- Valid connected population initialization and finite scalar evaluation.
+- Stable tournament selection, elitism, and mutation-only reproduction.
+- Eight focused clone-on-write mutation operators with invariant validation.
+- Inspectable parent and mutation records for each offspring generation.
+- Canonical experiment configuration digests and named RNG streams.
+- Structured lifecycle callbacks, standard logging, and generation statistics.
+- Recorded Python/NumPy/package/platform experiment metadata.
+- Versioned JSON graph serialization and evaluated-boundary checkpoints.
+- Exact deterministic continuation without re-evaluating saved fitness.
+- Lazy optional Gymnasium integration with no environment dependency in core.
+- Reproducible multi-episode fitness with common seeds and a hard rollout bound.
+- Strict modern `terminated`/`truncated` handling and Discrete action mapping.
+- Explicit memory reset, snapshot, restore, and atomic update contracts.
+- Null, fixed-register, and oldest-to-newest observation-history memory.
+- Stateful traversal by observation augmentation without duplicated graph logic.
+- Independent and heterogeneous controllers with transactional joint steps.
+- Safe immutable-graph parameter sharing with per-agent episode state.
+- Centralized shared control with mixed-radix heterogeneous joint actions.
+
+## Documentation
+
+- [Architecture](docs/architecture.md)
+- [Specification index](docs/specification/README.md)
+- [Open algorithmic questions](docs/specification/open-questions.md)
+
+## Examples
+
+Run the manual deterministic-team example with:
+
+```bash
+python examples/manual_team.py
+```
+
+Run the cyclic graph traversal example with:
+
+```bash
+python examples/manual_graph.py
+```
+
+Run a fixed-seed toy evolution with:
+
+```bash
+python examples/evolve_bandit.py
+```
+
+Run, save, load, and resume a reproducible experiment with:
+
+```bash
+python examples/reproducible_experiment.py
+```
+
+After installing the Gymnasium extra, run the small CartPole evolution with:
+
+```bash
+python examples/evolve_cartpole.py
+```
+
+Run the three-step delayed-signal memory example with:
+
+```bash
+python examples/stateful_delayed_signal.py
+```
+
+Run heterogeneous independent and centralized shared control with:
+
+```bash
+python examples/multiagent_control.py
+```
+
+## Development status
+
+Current version: `0.5.0` (Milestone 7, multi-agent TPG, pre-alpha).
+
+Run the local checks with:
+
+```bash
+ruff check .
+pyright
+pytest
+python -m build
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development boundaries.
+
+## License
+
+MIT licensed. Copyright (c) 2026 pyTPG contributors. See [LICENSE](LICENSE).