🔬 Show & Tell 25.4 — SpatialReasoner Architecture

[web3guru888]

🔬 SpatialReasoner Architecture — Cognitive Maps & Spatial Intelligence

Overview

Phase 25.4 introduces SpatialReasoner, implementing cognitive map theory (Tolman 1948) with a hybrid topological-metric representation. The SpatialReasoner maintains an internal spatial model of the environment, supports pathfinding, reference frame transformations, and mental rotation — core capabilities for embodied spatial intelligence.

Data Flow

┌──────────────────────────────────────────────────────────────┐
│                    HybridSpatialReasoner                      │
│                                                              │
│  ┌────────────┐                                              │
│  │ FusedState  │ (from SensorFusion 25.1)                    │
│  │ .position   │                                             │
│  │ .objects[]  │                                             │
│  │ .surfaces[] │                                             │
│  └─────┬──────┘                                              │
│        ▼                                                     │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              DUAL REPRESENTATION                     │    │
│  │                                                      │    │
│  │  ┌─────────────────┐    ┌────────────────────────┐  │    │
│  │  │ Topological Graph│    │ Metric Occupancy Grid  │  │    │
│  │  │                  │    │                         │  │    │
│  │  │  Kitchen──Hall   │    │ ░░░░░░░░░░░░░░░░░░░░  │  │    │
│  │  │    │        │    │    │ ░░░░████░░░░░░░░░░░░  │  │    │
│  │  │  Bath    Living  │    │ ░░░░████░░░░░░A░░░░░  │  │    │
│  │  │    │        │    │    │ ░░░░░░░░░░░░░░░░░░░░  │  │    │
│  │  │  Bedroom───┘     │    │ ░░████░░░░░░░░░░░░░░  │  │    │
│  │  │                  │    │ ░░████░░░░████░░░░░░  │  │    │
│  │  │ Nodes: places    │    │ ░░░░░░░░░░████░░░░░░  │  │    │
│  │  │ Edges: passages  │    │ ░░░░░░░░░░░░░░░░░░░░  │  │    │
│  │  │ (connectivity)   │    │ (precise geometry)     │  │    │
│  │  └─────────────────┘    └────────────────────────┘  │    │
│  │                                                      │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         ▼                                    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              SPATIAL OPERATIONS                       │    │
│  │                                                      │    │
│  │  ┌──────────┐ ┌──────────┐ ┌───────────────────┐   │    │
│  │  │ A* Path   │ │ Ref Frame│ │ Mental Rotation   │   │    │
│  │  │ Finding   │ │ Transform│ │ & Perspective     │   │    │
│  │  └──────────┘ └──────────┘ └───────────────────┘   │    │
│  │  ┌──────────┐ ┌──────────┐ ┌───────────────────┐   │    │
│  │  │ KD-Tree  │ │ Nearest  │ │ Visibility &      │   │    │
│  │  │ Queries  │ │ Neighbor │ │ Occlusion         │   │    │
│  │  └──────────┘ └──────────┘ └───────────────────┘   │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         ▼                                    │
│                  ┌──────────────┐                            │
│                  │ SpatialMap    │                            │
│                  │ .topo_graph   │                            │
│                  │ .metric_grid  │                            │
│                  │ .objects[]    │                            │
│                  │ .agent_pose   │                            │
│                  └──────┬───────┘                            │
└─────────────────────────┼────────────────────────────────────┘
                          │
              ┌───────────┼──────────────┐
              ▼           ▼              ▼
       MotorPlanner  AffordanceDet  EmbodiedOrch
          (25.3)       (25.2)         (25.5)

A* Pathfinding on the Topological Graph

find_path(Kitchen, Bedroom):

  Open:  {Kitchen(g=0, h=3)}
  
  Step 1: Expand Kitchen → neighbors: Hall(g=1), Bath(g=1)
    Open:  {Hall(g=1,h=2,f=3), Bath(g=1,h=2,f=3)}
    
  Step 2: Expand Hall → neighbors: Kitchen(visited), Living(g=2)
    Open:  {Bath(g=1,h=2,f=3), Living(g=2,h=1,f=3)}
    
  Step 3: Expand Bath → neighbors: Kitchen(visited), Bedroom(g=2)
    Open:  {Living(g=2,h=1,f=3), Bedroom(g=2,h=0,f=2)} ← GOAL!
    
  Path: Kitchen → Bath → Bedroom  (cost: 2)

Heuristic: Euclidean distance between node centroid positions. Guarantees optimality (admissible + consistent).

Reference Frame Transform

Converting between ego-centric and allocentric (world) frames:

Ego → World:                    World → Ego:
p_world = R(θ) · p_ego + t     p_ego = R(-θ) · (p_world - t)

where:
  R(θ) = ┌ cos(θ)  -sin(θ) ┐   t = agent position in world frame
         └ sin(θ)   cos(θ) ┘   θ = agent heading in world frame

Example:
  Agent at (5, 3), heading 90°:
  Object at ego (2, 0) → world (5, 5)  [2m ahead = 2m in +y direction]

Mental Rotation Pipeline

Spatial perspective-taking: "What does scene X look like from position Y?"

1. Query: view_from(observer_pos=(10,5), look_at=(5,5))
2. Build view frustum from observer position
3. Project all objects into observer's reference frame
4. Occlusion culling: ray-cast to determine visibility
5. Return: SpatialView with visible objects + relative positions

This supports SocialOrchestrator (24.5) perspective-taking by providing spatial grounding.

KD-Tree Spatial Index

For efficient nearest-neighbor and range queries on objects:

Build: O(n log n) from n object positions
Query: O(log n) for k-nearest-neighbors
Range: O(√n + k) for all objects within radius r

Rebuild policy:
  - Triggered when >20% of objects have moved significantly
  - Or explicitly via rebuild_index()
  - Background rebuild with read-copy-update (RCU) pattern

Prometheus Metrics

Metric	Type	Description
asi_spatial_reasoner_queries_total	Counter	Total spatial queries (label: query_type)
asi_spatial_reasoner_query_latency_seconds	Histogram	Query latency (label: query_type)
asi_spatial_reasoner_map_nodes	Gauge	Number of nodes in topological graph
asi_spatial_reasoner_grid_cells_occupied	Gauge	Occupied cells in metric grid
asi_spatial_reasoner_kdtree_rebuild_total	Counter	KD-tree rebuild count

PromQL:

# Query throughput by type
sum by (query_type) (rate(asi_spatial_reasoner_queries_total[5m]))

# Pathfinding latency p95
histogram_quantile(0.95, rate(asi_spatial_reasoner_query_latency_seconds_bucket{query_type="pathfind"}[5m]))

# Map growth
asi_spatial_reasoner_map_nodes

Integration Map

SensorFusion 25.1 ──→ SpatialReasoner 25.4 (FusedState → map update)
SpatialReasoner 25.4 ──→ MotorPlanner 25.3 (obstacle map for planning)
                    ──→ AffordanceDetector 25.2 (spatial relations for affordances)
                    ──→ EmbodiedOrchestrator 25.5 (spatial context)
                    ──→ PerspectiveTaker 24.3 (spatial perspective grounding)
TemporalGraph 17.1 ──→ SpatialReasoner (temporal indices for "where was X at time T?")

📌 Spec: #565 | Q&A: See companion discussion