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)[source]¶

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)[source]¶

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)[source]¶

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>)[source]¶

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.
`geometric_loop`	Fast geometric relation loop.
`geometry`	Deterministic geometric relation predicates and cache-invalidation signatures, shared by the scene-graph builder/store.
`image_relations`	Image-grounded VLM relation inference (VLM-primary scene graph).
`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`	Live scene graph and persistent caption/relation caches.
`types`	Core data structures for the Scene Graph layer.