mifrost
mifrost is a high-performance graph encoding library for planning states and transitions.
It combines C++ encoder engines (via nanobind) with Python-facing APIs.
The API is native-first: encoders return BatchEncoding by default, and PyTorch Geometric
(Data / HeteroData) objects are built on demand.
| Workflow | Platforms | Python versions |
|---|---|---|
| Unit & C++ Tests | macOS, Ubuntu | 3.12-3.14 |
| Install Smoke | macOS, Ubuntu | 3.12-3.14 |
| Wheel Builds | macOS, manylinux | cibuildwheel cp3.(12-13) |
| Docs Check | Ubuntu | 3.12 |
Documentation
- Website: https://maichmueller.github.io/mifrost/
- Tutorials: https://maichmueller.github.io/mifrost/tutorials/first-encoding/
- Encoder selection guide: https://maichmueller.github.io/mifrost/how-to/choose-an-encoder/
- API reference: https://maichmueller.github.io/mifrost/reference/api/
What it does
- Encodes planning states into graph structures for GNN pipelines.
- Supports single, batch, and stream-oriented encoding workflows.
- Exposes multiple encoder families:
HGraphEncoderHorizonEncoderTransitionHGraphEncoder/TransitionEffectsHGraphEncoderFlatRelationEncoder,FlatHorizonEncoder, and both flat transition lanesColorEncoderILGEncoder- Derived-graph family (homogeneous graphs for vanilla GNN pipelines):
StarGraphEncoder: reified star view where every atom becomes a fact node connected to its argument objectsObjectGraphEncoder: objects-only projection with configurable atom expansion (clique/chain/star_first)AtomLineGraphEncoder: star view plus line-share edges connecting co-occurring arguments of high-degree atomsHypergraphIncidenceEncoder: every encoded literal instance becomes one hyperedge over its argument objectsTupleTensorEncoder: star view plus variable-arity tuple channels (tuple_args/tuple_ptr) for tuple-level readoutsTransformerBiasEncoder: objects-only clique projection with shortest-path-distance biases for transformer attention
LiftedTaskEncoder: lifted planning-task graph (predicate/action schemas, parameters, preconditions/effects, goal); state-independent unlessinclude_state_facts=TrueObjectFeatureEncoder: compact objects-only graph that turns unary predicates into feature channels instead of dropping themSparseAtomCompositionEncoder: one occurrence vector per atom argument, plus the sparse pair/witness indices for composing atoms that share an object pair- Custom pure-Python toolkit (
mifrost.encoders.custom): define your own encoders withStateView+GraphWriter; batching, streaming, and a verification harness included
- Returns native
BatchEncodingobjects, with explicit helpers for:- PyG conversion (
encode_pyg,encode_batch_pyg,as_pyg)
- PyG conversion (
Requirements
- Python
>= 3.12 - A working C++ toolchain
- At least one optional planner for encoder use:
pymimir>=0.15.0orpytyr==0.0.34 - For Python-side graph assembly:
torchandtorch-geometric - For source builds: Conan (or
CONAN_COMMAND/CONAN_CMDpointing to it)
Python dependency files
requirements.txt: runtime Python dependency setrequirements/base-build.txt: planner-neutral PEP 517, CMake, and Conan toolingrequirements/build.txt: Python tooling for source builds (conan,cmake,ninja, etc.)requirements/test.txt: test-only Python dependenciesrequirements/perf.txt: performance-gate dependenciesrequirements/dev.txt: convenience union of build + test + perf + quality toolsrequirements/constraints-ci.txt: CI-only version constraints used by workflowspyproject.tomlbackend extras:.[pymimir],.[pytyr],.[backends]- Development extras:
.[test],.[perf],.[dev]
Installation
From PyPI
pip install "mifrost[pymimir]" \
--find-links https://github.com/maichmueller/mimir/releases/expanded_assets/v0.15.0
The Pymimir adapter shares nanobind's type registry with Pymimir, so it needs
the ABI-matched pymimir>=0.15.0 wheels published on the maintained
maichmueller/mimir release rather than the older upstream pymimir on PyPI;
--find-links lets pip pick them up. PyTyr resolves from PyPI directly:
pip install "mifrost[pytyr]"
pip install "mifrost[backends]" \
--find-links https://github.com/maichmueller/mimir/releases/expanded_assets/v0.15.0
From source (wheel)
git clone https://github.com/maichmueller/mifrost.git
cd mifrost
python scripts/install_pymimir_release.py
pip install --no-build-isolation ".[pymimir]"
The Pymimir adapter shares nanobind's runtime type registry with Pymimir, so
source builds require an ABI-matched Pymimir release. The helper above installs
the platform-specific wheel from the maintained maichmueller/mimir release
(currently 0.15.0) before building Mifrost. Set
MIFROST_PYMIMIR_RELEASE_VERSION when selecting a newer compatible release.
Source builds contain both adapter modules by default. Set
MIFROST_BUILD_BACKENDS=core, pymimir, pytyr, or both to build an
explicit subset; for example:
MIFROST_BUILD_BACKENDS=pytyr pip install ".[pytyr]"
If Conan is not on your PATH, set:
export CONAN_COMMAND=/path/to/conan
If pymimir is installed but CMake cannot locate it, set:
export MIFROST_MIMIR_CMAKE_DIR="$(python -c 'import pymimir; print(pymimir.get_cmake_dir())')"
Editable install (development)
python -m pip install --no-build-isolation \
--config-settings=editable.rebuild=true \
-Cbuild-dir=build_editable \
-e .
This enables import-triggered rebuild behavior from scikit-build-core for local development.
Reusable C++ SDK from the installed package
Installed wheels also ship the reusable native SDK alongside the Python module:
python -c 'import mifrost; print(mifrost.get_include_dir())'
python -c 'import mifrost; print(mifrost.get_cmake_dir())'
python -c 'import mifrost; print(mifrost.get_library_dir())'
Use mifrost.get_cmake_dir() in downstream CMake projects to extend CMAKE_PREFIX_PATH
or pass -Dmifrost_DIR="$(python -c 'import mifrost; print(mifrost.get_cmake_dir())')".
Quick start (native-first)
import mifrost
# Pymimir domains and PyTyr planning tasks select their backend per instance.
encoder = mifrost.HGraphEncoder(domain_or_planning_task)
# state: a matching Pymimir or PyTyr state
encoding = encoder.encode(state) # BatchEncoding
data = encoding.as_pyg() # HeteroData
batch_encoding = encoder.encode_batch([state1, state2, state3]) # BatchEncoding
batch = batch_encoding.as_pyg(as_batch=True) # HeteroDataBatch
# explicit PyG convenience helpers
data2 = encoder.encode_pyg(state)
batch2 = encoder.encode_batch_pyg([state1, state2, state3])
encoding_dict = batch_encoding.as_dict() # dictionary form
# note: encoding_dict["tensors"] entries are DLPack-exporting values
# (consume with torch.utils.dlpack.from_dlpack(...) or mifrost.encoding_to_tensors(...))
Every public encoder family supports backend="pymimir" or backend="pytyr"
for explicit selection; omitting it infers the backend from the constructor
input. Instances from both planners can safely coexist. Their compatible
outputs are ordinary planner-free BatchEncoding values and can be batched
together:
pymimir_encoder = mifrost.HGraphEncoder(pymimir_domain)
pytyr_encoder = mifrost.HGraphEncoder(pytyr_planning_task)
mixed = mifrost.batch_encodings(
[
pymimir_encoder.encode(pymimir_state),
pytyr_encoder.encode(pytyr_state),
],
fast_path=True,
)
assert mixed.num_graphs == 2
See examples/encoders/backend_interchangeability_example.py for a complete
same-process example that parses both planners, creates one mixed PyG batch,
and runs a Torch forward/backward step.
Example output (trimmed):
type(encoding): BatchEncoding
type(data): HeteroData
node_type_count: 28
node_types_head:
['[+]on[g]', '_symbol_', 'clear', 'object', 'ontable',
'[+]clear[g]', '[+]clear[g][sat]', '[+]handempty[g]']
edge_type_count: 54
type(batch_encoding): BatchEncoding
type(batch): HeteroDataBatch
num_graphs: 3
node_type_count: 28
encoding keys:
['node_feature_dims', 'node_names', 'num_graphs', 'object_names', 'schema', 'tensors']
schema keys:
['edge_tensors', 'edge_types', 'extensions', 'flags', 'graph_kind',
'node_tensors', 'node_types', 'version']
tensor_count: 164
tensor_keys_head:
['_symbol_|0|object/edge_index_0', '_symbol_|0|object/edge_index_1',
'object|0|_symbol_/edge_index_0', 'object|0|_symbol_/edge_index_1', ...]
Stream workflow:
stream = encoder.stream()
stream.append(state1)
stream.append(state2)
batch = stream.flush_pyg(as_batch=True) # HeteroDataBatch
# equivalent native form of the same flush; each flush resets the
# stream, so append states again before flushing a second time:
# batch_encoding = stream.flush() # BatchEncoding
# batch = batch_encoding.as_pyg(as_batch=True) # HeteroDataBatch
# mutable stream (supports update/remove)
mutable = encoder.mutable_stream()
sid = mutable.append(state1)
mutable.update(sid, state2)
mutable.remove(sid)
Example output:
type(batch): HeteroDataBatch
num_graphs: 2
node_type_count: 28
node_types_head:
['[+]clear[g]', '[+]clear[g][sat]', '[+]handempty[g]', '[+]handempty[g][sat]',
'[+]holding[g]', '[+]holding[g][sat]', '[+]on[g]', '[+]on[g][sat]']
Encoding quick lookup
C++ (HGraphEncoderEngine)
All methods append into an existing BatchBuilder (they do not clear it). Call builder.next_graph() to commit one graph.
-
encode(state, builder)/encode_state(state, builder)- State-only graph (objects + current facts).
-
encode_step<GoalTag>(state, goals_span, actions_span, builder)- Convenience overload for typed goal literals (wraps into
GoalInputsinternally).
- Convenience overload for typed goal literals (wraps into
-
encode(state, goals: GoalInputs, actions_span, builder)- Full step graph (state + goals + optional actions; plus optional derived relations depending on config).
-
encode(state, goals, actions_span, history_subgoals, history_max_steps, builder)- Full step graph plus history nodes/links (
dt-tagged subgoals).
- Full step graph plus history nodes/links (
C++ streaming
-
HGraphStreamEncoder(append-only)- Direct append into one persistent builder.
append(...) -> id,flush(),flush_pyg(),reset().
-
HGraphMutableStreamEncoder(cached/mutable, viaStreamEncoderBase)- Supports
update/removewith id stability and cache merge on flush. append(...) -> id,update(id, ...),remove(id),flush(),flush_pyg(),reset(),set_reuse_removed(bool).
- Supports
Python (HGraphEncoder)
-
encode(state, *, ...) -> BatchEncoding- One graph, native encoding object.
-
encode_pyg(state, *, ...) -> HeteroData- One graph, explicit PyG conversion path.
-
encode_batch(states, *, ...) -> BatchEncoding- Many graphs, native batch encoding object.
-
encode_batch_pyg(states, *, ...) -> HeteroDataBatch- Many graphs, explicit PyG conversion path.
-
encode_batchargument semantics-
statesis always the batch axis. -
Each extra batch argument is either shared (applies to all states) or a per-state sequence of length
len(states)with optionalNoneentries. -
Batch parsing/execution is C++-backed across encoders.
-
High-level
encode_batch(...)accepts wrapper/native planning inputs and converts wrapper/adapter-backed values in Python before entering the C++ batch parser. -
Low-level
_core._parse_*helpers and C++ batch internals are strict advanced-only. -
Unknown batch kwargs raise
TypeError; family-specific unsupported lanes raise a descriptiveValueErrorwhen they contain values. -
Per-state argument length mismatches raise
ValueError. -
Example:
- Shared goals/actions:
encoder.encode_batch(states, goals=goals, actions=actions)
- Per-state goals/actions:
encoder.encode_batch(states, goals=[goals0, goals1], actions=[[a0], None])
- Shared goals/actions:
-
Migration notes (hard break):
- Old encoder-specific inference/ignoring of batch kwargs was removed.
- Low-level
_core._parse_*batch parser helpers no longer accept adapter-backed custom Python types.- High-level encoder
encode_batch(...)now performs Python-side adapter conversion.
- High-level encoder
Transition*Encoderrequires alignedsuccessorsand rejects explicit action/history lanes.HorizonEncoderaccepts per-statedags/goals/subgoal_layersand rejects explicit action/history lanes.ColorEncoderrejects action payloads.
-
-
stream() -> HGraphEncoderStream- Create an append-only stream encoder backed by the same C++ engine.
-
mutable_stream() -> HGraphMutableEncoderStream- Create a mutable stream encoder supporting update/remove.
Python streaming (HGraphEncoderStream, append-only)
append(state, *, goals=None, actions=None, subgoal_layers=None, history_subgoals=None, history_max_steps=None) -> idflush() -> BatchEncodingflush_pyg(...) -> PyG
Python mutable streaming (HGraphMutableEncoderStream)
Cached stream wrapper (ids + edits), merges on flush.
append(state, *, goals=None, actions=None, subgoal_layers=None, history_subgoals=None, history_max_steps=None) -> idupdate(id, state, *, ...)remove(id)flush() -> BatchEncodingflush_pyg(...) -> PyG
Extending input types (adapter API)
Encoders are strict for native pymimir (advanced) types, but you can register explicit adapters
for custom wrappers:
import mifrost
mifrost.register_state_adapter(MyStateType, lambda s: s.to_advanced_state())
mifrost.register_domain_adapter(MyDomainType, lambda d: d.to_advanced_domain())
mifrost.register_literal_adapter(MyLiteralType, lambda l: l.to_advanced_literal())
mifrost.register_action_adapter(MyActionType, lambda a: a.to_advanced_action())
Adapters are matched by exact concrete type.
Batch hard-break note:
- High-level
encode_batch(...)/encode_batch_pyg(...)use adapter registries during Python-side preprocessing before calling strict C++ batch parsing. - Direct low-level
_core._parse_*batch helper calls remain advanced-only and reject adapter-backed objects.
Development
Configure and build C++ targets
python configure.py --config Release
python cbuild.py
Or use CMake presets:
cmake --preset local-release
cmake --build build/local-release
Build benchmarks:
python configure.py --config Release --build_dir build/bench-release --with_benchmarks
python cbuild.py build/bench-release --bench
Batch collation microbenchmark (batch_encodings, including pyobj collation):
python scripts/benchmark_batch_encodings.py --repeats 400 --warmup 50
Tests
Python tests:
pytest -q
C++ tests (after configure/build):
./build/<...>/src/mifrost_tests
Profiling
python scripts/profile_encoding.py --domain blocks --problem small
python scripts/profile_encoding.py --profile cprofile --include-goals
python scripts/profile_encoding.py --benchmark-pyg --no-export-node-names
Comprehensive scaling benchmark suite (diverse state batches, goals/actions combinations, transition encoders, horizon DAG-size sweeps):
python scripts/benchmark_encoder_suite.py \
--domain blocks \
--problem smedium \
--max-states 256 \
--batch-sizes 8,32,128 \
--horizon-dag-sizes 8,32,64 \
--horizon-batch-sizes 4,16 \
--include-lgan-values false,true \
--repeats 5 \
--warmup 1 \
--output-json /tmp/encoder_bench_suite.json
Include PyG conversion paths in the same run:
python scripts/benchmark_encoder_suite.py --benchmark-pyg
Output assembly notes
- Native-first:
encode(...)/encode_batch(...)returnBatchEncoding.BatchEncoding.as_pyg(...)converts to PyG.
- Convenience:
encode_pyg(...)/encode_batch_pyg(...)return PyG directly.
BatchEncodingsupportsas_dict(),schema_fingerprint(),save(...),load(...).mifrost.batch_encodings([...])batches single-graph encodings natively with schema checks.- Use
mifrost.encoding_to_tensors(encoding.as_dict())when feeding a custom downstream pipeline.
Encoder architecture note
- See
docs/development/architecture.mdfor the current Python/native layout and encoder architecture notes.
License
GPL-3.0-only
Metadata
Release files for mifrost 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mifrost-0.6.0.tar.gz | 928.1 kB | With provenance | Details for mifrost-0.6.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| mifrost-0.6.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.13 | CPython 3.13 | Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 | Details for mifrost-0.6.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
| mifrost-0.6.0-cp313-cp313-macosx_11_0_arm64.whl | CPython 3.13 | CPython 3.13 | macOS 11.0+ ARM64 | Details for mifrost-0.6.0-cp313-cp313-macosx_11_0_arm64.whl |
| mifrost-0.6.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 | Details for mifrost-0.6.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
| mifrost-0.6.0-cp312-cp312-macosx_11_0_arm64.whl | CPython 3.12 | CPython 3.12 | macOS 11.0+ ARM64 | Details for mifrost-0.6.0-cp312-cp312-macosx_11_0_arm64.whl |
Total release size: 38.9 MB
Release files / mifrost-0.6.0.tar.gz
| Download URL | mifrost-0.6.0.tar.gz |
|---|---|
| Size | 928.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ffcf17e2dd130665f316bf7fafbfc212f8f958d968271a8a982bf7b83d8113ed
|
|
BLAKE2b-256 checksum How to use checksums |
edb99e5cf6208326b5bb5e4976f2aa3f644239f0e4d1fd6f6d6c199612db63d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / mifrost-0.6.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | mifrost-0.6.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 11.3 MB |
| Tags | CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
9de2b456c6a64792a00b4cccae0b0b793732550f37af9b598e94b1ec629d15bb
|
|
BLAKE2b-256 checksum How to use checksums |
4a0f2f82ca73e9398ea1859c6435d9c84230fa99c44393d8a1dad50849832bf1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / mifrost-0.6.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | mifrost-0.6.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 7.6 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ec89aa3010273c4d85bdc3d69abeb521de555a246d642acd96784b227daeb2e5
|
|
BLAKE2b-256 checksum How to use checksums |
e0150d254e27d9d1d80a952d49d463dc6d19c2508e0d1d4ea05cd66f55cbc20c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / mifrost-0.6.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | mifrost-0.6.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 11.3 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
3c2979f6a40de64df87f7c5360ea03acabb02c2307725f88b2651fc35f48aca4
|
|
BLAKE2b-256 checksum How to use checksums |
d6c58681ef96f5d35d195344653f19ac5e86ef6706c5c4aaa9216a4542a5dd61
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / mifrost-0.6.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | mifrost-0.6.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 7.6 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b6bb706601ce6364163255ad2f77542544641d16e037a3795f1c816049723dc5
|
|
BLAKE2b-256 checksum How to use checksums |
6d348b91099e25916461188d09f9ab043895cd9c8bf2e31547b350397269a491
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logSecurity for mifrost 0.6.0
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.
Full provenance
All 5 files in this release have been uploaded with provenance metadata.
Attestation for mifrost-0.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logA 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.