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.
@@ -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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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