Build and query a spatial-semantic graph

panorai.graph consumes prepared evidence. Applications call pose, depth, semantic, oracle, or external providers explicitly and then pass typed results to the builder. The builder never selects a model, runs matching, or downloads a checkpoint.

The minimal lifecycle is:

  1. create SphericalViewNode and SemanticRegionNode observations with frame, split, access role, and provenance;

  2. adapt the exact matches and inliers that supported a pose into PairFeatureEvidence and RelativePoseEdge;

  3. call associate_regions and localize_region_pair independently;

  4. add accepted records to SpatialSemanticGraphBuilder;

  5. call snapshot(), archive with save_graph_archive, and query through SpatialSemanticGraphQuery.

No scale is invented. Without finite depth or metric scale, localization is reported as unbounded angular or scale-free support. Metric sparse-voxel support is only produced when metric evidence exists. One view never confirms an entity under the conservative-v1 policy.

Archives contain graph.jsonl plus SHA-256-addressed arrays/*.npz sidecars. Loading verifies every sidecar before reconstructing the immutable snapshot. Text queries require an encoder that explicitly declares compatible text-image alignment.

See Spatial-semantic graph API for the public classes and API stability in 3.x for the Experimental boundary.