108 lines
2.7 KiB
Markdown
108 lines
2.7 KiB
Markdown
|
# Spatial Specialist
|
||
|
|
|
||
|
|
**specialist_id:** `spatial`
|
||
|
|
**trigger_gates:** `has_spatial_relation`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Responsibility
|
||
|
|
|
||
|
|
The spatial specialist adds location, containment, direction, proximity, and topology constraints to objects. It attaches SpatialFacets to entities and events with spatial dimension, and emits spatial constraints between objects.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Manifest
|
||
|
|
|
||
|
|
```
|
||
|
|
declared_facet_kinds:
|
||
|
|
- spatial
|
||
|
|
|
||
|
|
declared_constraint_types:
|
||
|
|
- inside
|
||
|
|
- outside
|
||
|
|
- adjacent
|
||
|
|
- above
|
||
|
|
- below
|
||
|
|
- north_of
|
||
|
|
- south_of
|
||
|
|
- east_of
|
||
|
|
- west_of
|
||
|
|
- near
|
||
|
|
- far
|
||
|
|
- at_location
|
||
|
|
- between
|
||
|
|
- on_path
|
||
|
|
|
||
|
|
budget_caps:
|
||
|
|
max_objects_proposed: 4
|
||
|
|
max_facets_emitted: 8
|
||
|
|
max_constraints_emitted: 12
|
||
|
|
max_merges: 0
|
||
|
|
max_splits: 0
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Output: SpatialFacet
|
||
|
|
|
||
|
|
Attach to objects with a spatial dimension (entities, events, states, code objects with file location).
|
||
|
|
|
||
|
|
```
|
||
|
|
SpatialFacet fields used:
|
||
|
|
- location_label: string (natural language location)
|
||
|
|
- coordinates: {x, y, z} if numeric coords available
|
||
|
|
- containment_refs: constraint IDs for inside/outside relations
|
||
|
|
- reference_frame: coordinate system or reference object
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Output: Constraints
|
||
|
|
|
||
|
|
### `inside(A, B)`
|
||
|
|
|
||
|
|
Object A is contained within object B. Example: `inside(book, shelf)`, `inside(Alice, building)`.
|
||
|
|
|
||
|
|
### `adjacent(A, B)`
|
||
|
|
|
||
|
|
A and B are next to each other without containment.
|
||
|
|
|
||
|
|
### `at_location(A, L)`
|
||
|
|
|
||
|
|
Object A is at named location L. L should be a canonical object of kind `entity` (a place).
|
||
|
|
|
||
|
|
### `between(A, B, C)`
|
||
|
|
|
||
|
|
Object A is between objects B and C.
|
||
|
|
|
||
|
|
### Directional constraints
|
||
|
|
|
||
|
|
`north_of`, `south_of`, `east_of`, `west_of`, `above`, `below` — all take two argument_refs in the form `(subject, reference)`.
|
||
|
|
|
||
|
|
### `near(A, B)` / `far(A, B)`
|
||
|
|
|
||
|
|
Relative proximity. Strength is always `soft` since "near" is inherently vague without a defined scale.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Reference frame handling
|
||
|
|
|
||
|
|
Spatial constraints are only meaningful relative to a reference frame. When no frame is explicit in the input, use `"world"` as the default frame label.
|
||
|
|
|
||
|
|
```
|
||
|
|
SpatialFacet.reference_frame:
|
||
|
|
- "world" -- global geographic frame (default when unspecified)
|
||
|
|
- "local" -- relative to a locally established reference
|
||
|
|
- "{object_id}" -- relative to a specific object in WorldState
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Contract test requirements
|
||
|
|
|
||
|
|
- Given `Alice is in the kitchen`, must emit `at_location(E_alice, O_kitchen)` or `inside(E_alice, O_kitchen)`
|
||
|
|
- Given `The box is on the shelf`, must emit `above(O_box, O_shelf)` or `on(O_box, O_shelf)`
|
||
|
|
- Must not emit temporal or quantity constraints
|
||
|
|
- All spatial facets must have `location_label` set
|
||
|
|
- All emitted constraints must have `source_module: spatial`
|