planning-structs 0.1.0__tar.gz → 0.2.0__tar.gz

{planning_structs-0.1.0 → planning_structs-0.2.0}/CHANGELOG.md

@@ -6,6 +6,13 @@ All notable changes to this package are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-06
+
+### Added
+- `Trace.proposition_order` and `Trace.action_order` (optional): the data's own order of the entries
+  of vector states, and of the actions that integer actions refer to. Both default to `None`, so
+  existing code is unaffected.
+
 ## [0.1.0] - 2026-11-06
 
 First release, extracted from `rosame` 0.1.0 (`rosame.planning_structs`), where these structures were

{planning_structs-0.1.0 → planning_structs-0.2.0}/CITATION.cff

@@ -10,4 +10,4 @@ authors:
   - family-names: "Thiébaux"
     given-names: Sylvie
 repository-code: "https://github.com/xikaioliver/planning-structs"
-version: 0.1.0
+version: 0.2.0

{planning_structs-0.1.0 → planning_structs-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: planning-structs
-Version: 0.1.0
+Version: 0.2.0
 Summary: Typed STRIPS planning structures: domains, groundings, symbolic action models and traces
 Project-URL: Homepage, https://github.com/xikaioliver/planning-structs
 Project-URL: Issues, https://github.com/xikaioliver/planning-structs/issues
@@ -61,6 +61,13 @@ print(model)
 trace = Trace(objects=[("r1", "room"), ("r2", "room")],
               states=[["(robot-at r1)"], ["(robot-at r2)"]],
               actions=["(move r1 r2)"])
+
+# Data in its own order: name the entries of vector states and the actions integers refer to.
+trace = Trace(objects=[("r1", "room"), ("r2", "room")],
+              states=[[1.0, 0.0], [0.0, 1.0]],
+              actions=[0],
+              proposition_order=["(robot-at r1)", "(robot-at r2)"],
+              action_order=["(move r1 r2)", "(move r2 r1)"])
 ```
 
 ## Conventions

{planning_structs-0.1.0 → planning_structs-0.2.0}/README.md

@@ -39,6 +39,13 @@ print(model)
 trace = Trace(objects=[("r1", "room"), ("r2", "room")],
               states=[["(robot-at r1)"], ["(robot-at r2)"]],
               actions=["(move r1 r2)"])
+
+# Data in its own order: name the entries of vector states and the actions integers refer to.
+trace = Trace(objects=[("r1", "room"), ("r2", "room")],
+              states=[[1.0, 0.0], [0.0, 1.0]],
+              actions=[0],
+              proposition_order=["(robot-at r1)", "(robot-at r2)"],
+              action_order=["(move r1 r2)", "(move r2 r1)"])
 ```
 
 ## Conventions

{planning_structs-0.1.0 → planning_structs-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "planning-structs"
-version = "0.1.0"
+version = "0.2.0"
 description = "Typed STRIPS planning structures: domains, groundings, symbolic action models and traces"
 readme = "README.md"
 requires-python = ">=3.10"

{planning_structs-0.1.0 → planning_structs-0.2.0}/src/planning_structs/trace.py

@@ -10,7 +10,7 @@ Atoms and actions may be written "(in s1 r2)", "in s1 r2", ("in", "s1", "r2") or
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Sequence, Tuple
+from typing import Any, Optional, Sequence, Tuple
 
 
 @dataclass
@@ -20,13 +20,23 @@ class Trace:
     objects  [(name, type), ...]: every object the states and actions mention, including domain
              constants.
     states   T + 1 states. Each state is an iterable of true atoms, a dict {atom: probability} (atoms
-             not listed have probability 0), or a vector of probabilities over the propositions of
-             Instance(domain, objects), in their order; a whole [T + 1, P] array is also accepted.
-    actions  T actions; None marks an unknown action.
+             not listed have probability 0), or a vector of probabilities; a whole [T + 1, P] array
+             is also accepted. Vector entries follow `proposition_order` if given, otherwise the
+             propositions of Instance(domain, objects) in their order.
+    actions  T actions, each an action (e.g. "(move r1 r2)"), an integer, or None for an unknown
+             action. Integers index `action_order` if given, otherwise Instance(domain, objects).actions.
+
+    Optional, for data that comes in its own order:
+    proposition_order  the atoms naming the entries of vector states, in the data's order.
+    action_order       the actions that integer actions refer to, in the data's order.
+
+    These fields only describe the data; programs that consume traces resolve and validate them.
     """
     objects: Sequence[Tuple[str, str]]
     states: Any
     actions: Sequence[Any]
+    proposition_order: Optional[Sequence[Any]] = None
+    action_order: Optional[Sequence[Any]] = None
 
     def __post_init__(self) -> None:
         if hasattr(self.states, "__len__") and len(self.states) != len(self.actions) + 1:

planning_structs-0.2.0/tests/test_trace.py

@@ -0,0 +1,24 @@
+import pytest
+
+from planning_structs import Trace
+
+
+def test_trace_forms_and_length():
+    objs = [("r1", "room"), ("r2", "room")]
+    t = Trace(objs, [["(robot-at r1)"], {"(robot-at r2)": 0.9}], ["(move r1 r2)"])
+    assert t.length == 1
+    assert Trace(objs, [["(robot-at r1)"], ["(robot-at r1)"]], [None]).length == 1     # unknown action
+
+
+def test_states_must_be_one_more_than_actions():
+    with pytest.raises(ValueError):
+        Trace([("r1", "room")], [["(robot-at r1)"]], ["(move r1 r2)"])
+
+
+def test_optional_orders_default_to_none_and_are_kept():
+    objs = [("r1", "room"), ("r2", "room")]
+    plain = Trace(objs, [["(robot-at r1)"], ["(robot-at r2)"]], ["(move r1 r2)"])
+    assert plain.proposition_order is None and plain.action_order is None
+    ordered = Trace(objs, [[1.0, 0.0], [0.0, 1.0]], [0],
+                    proposition_order=["(robot-at r1)", "(robot-at r2)"], action_order=["(move r1 r2)"])
+    assert ordered.proposition_order == ["(robot-at r1)", "(robot-at r2)"] and ordered.action_order == ["(move r1 r2)"]

planning_structs-0.1.0/tests/test_trace.py

@@ -1,15 +0,0 @@
-import pytest
-
-from planning_structs import Trace
-
-
-def test_trace_forms_and_length():
-    objs = [("r1", "room"), ("r2", "room")]
-    t = Trace(objs, [["(robot-at r1)"], {"(robot-at r2)": 0.9}], ["(move r1 r2)"])
-    assert t.length == 1
-    assert Trace(objs, [["(robot-at r1)"], ["(robot-at r1)"]], [None]).length == 1     # unknown action
-
-
-def test_states_must_be_one_more_than_actions():
-    with pytest.raises(ValueError):
-        Trace([("r1", "room")], [["(robot-at r1)"]], ["(move r1 r2)"])