scene_service.scene_graph

Scene Graph — LLM-enhanced object relation layer over ObjectRegistry.

Runs as an async low-frequency background task (default every 30 s). Reads ObjectRegistry snapshots, generates captions and edge relations via configurable LLM, and exposes the result through SceneGraphStore for MCP tools and web visualization.

class scene_service.scene_graph.GeometryHint(distance: float, xy_overlap: float, vertical_order: str, containment: str)

Bases: object

Spatial cues passed to the LLM alongside the object pair.

containment: str

distance: float

vertical_order: str

xy_overlap: float

class scene_service.scene_graph.SceneGraphEdge(source_id: str, target_id: str, relation: str, confidence: float = 0.0, method: str = 'llm', reason: str = '', updated_at: float = <factory>, stale_rounds: int = 0)

Bases: object

Directed relation between two scene graph nodes.

confidence: float = 0.0

method: str = 'llm'

reason: str = ''

relation: str

source_id: str

stale_rounds: int = 0

target_id: str

updated_at: float

class scene_service.scene_graph.SceneGraphNode(object_id: str, label: str, bbox_center: tuple[float, float, float], bbox_extent: tuple[float, float, float], yaw: float = 0.0, caption: str | None = None, caption_updated_at: float | None = None, confidence: float = 0.0, observation_count: int = 0, last_seen: float | None = None)

Bases: object

One node in the scene graph, mapped 1:1 to an ObjectRegistry record.

bbox_center: tuple[float, float, float]

bbox_extent: tuple[float, float, float]

caption: str | None = None

caption_updated_at: float | None = None

confidence: float = 0.0

label: str

last_seen: float | None = None

object_id: str

observation_count: int = 0

yaw: float = 0.0

class scene_service.scene_graph.SceneGraphSnapshot(nodes: dict[str, ~scene_service.scene_graph.types.SceneGraphNode]=<factory>, edges: list[SceneGraphEdge] = <factory>, updated_at: float = <factory>)

Bases: object

Immutable snapshot of the full scene graph at a point in time.

edges: list[SceneGraphEdge]

nodes: dict[str, SceneGraphNode]

updated_at: float

Modules

builder	SceneGraphBuilder — async rebuild loop that reads ObjectRegistry, generates captions, infers relations via LLM, and stores a snapshot.
captioner	Node captioner — pluggable interface for generating captions.
llm_client	Minimal async OpenAI-compatible LLM client for scene graph inference.
prompts	LLM prompts for scene graph relation inference.
relations	Edge candidate generation and LLM-based relation inference.
store	Scene graph store — holds the latest snapshot and manages caches.
types	Core data structures for the Scene Graph layer.