dynos-core 0.1.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
dynos_core/__init__.py ADDED
@@ -0,0 +1,26 @@
1
+ """dynos-core: pure-Python domain types shared by client and backend.
2
+
3
+ Core types are inert data. They store domain structure (predicates, transitions,
4
+ object types) but do not evaluate, plan, register with the backend, or import
5
+ planning and reasoning. The backend (dynos package) extends these types with planning
6
+ capabilities.
7
+ """
8
+
9
+ from .atom import GroundAtom, World
10
+ from .factories import FluentBase, make_new_fluent, make_new_object
11
+ from .transition import PrimitiveAction, Transition, TransitionParams
12
+ from .types import ObjectType, SymbolicObject, ValueField
13
+
14
+ __all__ = [
15
+ "GroundAtom",
16
+ "World",
17
+ "FluentBase",
18
+ "make_new_fluent",
19
+ "make_new_object",
20
+ "PrimitiveAction",
21
+ "Transition",
22
+ "TransitionParams",
23
+ "SymbolicObject",
24
+ "ObjectType",
25
+ "ValueField",
26
+ ]
dynos_core/atom.py ADDED
@@ -0,0 +1,105 @@
1
+ """Core GroundAtom and World types.
2
+
3
+ The backend extends GroundAtom with evaluation logic (eval_given(state)).
4
+ """
5
+
6
+ from typing import Any, Iterable, Optional
7
+
8
+
9
+ class GroundAtom:
10
+ """A ground first-order proposition: a predicate applied to domain objects.
11
+
12
+ Created by calling a fluent (predicate schema) with domain objects::
13
+
14
+ robot_at(room_one) -> GroundAtom("robot_at", (room_one,))
15
+
16
+ fluent_name and args are the primary representation. This class
17
+ is pure data; it stores a proposition but cannot evaluate it.
18
+ """
19
+
20
+ __slots__ = ("_fluent_name", "_args")
21
+
22
+ def __init__(self, fluent_name: str, args: Optional[tuple] = None) -> None:
23
+ self._fluent_name = fluent_name
24
+ self._args: tuple = args if args else ()
25
+
26
+ @property
27
+ def fluent_name(self) -> str:
28
+ """Name of the predicate, e.g. 'robot_at'."""
29
+ return self._fluent_name
30
+
31
+ @property
32
+ def args(self) -> tuple:
33
+ """The grounded domain-object arguments, e.g. (room_one,)."""
34
+ return self._args
35
+
36
+ @property
37
+ def atom_name(self) -> str:
38
+ """Canonical display string, e.g. 'robot_at(room_one)'."""
39
+ if self._args:
40
+ return f"{self._fluent_name}({', '.join(str(a) for a in self._args)})"
41
+ return self._fluent_name
42
+
43
+ def eval_given(self, world: "World") -> bool:
44
+ """Check if this atom is true in world (simple containment)."""
45
+ return self in world
46
+
47
+ def children(self) -> tuple:
48
+ """State-tree children (none; GroundAtom is a leaf node)."""
49
+ return ()
50
+
51
+ def __repr__(self) -> str:
52
+ return self.atom_name
53
+
54
+ def __str__(self) -> str:
55
+ return self.atom_name
56
+
57
+ def __eq__(self, other: object) -> bool:
58
+ if hasattr(other, "fluent_name") and hasattr(other, "args"):
59
+ return self._fluent_name == other.fluent_name and self._args == other.args
60
+ return NotImplemented
61
+
62
+ def __hash__(self) -> int:
63
+ return hash((self._fluent_name, self._args))
64
+
65
+
66
+ class World:
67
+ """An immutable set of ground atoms that are currently true.
68
+
69
+ Constructed from any iterable of GroundAtom::
70
+
71
+ world = World([robot_at(room_one), carrying(box_a)])
72
+
73
+ Supports set algebra (|, &, -), hashing, and equality.
74
+ """
75
+
76
+ def __init__(self, atoms: Iterable["GroundAtom"] = ()) -> None:
77
+ self._atoms: frozenset = frozenset(atoms)
78
+
79
+ def __contains__(self, atom: object) -> bool:
80
+ return atom in self._atoms
81
+
82
+ def __iter__(self):
83
+ return iter(self._atoms)
84
+
85
+ def __len__(self) -> int:
86
+ return len(self._atoms)
87
+
88
+ def __or__(self, other: "World") -> "World":
89
+ return World(self._atoms | other._atoms)
90
+
91
+ def __and__(self, other: "World") -> "World":
92
+ return World(self._atoms & other._atoms)
93
+
94
+ def __sub__(self, other: "World") -> "World":
95
+ return World(self._atoms - other._atoms)
96
+
97
+ def __eq__(self, other: object) -> bool:
98
+ return isinstance(other, World) and self._atoms == other._atoms
99
+
100
+ def __hash__(self) -> int:
101
+ return hash(self._atoms)
102
+
103
+ def __repr__(self) -> str:
104
+ names = sorted(a.atom_name for a in self._atoms)
105
+ return f"World({{{', '.join(names)}}})"
@@ -0,0 +1,183 @@
1
+ """Frontend-to-backend class-extension helpers.
2
+
3
+ `dynos-sentry-domain` ships a tight public API to end users:
4
+ ``Zone``, ``Coordinate``, and ``SurveyParams`` declare only the
5
+ user-visible fields. The backend needs more; ``Coordinate`` with
6
+ ``altitude`` / ``depth`` for trackline rendering, ``SurveyParams``
7
+ with planner-visible ``entry`` / ``exit`` coordinates for zone
8
+ chaining.
9
+
10
+ This module provides the *only* supported way to add fields to a
11
+ publicly-declared ``ObjectType`` or ``TransitionParams`` from
12
+ backend code. It is called from modules the publish script stubs
13
+ out (currently ``dynos_sentry._vehicle``), so extensions **disappear
14
+ from the public wheel**; the stub runs zero extension calls, and
15
+ the shipped classes stay minimal.
16
+
17
+ Rules:
18
+
19
+ * **Additive only.** Extensions never overwrite an existing field;
20
+ duplicate names raise ``FieldAlreadyDeclaredError``.
21
+ * **Import-time.** Call extension helpers at module load, before
22
+ any plan construction consumes the class. They mutate the target
23
+ class in place and also rebind it in its owner module when the
24
+ rebind changes class identity (TransitionParams case; see below).
25
+ * **`ObjectType`** extensions mutate ``cls._value_fields`` and
26
+ ``setattr`` a descriptor for each new field. ``make_new_object``
27
+ re-reads ``_value_fields`` on every call, so extensions propagate
28
+ automatically. Existing instances (if any) get the new fields'
29
+ accessors through the class descriptor; their stored
30
+ ``_field_values`` dict simply won't have values for extended
31
+ fields until one is written.
32
+ * **`TransitionParams`** extensions are subclass-based: we build a
33
+ new frozen dataclass inheriting from ``cls`` with the extra
34
+ fields and rebind the old name in its owning module. Any
35
+ ``Transition`` instance that captured the original class as
36
+ ``_params_type`` is patched in place (through the weak registry
37
+ in ``dynos_core.transition``) so ``transition.params.<new_field>``
38
+ resolves on the extended schema.
39
+
40
+ Ordering constraint that ships as a Python comment in the target
41
+ module: extension calls MUST precede any Transition.define() that
42
+ references the new fields via ``t.params.<new_field>()``, because
43
+ ``define()`` resolves the param placeholders against the current
44
+ accessor. The stub-on-publish design means the constraint only
45
+ bites in the backend tree; public installs skip the whole path.
46
+ """
47
+
48
+ from __future__ import annotations
49
+
50
+ import dataclasses
51
+ import sys
52
+ from typing import Any, Dict, Type
53
+
54
+ from dynos_core.types import ObjectType, ValueField
55
+ from dynos_core.transition import (
56
+ Transition,
57
+ TransitionParams,
58
+ _TRANSITION_REGISTRY,
59
+ )
60
+
61
+
62
+ class ExtensionError(RuntimeError):
63
+ """Base class for extension-machinery failures."""
64
+
65
+
66
+ class FieldAlreadyDeclaredError(ExtensionError):
67
+ """Raised when an extension tries to add a field the target class
68
+ already declares. Extensions are additive only."""
69
+
70
+
71
+ class InvalidExtensionTargetError(ExtensionError):
72
+ """Raised when the target class isn't a supported extension target
73
+ (an ObjectType subclass or a TransitionParams subclass)."""
74
+
75
+
76
+ def extend_object_type(
77
+ cls: Type[ObjectType],
78
+ *,
79
+ equivalence: Any = None,
80
+ **fields: ValueField,
81
+ ) -> Type[ObjectType]:
82
+ """Add ``ValueField`` descriptors and/or an equivalence lambda to
83
+ an ``ObjectType`` subclass in place.
84
+
85
+ Returns ``cls`` for caller convenience. Safe to call multiple
86
+ times with disjoint field sets; duplicate names raise.
87
+ """
88
+ if not (isinstance(cls, type) and issubclass(cls, ObjectType)):
89
+ raise InvalidExtensionTargetError(
90
+ f"extend_object_type: {cls!r} is not an ObjectType subclass"
91
+ )
92
+
93
+ value_fields: Dict[str, type] = getattr(cls, "_value_fields", {})
94
+
95
+ for name, vf in fields.items():
96
+ if not isinstance(vf, ValueField):
97
+ raise InvalidExtensionTargetError(
98
+ f"extend_object_type: {name!r} must be a ValueField, "
99
+ f"got {type(vf).__name__}"
100
+ )
101
+ if name in value_fields:
102
+ raise FieldAlreadyDeclaredError(
103
+ f"extend_object_type: {cls.__name__}.{name} is already "
104
+ f"declared; extensions are additive only."
105
+ )
106
+ # ``__set_name__`` normally runs at class-body evaluation time;
107
+ # call it manually so the descriptor knows its name.
108
+ vf.__set_name__(cls, name)
109
+ setattr(cls, name, vf)
110
+ value_fields[name] = vf._field_type
111
+
112
+ # Store (possibly-new) dict on the class; if it was inherited, we
113
+ # want our own copy on this class so we don't mutate a parent's.
114
+ cls._value_fields = value_fields
115
+
116
+ if equivalence is not None:
117
+ setattr(cls, "equivalence", equivalence)
118
+
119
+ return cls
120
+
121
+
122
+ def extend_transition_params(
123
+ cls: Type[TransitionParams],
124
+ **new_fields: type,
125
+ ) -> Type[TransitionParams]:
126
+ """Add typed fields to a ``TransitionParams`` subclass.
127
+
128
+ Builds a new frozen dataclass inheriting from ``cls`` with the
129
+ extra fields, rebinds the name in ``cls.__module__`` so
130
+ subsequent imports see the extended version, and patches every
131
+ live ``Transition`` instance whose ``_params_type`` captured the
132
+ original class.
133
+
134
+ Returns the new class for caller convenience.
135
+ """
136
+ if not (isinstance(cls, type) and issubclass(cls, TransitionParams)):
137
+ raise InvalidExtensionTargetError(
138
+ f"extend_transition_params: {cls!r} is not a "
139
+ f"TransitionParams subclass"
140
+ )
141
+
142
+ existing = set(cls.__dataclass_fields__)
143
+ for name in new_fields:
144
+ if name in existing:
145
+ raise FieldAlreadyDeclaredError(
146
+ f"extend_transition_params: {cls.__name__}.{name} is "
147
+ f"already declared; extensions are additive only."
148
+ )
149
+
150
+ # Build the extended class. Construct via ``type()`` with a
151
+ # namespace carrying the new fields as ``__annotations__``;
152
+ # ``TransitionParams.__init_subclass__`` then applies
153
+ # ``@dataclass(frozen=True)`` for us as part of normal subclass
154
+ # processing. Don't use ``dataclasses.make_dataclass`` because
155
+ # it applies ``@dataclass`` eagerly and then
156
+ # ``__init_subclass__`` applies it a second time; on Python 3.8
157
+ # that hits ``TypeError: Cannot overwrite attribute __setattr__``.
158
+ namespace = {
159
+ "__annotations__": dict(new_fields),
160
+ "__module__": cls.__module__,
161
+ "__qualname__": cls.__qualname__,
162
+ }
163
+ new_cls = type(cls.__name__, (cls,), namespace)
164
+
165
+ # Rebind the name in the owning module so ``from <owner> import
166
+ # <Name>`` returns the new class after this call.
167
+ owner_module = sys.modules.get(cls.__module__)
168
+ if owner_module is not None:
169
+ setattr(owner_module, cls.__name__, new_cls)
170
+
171
+ # Patch every live Transition whose _params_type is the old
172
+ # class. Backend Transition has a _rebuild_params_accessor
173
+ # helper that rebuilds a fresh ParamsAccessor; core Transition
174
+ # just updates _params_type and lets the permissive
175
+ # _CoreParamsAccessor continue to work.
176
+ for t in list(_TRANSITION_REGISTRY):
177
+ if getattr(t, "_params_type", None) is cls:
178
+ t._params_type = new_cls
179
+ rebuild = getattr(t, "_rebuild_params_accessor", None)
180
+ if callable(rebuild):
181
+ rebuild()
182
+
183
+ return new_cls
@@ -0,0 +1,67 @@
1
+ """Core factory functions for domain construction.
2
+
3
+ Pure-Python factories with no backend dependency.
4
+ make_new_fluent returns a FluentBase (callable that produces
5
+ GroundAtom). make_new_object returns a SymbolicObject. Neither
6
+ performs any registration; that is the backend's responsibility.
7
+ """
8
+
9
+ from typing import Any, Optional
10
+
11
+ from dynos_core.atom import GroundAtom
12
+ from dynos_core.types import SymbolicObject
13
+
14
+
15
+ class FluentBase:
16
+ """Client-side fluent: calling it returns a GroundAtom."""
17
+
18
+ def __init__(self, name: str, _default: bool = False, **arg_types: Any) -> None:
19
+ self._name = name
20
+ self._default = _default
21
+ self._arg_types = arg_types
22
+
23
+ def __call__(self, *args: Any, **kwargs: Any) -> GroundAtom:
24
+ all_args = args + tuple(kwargs.values())
25
+ return GroundAtom(fluent_name=self._name, args=all_args)
26
+
27
+ @property
28
+ def name(self) -> str:
29
+ return self._name
30
+
31
+ @property
32
+ def arity(self) -> int:
33
+ return len(self._arg_types)
34
+
35
+ def __str__(self) -> str:
36
+ return self._name
37
+
38
+ def __repr__(self) -> str:
39
+ return f"FluentBase({self._name!r})"
40
+
41
+
42
+ def make_new_fluent(name: Optional[str] = None, default: bool = False, **arg_types: Any) -> FluentBase:
43
+ """Create a fluent (predicate schema).
44
+
45
+ Returns a FluentBase callable. No backend registration occurs.
46
+ The *default* flag is stored on the fluent for the backend adapter to read.
47
+ """
48
+ return FluentBase(name=name, _default=default, **arg_types)
49
+
50
+
51
+ def make_new_object(type_cls: Any, name: Optional[str] = None, **values: Any) -> SymbolicObject:
52
+ """Create a domain object reference.
53
+
54
+ Returns a SymbolicObject. No backend registration occurs.
55
+ Uses varname for name inference when *name* is not provided.
56
+ """
57
+ type_name = (
58
+ getattr(type_cls, "_domain_type_name", None)
59
+ or getattr(type_cls, "__name__", str(type_cls)).lower()
60
+ )
61
+ if name is None:
62
+ try:
63
+ from varname.core import varname as _varname
64
+ name = _varname()
65
+ except Exception:
66
+ name = type_name
67
+ return SymbolicObject(name=name, type_name=type_name)
@@ -0,0 +1,237 @@
1
+ """Core Transition and TransitionParams types.
2
+
3
+ Pure-Python data model with no backend dependency.
4
+ The backend extends Transition with planning integration (cost, action
5
+ building, domain attachment, applicability checking). Core Transition is
6
+ an inert schema that stores preconditions and effects as lists.
7
+ """
8
+
9
+ import weakref
10
+ from dataclasses import dataclass
11
+ from typing import Any, Dict, List, Optional
12
+
13
+ # Every ``Transition`` registers itself here on ``__init__``. Used by
14
+ # ``dynos_core.extension.extend_transition_params`` to find instances
15
+ # that captured a now-extended params class as ``_params_type`` and
16
+ # rebind them to the new class. WeakSet so garbage-collected
17
+ # Transitions don't leak.
18
+ _TRANSITION_REGISTRY: "weakref.WeakSet" = weakref.WeakSet()
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class PrimitiveAction:
23
+ """A named action with string-valued parameters. Pure data."""
24
+
25
+ action_name: str
26
+ parameters: Dict[str, str]
27
+
28
+ def to_dict(self) -> dict:
29
+ return {"action_name": self.action_name, "parameters": self.parameters}
30
+
31
+ @classmethod
32
+ def from_dict(cls, d: dict) -> "PrimitiveAction":
33
+ return cls(action_name=d["action_name"], parameters=d.get("parameters", {}))
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class TransitionParams:
38
+ """Base class for transition parameter dataclasses.
39
+
40
+ Subclasses get @dataclass(frozen=True) applied automatically if they
41
+ haven't been decorated already.
42
+ """
43
+
44
+ def __init_subclass__(cls, **kwargs: Any) -> None:
45
+ super().__init_subclass__(**kwargs)
46
+ if "__dataclass_fields__" not in cls.__dict__:
47
+ dataclass(frozen=True)(cls)
48
+
49
+ @classmethod
50
+ def field_names(cls) -> List[str]:
51
+ return list(cls.__dataclass_fields__.keys())
52
+
53
+ def to_dict(self) -> Dict[str, str]:
54
+ """Serialize all fields to a string-keyed dict."""
55
+ result: Dict[str, str] = {}
56
+ for k in self.field_names():
57
+ v = getattr(self, k)
58
+ if hasattr(v, "to_str"):
59
+ result[k] = v.to_str()
60
+ elif hasattr(v, "name"):
61
+ result[k] = str(v.name)
62
+ else:
63
+ result[k] = str(v)
64
+ return result
65
+
66
+ @classmethod
67
+ def from_dict(cls, d: Dict[str, Any]) -> "TransitionParams":
68
+ """Reconstruct from a string-keyed dict.
69
+
70
+ String values whose field type is an ObjectType subclass are
71
+ wrapped via the type constructor (e.g. Room("room_one")).
72
+ This matches the backend's richer from_dict behavior.
73
+ """
74
+ import typing
75
+
76
+ try:
77
+ hints = typing.get_type_hints(cls)
78
+ except Exception:
79
+ hints = {}
80
+
81
+ kwargs: Dict[str, Any] = {}
82
+ for k in cls.field_names():
83
+ if k not in d:
84
+ continue
85
+ value = d[k]
86
+ hint = hints.get(k)
87
+ # Wrap string values when the type hint is an ObjectType subclass
88
+ if (
89
+ isinstance(value, str)
90
+ and hint is not None
91
+ and isinstance(hint, type)
92
+ and hasattr(hint, "_domain_type_name")
93
+ ):
94
+ value = hint(value)
95
+ kwargs[k] = value
96
+ return cls(**kwargs)
97
+
98
+
99
+ class _ParamPlaceholder:
100
+ """Returned by _CoreParamsAccessor.fieldname; str() == field name."""
101
+
102
+ def __init__(self, name: str) -> None:
103
+ self._name = name
104
+
105
+ @property
106
+ def name(self) -> str:
107
+ return self._name
108
+
109
+ def __call__(self) -> "_ParamPlaceholder":
110
+ return self
111
+
112
+ def __str__(self) -> str:
113
+ return self._name
114
+
115
+ def __repr__(self) -> str:
116
+ return f"<param:{self._name}>"
117
+
118
+ def __eq__(self, other: object) -> bool:
119
+ if isinstance(other, _ParamPlaceholder):
120
+ return self._name == other._name
121
+ return NotImplemented
122
+
123
+ def __hash__(self) -> int:
124
+ return hash(self._name)
125
+
126
+
127
+ class _CoreParamsAccessor:
128
+ """Thin params accessor: any attribute returns a _ParamPlaceholder."""
129
+
130
+ def __getattr__(self, name: str) -> _ParamPlaceholder:
131
+ if name.startswith("_"):
132
+ raise AttributeError(name)
133
+ return _ParamPlaceholder(name)
134
+
135
+
136
+ class Transition:
137
+ """A named transition schema storing preconditions and effects.
138
+
139
+ This is the core data model. It does not evaluate or plan. The backend
140
+ extends this class with planning capabilities (cost, action building,
141
+ domain attachment, applicability).
142
+ """
143
+
144
+ def __init__(
145
+ self,
146
+ name: Optional[str] = None,
147
+ params_type: Optional[type] = None,
148
+ **kwargs: Any,
149
+ ) -> None:
150
+ if not name:
151
+ from varname.core import varname as _varname
152
+ name = _varname()
153
+ if not name:
154
+ raise AttributeError(name)
155
+ self._name = name
156
+
157
+ self._params_type = params_type
158
+ self._params_accessor = _CoreParamsAccessor()
159
+
160
+ # Planning data (stored by define(), read by backend at registration)
161
+ self._preconditions: List[Any] = []
162
+ self._effects_pos: List[Any] = []
163
+ self._effects_neg: List[Any] = []
164
+ self._effects_pos_cond: List[Any] = [] # (effect, condition) tuples
165
+ self._completes_when: Any = None
166
+ self._fails_when: Any = None
167
+
168
+ # Extension registry: allows
169
+ # ``dynos_core.extension.extend_transition_params`` to find
170
+ # this instance later and rebind its ``_params_type`` if the
171
+ # params class gets extended.
172
+ _TRANSITION_REGISTRY.add(self)
173
+
174
+ @property
175
+ def name(self) -> str:
176
+ return self._name
177
+
178
+ @property
179
+ def params_type(self) -> Optional[type]:
180
+ return self._params_type
181
+
182
+ @property
183
+ def params(self) -> _CoreParamsAccessor:
184
+ """Params accessor: .fieldname() returns a placeholder for define()."""
185
+ return self._params_accessor
186
+
187
+ @property
188
+ def preconditions(self) -> List[Any]:
189
+ return self._preconditions
190
+
191
+ @property
192
+ def effects_pos(self) -> List[Any]:
193
+ return self._effects_pos
194
+
195
+ @property
196
+ def effects_neg(self) -> List[Any]:
197
+ return self._effects_neg
198
+
199
+ @property
200
+ def effects_pos_cond(self) -> List[Any]:
201
+ """List of (effect, condition) tuples representing conditional effects."""
202
+ return self._effects_pos_cond
203
+
204
+ @property
205
+ def completes_when(self) -> Any:
206
+ return self._completes_when
207
+
208
+ @property
209
+ def fails_when(self) -> Any:
210
+ return self._fails_when
211
+
212
+ def define(
213
+ self,
214
+ preconditions: Any = (),
215
+ adds: Any = (),
216
+ removes: Any = (),
217
+ adds_conditional: Any = (),
218
+ completes_when: Any = None,
219
+ fails_when: Any = None,
220
+ **kwargs: Any,
221
+ ) -> "Transition":
222
+ """Store planning data. Read by the backend at registration time.
223
+
224
+ ``adds_conditional`` carries ``(effect, condition)`` tuples that
225
+ the backend writer emits as conditional effects. The core
226
+ Transition just stores them; no interpretation at this layer.
227
+ """
228
+ self._preconditions = list(preconditions)
229
+ self._effects_pos = list(adds)
230
+ self._effects_neg = list(removes)
231
+ self._effects_pos_cond = list(adds_conditional or ())
232
+ self._completes_when = completes_when
233
+ self._fails_when = fails_when
234
+ return self
235
+
236
+ def __repr__(self) -> str:
237
+ return f"Transition(name={self._name!r})"
dynos_core/types.py ADDED
@@ -0,0 +1,172 @@
1
+ """Core ObjectType, ValueField, and SymbolicObject types.
2
+
3
+ Pure-Python type declarations with no backend, planner, or vehicle dependency.
4
+ The backend extends ObjectType with planning type registration, ObjectRef
5
+ integration, and FieldAccessor with NumericBeliefDatabase read/write.
6
+ Core types are inert descriptors and lightweight references.
7
+ """
8
+
9
+ from typing import Any, Optional
10
+
11
+
12
+ class SymbolicObject:
13
+ """A named domain object. str(obj) == obj.name.
14
+
15
+ The backend extends this with first-order logic planning integration and
16
+ NumericBeliefDatabase access.
17
+ """
18
+
19
+ def __init__(self, name: str, type_name: str) -> None:
20
+ self._name = name
21
+ self._type_name = type_name
22
+
23
+ @property
24
+ def name(self) -> str:
25
+ return self._name
26
+
27
+ def __str__(self) -> str:
28
+ return self._name
29
+
30
+ def __repr__(self) -> str:
31
+ return f"{self._type_name}({self._name!r})"
32
+
33
+ def __eq__(self, other: object) -> bool:
34
+ if isinstance(other, SymbolicObject):
35
+ return self._name == other._name
36
+ if hasattr(other, "name"):
37
+ return self._name == str(other.name)
38
+ return NotImplemented
39
+
40
+ def __hash__(self) -> int:
41
+ return hash(self._name)
42
+
43
+ def to_str(self) -> str:
44
+ return self._name
45
+
46
+
47
+ class _ThinFieldAccessor:
48
+ """Read-only field accessor for core ObjectType instances.
49
+
50
+ Only reads from the _field_values dict stored directly on the object.
51
+ The backend extends this with NumericBeliefDatabase integration and write
52
+ support.
53
+ """
54
+
55
+ def __init__(self, obj: Any, field_name: str) -> None:
56
+ self._obj = obj
57
+ self._field_name = field_name
58
+
59
+ def get(self) -> Any:
60
+ fv = getattr(self._obj, "_field_values", None)
61
+ if fv is not None:
62
+ return fv.get(self._field_name)
63
+ return None
64
+
65
+ def __repr__(self) -> str:
66
+ return f"ThinFieldAccessor({self._field_name!r})"
67
+
68
+
69
+ class ValueField:
70
+ """Descriptor for ObjectType value fields.
71
+
72
+ In core, this supports frozen-dataclass mode only:
73
+ Coordinate(latitude=5.0) stores values in _field_values;
74
+ accessing coord.latitude returns a _ThinFieldAccessor.
75
+ The backend extends this with full read/write NumericBeliefDatabase support.
76
+ """
77
+
78
+ def __init__(self, field_type: type) -> None:
79
+ self._field_type = field_type
80
+ self._name: str = ""
81
+
82
+ def __set_name__(self, owner: type, name: str) -> None:
83
+ self._name = name
84
+
85
+ def __get__(self, obj: Any, objtype: Any = None) -> Any:
86
+ if obj is None:
87
+ return self
88
+ return _ThinFieldAccessor(obj, self._name)
89
+
90
+
91
+ class ObjectType:
92
+ """Base class for domain object types (core version).
93
+
94
+ Subclasses declare value fields via ValueField descriptors::
95
+
96
+ class Box(ObjectType, type_name="box"):
97
+ weight = ValueField(float)
98
+
99
+ The backend extends it with planning and numerics functions.
100
+ """
101
+
102
+ _domain_type_name: str = ""
103
+
104
+ def __init_subclass__(cls, type_name: Optional[str] = None, **kwargs: Any) -> None:
105
+ super().__init_subclass__(**kwargs)
106
+ cls._domain_type_name = (
107
+ type_name if type_name is not None else cls.__name__.lower()
108
+ )
109
+ cls._value_fields = {
110
+ name: val._field_type
111
+ for name, val in cls.__dict__.items()
112
+ if isinstance(val, ValueField)
113
+ }
114
+
115
+ class _NameDescriptor:
116
+ """Class-level: returns type name. Instance-level: returns instance name."""
117
+
118
+ def __get__(self, obj: Any, objtype: Any = None) -> str:
119
+ if obj is None:
120
+ return objtype._domain_type_name
121
+ return getattr(obj, "_instance_name", obj._domain_type_name)
122
+
123
+ name = _NameDescriptor()
124
+
125
+ def __init__(self, value: Any = None, type_name: Optional[str] = None, **kwargs: Any) -> None:
126
+ if isinstance(value, str):
127
+ object.__setattr__(self, "_instance_name", value)
128
+ elif hasattr(value, "name"):
129
+ object.__setattr__(self, "_instance_name", str(value.name))
130
+ elif value is not None:
131
+ object.__setattr__(self, "_instance_name", str(value))
132
+ if kwargs:
133
+ object.__setattr__(self, "_field_values", kwargs)
134
+
135
+ def to_str(self) -> str:
136
+ """Return the instance name (mirrors ObjectRef.to_str() API)."""
137
+ return getattr(self, "_instance_name", self._domain_type_name)
138
+
139
+ def __str__(self) -> str:
140
+ """``str(instance)`` is the instance name. Backend callsites
141
+ like ``Orchestrator.get_geojson`` take ``str(grounded_param)``
142
+ to key into ``list_objects(type_filter="coordinate")``; they
143
+ need the instance name, not Python's default ``<X object at ...>``
144
+ repr. ``__repr__`` matches because that's what shows up in
145
+ ``Transition`` debug output and makes plan dumps readable."""
146
+ return getattr(self, "_instance_name", self._domain_type_name)
147
+
148
+ def __repr__(self) -> str:
149
+ return getattr(self, "_instance_name", self._domain_type_name)
150
+
151
+ def to_python(self) -> str:
152
+ """Emit the Python source expression to recreate this object."""
153
+ cls = type(self)
154
+ parts = []
155
+ value_fields = getattr(cls, "_value_fields", None)
156
+ field_values = getattr(self, "_field_values", None)
157
+ if value_fields is not None and field_values is not None:
158
+ for field_name in value_fields:
159
+ if field_name not in field_values:
160
+ continue
161
+ val: Any = field_values[field_name]
162
+ if hasattr(val, "to_python"):
163
+ parts.append(f"{field_name}={val.to_python()}")
164
+ elif isinstance(val, list):
165
+ items = [
166
+ v.to_python() if hasattr(v, "to_python") else repr(v)
167
+ for v in val
168
+ ]
169
+ parts.append(f"{field_name}=[{', '.join(items)}]")
170
+ else:
171
+ parts.append(f"{field_name}={repr(val)}")
172
+ return f"{cls.__name__}({', '.join(parts)})"
@@ -0,0 +1,152 @@
1
+ Metadata-Version: 2.1
2
+ Name: dynos-core
3
+ Version: 0.1.2
4
+ Summary: Core symbolic-planning types and protocols shared by DYNOS packages
5
+ License: Apache-2.0
6
+ Requires-Python: >=3.8
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: varname
9
+
10
+ # dynos-core
11
+
12
+ Pure-Python types for describing a planning domain. Predicates, transitions,
13
+ object types, and the world states they describe. `dynos-core` is the data
14
+ layer that every other DYNOS package shares.
15
+
16
+ This contains no planner, no executor, and no network code, it's just classes
17
+ that define a domain. The DYNOS backend reads these structures to
18
+ plan/execute/monitor/verify, clients read them to talk about goals, both share
19
+ the same in-memory representation.
20
+
21
+ Most users do not install `dynos-core` directly, You get it transitively when
22
+ you `pip install dynos-client` (or any package above it). Install it on its own
23
+ if you are authoring a new domain (or extending a new one, like when making
24
+ custom actions) and want the lowest-level types without pulling in the HTTP
25
+ client.
26
+
27
+ ## Install
28
+
29
+ ```bash
30
+ pip install dynos-core
31
+ ```
32
+
33
+ Single dependency: `varname`. This is used to infer the names of objects being
34
+ created.
35
+
36
+ ## Concepts
37
+
38
+ DYNOS describes the world as a set of named facts (fluents) about typed
39
+ objects. A goal is a state of those facts; a plan is a sequence of transitions
40
+ that move from one state to another. Actions are specific code implementations
41
+ of transitions.
42
+
43
+ ### Fluents and ground atoms
44
+
45
+ A fluent is a named, parameterised proposition. `make_new_fluent` creates one;
46
+ calling it on specific objects creates a `GroundAtom`. This is a fluent
47
+ applied to particular arguments.
48
+
49
+ ```python
50
+ from dynos_core import make_new_fluent, ObjectType, World
51
+
52
+ class Robot(ObjectType): ...
53
+ class Room(ObjectType): ...
54
+
55
+ at = make_new_fluent("at", robot=Robot, room=Room)
56
+ r = Robot("r1")
57
+ kitchen = Room("kitchen")
58
+
59
+ current = World({at(r, kitchen)})
60
+ print(at(r, kitchen) in current) # True
61
+ ```
62
+
63
+ A `World` is a frozenset of `GroundAtom` describing what is currently true. In
64
+ the current implementation, anything not in the set is false (closed-world
65
+ assumption), but more principled approaches are being designed.
66
+
67
+ ### Object types and value fields
68
+
69
+ An `ObjectType` is a category of thing in the domain. For example, Robot, Room,
70
+ Zone, Coordinate. `ValueField` descriptors attach typed numeric/string fields:
71
+
72
+ ```python
73
+ from dynos_core import ObjectType, ValueField
74
+
75
+ class Zone(ObjectType):
76
+ altitude = ValueField(float)
77
+ vertices = ValueField(list)
78
+ ```
79
+
80
+ The class is pure Python; instances live in a backend-managed numeric database
81
+ at runtime, accessible through the same descriptor syntax
82
+ (`zone.altitude.get()` / `.set(70.0)`). `dynos-core` only declares the schema.
83
+
84
+ ### Transitions
85
+
86
+ A `Transition` is an action *schema*: name, parameter type, preconditions,
87
+ effects. It says nothing about how the action runs.
88
+
89
+ ```python
90
+ from dynos_core import Transition, TransitionParams
91
+
92
+ class GotoParams(TransitionParams):
93
+ start: Room
94
+ end: Room
95
+
96
+ goto = Transition("goto", params_type=GotoParams).define(
97
+ preconditions=[at(GotoParams.start)],
98
+ adds=[at(GotoParams.end)],
99
+ removes=[at(GotoParams.start)],
100
+ )
101
+ ```
102
+
103
+ The `define()` call stores the symbolic spec on the transition. The `dynos`
104
+ backend extends `Transition` with cost callbacks, applicability checks, and
105
+ execution hooks; this package's `Transition` is just data.
106
+
107
+ ### Extensions
108
+
109
+ `extend_object_type` and `extend_transition_params` add fields after the class
110
+ is declared. This supports the *publish-stub* pattern: a domain package
111
+ declares a small public schema; the backend extends it with private fields at
112
+ import time. The public release strips the extension calls so users see only
113
+ the public surface.
114
+
115
+ ```python
116
+ from dynos_core.extension import extend_object_type
117
+ extend_object_type(Zone, depth=ValueField(float)) # backend-only addition
118
+ ```
119
+
120
+ See `extension.py` for the full rules (additive only, must run before any plan construction, etc.).
121
+
122
+ ## What dynos-core does NOT do
123
+
124
+ - No planner. The actual planning lives in the `dynos` backend (not on PyPI).
125
+ - No `@Action` / `@Belief` / `@Script` decorators. Those run code; this package
126
+ is data only. They live in the backend (and you import them from
127
+ `dynos.databases.typed_action` when building a backend; or via the
128
+ conditional-import pattern documented in `dynos-client`'s README when
129
+ authoring client-only code).
130
+ - No network or robot connectivity. That's `dynos-client`.
131
+
132
+ ## Public API
133
+
134
+ | Symbol | Purpose |
135
+ |-----------------------------------------|----------------------------------------------------------------------------|
136
+ | `GroundAtom` | A fluent applied to specific objects; the leaf of the symbolic state tree. |
137
+ | `World` | Frozenset of `GroundAtom`; one snapshot of the symbolic state. |
138
+ | `FluentBase` | Base class for fluents (rarely instantiated directly). |
139
+ | `make_new_fluent(name, **types)` | Factory: returns a callable that produces `GroundAtom`. |
140
+ | `make_new_object(type, name, **fields)` | Factory: registers an `ObjectType` instance with the numeric database. |
141
+ | `Transition` | Action schema (preconditions, effects, parameter type). |
142
+ | `TransitionParams` | Base class for typed parameter dataclasses. |
143
+ | `PrimitiveAction` | Frozen `(action_name, parameters)` pair — what flows over the wire. |
144
+ | `ObjectType` | Base class for typed domain entities. |
145
+ | `SymbolicObject` | An instance of an `ObjectType`. |
146
+ | `ValueField` | Descriptor for typed numeric/string attributes on `ObjectType`. |
147
+
148
+ ## Next
149
+
150
+ To talk to a running DYNOS backend, install `dynos-client`. To get the Sentry
151
+ survey vocabulary, install `dynos-sentry-domain`. The walkthrough at
152
+ `user_guide.md` ties them together end-to-end.
@@ -0,0 +1,10 @@
1
+ dynos_core/__init__.py,sha256=Dcg95QzQJJZtIFQazadgM36xHC3pHC1L_VaAxpW_XUc,801
2
+ dynos_core/atom.py,sha256=vHEcOaSPCnubCXD0xqMaE7xHDJhPq0aEcqnSQmIiCUU,3209
3
+ dynos_core/extension.py,sha256=Ua8r45nhnkoJjmmX3_OS3xxx4C_p5jBX4Jk6admgVZU,7326
4
+ dynos_core/factories.py,sha256=0OclMUdpMWncq8xU91AqNpSWPlZ5a8Ddvgoq2Q79W94,2162
5
+ dynos_core/transition.py,sha256=AHhS9nXbZlk7fYe7SEuU_wpmL9bdtUSg2dL_whwc7P8,7385
6
+ dynos_core/types.py,sha256=-iPmZL1p6nkAIBSjxifMtxVfpD5c3kfzThF_vaT3R8I,6075
7
+ dynos_core-0.1.2.dist-info/METADATA,sha256=xWJ-vVOuNFXfCdZ-b2gzXE2-bhrdfbh9ZU971AdnGoA,6255
8
+ dynos_core-0.1.2.dist-info/WHEEL,sha256=BNRMDyzLkkcmlv0J8ppDQkk2VED33SesJDynr9ED1gc,91
9
+ dynos_core-0.1.2.dist-info/top_level.txt,sha256=gA0fvFWfDITZw0n3mWL-IBnXOxX_V1Jw40HdkMWR4lw,11
10
+ dynos_core-0.1.2.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (75.3.4)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1 @@
1
+ dynos_core