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:

pip install pytpg

For development from a checkout:

python -m pip install -e ".[dev]"

Install the optional Gymnasium integration with:

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.

Minimal example

The following manually constructs and executes a one-team TPG graph:

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
• Specification index
• Open algorithmic questions

Examples

Run the manual deterministic-team example with:

python examples/manual_team.py

Run the cyclic graph traversal example with:

python examples/manual_graph.py

Run a fixed-seed toy evolution with:

python examples/evolve_bandit.py

Run, save, load, and resume a reproducible experiment with:

python examples/reproducible_experiment.py

After installing the Gymnasium extra, run the small CartPole evolution with:

python examples/evolve_cartpole.py

Run the three-step delayed-signal memory example with:

python examples/stateful_delayed_signal.py

Run heterogeneous independent and centralized shared control with:

python examples/multiagent_control.py

Development status

Current version: 0.5.0 (Milestone 7, multi-agent TPG, pre-alpha).

Run the local checks with:

ruff check .
pyright
pytest
python -m build

See CONTRIBUTING.md for the development boundaries.

License

MIT licensed. Copyright (c) 2026 pyTPG contributors. See LICENSE.

Execution visualization

Record actual eligible bids, winners, excluded references and traversal paths with GraphRuntime.traverse_detailed() and TraceSession. Install pip install "pytpg[visualization]" to render standalone offline HTML with Play/Pause, a decision timeline and whole-session activation counts.

Run python examples/visualize_trace.py, or render recorded JSON with pytpg-visualize episode_trace.json --output trace.html. See execution visualization for Python usage and schema details.