Runir: Representations for Generalized Planning in C++ and Python

Runir is designed to address several challenges in the integration of learning and planning based systems:

Dataset construction from planning tasks and classes of tasks over a common planning domain.
State Model Representations that expose a task's dynamics in a representation suitable for relational learning.
Symbolic feature languages with formal syntax, semantics, parsing, generation, and evaluation.
Generalized policy evaluation on planning examples with explicit access to policy failures and counterexamples.
Equivalence abstractions for comparing states and tasks through graph, object-graph, and equivalence-graph representations.

Runir is the learning and representation layer for the planning-and-learning ecosystem. Tyr provides the planning backend: PDDL/formalism objects, task repositories, state repositories, successor generation, search algorithms, and Python bindings. Runir builds on top of that backend to make planning tasks inspectable and learnable, not only solvable.

Components

runir::graphs: typed graph data structures, static/dynamic graphs, BGL adapters, shortest paths, strongly connected components, topological sort, color refinement, Weisfeiler-Lehman certificates, and nauty-backed graph isomorphism certificates.
runir::datasets: task classes, per-task search contexts, state graphs, annotated state graphs, object graphs, and equivalence graphs built from policies such as identity or graph-isomorphism reduction.
runir::kr::dl: description-logic constructors, grammars, CNF grammars, denotations, evaluation, parsing, formatting, and grammar factories.
runir::kr::ps: rule-based generalized policies over typed features, conditions, effects, policy parsing, policy factories, and policy execution on annotated state graphs.
pyrunir: Python bindings for the same components with stubs.

The native CMake package exports runir::core as the aggregate target and component targets such as runir::graphs, runir::datasets, and runir::kr. The Python package is pyrunir.

Dependencies

Python 3.11 or newer.
pyyggdrasil >= 0.4.1, < 0.5 for shared third-party native dependencies.
pytyr >= 0.4.3, < 0.5 for Tyr planning, formalism, search, and C++ headers/libraries.
pypddl >= 1.4.1, < 1.5 through Tyr/PDDL parsing infrastructure.
pypddl-datasets >= 0.0.17, < 0.1 for the PDDL benchmark data used by the C++ test and profiling fixtures (resolved from its cache at CMake configure time).
scikit-build-core for Python wheel builds.

The shared workspace layout, layered install order, and the common build-from-source and CMake-integration patterns are documented in the Planning and Learning build instructions; the sections below cover runir/pyrunir-specific details.

Build C++

Install Runir's native dependency providers into the active Python environment, then configure CMake with their native prefixes:

python -m pip install 'pyyggdrasil>=0.5.0,<0.6' 'pypddl>=1.6.0,<1.7' 'pytyr>=0.6.0,<0.7' 'pypddl-datasets>=0.0.17,<0.1'

cmake -S . -B build

cmake --build build -j4

CMake discovers the installed provider packages automatically through cmake/bootstrap_pyyggdrasil.cmake (which locates pyyggdrasil and adds its native prefix to CMAKE_PREFIX_PATH; find_package(yggdrasil) then resolves the rest of the chain) and links against the yggdrasil::yggdrasil and tyr::core targets. To point at different prefixes explicitly:

cmake -S . -B build \
  -DCMAKE_PREFIX_PATH="$(python -m pyyggdrasil --prefix);$(python -m pypddl --prefix);$(python -m pytyr --prefix)"

CMake options:

Option	Default	Description
`RUNIR_BUILD_TESTS`	`OFF`	Build Runir tests.
`RUNIR_BUILD_EXECUTABLES`	`OFF`	Build Runir executables.
`RUNIR_BUILD_PYRUNIR`	`OFF`	Build `pyrunir` Python bindings.
`RUNIR_HEADER_INSTANTIATION`	`OFF`	Instantiate templates in in-tree translation units at higher compile-time cost.
`RUNIR_DELTA_EVALUATION`	`ON`	Use incremental feature evaluation in `find_solution`.
`RUNIR_USE_LLD`	`ON`	Use LLVM `lld` with Clang when available.
`RUNIR_ENABLE_LTO`	`ON`	Enable link-time optimization for Release builds.

Single-config CMake builds default to Release. On GCC and Clang, Debug builds use -Og with debug symbols, RelWithDebInfo keeps frame pointers and disables LTO, and Release LTO uses GCC LTO or Clang ThinLTO. Editable installs and wheels disable RUNIR_USE_LLD and RUNIR_ENABLE_LTO by default for build reliability.

Run tests from a build configured with -DRUNIR_BUILD_TESTS=ON:

ctest --test-dir build --output-on-failure

Install Runir from a configured build directory with:

cmake --install build --prefix=<path/to/installation-directory>

Build Python

python -m pip install .[test]
pytest python/tests

Python Serialization

pyrunir.serialization exposes the native serializers with caller-selected dictionary tables shared with Tyr. See the serialization output reference.

Template and include rules

Headers and templates follow the template and include rules maintained in yggdrasil.

CMake Integration

This section covers pyrunir-specific paths and targets; the general pattern for consuming the native prefixes from CMake is in the common CMake integration instructions.

The Python package pyrunir installs Runir's native headers, shared libraries, and CMake package config under pyrunir.native_prefix(). Use pyrunir.cmake_prefix() and pyrunir.cmake_dir() (or python -m pyrunir --prefix / --cmake-dir from the shell) to locate them. Downstream CMake projects should include the native prefixes of pyrunir and its native package dependencies in CMAKE_PREFIX_PATH:

cmake -S . -B build \
  -DCMAKE_PREFIX_PATH="$(python -m pyyggdrasil --prefix);$(python -m pypddl --prefix);$(python -m pytyr --prefix);$(python -m pyrunir --prefix)"

Runir exports the runir::core aggregate target and component targets such as runir::graphs, runir::datasets, and runir::kr.

Intended Workflow

Runir is designed for experiments where a learning system needs structured access to planning behavior:

Parse and instantiate tasks with Tyr.
Build state graphs or equivalence graphs with Runir datasets.
Define symbolic features in a KR language such as description logics.
Build or parse a generalized policy over those features.
Execute the policy on examples and inspect failures or counterexamples.

Extended policies support query features and Action rules for selecting complete action tuples and checking declared effect contracts. Their proof search combines lazy Choose exploration with incremental AND/OR success propagation. See KR evaluation storage for result bindings, view lifetimes, and internal rule evaluators.

Indexical concept policies are available as the separate icp family, with Ext features, Load and Crule effects, concept histories, and greedy or universal execution.

This keeps low-level planning mechanics in Tyr while giving learning code a high-level, typed interface for representations, abstractions, and policy evaluation.

Metadata

Release files for pyrunir 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyrunir 0.6.0
File	Size	Uploaded	Provenance
pyrunir-0.6.0.tar.gz	1.1 MB	Oct 23, 2026	With provenance	Details

Built distributions (wheels)

Table of built distributions (wheels) for pyrunir 0.6.0
File	Interpreter	ABI	Platform	Reset
pyrunir-0.6.0-cp311-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl 8.0 MB Oct 23, 2026 With provenance	CPython 3.11	abi3	Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64	Details
pyrunir-0.6.0-cp311-abi3-macosx_11_0_arm64.whl 6.2 MB Oct 23, 2026 With provenance	CPython 3.11	abi3	macOS 11.0+ ARM64	Details

Total release size: 15.3 MB

Release files / pyrunir-0.6.0.tar.gz

Download URL	pyrunir-0.6.0.tar.gz
Size	1.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`45db94922752acffc272843f6ed90e428b3e25169584426e8d6533f3e3d8080b`
BLAKE2b-256 checksum How to use checksums	`a9487ca2ced2d0f48a74ad03b558f77b6eaf66ea7f146aed29e694a1a336079a`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/planning-and-learning/runir
Publishing commit: github.com/planning-and-learning/runir/tree/4c473074e3a83a8cdbd6d2873b43c0b2bd200b0d

Workflow

Publishing configuration: github.com/planning-and-learning/runir/blob/4c473074e3a83a8cdbd6d2873b43c0b2bd200b0d/.github/workflows/release.yml
Publishing logs: github.com/planning-and-learning/runir/actions/runs/40034673754/attempts/1

Artifact

Subject: pyrunir-0.6.0.tar.gz
SHA-256 checksum: 45db94922752acffc272843f6ed90e428b3e25169584426e8d6533f3e3d8080b Verifying attestations

Release files / pyrunir-0.6.0-cp311-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL	pyrunir-0.6.0-cp311-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size	8.0 MB
Tags	CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum How to use checksums	`1202ec6e49b553536d532cee8d720264cefcdba936d29a0b0c514178f50f2b81`
BLAKE2b-256 checksum How to use checksums	`67f7008c80f65cf7be66deaee6e5db8dd5c56e0c693bcfe2ae267ff133aa2918`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/planning-and-learning/runir
Publishing commit: github.com/planning-and-learning/runir/tree/4c473074e3a83a8cdbd6d2873b43c0b2bd200b0d

Workflow

Publishing configuration: github.com/planning-and-learning/runir/blob/4c473074e3a83a8cdbd6d2873b43c0b2bd200b0d/.github/workflows/release.yml
Publishing logs: github.com/planning-and-learning/runir/actions/runs/40034673754/attempts/1

Artifact

Subject: pyrunir-0.6.0-cp311-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
SHA-256 checksum: 1202ec6e49b553536d532cee8d720264cefcdba936d29a0b0c514178f50f2b81 Verifying attestations

Release files / pyrunir-0.6.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL	pyrunir-0.6.0-cp311-abi3-macosx_11_0_arm64.whl
Size	6.2 MB
Tags	CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`8947105aecb5d9faf05df6e9d43fc64271aed5a02102afe5750b084953a6cc12`
BLAKE2b-256 checksum How to use checksums	`2475cc250aae51900dc4b013a3027e687890ffbb648c267b18b22ac618a72045`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/planning-and-learning/runir
Publishing commit: github.com/planning-and-learning/runir/tree/4c473074e3a83a8cdbd6d2873b43c0b2bd200b0d

Workflow

Publishing configuration: github.com/planning-and-learning/runir/blob/4c473074e3a83a8cdbd6d2873b43c0b2bd200b0d/.github/workflows/release.yml
Publishing logs: github.com/planning-and-learning/runir/actions/runs/40034673754/attempts/1

Artifact

Subject: pyrunir-0.6.0-cp311-abi3-macosx_11_0_arm64.whl
SHA-256 checksum: 8947105aecb5d9faf05df6e9d43fc64271aed5a02102afe5750b084953a6cc12 Verifying attestations

Security for pyrunir 0.6.0

Report project as malware

Provenance

Full provenance

All 3 files in this release have been uploaded with provenance metadata.

Attestation for pyrunir-0.6.0.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/planning-and-learning/runir
Publishing commit: github.com/planning-and-learning/runir/tree/4c473074e3a83a8cdbd6d2873b43c0b2bd200b0d

Workflow

Publishing configuration: github.com/planning-and-learning/runir/blob/4c473074e3a83a8cdbd6d2873b43c0b2bd200b0d/.github/workflows/release.yml
Publishing logs: github.com/planning-and-learning/runir/actions/runs/40034673754/attempts/1

Artifact

Subject: pyrunir-0.6.0.tar.gz
SHA-256 checksum: 45db94922752acffc272843f6ed90e428b3e25169584426e8d6533f3e3d8080b Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.