Skip to content

Derived-Graph Encoders

StarGraphEncoder

Bases: _DerivedEncoderBase

Reified star view over objects and atoms.

Each atom becomes a fact node connected to its argument object nodes via star (hub) edges; goal atoms are marked in the goal channel.

The input must be a pymimir.Problem or pytyr.PlanningTask. Domains are rejected because object tables are problem-scoped.

Source code in src/mifrost/encoders/derived.py
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
class StarGraphEncoder(_DerivedEncoderBase):
    """
    Reified star view over objects and atoms.

    Each atom becomes a fact node connected to its argument object nodes via
    star (hub) edges; goal atoms are marked in the goal channel.

    The input must be a ``pymimir.Problem`` or ``pytyr.PlanningTask``.
    Domains are rejected because object tables are problem-scoped.
    """

    def __init__(
        self,
        problem: Any,
        *,
        backend: DerivedBackendName | str | None = None,
        include_reverse_edges: bool = True,
        export_node_names: bool = True,
    ) -> None:
        """Create a star-view derived-graph encoder for one problem."""
        config = _neutral_core.SemanticDerivedGraphEncoderConfig(
            node_universe="objects_and_atoms",
            atom_expansion="star",
            include_reverse_edges=include_reverse_edges,
            export_node_names=export_node_names,
        )
        super().__init__(problem, config, backend=backend)
        self.include_reverse_edges = include_reverse_edges
        self.export_node_names = export_node_names

    def stream(self) -> StarGraphEncoderStream:
        """Create a streaming encoder sharing this encoder's engine."""
        return StarGraphEncoderStream(self)

__init__(problem, *, backend=None, include_reverse_edges=True, export_node_names=True)

Create a star-view derived-graph encoder for one problem.

Source code in src/mifrost/encoders/derived.py
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
def __init__(
    self,
    problem: Any,
    *,
    backend: DerivedBackendName | str | None = None,
    include_reverse_edges: bool = True,
    export_node_names: bool = True,
) -> None:
    """Create a star-view derived-graph encoder for one problem."""
    config = _neutral_core.SemanticDerivedGraphEncoderConfig(
        node_universe="objects_and_atoms",
        atom_expansion="star",
        include_reverse_edges=include_reverse_edges,
        export_node_names=export_node_names,
    )
    super().__init__(problem, config, backend=backend)
    self.include_reverse_edges = include_reverse_edges
    self.export_node_names = export_node_names

stream()

Create a streaming encoder sharing this encoder's engine.

Source code in src/mifrost/encoders/derived.py
646
647
648
def stream(self) -> StarGraphEncoderStream:
    """Create a streaming encoder sharing this encoder's engine."""
    return StarGraphEncoderStream(self)

ObjectGraphEncoder

Bases: _DerivedEncoderBase

Objects-only projection with a configurable atom expansion.

Only object nodes are materialized; each atom connects its arguments according to atom_expansion:

  • "clique": fully connect the atom's arguments.
  • "chain": chain the arguments in order.
  • "star_first": hub on the first argument.

Arity-1 literals emit a unary_self loop and arity-0 literals a nullary_self loop on the trailing anchor node, so every instance leaves a labeled trace. Pairwise edges still cannot say which pairs belong to the same arity >= 3 literal, so this universe always carries the tuple instance table (include_tuple_tensors is forced on by the engine's config normalization) — that table is the authoritative, lossless instance list.

The input must be a pymimir.Problem or pytyr.PlanningTask. Domains are rejected because object tables are problem-scoped.

Source code in src/mifrost/encoders/derived.py
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
class ObjectGraphEncoder(_DerivedEncoderBase):
    """
    Objects-only projection with a configurable atom expansion.

    Only object nodes are materialized; each atom connects its arguments
    according to ``atom_expansion``:

    - ``"clique"``: fully connect the atom's arguments.
    - ``"chain"``: chain the arguments in order.
    - ``"star_first"``: hub on the first argument.

    Arity-1 literals emit a ``unary_self`` loop and arity-0 literals a
    ``nullary_self`` loop on the trailing anchor node, so every instance
    leaves a labeled trace. Pairwise edges still cannot say which pairs
    belong to the same arity >= 3 literal, so this universe *always* carries
    the tuple instance table (``include_tuple_tensors`` is forced on by the
    engine's config normalization) — that table is the authoritative,
    lossless instance list.

    The input must be a ``pymimir.Problem`` or ``pytyr.PlanningTask``.
    Domains are rejected because object tables are problem-scoped.
    """

    def __init__(
        self,
        problem: Any,
        *,
        atom_expansion: str = "clique",
        backend: DerivedBackendName | str | None = None,
        include_reverse_edges: bool = True,
        export_node_names: bool = True,
    ) -> None:
        """Create an objects-only derived-graph encoder for one problem."""
        config = _neutral_core.SemanticDerivedGraphEncoderConfig(
            node_universe="objects_only",
            atom_expansion=atom_expansion,
            include_reverse_edges=include_reverse_edges,
            export_node_names=export_node_names,
        )
        super().__init__(problem, config, backend=backend)
        self.atom_expansion = atom_expansion
        self.include_reverse_edges = include_reverse_edges
        self.export_node_names = export_node_names

    def _accepted_kwargs(self) -> set[str]:
        return super()._accepted_kwargs() | {"atom_expansion"}

    def _encode(
        self,
        state: StateInput,
        *,
        goals: GoalBatchInput = None,
        actions: ActionBatchInput = None,
        subgoal_layers: SubgoalLayersInput = None,
        history_subgoals: HistorySubgoalsBatchParam = None,
        history_max_steps: int | None = None,
        atom_expansion: str | None = None,
    ) -> HomoEncoding:
        self._check_atom_expansion(atom_expansion)
        return super()._encode(
            state,
            goals=goals,
            actions=actions,
            subgoal_layers=subgoal_layers,
            history_subgoals=history_subgoals,
            history_max_steps=history_max_steps,
        )

    def _encode_batch(
        self,
        states: StateBatchInput,
        *,
        goals: GoalBatchParam = None,
        actions: ActionBatchParam = None,
        subgoal_layers: SubgoalLayersBatchParam = None,
        history_subgoals: HistorySubgoalsBatchParam = None,
        history_max_steps: int | None = None,
        atom_expansion: str | None = None,
    ) -> HomoEncoding:
        self._check_atom_expansion(atom_expansion)
        return super()._encode_batch(
            states,
            goals=goals,
            actions=actions,
            subgoal_layers=subgoal_layers,
            history_subgoals=history_subgoals,
            history_max_steps=history_max_steps,
        )

    def _check_atom_expansion(self, atom_expansion: str | None) -> None:
        if atom_expansion is not None and atom_expansion != self.atom_expansion:
            raise ValueError(
                "atom_expansion is fixed at construction "
                f"(configured {self.atom_expansion!r}, got {atom_expansion!r})"
            )

    def stream(self) -> ObjectGraphEncoderStream:
        """Create a streaming encoder sharing this encoder's engine."""
        return ObjectGraphEncoderStream(self)

__init__(problem, *, atom_expansion='clique', backend=None, include_reverse_edges=True, export_node_names=True)

Create an objects-only derived-graph encoder for one problem.

Source code in src/mifrost/encoders/derived.py
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
def __init__(
    self,
    problem: Any,
    *,
    atom_expansion: str = "clique",
    backend: DerivedBackendName | str | None = None,
    include_reverse_edges: bool = True,
    export_node_names: bool = True,
) -> None:
    """Create an objects-only derived-graph encoder for one problem."""
    config = _neutral_core.SemanticDerivedGraphEncoderConfig(
        node_universe="objects_only",
        atom_expansion=atom_expansion,
        include_reverse_edges=include_reverse_edges,
        export_node_names=export_node_names,
    )
    super().__init__(problem, config, backend=backend)
    self.atom_expansion = atom_expansion
    self.include_reverse_edges = include_reverse_edges
    self.export_node_names = export_node_names

stream()

Create a streaming encoder sharing this encoder's engine.

Source code in src/mifrost/encoders/derived.py
754
755
756
def stream(self) -> ObjectGraphEncoderStream:
    """Create a streaming encoder sharing this encoder's engine."""
    return ObjectGraphEncoderStream(self)

AtomLineGraphEncoder

Bases: _DerivedEncoderBase

Atom line graph over the star universe.

Builds the star view (objects and atoms) and additionally connects co-occurring argument edges of high-degree atoms through line-share edges bounded by line_graph_max_degree.

The input must be a pymimir.Problem or pytyr.PlanningTask. Domains are rejected because object tables are problem-scoped.

Source code in src/mifrost/encoders/derived.py
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
class AtomLineGraphEncoder(_DerivedEncoderBase):
    """
    Atom line graph over the star universe.

    Builds the star view (objects and atoms) and additionally connects
    co-occurring argument edges of high-degree atoms through line-share
    edges bounded by ``line_graph_max_degree``.

    The input must be a ``pymimir.Problem`` or ``pytyr.PlanningTask``.
    Domains are rejected because object tables are problem-scoped.
    """

    def __init__(
        self,
        problem: Any,
        *,
        line_graph_max_degree: int = 32,
        backend: DerivedBackendName | str | None = None,
        include_reverse_edges: bool = True,
        export_node_names: bool = True,
    ) -> None:
        """Create an atom line-graph encoder for one problem."""
        config = _neutral_core.SemanticDerivedGraphEncoderConfig(
            node_universe="objects_and_atoms",
            atom_expansion="star",
            include_line_graph=True,
            include_reverse_edges=include_reverse_edges,
            line_graph_max_degree=line_graph_max_degree,
            export_node_names=export_node_names,
        )
        super().__init__(problem, config, backend=backend)
        self.line_graph_max_degree = line_graph_max_degree
        self.include_reverse_edges = include_reverse_edges
        self.export_node_names = export_node_names

    def stream(self) -> AtomLineGraphEncoderStream:
        """Create a streaming encoder sharing this encoder's engine."""
        return AtomLineGraphEncoderStream(self)

__init__(problem, *, line_graph_max_degree=32, backend=None, include_reverse_edges=True, export_node_names=True)

Create an atom line-graph encoder for one problem.

Source code in src/mifrost/encoders/derived.py
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
def __init__(
    self,
    problem: Any,
    *,
    line_graph_max_degree: int = 32,
    backend: DerivedBackendName | str | None = None,
    include_reverse_edges: bool = True,
    export_node_names: bool = True,
) -> None:
    """Create an atom line-graph encoder for one problem."""
    config = _neutral_core.SemanticDerivedGraphEncoderConfig(
        node_universe="objects_and_atoms",
        atom_expansion="star",
        include_line_graph=True,
        include_reverse_edges=include_reverse_edges,
        line_graph_max_degree=line_graph_max_degree,
        export_node_names=export_node_names,
    )
    super().__init__(problem, config, backend=backend)
    self.line_graph_max_degree = line_graph_max_degree
    self.include_reverse_edges = include_reverse_edges
    self.export_node_names = export_node_names

stream()

Create a streaming encoder sharing this encoder's engine.

Source code in src/mifrost/encoders/derived.py
801
802
803
def stream(self) -> AtomLineGraphEncoderStream:
    """Create a streaming encoder sharing this encoder's engine."""
    return AtomLineGraphEncoderStream(self)

HypergraphIncidenceEncoder

Bases: _DerivedEncoderBase

Hyperedge incidence view over objects and atoms.

Every encoded literal instance (static facts, state facts, goal and subgoal literals, history literals, grounded actions) becomes one hyperedge over its argument object nodes. encode_pyg restacks the native incidence fields into hyperedge_index / hyperedge_attr_ids so stock PyG hypergraph layers consume the output.

hyperedge_attr_ids is [M, 6] in x_ids column order (role, relation_id + 1, sign, goal level, history dt, category) — one label row per instance, not just its role. A zero-arity instance takes the anchor node as its single member, so no hyperedge is empty and hyperedge_index[1].max() + 1 == hyperedge_attr_ids.size(0) — exactly the edge count torch_geometric.nn.HypergraphConv infers when num_edges is not passed. num_hyperedges carries the authoritative per-graph count.

The input must be a pymimir.Problem or pytyr.PlanningTask. Domains are rejected because object tables are problem-scoped.

Source code in src/mifrost/encoders/derived.py
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
class HypergraphIncidenceEncoder(_DerivedEncoderBase):
    """
    Hyperedge incidence view over objects and atoms.

    Every encoded literal instance (static facts, state facts, goal and
    subgoal literals, history literals, grounded actions) becomes one
    hyperedge over its argument object nodes. ``encode_pyg`` restacks the
    native incidence fields into ``hyperedge_index`` /
    ``hyperedge_attr_ids`` so stock PyG hypergraph layers consume the output.

    ``hyperedge_attr_ids`` is ``[M, 6]`` in ``x_ids`` column order (role,
    ``relation_id + 1``, sign, goal level, history dt, category) — one label
    row per instance, not just its role. A zero-arity instance takes the
    anchor node as its single member, so no hyperedge is empty and
    ``hyperedge_index[1].max() + 1 == hyperedge_attr_ids.size(0)`` — exactly
    the edge count ``torch_geometric.nn.HypergraphConv`` infers when
    ``num_edges`` is not passed. ``num_hyperedges`` carries the authoritative
    per-graph count.

    The input must be a ``pymimir.Problem`` or ``pytyr.PlanningTask``.
    Domains are rejected because object tables are problem-scoped.
    """

    def __init__(
        self,
        problem: Any,
        *,
        backend: DerivedBackendName | str | None = None,
        include_reverse_edges: bool = True,
        export_node_names: bool = True,
    ) -> None:
        """Create a hyperedge-incidence derived-graph encoder for one problem."""
        config = _neutral_core.SemanticDerivedGraphEncoderConfig(
            node_universe="objects_and_atoms",
            atom_expansion="star",
            include_hyperedge_incidence=True,
            include_reverse_edges=include_reverse_edges,
            export_node_names=export_node_names,
        )
        super().__init__(problem, config, backend=backend)
        self.include_reverse_edges = include_reverse_edges
        self.export_node_names = export_node_names

    def _accepted_kwargs(self) -> set[str]:
        return super()._accepted_kwargs() | {"hyperedge"}

    def _check_hyperedge(self, hyperedge: bool | None) -> None:
        if hyperedge is not None and not hyperedge:
            raise ValueError(
                "hyperedge is fixed at construction "
                "(hyperedge incidence is always enabled)"
            )

    def _encode(
        self,
        state: StateInput,
        *,
        goals: GoalBatchInput = None,
        actions: ActionBatchInput = None,
        subgoal_layers: SubgoalLayersInput = None,
        history_subgoals: HistorySubgoalsBatchParam = None,
        history_max_steps: int | None = None,
        hyperedge: bool | None = None,
    ) -> HomoEncoding:
        self._check_hyperedge(hyperedge)
        return super()._encode(
            state,
            goals=goals,
            actions=actions,
            subgoal_layers=subgoal_layers,
            history_subgoals=history_subgoals,
            history_max_steps=history_max_steps,
        )

    def _encode_batch(
        self,
        states: StateBatchInput,
        *,
        goals: GoalBatchParam = None,
        actions: ActionBatchParam = None,
        subgoal_layers: SubgoalLayersBatchParam = None,
        history_subgoals: HistorySubgoalsBatchParam = None,
        history_max_steps: int | None = None,
        hyperedge: bool | None = None,
    ) -> HomoEncoding:
        self._check_hyperedge(hyperedge)
        return super()._encode_batch(
            states,
            goals=goals,
            actions=actions,
            subgoal_layers=subgoal_layers,
            history_subgoals=history_subgoals,
            history_max_steps=history_max_steps,
        )

    def stream(self) -> HypergraphIncidenceEncoderStream:
        """Create a streaming encoder sharing this engine."""
        return HypergraphIncidenceEncoderStream(self)

__init__(problem, *, backend=None, include_reverse_edges=True, export_node_names=True)

Create a hyperedge-incidence derived-graph encoder for one problem.

Source code in src/mifrost/encoders/derived.py
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
def __init__(
    self,
    problem: Any,
    *,
    backend: DerivedBackendName | str | None = None,
    include_reverse_edges: bool = True,
    export_node_names: bool = True,
) -> None:
    """Create a hyperedge-incidence derived-graph encoder for one problem."""
    config = _neutral_core.SemanticDerivedGraphEncoderConfig(
        node_universe="objects_and_atoms",
        atom_expansion="star",
        include_hyperedge_incidence=True,
        include_reverse_edges=include_reverse_edges,
        export_node_names=export_node_names,
    )
    super().__init__(problem, config, backend=backend)
    self.include_reverse_edges = include_reverse_edges
    self.export_node_names = export_node_names

stream()

Create a streaming encoder sharing this engine.

Source code in src/mifrost/encoders/derived.py
908
909
910
def stream(self) -> HypergraphIncidenceEncoderStream:
    """Create a streaming encoder sharing this engine."""
    return HypergraphIncidenceEncoderStream(self)

TupleTensorEncoder

Bases: _DerivedEncoderBase

Star view over objects and atoms with reified tuple channels.

Builds the star view (objects and atoms) and additionally exposes every encoded literal instance as a variable-arity tuple: tuple_args holds the argument node ids, tuple_sizes their per-tuple arity and tuple_ptr the CSR derived from it, while tuple_rel_ids / tuple_role_ids / tuple_sign_ids / tuple_level_ids / tuple_dt_ids / tuple_category_ids mirror the six x_ids channels one row per instance (also stacked as tuple_attr_ids).

Relation ids are now unified: tuple_rel_ids indexes vocab_relations, which is vocab_predicates ++ vocab_actions, so a predicate keeps id p and action schema a gets num_predicates + a. Action-role and predicate-role tuples can no longer collide, one Embedding(len(vocab_relations) + 1, ...) covers the whole channel, and num_predicates splits the space without string compares. The one remaining caveat is the -1 sentinel: tuple_rel_ids stores the raw relation id, using -1 for "no relation", whereas x_ids[:, 1] and tuple_attr_ids[:, 1] store relation_id + 1 with 0 meaning the same thing — shift before sharing an embedding table with x_ids.

The graph view is a set (a repeated instance interns to one node and emits its edges once) while this tuple table is a multiset: two identical goal literals produce two rows pointing at the same node. That is what makes the table, not the topology, the lossless record.

The input must be a pymimir.Problem or pytyr.PlanningTask. Domains are rejected because object tables are problem-scoped.

Source code in src/mifrost/encoders/derived.py
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
class TupleTensorEncoder(_DerivedEncoderBase):
    """
    Star view over objects and atoms with reified tuple channels.

    Builds the star view (objects and atoms) and additionally exposes every
    encoded literal instance as a variable-arity tuple: ``tuple_args`` holds
    the argument node ids, ``tuple_sizes`` their per-tuple arity and
    ``tuple_ptr`` the CSR derived from it, while ``tuple_rel_ids`` /
    ``tuple_role_ids`` / ``tuple_sign_ids`` / ``tuple_level_ids`` /
    ``tuple_dt_ids`` / ``tuple_category_ids`` mirror the six ``x_ids``
    channels one row per instance (also stacked as ``tuple_attr_ids``).

    Relation ids are now **unified**: ``tuple_rel_ids`` indexes
    ``vocab_relations``, which is ``vocab_predicates ++ vocab_actions``, so a
    predicate keeps id ``p`` and action schema ``a`` gets ``num_predicates +
    a``. Action-role and predicate-role tuples can no longer collide, one
    ``Embedding(len(vocab_relations) + 1, ...)`` covers the whole channel, and
    ``num_predicates`` splits the space without string compares. The one
    remaining caveat is the ``-1`` sentinel: ``tuple_rel_ids`` stores the
    *raw* relation id, using ``-1`` for "no relation", whereas ``x_ids[:, 1]``
    and ``tuple_attr_ids[:, 1]`` store ``relation_id + 1`` with ``0`` meaning
    the same thing — shift before sharing an embedding table with ``x_ids``.

    The graph view is a *set* (a repeated instance interns to one node and
    emits its edges once) while this tuple table is a *multiset*: two
    identical goal literals produce two rows pointing at the same node. That
    is what makes the table, not the topology, the lossless record.

    The input must be a ``pymimir.Problem`` or ``pytyr.PlanningTask``.
    Domains are rejected because object tables are problem-scoped.
    """

    def __init__(
        self,
        problem: Any,
        *,
        backend: DerivedBackendName | str | None = None,
        export_node_names: bool = True,
    ) -> None:
        """Create a tuple-channel derived-graph encoder for one problem."""
        config = _neutral_core.SemanticDerivedGraphEncoderConfig(
            node_universe="objects_and_atoms",
            atom_expansion="star",
            include_tuple_tensors=True,
            export_node_names=export_node_names,
        )
        super().__init__(problem, config, backend=backend)
        self.export_node_names = export_node_names

    def stream(self) -> TupleTensorEncoderStream:
        """Create a streaming encoder sharing this encoder's engine."""
        return TupleTensorEncoderStream(self)

__init__(problem, *, backend=None, export_node_names=True)

Create a tuple-channel derived-graph encoder for one problem.

Source code in src/mifrost/encoders/derived.py
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
def __init__(
    self,
    problem: Any,
    *,
    backend: DerivedBackendName | str | None = None,
    export_node_names: bool = True,
) -> None:
    """Create a tuple-channel derived-graph encoder for one problem."""
    config = _neutral_core.SemanticDerivedGraphEncoderConfig(
        node_universe="objects_and_atoms",
        atom_expansion="star",
        include_tuple_tensors=True,
        export_node_names=export_node_names,
    )
    super().__init__(problem, config, backend=backend)
    self.export_node_names = export_node_names

stream()

Create a streaming encoder sharing this encoder's engine.

Source code in src/mifrost/encoders/derived.py
969
970
971
def stream(self) -> TupleTensorEncoderStream:
    """Create a streaming encoder sharing this encoder's engine."""
    return TupleTensorEncoderStream(self)

TransformerBiasEncoder

Bases: _DerivedEncoderBase

Objects-only clique projection with shortest-path distance biases.

Only object nodes are materialized (clique atom expansion); every pair of objects connected through shared fact instances within spd_max_hops bipartite hops is reported via spd_src / spd_dst / spd_dist for transformer attention-bias consumption.

Being an objects_only view, it inherits that universe's contract: an anchor node is appended, and the tuple instance table is always carried (see :class:ObjectGraphEncoder). The anchor is not an object, so the spd_* lanes never reference it.

The input must be a pymimir.Problem or pytyr.PlanningTask. Domains are rejected because object tables are problem-scoped.

Source code in src/mifrost/encoders/derived.py
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
class TransformerBiasEncoder(_DerivedEncoderBase):
    """
    Objects-only clique projection with shortest-path distance biases.

    Only object nodes are materialized (clique atom expansion); every pair of
    objects connected through shared fact instances within ``spd_max_hops``
    bipartite hops is reported via ``spd_src`` / ``spd_dst`` / ``spd_dist``
    for transformer attention-bias consumption.

    Being an ``objects_only`` view, it inherits that universe's contract: an
    anchor node is appended, and the tuple instance table is always carried
    (see :class:`ObjectGraphEncoder`). The anchor is not an object, so the
    ``spd_*`` lanes never reference it.

    The input must be a ``pymimir.Problem`` or ``pytyr.PlanningTask``.
    Domains are rejected because object tables are problem-scoped.
    """

    def __init__(
        self,
        problem: Any,
        *,
        spd_max_hops: int = 4,
        backend: DerivedBackendName | str | None = None,
        include_reverse_edges: bool = True,
        export_node_names: bool = True,
    ) -> None:
        """Create an spd-annotated objects-only derived-graph encoder."""
        config = _neutral_core.SemanticDerivedGraphEncoderConfig(
            node_universe="objects_only",
            atom_expansion="clique",
            include_spd=True,
            spd_max_hops=spd_max_hops,
            include_reverse_edges=include_reverse_edges,
            export_node_names=export_node_names,
        )
        super().__init__(problem, config, backend=backend)
        self.spd_max_hops = spd_max_hops
        self.include_reverse_edges = include_reverse_edges
        self.export_node_names = export_node_names

    def stream(self) -> TransformerBiasEncoderStream:
        """Create a streaming encoder sharing this engine."""
        return TransformerBiasEncoderStream(self)

__init__(problem, *, spd_max_hops=4, backend=None, include_reverse_edges=True, export_node_names=True)

Create an spd-annotated objects-only derived-graph encoder.

Source code in src/mifrost/encoders/derived.py
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
def __init__(
    self,
    problem: Any,
    *,
    spd_max_hops: int = 4,
    backend: DerivedBackendName | str | None = None,
    include_reverse_edges: bool = True,
    export_node_names: bool = True,
) -> None:
    """Create an spd-annotated objects-only derived-graph encoder."""
    config = _neutral_core.SemanticDerivedGraphEncoderConfig(
        node_universe="objects_only",
        atom_expansion="clique",
        include_spd=True,
        spd_max_hops=spd_max_hops,
        include_reverse_edges=include_reverse_edges,
        export_node_names=export_node_names,
    )
    super().__init__(problem, config, backend=backend)
    self.spd_max_hops = spd_max_hops
    self.include_reverse_edges = include_reverse_edges
    self.export_node_names = export_node_names

stream()

Create a streaming encoder sharing this engine.

Source code in src/mifrost/encoders/derived.py
1022
1023
1024
def stream(self) -> TransformerBiasEncoderStream:
    """Create a streaming encoder sharing this engine."""
    return TransformerBiasEncoderStream(self)