dynos-warehouse-domain 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_warehouse_domain-0.1.2/PKG-INFO +273 -0
- dynos_warehouse_domain-0.1.2/README.md +264 -0
- dynos_warehouse_domain-0.1.2/pyproject.toml +15 -0
- dynos_warehouse_domain-0.1.2/setup.cfg +4 -0
- dynos_warehouse_domain-0.1.2/src/dynos_warehouse/__init__.py +0 -0
- dynos_warehouse_domain-0.1.2/src/dynos_warehouse/warehouse.py +157 -0
- dynos_warehouse_domain-0.1.2/src/dynos_warehouse_domain.egg-info/PKG-INFO +273 -0
- dynos_warehouse_domain-0.1.2/src/dynos_warehouse_domain.egg-info/SOURCES.txt +9 -0
- dynos_warehouse_domain-0.1.2/src/dynos_warehouse_domain.egg-info/dependency_links.txt +1 -0
- dynos_warehouse_domain-0.1.2/src/dynos_warehouse_domain.egg-info/requires.txt +1 -0
- dynos_warehouse_domain-0.1.2/src/dynos_warehouse_domain.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: dynos-warehouse-domain
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: Public warehouse-bot domain for DYNOS
|
|
5
|
+
License: Apache-2.0
|
|
6
|
+
Requires-Python: >=3.8
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
Requires-Dist: dynos-client>=0.1.2
|
|
9
|
+
|
|
10
|
+
# dynos-warehouse-domain
|
|
11
|
+
|
|
12
|
+
A small, deliberately-toy domain and a bit of a tutorial. This represents a
|
|
13
|
+
robot that moves between rooms, picks up boxes, and puts them down. It is the
|
|
14
|
+
simplest interesting domain that exercises every part of the symbolic planning
|
|
15
|
+
stack (preconditions, effects, typed objects, goals) without any of the
|
|
16
|
+
AUV-specific machinery the Sentry domain layers on top.
|
|
17
|
+
|
|
18
|
+
If you have never used a task planner before, this is the package to read
|
|
19
|
+
first. This is sort of a sibling package to `dynos-sentry-domain`. They both
|
|
20
|
+
depend on `dynos-client`, but neither depends on the other; pick whichever fits
|
|
21
|
+
your problem. You probably want to learn the concepts here and then move to
|
|
22
|
+
`dynos-sentry-domain`.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install dynos-warehouse-domain
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Pulls in `dynos-client` and `dynos-core` transitively.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Symbolic planning in five minutes
|
|
35
|
+
|
|
36
|
+
DYNOS is a **task planner**. You hand it a description of the world and a goal;
|
|
37
|
+
it hands you back a sequence of actions that, executed in order, will make the
|
|
38
|
+
goal true. There are three pieces.
|
|
39
|
+
|
|
40
|
+
### 1. The world as a set of facts
|
|
41
|
+
|
|
42
|
+
DYNOS describes the world as a set of named, typed facts called fluents. A
|
|
43
|
+
fluent is just a labeled question with a true/false answer:
|
|
44
|
+
|
|
45
|
+
- `robot_at(room_one)` -> "is the robot in room one?"
|
|
46
|
+
- `holding(box_a)` -> "is the robot holding box A?"
|
|
47
|
+
- `hands_free()` -> "are the robot's hands empty?"
|
|
48
|
+
|
|
49
|
+
The set of fluents that are currently true is the world state. Anything not in
|
|
50
|
+
that set is false. This is called a closed-world model, and it's why you only
|
|
51
|
+
have to list what's true. It's also an approximation, but we work around it
|
|
52
|
+
pretty effectively by constantly re-planning and re-assessing what goes on in
|
|
53
|
+
the world.
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
World right now:
|
|
57
|
+
{ robot_at(room_robot_home), hands_free(), box_at(room_one, box_a) }
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
That's the entire description of the situation: robot is at home, hands are
|
|
61
|
+
empty, box A sits in room one. No coordinates, no images, no continuous sensor
|
|
62
|
+
data, just a set of true facts. Symbolic planning works on these boolean facts.
|
|
63
|
+
DYNOS does extend this by having a separate channel for continuous values like
|
|
64
|
+
coordinates and altitudes; that's `ValueField` on object types that will get
|
|
65
|
+
explored more later.
|
|
66
|
+
|
|
67
|
+
### 2. Actions described as before/after
|
|
68
|
+
|
|
69
|
+
A transition describes what an action looks like *symbolically*. It does
|
|
70
|
+
not run any code. It declares:
|
|
71
|
+
|
|
72
|
+
- preconditions: facts that must already be true for the action to be legal
|
|
73
|
+
- adds: facts that become true after the action runs
|
|
74
|
+
- removes: facts that stop being true
|
|
75
|
+
|
|
76
|
+
The `pick` transition in this package, for example, says: "to pick up a box,
|
|
77
|
+
your hands must be free, you must be in the room with the box, and the box must
|
|
78
|
+
be in that room. Afterwards you're holding the box, the box is no longer in the
|
|
79
|
+
room, and your hands are no longer free."
|
|
80
|
+
|
|
81
|
+
We represent this in python, which aids with introspection and debug:
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
pick.define(
|
|
85
|
+
preconditions=[hands_free(),
|
|
86
|
+
robot_at(pick.params.room()),
|
|
87
|
+
box_at(pick.params.room(), pick.params.box())],
|
|
88
|
+
adds=[holding(pick.params.box())],
|
|
89
|
+
removes=[box_at(pick.params.room(), pick.params.box()), hands_free()],
|
|
90
|
+
)
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The DYNOS backend reads the data when it plans, and there's a separate piece of
|
|
94
|
+
code (an `@Action` method, not in this package) that actually moves the robot.
|
|
95
|
+
The strict separation is what lets the planner reason about long sequences
|
|
96
|
+
without knowing anything about hardware.
|
|
97
|
+
|
|
98
|
+
### 3. Goals are desired states
|
|
99
|
+
|
|
100
|
+
A goal is a set of facts you want to be true. You don't tell the planner what
|
|
101
|
+
to do; you tell it what should be true at the end. This way, the planner can
|
|
102
|
+
figure out the optimization and missing steps for you, and can re-plan to
|
|
103
|
+
re-solve when things change. For example:
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
Goal: { box_at(room_two, box_a) }
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
"I want box A to end up in room two." The planner searches over transitions to
|
|
110
|
+
find a sequence whose combined effect changes the current state into one that
|
|
111
|
+
satisfies the goal. For the world above, against this goal, the planner
|
|
112
|
+
returns:
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
1. move(start=room_robot_home, end=room_one)
|
|
116
|
+
2. pick(room=room_one, box=box_a)
|
|
117
|
+
3. move(start=room_one, end=room_two)
|
|
118
|
+
4. place(room=room_two, box=box_a)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
You did not write that sequence, the planner derived it from the preconditions
|
|
122
|
+
and effects you wrote. If the situation changes (e.g., an obstacle blocks
|
|
123
|
+
`room_one`) you describe the change as a fact the planner sees, set the same
|
|
124
|
+
goal, and you get a new plan. This is the `dynos call goal "..."` + `dynos call
|
|
125
|
+
execute` workflow you'll see in the cross-package walkthrough, or that you can
|
|
126
|
+
trigger from the orchestrator (as the mission executive will do during
|
|
127
|
+
operation).
|
|
128
|
+
|
|
129
|
+
That's it. Everything else in DYNOS, like coverage surveys, lifecycle phases,
|
|
130
|
+
multi-stage missions, and replanning on failure, is built on these three
|
|
131
|
+
principles.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## The warehouse domain concretely
|
|
136
|
+
|
|
137
|
+
This package ships everything you need to give the planner the example above.
|
|
138
|
+
|
|
139
|
+
### Object types
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
class Box(ObjectType):
|
|
143
|
+
weight = ValueField(float)
|
|
144
|
+
|
|
145
|
+
class Room(ObjectType):
|
|
146
|
+
capacity = ValueField(int)
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
`Box` and `Room` are typed entities. Fluent argument types are checked against
|
|
150
|
+
them: `box_at(room=Room, box=Box)` will reject `box_at(room_one, room_two)`
|
|
151
|
+
because the second argument has the wrong type. The `weight` and `capacity`
|
|
152
|
+
`ValueField` descriptors hang continuous values off each instance — useful if
|
|
153
|
+
you want to later add a "robot can only carry boxes lighter than X kg"
|
|
154
|
+
constraint.
|
|
155
|
+
|
|
156
|
+
### Pre-built objects
|
|
157
|
+
|
|
158
|
+
The package creates eight specific instances at import time, ready for goals:
|
|
159
|
+
|
|
160
|
+
- Boxes: `box_a`, `box_b`, `box_c`
|
|
161
|
+
- Rooms: `room_robot_home`, `room_loading_bay`, `room_one`, `room_two`, `room_three`
|
|
162
|
+
|
|
163
|
+
This saves you from writing `make_new_object(Box)` for the toy examples; the
|
|
164
|
+
names are just stable handles into the numeric database.
|
|
165
|
+
|
|
166
|
+
### Fluents
|
|
167
|
+
|
|
168
|
+
| Fluent | Meaning |
|
|
169
|
+
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
|
|
170
|
+
| `hands_free()` | True iff the robot is not currently holding anything. (Defaults to `True`, so the initial world has it true unless you explicitly remove it.) |
|
|
171
|
+
| `robot_at(room)` | The robot is in `room`. |
|
|
172
|
+
| `box_at(room, box)` | `box` is sitting in `room`. |
|
|
173
|
+
| `holding(box)` | The robot is holding `box`. |
|
|
174
|
+
|
|
175
|
+
### Transitions (the robot's verbs)
|
|
176
|
+
|
|
177
|
+
| Transition | Parameters | Meaning |
|
|
178
|
+
|--------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------|
|
|
179
|
+
| `pick(room, box)` | `PickPlaceParams` | Pick up a box that's in the same room as the robot. |
|
|
180
|
+
| `place(room, box)` | `PickPlaceParams` | Put down a held box in the room the robot is in. |
|
|
181
|
+
| `move(start, end)` | `MoveParams` | Move from `start` to `end`. (No connectivity graph: every room is reachable from every other room. This is intentional for the toy.) |
|
|
182
|
+
|
|
183
|
+
Read `warehouse.py` for the full preconditions / adds / removes.
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## Use it
|
|
188
|
+
|
|
189
|
+
### Against a running backend
|
|
190
|
+
|
|
191
|
+
Same flow as the Sentry domain (see `dynos-client`'s README for the session/login basics). Once you have a session:
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
from dynos_client import RemoteOrchestrator
|
|
195
|
+
from dynos_warehouse import box_a, room_one, room_robot_home, room_two, box_at, robot_at, hands_free
|
|
196
|
+
|
|
197
|
+
orch = RemoteOrchestrator.from_config()
|
|
198
|
+
|
|
199
|
+
# Tell the backend the initial world
|
|
200
|
+
orch.set_start([
|
|
201
|
+
robot_at(room_robot_home),
|
|
202
|
+
hands_free(),
|
|
203
|
+
box_at(room_one, box_a),
|
|
204
|
+
])
|
|
205
|
+
|
|
206
|
+
# Set the goal
|
|
207
|
+
orch.set_goal([box_at(room_two, box_a)])
|
|
208
|
+
|
|
209
|
+
# Inspect the plan before running it
|
|
210
|
+
print(orch.get_plan())
|
|
211
|
+
|
|
212
|
+
# Run it
|
|
213
|
+
orch.execute_plan()
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
The CLI equivalent uses string-form goals:
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
dynos call goal "box_at(room_two, box_a)"
|
|
220
|
+
dynos call plan
|
|
221
|
+
dynos call execute
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### Offline (no backend at all)
|
|
225
|
+
|
|
226
|
+
Because `Transition` is inert data in `dynos-core`, you can introspect it without any backend or network:
|
|
227
|
+
|
|
228
|
+
```python
|
|
229
|
+
from dynos_warehouse import pick
|
|
230
|
+
|
|
231
|
+
for p in pick.preconditions:
|
|
232
|
+
print(p)
|
|
233
|
+
# Output:
|
|
234
|
+
# hands_free()
|
|
235
|
+
# robot_at(room)
|
|
236
|
+
# box_at(room, box)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
This is the fastest way to confirm you've understood a domain: print the
|
|
240
|
+
preconditions and effects of every transition and check that the resulting
|
|
241
|
+
before/after picture matches your mental model.
|
|
242
|
+
|
|
243
|
+
## Public API
|
|
244
|
+
|
|
245
|
+
| Symbol | Kind | Purpose |
|
|
246
|
+
|--------------------------------------------------------------------------------------------------------|---------------------|--------------------------------|
|
|
247
|
+
| `Box`, `Room` | object type | Typed entities. |
|
|
248
|
+
| `box_a`, `box_b`, `box_c`, `room_robot_home`, `room_loading_bay`, `room_one`, `room_two`, `room_three` | object | Pre-built instances. |
|
|
249
|
+
| `hands_free`, `robot_at`, `box_at`, `holding` | fluent | Boolean facts about the world. |
|
|
250
|
+
| `PickPlaceParams`, `MoveParams` | parameter dataclass | Transition argument types. |
|
|
251
|
+
| `pick`, `place`, `move` | transition | The robot's verbs. |
|
|
252
|
+
|
|
253
|
+
## What's NOT here
|
|
254
|
+
|
|
255
|
+
- No executable behaviour. The transitions are symbolic specs; nothing in
|
|
256
|
+
this package moves a real or simulated robot. Pair it with a backend that has
|
|
257
|
+
registered `@Action` methods bound to `pick` / `place` / `move`.
|
|
258
|
+
- No room connectivity graph. `move(start, end)` is unconditional. If you want
|
|
259
|
+
a topology where some rooms are only reachable from others, add a
|
|
260
|
+
`connected(a, b)` fluent and put it in `move`'s preconditions.
|
|
261
|
+
- No payload constraints. `pick` doesn't check `Box.weight` against
|
|
262
|
+
`Room.capacity`. Add a numeric precondition to `pick.define(...)` if you want
|
|
263
|
+
one — that's exactly the kind of extension this domain is meant for.
|
|
264
|
+
|
|
265
|
+
## Next
|
|
266
|
+
|
|
267
|
+
- `dynos-core`: the data-layer types (`Transition`, `ObjectType`,
|
|
268
|
+
`ValueField`, `make_new_fluent`) you'll reach for when extending or replacing
|
|
269
|
+
this domain.
|
|
270
|
+
- `dynos-client`: the HTTP client and `dynos` CLI for talking to a backend.
|
|
271
|
+
- `dynos-sentry-domain`: the same machinery applied to a real underwater
|
|
272
|
+
vehicle, with surveys and lifecycle phases.
|
|
273
|
+
- `user_guide.md`: install + auth + first mission, end-to-end.
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
# dynos-warehouse-domain
|
|
2
|
+
|
|
3
|
+
A small, deliberately-toy domain and a bit of a tutorial. This represents a
|
|
4
|
+
robot that moves between rooms, picks up boxes, and puts them down. It is the
|
|
5
|
+
simplest interesting domain that exercises every part of the symbolic planning
|
|
6
|
+
stack (preconditions, effects, typed objects, goals) without any of the
|
|
7
|
+
AUV-specific machinery the Sentry domain layers on top.
|
|
8
|
+
|
|
9
|
+
If you have never used a task planner before, this is the package to read
|
|
10
|
+
first. This is sort of a sibling package to `dynos-sentry-domain`. They both
|
|
11
|
+
depend on `dynos-client`, but neither depends on the other; pick whichever fits
|
|
12
|
+
your problem. You probably want to learn the concepts here and then move to
|
|
13
|
+
`dynos-sentry-domain`.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pip install dynos-warehouse-domain
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Pulls in `dynos-client` and `dynos-core` transitively.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Symbolic planning in five minutes
|
|
26
|
+
|
|
27
|
+
DYNOS is a **task planner**. You hand it a description of the world and a goal;
|
|
28
|
+
it hands you back a sequence of actions that, executed in order, will make the
|
|
29
|
+
goal true. There are three pieces.
|
|
30
|
+
|
|
31
|
+
### 1. The world as a set of facts
|
|
32
|
+
|
|
33
|
+
DYNOS describes the world as a set of named, typed facts called fluents. A
|
|
34
|
+
fluent is just a labeled question with a true/false answer:
|
|
35
|
+
|
|
36
|
+
- `robot_at(room_one)` -> "is the robot in room one?"
|
|
37
|
+
- `holding(box_a)` -> "is the robot holding box A?"
|
|
38
|
+
- `hands_free()` -> "are the robot's hands empty?"
|
|
39
|
+
|
|
40
|
+
The set of fluents that are currently true is the world state. Anything not in
|
|
41
|
+
that set is false. This is called a closed-world model, and it's why you only
|
|
42
|
+
have to list what's true. It's also an approximation, but we work around it
|
|
43
|
+
pretty effectively by constantly re-planning and re-assessing what goes on in
|
|
44
|
+
the world.
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
World right now:
|
|
48
|
+
{ robot_at(room_robot_home), hands_free(), box_at(room_one, box_a) }
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
That's the entire description of the situation: robot is at home, hands are
|
|
52
|
+
empty, box A sits in room one. No coordinates, no images, no continuous sensor
|
|
53
|
+
data, just a set of true facts. Symbolic planning works on these boolean facts.
|
|
54
|
+
DYNOS does extend this by having a separate channel for continuous values like
|
|
55
|
+
coordinates and altitudes; that's `ValueField` on object types that will get
|
|
56
|
+
explored more later.
|
|
57
|
+
|
|
58
|
+
### 2. Actions described as before/after
|
|
59
|
+
|
|
60
|
+
A transition describes what an action looks like *symbolically*. It does
|
|
61
|
+
not run any code. It declares:
|
|
62
|
+
|
|
63
|
+
- preconditions: facts that must already be true for the action to be legal
|
|
64
|
+
- adds: facts that become true after the action runs
|
|
65
|
+
- removes: facts that stop being true
|
|
66
|
+
|
|
67
|
+
The `pick` transition in this package, for example, says: "to pick up a box,
|
|
68
|
+
your hands must be free, you must be in the room with the box, and the box must
|
|
69
|
+
be in that room. Afterwards you're holding the box, the box is no longer in the
|
|
70
|
+
room, and your hands are no longer free."
|
|
71
|
+
|
|
72
|
+
We represent this in python, which aids with introspection and debug:
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
pick.define(
|
|
76
|
+
preconditions=[hands_free(),
|
|
77
|
+
robot_at(pick.params.room()),
|
|
78
|
+
box_at(pick.params.room(), pick.params.box())],
|
|
79
|
+
adds=[holding(pick.params.box())],
|
|
80
|
+
removes=[box_at(pick.params.room(), pick.params.box()), hands_free()],
|
|
81
|
+
)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The DYNOS backend reads the data when it plans, and there's a separate piece of
|
|
85
|
+
code (an `@Action` method, not in this package) that actually moves the robot.
|
|
86
|
+
The strict separation is what lets the planner reason about long sequences
|
|
87
|
+
without knowing anything about hardware.
|
|
88
|
+
|
|
89
|
+
### 3. Goals are desired states
|
|
90
|
+
|
|
91
|
+
A goal is a set of facts you want to be true. You don't tell the planner what
|
|
92
|
+
to do; you tell it what should be true at the end. This way, the planner can
|
|
93
|
+
figure out the optimization and missing steps for you, and can re-plan to
|
|
94
|
+
re-solve when things change. For example:
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
Goal: { box_at(room_two, box_a) }
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
"I want box A to end up in room two." The planner searches over transitions to
|
|
101
|
+
find a sequence whose combined effect changes the current state into one that
|
|
102
|
+
satisfies the goal. For the world above, against this goal, the planner
|
|
103
|
+
returns:
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
1. move(start=room_robot_home, end=room_one)
|
|
107
|
+
2. pick(room=room_one, box=box_a)
|
|
108
|
+
3. move(start=room_one, end=room_two)
|
|
109
|
+
4. place(room=room_two, box=box_a)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
You did not write that sequence, the planner derived it from the preconditions
|
|
113
|
+
and effects you wrote. If the situation changes (e.g., an obstacle blocks
|
|
114
|
+
`room_one`) you describe the change as a fact the planner sees, set the same
|
|
115
|
+
goal, and you get a new plan. This is the `dynos call goal "..."` + `dynos call
|
|
116
|
+
execute` workflow you'll see in the cross-package walkthrough, or that you can
|
|
117
|
+
trigger from the orchestrator (as the mission executive will do during
|
|
118
|
+
operation).
|
|
119
|
+
|
|
120
|
+
That's it. Everything else in DYNOS, like coverage surveys, lifecycle phases,
|
|
121
|
+
multi-stage missions, and replanning on failure, is built on these three
|
|
122
|
+
principles.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## The warehouse domain concretely
|
|
127
|
+
|
|
128
|
+
This package ships everything you need to give the planner the example above.
|
|
129
|
+
|
|
130
|
+
### Object types
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
class Box(ObjectType):
|
|
134
|
+
weight = ValueField(float)
|
|
135
|
+
|
|
136
|
+
class Room(ObjectType):
|
|
137
|
+
capacity = ValueField(int)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
`Box` and `Room` are typed entities. Fluent argument types are checked against
|
|
141
|
+
them: `box_at(room=Room, box=Box)` will reject `box_at(room_one, room_two)`
|
|
142
|
+
because the second argument has the wrong type. The `weight` and `capacity`
|
|
143
|
+
`ValueField` descriptors hang continuous values off each instance — useful if
|
|
144
|
+
you want to later add a "robot can only carry boxes lighter than X kg"
|
|
145
|
+
constraint.
|
|
146
|
+
|
|
147
|
+
### Pre-built objects
|
|
148
|
+
|
|
149
|
+
The package creates eight specific instances at import time, ready for goals:
|
|
150
|
+
|
|
151
|
+
- Boxes: `box_a`, `box_b`, `box_c`
|
|
152
|
+
- Rooms: `room_robot_home`, `room_loading_bay`, `room_one`, `room_two`, `room_three`
|
|
153
|
+
|
|
154
|
+
This saves you from writing `make_new_object(Box)` for the toy examples; the
|
|
155
|
+
names are just stable handles into the numeric database.
|
|
156
|
+
|
|
157
|
+
### Fluents
|
|
158
|
+
|
|
159
|
+
| Fluent | Meaning |
|
|
160
|
+
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
|
|
161
|
+
| `hands_free()` | True iff the robot is not currently holding anything. (Defaults to `True`, so the initial world has it true unless you explicitly remove it.) |
|
|
162
|
+
| `robot_at(room)` | The robot is in `room`. |
|
|
163
|
+
| `box_at(room, box)` | `box` is sitting in `room`. |
|
|
164
|
+
| `holding(box)` | The robot is holding `box`. |
|
|
165
|
+
|
|
166
|
+
### Transitions (the robot's verbs)
|
|
167
|
+
|
|
168
|
+
| Transition | Parameters | Meaning |
|
|
169
|
+
|--------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------|
|
|
170
|
+
| `pick(room, box)` | `PickPlaceParams` | Pick up a box that's in the same room as the robot. |
|
|
171
|
+
| `place(room, box)` | `PickPlaceParams` | Put down a held box in the room the robot is in. |
|
|
172
|
+
| `move(start, end)` | `MoveParams` | Move from `start` to `end`. (No connectivity graph: every room is reachable from every other room. This is intentional for the toy.) |
|
|
173
|
+
|
|
174
|
+
Read `warehouse.py` for the full preconditions / adds / removes.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Use it
|
|
179
|
+
|
|
180
|
+
### Against a running backend
|
|
181
|
+
|
|
182
|
+
Same flow as the Sentry domain (see `dynos-client`'s README for the session/login basics). Once you have a session:
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
from dynos_client import RemoteOrchestrator
|
|
186
|
+
from dynos_warehouse import box_a, room_one, room_robot_home, room_two, box_at, robot_at, hands_free
|
|
187
|
+
|
|
188
|
+
orch = RemoteOrchestrator.from_config()
|
|
189
|
+
|
|
190
|
+
# Tell the backend the initial world
|
|
191
|
+
orch.set_start([
|
|
192
|
+
robot_at(room_robot_home),
|
|
193
|
+
hands_free(),
|
|
194
|
+
box_at(room_one, box_a),
|
|
195
|
+
])
|
|
196
|
+
|
|
197
|
+
# Set the goal
|
|
198
|
+
orch.set_goal([box_at(room_two, box_a)])
|
|
199
|
+
|
|
200
|
+
# Inspect the plan before running it
|
|
201
|
+
print(orch.get_plan())
|
|
202
|
+
|
|
203
|
+
# Run it
|
|
204
|
+
orch.execute_plan()
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
The CLI equivalent uses string-form goals:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
dynos call goal "box_at(room_two, box_a)"
|
|
211
|
+
dynos call plan
|
|
212
|
+
dynos call execute
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### Offline (no backend at all)
|
|
216
|
+
|
|
217
|
+
Because `Transition` is inert data in `dynos-core`, you can introspect it without any backend or network:
|
|
218
|
+
|
|
219
|
+
```python
|
|
220
|
+
from dynos_warehouse import pick
|
|
221
|
+
|
|
222
|
+
for p in pick.preconditions:
|
|
223
|
+
print(p)
|
|
224
|
+
# Output:
|
|
225
|
+
# hands_free()
|
|
226
|
+
# robot_at(room)
|
|
227
|
+
# box_at(room, box)
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
This is the fastest way to confirm you've understood a domain: print the
|
|
231
|
+
preconditions and effects of every transition and check that the resulting
|
|
232
|
+
before/after picture matches your mental model.
|
|
233
|
+
|
|
234
|
+
## Public API
|
|
235
|
+
|
|
236
|
+
| Symbol | Kind | Purpose |
|
|
237
|
+
|--------------------------------------------------------------------------------------------------------|---------------------|--------------------------------|
|
|
238
|
+
| `Box`, `Room` | object type | Typed entities. |
|
|
239
|
+
| `box_a`, `box_b`, `box_c`, `room_robot_home`, `room_loading_bay`, `room_one`, `room_two`, `room_three` | object | Pre-built instances. |
|
|
240
|
+
| `hands_free`, `robot_at`, `box_at`, `holding` | fluent | Boolean facts about the world. |
|
|
241
|
+
| `PickPlaceParams`, `MoveParams` | parameter dataclass | Transition argument types. |
|
|
242
|
+
| `pick`, `place`, `move` | transition | The robot's verbs. |
|
|
243
|
+
|
|
244
|
+
## What's NOT here
|
|
245
|
+
|
|
246
|
+
- No executable behaviour. The transitions are symbolic specs; nothing in
|
|
247
|
+
this package moves a real or simulated robot. Pair it with a backend that has
|
|
248
|
+
registered `@Action` methods bound to `pick` / `place` / `move`.
|
|
249
|
+
- No room connectivity graph. `move(start, end)` is unconditional. If you want
|
|
250
|
+
a topology where some rooms are only reachable from others, add a
|
|
251
|
+
`connected(a, b)` fluent and put it in `move`'s preconditions.
|
|
252
|
+
- No payload constraints. `pick` doesn't check `Box.weight` against
|
|
253
|
+
`Room.capacity`. Add a numeric precondition to `pick.define(...)` if you want
|
|
254
|
+
one — that's exactly the kind of extension this domain is meant for.
|
|
255
|
+
|
|
256
|
+
## Next
|
|
257
|
+
|
|
258
|
+
- `dynos-core`: the data-layer types (`Transition`, `ObjectType`,
|
|
259
|
+
`ValueField`, `make_new_fluent`) you'll reach for when extending or replacing
|
|
260
|
+
this domain.
|
|
261
|
+
- `dynos-client`: the HTTP client and `dynos` CLI for talking to a backend.
|
|
262
|
+
- `dynos-sentry-domain`: the same machinery applied to a real underwater
|
|
263
|
+
vehicle, with surveys and lifecycle phases.
|
|
264
|
+
- `user_guide.md`: install + auth + first mission, 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-warehouse-domain"
|
|
7
|
+
version = "0.1.2"
|
|
8
|
+
description = "Public warehouse-bot domain for DYNOS"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "Apache-2.0" }
|
|
11
|
+
requires-python = ">=3.8"
|
|
12
|
+
dependencies = ["dynos-client>=0.1.2"]
|
|
13
|
+
|
|
14
|
+
[tool.setuptools.packages.find]
|
|
15
|
+
where = ["src"]
|
|
File without changes
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Warehouse Domain: toy problem good for testing
|
|
3
|
+
|
|
4
|
+
This module defines a warehouse robot domain where the robot can:
|
|
5
|
+
- pick: Pick up a box from a room
|
|
6
|
+
- place: Place a held box in a room
|
|
7
|
+
- move: Move between rooms
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from dynos_client.domain import (
|
|
11
|
+
ObjectType,
|
|
12
|
+
Transition,
|
|
13
|
+
TransitionParams,
|
|
14
|
+
ValueField,
|
|
15
|
+
make_new_fluent,
|
|
16
|
+
make_new_object,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
# fmt: off
|
|
20
|
+
# making object types: create the idea of a box and a room
|
|
21
|
+
|
|
22
|
+
class Box(ObjectType):
|
|
23
|
+
weight = ValueField(float)
|
|
24
|
+
|
|
25
|
+
class Room(ObjectType):
|
|
26
|
+
capacity = ValueField(int)
|
|
27
|
+
|
|
28
|
+
# making objects: create specific boxes and rooms
|
|
29
|
+
|
|
30
|
+
box_a = make_new_object(Box)
|
|
31
|
+
box_b = make_new_object(Box)
|
|
32
|
+
box_c = make_new_object(Box)
|
|
33
|
+
|
|
34
|
+
room_robot_home = make_new_object(Room)
|
|
35
|
+
room_loading_bay = make_new_object(Room)
|
|
36
|
+
room_one = make_new_object(Room)
|
|
37
|
+
room_two = make_new_object(Room)
|
|
38
|
+
room_three = make_new_object(Room)
|
|
39
|
+
|
|
40
|
+
# making fluents: facts about the world
|
|
41
|
+
|
|
42
|
+
hands_free = make_new_fluent( default=True)
|
|
43
|
+
box_at = make_new_fluent(location=Room, box=Box, )
|
|
44
|
+
robot_at = make_new_fluent(location=Room, )
|
|
45
|
+
holding = make_new_fluent( box=Box, )
|
|
46
|
+
|
|
47
|
+
# fmt: on
|
|
48
|
+
|
|
49
|
+
# making transition parameters -- these are the objects the steps each require
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class PickPlaceParams(TransitionParams):
|
|
53
|
+
room: Room
|
|
54
|
+
box: Box
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class MoveParams(TransitionParams):
|
|
58
|
+
start: Room
|
|
59
|
+
end: Room
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
pick = Transition(
|
|
63
|
+
params_type=PickPlaceParams,
|
|
64
|
+
)
|
|
65
|
+
|
|
66
|
+
place = Transition(
|
|
67
|
+
params_type=PickPlaceParams,
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
move = Transition(
|
|
71
|
+
params_type=MoveParams,
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
# transition definitions: how they interact with the world
|
|
76
|
+
|
|
77
|
+
pick.define(
|
|
78
|
+
preconditions=[
|
|
79
|
+
# Hands must be free before picking
|
|
80
|
+
hands_free(),
|
|
81
|
+
# Robot must be in the room
|
|
82
|
+
robot_at(pick.params.room()),
|
|
83
|
+
# Box must be in the room
|
|
84
|
+
box_at(pick.params.room(), pick.params.box()),
|
|
85
|
+
],
|
|
86
|
+
adds=[
|
|
87
|
+
# After picking, we're holding the box
|
|
88
|
+
holding(pick.params.box()),
|
|
89
|
+
],
|
|
90
|
+
removes=[
|
|
91
|
+
# After picking, the box is no longer in the room
|
|
92
|
+
box_at(pick.params.room(), pick.params.box()),
|
|
93
|
+
# After picking, hands are no longer free
|
|
94
|
+
hands_free(),
|
|
95
|
+
],
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
place.define(
|
|
99
|
+
preconditions=[
|
|
100
|
+
# Must be holding the box
|
|
101
|
+
holding(place.params.box()),
|
|
102
|
+
# Robot must be in the room where we're placing
|
|
103
|
+
robot_at(place.params.room()),
|
|
104
|
+
],
|
|
105
|
+
adds=[
|
|
106
|
+
# After placing, the box is in the room
|
|
107
|
+
box_at(place.params.room(), place.params.box()),
|
|
108
|
+
# After placing, hands are free again
|
|
109
|
+
hands_free(),
|
|
110
|
+
],
|
|
111
|
+
removes=[
|
|
112
|
+
# After placing, we're no longer holding the box
|
|
113
|
+
holding(place.params.box()),
|
|
114
|
+
],
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
move.define(
|
|
118
|
+
preconditions=[
|
|
119
|
+
# Robot must be at the start location
|
|
120
|
+
robot_at(move.params.start()),
|
|
121
|
+
],
|
|
122
|
+
adds=[
|
|
123
|
+
# After moving, robot is at the end location
|
|
124
|
+
robot_at(move.params.end()),
|
|
125
|
+
],
|
|
126
|
+
removes=[
|
|
127
|
+
# After moving, robot is no longer at the start location
|
|
128
|
+
robot_at(move.params.start()),
|
|
129
|
+
],
|
|
130
|
+
)
|
|
131
|
+
|
|
132
|
+
__all__ = [
|
|
133
|
+
# Object types
|
|
134
|
+
"Box",
|
|
135
|
+
"Room",
|
|
136
|
+
# Objects
|
|
137
|
+
"box_a",
|
|
138
|
+
"box_b",
|
|
139
|
+
"box_c",
|
|
140
|
+
"room_robot_home",
|
|
141
|
+
"room_loading_bay",
|
|
142
|
+
"room_one",
|
|
143
|
+
"room_two",
|
|
144
|
+
"room_three",
|
|
145
|
+
# Fluents
|
|
146
|
+
"robot_at",
|
|
147
|
+
"box_at",
|
|
148
|
+
"holding",
|
|
149
|
+
"hands_free",
|
|
150
|
+
# Param types
|
|
151
|
+
"PickPlaceParams",
|
|
152
|
+
"MoveParams",
|
|
153
|
+
# Transitions
|
|
154
|
+
"pick",
|
|
155
|
+
"place",
|
|
156
|
+
"move",
|
|
157
|
+
]
|
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: dynos-warehouse-domain
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: Public warehouse-bot domain for DYNOS
|
|
5
|
+
License: Apache-2.0
|
|
6
|
+
Requires-Python: >=3.8
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
Requires-Dist: dynos-client>=0.1.2
|
|
9
|
+
|
|
10
|
+
# dynos-warehouse-domain
|
|
11
|
+
|
|
12
|
+
A small, deliberately-toy domain and a bit of a tutorial. This represents a
|
|
13
|
+
robot that moves between rooms, picks up boxes, and puts them down. It is the
|
|
14
|
+
simplest interesting domain that exercises every part of the symbolic planning
|
|
15
|
+
stack (preconditions, effects, typed objects, goals) without any of the
|
|
16
|
+
AUV-specific machinery the Sentry domain layers on top.
|
|
17
|
+
|
|
18
|
+
If you have never used a task planner before, this is the package to read
|
|
19
|
+
first. This is sort of a sibling package to `dynos-sentry-domain`. They both
|
|
20
|
+
depend on `dynos-client`, but neither depends on the other; pick whichever fits
|
|
21
|
+
your problem. You probably want to learn the concepts here and then move to
|
|
22
|
+
`dynos-sentry-domain`.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install dynos-warehouse-domain
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Pulls in `dynos-client` and `dynos-core` transitively.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Symbolic planning in five minutes
|
|
35
|
+
|
|
36
|
+
DYNOS is a **task planner**. You hand it a description of the world and a goal;
|
|
37
|
+
it hands you back a sequence of actions that, executed in order, will make the
|
|
38
|
+
goal true. There are three pieces.
|
|
39
|
+
|
|
40
|
+
### 1. The world as a set of facts
|
|
41
|
+
|
|
42
|
+
DYNOS describes the world as a set of named, typed facts called fluents. A
|
|
43
|
+
fluent is just a labeled question with a true/false answer:
|
|
44
|
+
|
|
45
|
+
- `robot_at(room_one)` -> "is the robot in room one?"
|
|
46
|
+
- `holding(box_a)` -> "is the robot holding box A?"
|
|
47
|
+
- `hands_free()` -> "are the robot's hands empty?"
|
|
48
|
+
|
|
49
|
+
The set of fluents that are currently true is the world state. Anything not in
|
|
50
|
+
that set is false. This is called a closed-world model, and it's why you only
|
|
51
|
+
have to list what's true. It's also an approximation, but we work around it
|
|
52
|
+
pretty effectively by constantly re-planning and re-assessing what goes on in
|
|
53
|
+
the world.
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
World right now:
|
|
57
|
+
{ robot_at(room_robot_home), hands_free(), box_at(room_one, box_a) }
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
That's the entire description of the situation: robot is at home, hands are
|
|
61
|
+
empty, box A sits in room one. No coordinates, no images, no continuous sensor
|
|
62
|
+
data, just a set of true facts. Symbolic planning works on these boolean facts.
|
|
63
|
+
DYNOS does extend this by having a separate channel for continuous values like
|
|
64
|
+
coordinates and altitudes; that's `ValueField` on object types that will get
|
|
65
|
+
explored more later.
|
|
66
|
+
|
|
67
|
+
### 2. Actions described as before/after
|
|
68
|
+
|
|
69
|
+
A transition describes what an action looks like *symbolically*. It does
|
|
70
|
+
not run any code. It declares:
|
|
71
|
+
|
|
72
|
+
- preconditions: facts that must already be true for the action to be legal
|
|
73
|
+
- adds: facts that become true after the action runs
|
|
74
|
+
- removes: facts that stop being true
|
|
75
|
+
|
|
76
|
+
The `pick` transition in this package, for example, says: "to pick up a box,
|
|
77
|
+
your hands must be free, you must be in the room with the box, and the box must
|
|
78
|
+
be in that room. Afterwards you're holding the box, the box is no longer in the
|
|
79
|
+
room, and your hands are no longer free."
|
|
80
|
+
|
|
81
|
+
We represent this in python, which aids with introspection and debug:
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
pick.define(
|
|
85
|
+
preconditions=[hands_free(),
|
|
86
|
+
robot_at(pick.params.room()),
|
|
87
|
+
box_at(pick.params.room(), pick.params.box())],
|
|
88
|
+
adds=[holding(pick.params.box())],
|
|
89
|
+
removes=[box_at(pick.params.room(), pick.params.box()), hands_free()],
|
|
90
|
+
)
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The DYNOS backend reads the data when it plans, and there's a separate piece of
|
|
94
|
+
code (an `@Action` method, not in this package) that actually moves the robot.
|
|
95
|
+
The strict separation is what lets the planner reason about long sequences
|
|
96
|
+
without knowing anything about hardware.
|
|
97
|
+
|
|
98
|
+
### 3. Goals are desired states
|
|
99
|
+
|
|
100
|
+
A goal is a set of facts you want to be true. You don't tell the planner what
|
|
101
|
+
to do; you tell it what should be true at the end. This way, the planner can
|
|
102
|
+
figure out the optimization and missing steps for you, and can re-plan to
|
|
103
|
+
re-solve when things change. For example:
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
Goal: { box_at(room_two, box_a) }
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
"I want box A to end up in room two." The planner searches over transitions to
|
|
110
|
+
find a sequence whose combined effect changes the current state into one that
|
|
111
|
+
satisfies the goal. For the world above, against this goal, the planner
|
|
112
|
+
returns:
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
1. move(start=room_robot_home, end=room_one)
|
|
116
|
+
2. pick(room=room_one, box=box_a)
|
|
117
|
+
3. move(start=room_one, end=room_two)
|
|
118
|
+
4. place(room=room_two, box=box_a)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
You did not write that sequence, the planner derived it from the preconditions
|
|
122
|
+
and effects you wrote. If the situation changes (e.g., an obstacle blocks
|
|
123
|
+
`room_one`) you describe the change as a fact the planner sees, set the same
|
|
124
|
+
goal, and you get a new plan. This is the `dynos call goal "..."` + `dynos call
|
|
125
|
+
execute` workflow you'll see in the cross-package walkthrough, or that you can
|
|
126
|
+
trigger from the orchestrator (as the mission executive will do during
|
|
127
|
+
operation).
|
|
128
|
+
|
|
129
|
+
That's it. Everything else in DYNOS, like coverage surveys, lifecycle phases,
|
|
130
|
+
multi-stage missions, and replanning on failure, is built on these three
|
|
131
|
+
principles.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## The warehouse domain concretely
|
|
136
|
+
|
|
137
|
+
This package ships everything you need to give the planner the example above.
|
|
138
|
+
|
|
139
|
+
### Object types
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
class Box(ObjectType):
|
|
143
|
+
weight = ValueField(float)
|
|
144
|
+
|
|
145
|
+
class Room(ObjectType):
|
|
146
|
+
capacity = ValueField(int)
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
`Box` and `Room` are typed entities. Fluent argument types are checked against
|
|
150
|
+
them: `box_at(room=Room, box=Box)` will reject `box_at(room_one, room_two)`
|
|
151
|
+
because the second argument has the wrong type. The `weight` and `capacity`
|
|
152
|
+
`ValueField` descriptors hang continuous values off each instance — useful if
|
|
153
|
+
you want to later add a "robot can only carry boxes lighter than X kg"
|
|
154
|
+
constraint.
|
|
155
|
+
|
|
156
|
+
### Pre-built objects
|
|
157
|
+
|
|
158
|
+
The package creates eight specific instances at import time, ready for goals:
|
|
159
|
+
|
|
160
|
+
- Boxes: `box_a`, `box_b`, `box_c`
|
|
161
|
+
- Rooms: `room_robot_home`, `room_loading_bay`, `room_one`, `room_two`, `room_three`
|
|
162
|
+
|
|
163
|
+
This saves you from writing `make_new_object(Box)` for the toy examples; the
|
|
164
|
+
names are just stable handles into the numeric database.
|
|
165
|
+
|
|
166
|
+
### Fluents
|
|
167
|
+
|
|
168
|
+
| Fluent | Meaning |
|
|
169
|
+
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
|
|
170
|
+
| `hands_free()` | True iff the robot is not currently holding anything. (Defaults to `True`, so the initial world has it true unless you explicitly remove it.) |
|
|
171
|
+
| `robot_at(room)` | The robot is in `room`. |
|
|
172
|
+
| `box_at(room, box)` | `box` is sitting in `room`. |
|
|
173
|
+
| `holding(box)` | The robot is holding `box`. |
|
|
174
|
+
|
|
175
|
+
### Transitions (the robot's verbs)
|
|
176
|
+
|
|
177
|
+
| Transition | Parameters | Meaning |
|
|
178
|
+
|--------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------|
|
|
179
|
+
| `pick(room, box)` | `PickPlaceParams` | Pick up a box that's in the same room as the robot. |
|
|
180
|
+
| `place(room, box)` | `PickPlaceParams` | Put down a held box in the room the robot is in. |
|
|
181
|
+
| `move(start, end)` | `MoveParams` | Move from `start` to `end`. (No connectivity graph: every room is reachable from every other room. This is intentional for the toy.) |
|
|
182
|
+
|
|
183
|
+
Read `warehouse.py` for the full preconditions / adds / removes.
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## Use it
|
|
188
|
+
|
|
189
|
+
### Against a running backend
|
|
190
|
+
|
|
191
|
+
Same flow as the Sentry domain (see `dynos-client`'s README for the session/login basics). Once you have a session:
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
from dynos_client import RemoteOrchestrator
|
|
195
|
+
from dynos_warehouse import box_a, room_one, room_robot_home, room_two, box_at, robot_at, hands_free
|
|
196
|
+
|
|
197
|
+
orch = RemoteOrchestrator.from_config()
|
|
198
|
+
|
|
199
|
+
# Tell the backend the initial world
|
|
200
|
+
orch.set_start([
|
|
201
|
+
robot_at(room_robot_home),
|
|
202
|
+
hands_free(),
|
|
203
|
+
box_at(room_one, box_a),
|
|
204
|
+
])
|
|
205
|
+
|
|
206
|
+
# Set the goal
|
|
207
|
+
orch.set_goal([box_at(room_two, box_a)])
|
|
208
|
+
|
|
209
|
+
# Inspect the plan before running it
|
|
210
|
+
print(orch.get_plan())
|
|
211
|
+
|
|
212
|
+
# Run it
|
|
213
|
+
orch.execute_plan()
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
The CLI equivalent uses string-form goals:
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
dynos call goal "box_at(room_two, box_a)"
|
|
220
|
+
dynos call plan
|
|
221
|
+
dynos call execute
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### Offline (no backend at all)
|
|
225
|
+
|
|
226
|
+
Because `Transition` is inert data in `dynos-core`, you can introspect it without any backend or network:
|
|
227
|
+
|
|
228
|
+
```python
|
|
229
|
+
from dynos_warehouse import pick
|
|
230
|
+
|
|
231
|
+
for p in pick.preconditions:
|
|
232
|
+
print(p)
|
|
233
|
+
# Output:
|
|
234
|
+
# hands_free()
|
|
235
|
+
# robot_at(room)
|
|
236
|
+
# box_at(room, box)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
This is the fastest way to confirm you've understood a domain: print the
|
|
240
|
+
preconditions and effects of every transition and check that the resulting
|
|
241
|
+
before/after picture matches your mental model.
|
|
242
|
+
|
|
243
|
+
## Public API
|
|
244
|
+
|
|
245
|
+
| Symbol | Kind | Purpose |
|
|
246
|
+
|--------------------------------------------------------------------------------------------------------|---------------------|--------------------------------|
|
|
247
|
+
| `Box`, `Room` | object type | Typed entities. |
|
|
248
|
+
| `box_a`, `box_b`, `box_c`, `room_robot_home`, `room_loading_bay`, `room_one`, `room_two`, `room_three` | object | Pre-built instances. |
|
|
249
|
+
| `hands_free`, `robot_at`, `box_at`, `holding` | fluent | Boolean facts about the world. |
|
|
250
|
+
| `PickPlaceParams`, `MoveParams` | parameter dataclass | Transition argument types. |
|
|
251
|
+
| `pick`, `place`, `move` | transition | The robot's verbs. |
|
|
252
|
+
|
|
253
|
+
## What's NOT here
|
|
254
|
+
|
|
255
|
+
- No executable behaviour. The transitions are symbolic specs; nothing in
|
|
256
|
+
this package moves a real or simulated robot. Pair it with a backend that has
|
|
257
|
+
registered `@Action` methods bound to `pick` / `place` / `move`.
|
|
258
|
+
- No room connectivity graph. `move(start, end)` is unconditional. If you want
|
|
259
|
+
a topology where some rooms are only reachable from others, add a
|
|
260
|
+
`connected(a, b)` fluent and put it in `move`'s preconditions.
|
|
261
|
+
- No payload constraints. `pick` doesn't check `Box.weight` against
|
|
262
|
+
`Room.capacity`. Add a numeric precondition to `pick.define(...)` if you want
|
|
263
|
+
one — that's exactly the kind of extension this domain is meant for.
|
|
264
|
+
|
|
265
|
+
## Next
|
|
266
|
+
|
|
267
|
+
- `dynos-core`: the data-layer types (`Transition`, `ObjectType`,
|
|
268
|
+
`ValueField`, `make_new_fluent`) you'll reach for when extending or replacing
|
|
269
|
+
this domain.
|
|
270
|
+
- `dynos-client`: the HTTP client and `dynos` CLI for talking to a backend.
|
|
271
|
+
- `dynos-sentry-domain`: the same machinery applied to a real underwater
|
|
272
|
+
vehicle, with surveys and lifecycle phases.
|
|
273
|
+
- `user_guide.md`: install + auth + first mission, end-to-end.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
src/dynos_warehouse/__init__.py
|
|
4
|
+
src/dynos_warehouse/warehouse.py
|
|
5
|
+
src/dynos_warehouse_domain.egg-info/PKG-INFO
|
|
6
|
+
src/dynos_warehouse_domain.egg-info/SOURCES.txt
|
|
7
|
+
src/dynos_warehouse_domain.egg-info/dependency_links.txt
|
|
8
|
+
src/dynos_warehouse_domain.egg-info/requires.txt
|
|
9
|
+
src/dynos_warehouse_domain.egg-info/top_level.txt
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
dynos-client>=0.1.2
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
dynos_warehouse
|