Spatial-semantic graph API¶

The Experimental panorai-spatial-semantic-graph/v1 contract separates observations, correspondence candidates, spatial posteriors, entity hypotheses, lifecycle events, persistence, and query.

Experimental spatial-semantic graph contracts and lifecycle APIs.

Importing panorai.graph loads no neural-network, reconstruction, or database backend. Perception providers are selected and called explicitly by the application; the graph builder only consumes their prepared results.

class panorai.graph.CallablePanorAiProvider(source, function)¶

Explicit adapter around a caller-supplied public PanorAi callable.

function¶

provide(value)¶

source¶

class panorai.graph.DisabledProvider(source: 'EvidenceSource')¶

provide(value=None)¶

source¶

class panorai.graph.EvidenceMode(*values)¶

How evidence entered the graph contract.

DISABLED = 'disabled'¶

ESTIMATED = 'estimated'¶

EXTERNAL = 'external'¶

ORACLE = 'oracle'¶

class panorai.graph.EvidenceProvider(*args, **kwargs)¶

provide(value)¶: Produce one explicit evidence result.

source¶

class panorai.graph.EvidenceSource(source_id, modality, mode, method_id, interface_version, access_role='method_input', frame=None, units=None, split=None, calibration_id=None, correlation_group=None, model_id=None, config_hash=None, generating_commit=None, provenance=<factory>)¶

Provenance and access policy for one evidence-producing modality.

access_role¶

property allowed_as_method_evidence¶

calibration_id¶

config_hash¶

correlation_group¶

frame¶

generating_commit¶

interface_version¶

method_id¶

modality¶

mode¶

model_id¶

provenance¶

source_id¶

split¶

units¶

class panorai.graph.ExternalProvider(source: 'EvidenceSource', result: 'OutputT')¶

provide(value=None)¶

result¶

source¶

exception panorai.graph.GraphArchiveError¶: Raised when a graph archive is incomplete, incompatible, or corrupt.

class panorai.graph.GraphBuilderConfig(graph_name: 'str', promotion_policy: 'PromotionPolicy')¶

classmethod conservative_v1(graph_name)¶

graph_name¶

promotion_policy¶

class panorai.graph.GraphEvent(event_id: 'str', event_type: 'str', subject_ids: 'tuple[str, ...]', payload: 'Mapping[str, Any]' = <factory>)¶

classmethod create(event_type, subject_ids, payload=None)¶

event_id¶

event_type¶

payload¶

subject_ids¶

class panorai.graph.GraphQueryFilters(splits: 'tuple[str, ...]' = (), frames: 'tuple[str, ...]' = (), source_modalities: 'tuple[str, ...]' = (), hypothesis_states: 'tuple[str, ...]' = (), min_confidence: 'float' = 0.0)¶

frames¶

hypothesis_states¶

min_confidence¶

source_modalities¶

splits¶

class panorai.graph.GraphQueryResult(hypothesis_id: 'str', score: 'float', score_components: 'Mapping[str, float]', uncertainty: 'float | None', evidence_ids: 'tuple[str, ...]', state: 'str', class_name: 'str')¶

class_name¶

evidence_ids¶

hypothesis_id¶

score¶

score_components¶

state¶

uncertainty¶

class panorai.graph.ObjectHypothesisNode(hypothesis_id: 'str', class_id: 'int', class_name: 'str', state: 'HypothesisState', region_ids: 'tuple[str, ...]', view_ids: 'tuple[str, ...]', correspondence_edge_ids: 'tuple[str, ...]', posterior_ids: 'tuple[str, ...]', confidence: 'float', lineage_parent_ids: 'tuple[str, ...]' = (), superseded_by_ids: 'tuple[str, ...]' = (), independent_view_count: 'int' = 0)¶

class_id¶

class_name¶

confidence¶

correspondence_edge_ids¶

hypothesis_id¶

independent_view_count¶

lineage_parent_ids¶

posterior_ids¶

region_ids¶

state¶

superseded_by_ids¶

view_ids¶

class panorai.graph.OracleProvider(source: 'EvidenceSource', result: 'OutputT')¶

provide(value=None)¶

result¶

source¶

class panorai.graph.PairFeatureEvidence(evidence_id, view_id_a, view_id_b, feature_indices_a, feature_indices_b, bearings_a, bearings_b, valid, pose_inlier_mask, pose_residuals_rad, descriptor_type, descriptor_metric, source)¶

Feature correspondences reused from the pose-supporting match set.

bearings_a¶

bearings_b¶

descriptor_metric¶

descriptor_type¶

evidence_id¶

feature_indices_a¶

feature_indices_b¶

pose_inlier_mask¶

pose_residuals_rad¶

source¶

valid¶

view_id_a¶

view_id_b¶

class panorai.graph.PairwiseLocalizationConfig(min_triangulated_points: 'int' = 2, min_triangulation_angle_deg: 'float' = 0.5, max_reprojection_error_deg: 'float' = 2.0, voxel_size: 'float | None' = None, preset: 'str' = 'conservative-v1')¶

max_reprojection_error_deg¶

min_triangulated_points¶

min_triangulation_angle_deg¶

preset¶

voxel_size¶

class panorai.graph.PairwiseLocalizationInput(candidate: 'RegionCorrespondenceCandidate', region_a: 'SemanticRegionNode', region_b: 'SemanticRegionNode', feature_evidence: 'PairFeatureEvidence', pose: 'RelativePoseEdge', bounds_xyz: 'np.ndarray | None' = None)¶

bounds_xyz¶

candidate¶

feature_evidence¶

pose¶

region_a¶

region_b¶

class panorai.graph.PairwiseLocalizationResult(posterior: 'SpatialSemanticPosterior', triangulated_points: 'np.ndarray', supporting_match_indices: 'np.ndarray', parallax_deg: 'np.ndarray', reprojection_error_deg: 'np.ndarray')¶

parallax_deg¶

posterior¶

reprojection_error_deg¶

supporting_match_indices¶

triangulated_points¶

class panorai.graph.PromotionPolicy(policy_id: 'str', min_independent_views: 'int', min_confidence: 'float', dormant_below_confidence: 'float')¶

classmethod conservative_v1()¶

dormant_below_confidence¶

min_confidence¶

min_independent_views¶

policy_id¶

class panorai.graph.RegionAssociationConfig(min_region_matches=3, min_region_pose_inliers=3, max_median_pose_residual_deg=1.5, ambiguity_margin=0.05, require_accepted_pose=True, preset='conservative-v1')¶

Versioned conservative policy for the two-view association baseline.

ambiguity_margin¶

max_median_pose_residual_deg¶

min_region_matches¶

min_region_pose_inliers¶

preset¶

require_accepted_pose¶

class panorai.graph.RegionAssociationInput(regions_a: 'tuple[SemanticRegionNode, ...]', regions_b: 'tuple[SemanticRegionNode, ...]', feature_evidence: 'PairFeatureEvidence', pose: 'RelativePoseEdge', query_class_ids: 'tuple[int, ...] | None' = None)¶

feature_evidence¶

pose¶

query_class_ids¶

regions_a¶

regions_b¶

class panorai.graph.RegionAssociationResult(candidates: 'tuple[RegionCorrespondenceCandidate, ...]', edges: 'tuple[RegionCorrespondenceEdge, ...]', diagnostics: 'dict[str, int | float | str]')¶

candidates¶

diagnostics¶

edges¶

class panorai.graph.RegionCorrespondenceCandidate(candidate_id: 'str', region_id_a: 'str', region_id_b: 'str', view_id_a: 'str', view_id_b: 'str', class_id: 'int', class_name: 'str', match_indices: 'np.ndarray', inlier_match_indices: 'np.ndarray', semantic_score: 'float', geometric_score: 'float', ranking_score: 'float', median_pose_residual_rad: 'float | None', state: 'AssociationState', reasons: 'tuple[str, ...]' = ())¶

candidate_id¶

class_id¶

class_name¶

geometric_score¶

inlier_match_indices¶

match_indices¶

median_pose_residual_rad¶

ranking_score¶

reasons¶

region_id_a¶

region_id_b¶

semantic_score¶

state¶

view_id_a¶

view_id_b¶

class panorai.graph.RegionCorrespondenceEdge(edge_id: 'str', candidate_id: 'str', region_id_a: 'str', region_id_b: 'str', confidence: 'float', source_evidence_ids: 'tuple[str, ...]', correlation_groups: 'tuple[str, ...]' = (), polarity: "Literal['positive', 'negative']" = 'positive')¶

candidate_id¶

confidence¶

correlation_groups¶

edge_id¶

polarity¶

region_id_a¶

region_id_b¶

source_evidence_ids¶

class panorai.graph.RelativePoseEdge(edge_id: 'str', view_id_a: 'str', view_id_b: 'str', rotation_b_from_a: 'np.ndarray', translation_direction_b_from_a: 'np.ndarray', accepted: 'bool', degenerate: 'bool', source: 'EvidenceSource', feature_evidence_id: 'str', translation_scale: 'float | None' = None, units: 'str | None' = None, failure_reasons: 'tuple[str, ...]' = ())¶

accepted¶

degenerate¶

edge_id¶

failure_reasons¶

feature_evidence_id¶

rotation_b_from_a¶

source¶

translation_direction_b_from_a¶

translation_scale¶

units¶

view_id_a¶

view_id_b¶

class panorai.graph.SemanticRegionNode(region_id: 'str', view_id: 'str', class_id: 'int', class_name: 'str', vocabulary: 'str', semantic_score: 'float', feature_indices: 'np.ndarray', membership_weights: 'np.ndarray', centroid_bearing: 'np.ndarray', source: 'EvidenceSource', embedding: 'np.ndarray | None' = None, encoder_id: 'str | None' = None, text_image_aligned: 'bool' = False, correlation_group: 'str | None' = None)¶

centroid_bearing¶

class_id¶

class_name¶

correlation_group¶

embedding¶

encoder_id¶

feature_indices¶

membership_weights¶

region_id¶

semantic_score¶

source¶

text_image_aligned¶

view_id¶

vocabulary¶

class panorai.graph.SpatialSemanticGraph(graph_id: 'str', views: 'tuple[SphericalViewNode, ...]', feature_evidence: 'tuple[PairFeatureEvidence, ...]', pose_edges: 'tuple[RelativePoseEdge, ...]', regions: 'tuple[SemanticRegionNode, ...]', correspondence_candidates: 'tuple[RegionCorrespondenceCandidate, ...]', correspondence_edges: 'tuple[RegionCorrespondenceEdge, ...]', posteriors: 'tuple[SpatialSemanticPosterior, ...]', hypotheses: 'tuple[ObjectHypothesisNode, ...]', event_ids: 'tuple[str, ...]', interface: 'str' = 'panorai-spatial-semantic-graph/v1', stability: 'str' = 'experimental')¶

correspondence_candidates¶

correspondence_edges¶

describe()¶

event_ids¶

feature_evidence¶

graph_id¶

hypotheses¶

interface¶

pose_edges¶

posteriors¶

regions¶

stability¶

views¶

class panorai.graph.SpatialSemanticGraphBuilder(config)¶

Accumulate prepared evidence and materialize deterministic snapshots.

The builder never selects or calls a provider. All perception results are passed explicitly through add_* methods.

add_candidate(candidate)¶

add_correspondence(edge)¶

add_feature_evidence(evidence)¶

add_many(records)¶

add_pose(pose)¶

add_posterior(posterior)¶

add_region(region)¶

add_view(view)¶

property events¶

merge_hypotheses(hypothesis_ids)¶

snapshot()¶

split_hypothesis(hypothesis_id, region_groups)¶

class panorai.graph.SpatialSemanticGraphQuery(graph)¶

neighbors(node_id)¶

query_embedding(embedding, *, encoder_id, filters=None, limit=10)¶

query_spatial(bounds_xyz, *, frame, units, filters=None, limit=10)¶

query_text(text, *, encoder, filters=None, limit=10)¶

class panorai.graph.SpatialSemanticPosterior(posterior_id: 'str', frame: 'str', units: 'str', mode: 'PosteriorMode', support_kind: "Literal['angular', 'ray', 'sparse_voxel']", log_probabilities: 'np.ndarray', support: 'np.ndarray', map_position_xyz: 'np.ndarray | None', centroid_xyz: 'np.ndarray | None', covariance_xyz: 'np.ndarray | None', bounding_box_xyz: 'np.ndarray | None', bearing_xyz: 'np.ndarray | None', confidence: 'float', source_evidence_ids: 'tuple[str, ...]', diagnostics: 'Mapping[str, float | int | str]' = <factory>)¶

bearing_xyz¶

bounding_box_xyz¶

centroid_xyz¶

confidence¶

covariance_xyz¶

diagnostics¶

frame¶

log_probabilities¶

map_position_xyz¶

mode¶

posterior_id¶

source_evidence_ids¶

support¶

support_kind¶

units¶

class panorai.graph.SphericalViewNode(view_id: 'str', frame: 'str', split: 'str', source_checksum: 'str', access_role: 'AccessRole' = 'method_input', timestamp: 'float | None' = None, metadata: 'Mapping[str, str]' = <factory>)¶

access_role¶

frame¶

metadata¶

source_checksum¶

split¶

timestamp¶

view_id¶

class panorai.graph.TextImageEncoder(*args, **kwargs)¶

encode_text(text)¶

encoder_id¶

text_image_aligned¶

panorai.graph.assign_region_correspondences(candidates, config=None)¶: Apply deterministic one-to-one assignment and expose ambiguity.

panorai.graph.associate_regions(evidence, config=None)¶

panorai.graph.load_graph_archive(directory)¶: Load and checksum-verify a graph archive snapshot.

panorai.graph.localize_region_pair(evidence, config=None)¶: Estimate an honest angular, scale-free, or metric posterior.

panorai.graph.neighbors(graph, node_id)¶

panorai.graph.propose_region_correspondences(evidence, config=None)¶: Score class-compatible pairs without changing the pose result.

panorai.graph.query_embedding(graph, embedding, *, encoder_id, **kwargs)¶

panorai.graph.query_spatial(graph, bounds_xyz, *, frame, units, **kwargs)¶

panorai.graph.query_text(graph, text, *, encoder, **kwargs)¶

panorai.graph.replay_graph_archive(directory)¶: Replay the archive’s canonical records into the immutable snapshot.

panorai.graph.save_graph_archive(graph, directory, *, events=())¶: Write a canonical portable archive and return graph.jsonl.