dynos-core 0.1.2__tar.gz
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-0.1.2/PKG-INFO +152 -0
- dynos_core-0.1.2/README.md +143 -0
- dynos_core-0.1.2/pyproject.toml +15 -0
- dynos_core-0.1.2/setup.cfg +4 -0
- dynos_core-0.1.2/src/dynos_core/__init__.py +26 -0
- dynos_core-0.1.2/src/dynos_core/atom.py +105 -0
- dynos_core-0.1.2/src/dynos_core/extension.py +183 -0
- dynos_core-0.1.2/src/dynos_core/factories.py +67 -0
- dynos_core-0.1.2/src/dynos_core/transition.py +237 -0
- dynos_core-0.1.2/src/dynos_core/types.py +172 -0
- dynos_core-0.1.2/src/dynos_core.egg-info/PKG-INFO +152 -0
- dynos_core-0.1.2/src/dynos_core.egg-info/SOURCES.txt +13 -0
- dynos_core-0.1.2/src/dynos_core.egg-info/dependency_links.txt +1 -0
- dynos_core-0.1.2/src/dynos_core.egg-info/requires.txt +1 -0
- dynos_core-0.1.2/src/dynos_core.egg-info/top_level.txt +1 -0
|
@@ -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,143 @@
|
|
|
1
|
+
# dynos-core
|
|
2
|
+
|
|
3
|
+
Pure-Python types for describing a planning domain. Predicates, transitions,
|
|
4
|
+
object types, and the world states they describe. `dynos-core` is the data
|
|
5
|
+
layer that every other DYNOS package shares.
|
|
6
|
+
|
|
7
|
+
This contains no planner, no executor, and no network code, it's just classes
|
|
8
|
+
that define a domain. The DYNOS backend reads these structures to
|
|
9
|
+
plan/execute/monitor/verify, clients read them to talk about goals, both share
|
|
10
|
+
the same in-memory representation.
|
|
11
|
+
|
|
12
|
+
Most users do not install `dynos-core` directly, You get it transitively when
|
|
13
|
+
you `pip install dynos-client` (or any package above it). Install it on its own
|
|
14
|
+
if you are authoring a new domain (or extending a new one, like when making
|
|
15
|
+
custom actions) and want the lowest-level types without pulling in the HTTP
|
|
16
|
+
client.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pip install dynos-core
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Single dependency: `varname`. This is used to infer the names of objects being
|
|
25
|
+
created.
|
|
26
|
+
|
|
27
|
+
## Concepts
|
|
28
|
+
|
|
29
|
+
DYNOS describes the world as a set of named facts (fluents) about typed
|
|
30
|
+
objects. A goal is a state of those facts; a plan is a sequence of transitions
|
|
31
|
+
that move from one state to another. Actions are specific code implementations
|
|
32
|
+
of transitions.
|
|
33
|
+
|
|
34
|
+
### Fluents and ground atoms
|
|
35
|
+
|
|
36
|
+
A fluent is a named, parameterised proposition. `make_new_fluent` creates one;
|
|
37
|
+
calling it on specific objects creates a `GroundAtom`. This is a fluent
|
|
38
|
+
applied to particular arguments.
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
from dynos_core import make_new_fluent, ObjectType, World
|
|
42
|
+
|
|
43
|
+
class Robot(ObjectType): ...
|
|
44
|
+
class Room(ObjectType): ...
|
|
45
|
+
|
|
46
|
+
at = make_new_fluent("at", robot=Robot, room=Room)
|
|
47
|
+
r = Robot("r1")
|
|
48
|
+
kitchen = Room("kitchen")
|
|
49
|
+
|
|
50
|
+
current = World({at(r, kitchen)})
|
|
51
|
+
print(at(r, kitchen) in current) # True
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
A `World` is a frozenset of `GroundAtom` describing what is currently true. In
|
|
55
|
+
the current implementation, anything not in the set is false (closed-world
|
|
56
|
+
assumption), but more principled approaches are being designed.
|
|
57
|
+
|
|
58
|
+
### Object types and value fields
|
|
59
|
+
|
|
60
|
+
An `ObjectType` is a category of thing in the domain. For example, Robot, Room,
|
|
61
|
+
Zone, Coordinate. `ValueField` descriptors attach typed numeric/string fields:
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
from dynos_core import ObjectType, ValueField
|
|
65
|
+
|
|
66
|
+
class Zone(ObjectType):
|
|
67
|
+
altitude = ValueField(float)
|
|
68
|
+
vertices = ValueField(list)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The class is pure Python; instances live in a backend-managed numeric database
|
|
72
|
+
at runtime, accessible through the same descriptor syntax
|
|
73
|
+
(`zone.altitude.get()` / `.set(70.0)`). `dynos-core` only declares the schema.
|
|
74
|
+
|
|
75
|
+
### Transitions
|
|
76
|
+
|
|
77
|
+
A `Transition` is an action *schema*: name, parameter type, preconditions,
|
|
78
|
+
effects. It says nothing about how the action runs.
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
from dynos_core import Transition, TransitionParams
|
|
82
|
+
|
|
83
|
+
class GotoParams(TransitionParams):
|
|
84
|
+
start: Room
|
|
85
|
+
end: Room
|
|
86
|
+
|
|
87
|
+
goto = Transition("goto", params_type=GotoParams).define(
|
|
88
|
+
preconditions=[at(GotoParams.start)],
|
|
89
|
+
adds=[at(GotoParams.end)],
|
|
90
|
+
removes=[at(GotoParams.start)],
|
|
91
|
+
)
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The `define()` call stores the symbolic spec on the transition. The `dynos`
|
|
95
|
+
backend extends `Transition` with cost callbacks, applicability checks, and
|
|
96
|
+
execution hooks; this package's `Transition` is just data.
|
|
97
|
+
|
|
98
|
+
### Extensions
|
|
99
|
+
|
|
100
|
+
`extend_object_type` and `extend_transition_params` add fields after the class
|
|
101
|
+
is declared. This supports the *publish-stub* pattern: a domain package
|
|
102
|
+
declares a small public schema; the backend extends it with private fields at
|
|
103
|
+
import time. The public release strips the extension calls so users see only
|
|
104
|
+
the public surface.
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
from dynos_core.extension import extend_object_type
|
|
108
|
+
extend_object_type(Zone, depth=ValueField(float)) # backend-only addition
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
See `extension.py` for the full rules (additive only, must run before any plan construction, etc.).
|
|
112
|
+
|
|
113
|
+
## What dynos-core does NOT do
|
|
114
|
+
|
|
115
|
+
- No planner. The actual planning lives in the `dynos` backend (not on PyPI).
|
|
116
|
+
- No `@Action` / `@Belief` / `@Script` decorators. Those run code; this package
|
|
117
|
+
is data only. They live in the backend (and you import them from
|
|
118
|
+
`dynos.databases.typed_action` when building a backend; or via the
|
|
119
|
+
conditional-import pattern documented in `dynos-client`'s README when
|
|
120
|
+
authoring client-only code).
|
|
121
|
+
- No network or robot connectivity. That's `dynos-client`.
|
|
122
|
+
|
|
123
|
+
## Public API
|
|
124
|
+
|
|
125
|
+
| Symbol | Purpose |
|
|
126
|
+
|-----------------------------------------|----------------------------------------------------------------------------|
|
|
127
|
+
| `GroundAtom` | A fluent applied to specific objects; the leaf of the symbolic state tree. |
|
|
128
|
+
| `World` | Frozenset of `GroundAtom`; one snapshot of the symbolic state. |
|
|
129
|
+
| `FluentBase` | Base class for fluents (rarely instantiated directly). |
|
|
130
|
+
| `make_new_fluent(name, **types)` | Factory: returns a callable that produces `GroundAtom`. |
|
|
131
|
+
| `make_new_object(type, name, **fields)` | Factory: registers an `ObjectType` instance with the numeric database. |
|
|
132
|
+
| `Transition` | Action schema (preconditions, effects, parameter type). |
|
|
133
|
+
| `TransitionParams` | Base class for typed parameter dataclasses. |
|
|
134
|
+
| `PrimitiveAction` | Frozen `(action_name, parameters)` pair — what flows over the wire. |
|
|
135
|
+
| `ObjectType` | Base class for typed domain entities. |
|
|
136
|
+
| `SymbolicObject` | An instance of an `ObjectType`. |
|
|
137
|
+
| `ValueField` | Descriptor for typed numeric/string attributes on `ObjectType`. |
|
|
138
|
+
|
|
139
|
+
## Next
|
|
140
|
+
|
|
141
|
+
To talk to a running DYNOS backend, install `dynos-client`. To get the Sentry
|
|
142
|
+
survey vocabulary, install `dynos-sentry-domain`. The walkthrough at
|
|
143
|
+
`user_guide.md` ties them together end-to-end.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "dynos-core"
|
|
7
|
+
version = "0.1.2"
|
|
8
|
+
description = "Core symbolic-planning types and protocols shared by DYNOS packages"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "Apache-2.0" }
|
|
11
|
+
requires-python = ">=3.8"
|
|
12
|
+
dependencies = ["varname"]
|
|
13
|
+
|
|
14
|
+
[tool.setuptools.packages.find]
|
|
15
|
+
where = ["src"]
|
|
@@ -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
|
+
]
|
|
@@ -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})"
|
|
@@ -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,13 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
src/dynos_core/__init__.py
|
|
4
|
+
src/dynos_core/atom.py
|
|
5
|
+
src/dynos_core/extension.py
|
|
6
|
+
src/dynos_core/factories.py
|
|
7
|
+
src/dynos_core/transition.py
|
|
8
|
+
src/dynos_core/types.py
|
|
9
|
+
src/dynos_core.egg-info/PKG-INFO
|
|
10
|
+
src/dynos_core.egg-info/SOURCES.txt
|
|
11
|
+
src/dynos_core.egg-info/dependency_links.txt
|
|
12
|
+
src/dynos_core.egg-info/requires.txt
|
|
13
|
+
src/dynos_core.egg-info/top_level.txt
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
varname
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
dynos_core
|