Struct CategoryLayer 

pub struct CategoryLayer {
    pub summaries: Vec<CategorySummary>,
    pub name_to_index: HashMap<String, usize>,
    pub graph: CategoryGraph,
    pub inner_spheres: HashMap<usize, InnerSphere>,
    pub domain_groups: Vec<DomainGroup>,
    pub group_inner_spheres: HashMap<usize, InnerSphere>,
    pub spatial_quality: SpatialQuality,
    /* private fields */
}

Category Enrichment Layer: aggregate statistics, inter-category graph, bridge item detection, and automatic inner spheres over a projected SphereQL corpus.

This is a read-only structure computed from an existing pipeline’s data. It adds category-level reasoning without modifying the underlying projection or spatial index.

Fields

summaries: Vec<CategorySummary>

One summary per unique category, in insertion order.

name_to_index: HashMap<String, usize>

Map from category name to index in summaries.

graph: CategoryGraph

The inter-category adjacency graph.

inner_spheres: HashMap<usize, InnerSphere>

Inner spheres keyed by category index. Only present for categories that meet the size and EVR-improvement thresholds.

domain_groups: Vec<DomainGroup>

Domain groups discovered from category geometry. Default nearest() routing chooses the closest group via these centroids.

group_inner_spheres: HashMap<usize, InnerSphere>

Inner spheres keyed by domain-group index. Built only when the group’s union of members beats the EVR threshold versus the outer projection — the realistic-grouping unit per the v2 routing design (replaces the previous one-per-category default).

spatial_quality: SpatialQuality

Pre-computed spatial properties of the category layout on S². Used for bridge quality scoring, confidence signals, and routing.

Implementations

impl CategoryLayer

pub fn build<P: Projection>( categories: &[String], embeddings: &[Embedding], projected_positions: &[SphericalPoint], projection: &P, evr: f64, ) -> Self

Build the category enrichment layer from pipeline data.

• categories[i] is the category name for item i.
• embeddings[i] is the raw embedding for item i.
• projected_positions[i] is the spherical position on the outer sphere.
• projection is used to project category centroids and measure per-point certainty for inner sphere threshold decisions.

Inner spheres are automatically constructed for categories that:

1. Have ≥ 20 members
2. Show ≥ 0.10 EVR improvement over the global projection

Categories with ≥ 80 members additionally try kernel PCA and select it if it improves EVR by ≥ 0.05 over linear PCA.

O(N·C + C²) for the base layer, plus O(n_c²·d) per inner sphere.

Uses PipelineConfig::default for all tunables. Call Self::build_with_config to override.

pub fn build_with_config<P: Projection>( categories: &[String], embeddings: &[Embedding], projected_positions: &[SphericalPoint], projection: &P, evr: f64, config: &PipelineConfig, ) -> Self

Configurable variant of Self::build. Threads a PipelineConfig through spatial quality, bridge classification, and inner-sphere gating.

pub fn annotate_bridge_relations(&mut self, labels: &[String])

Annotate every bridge with a heuristically inferred RelationType.

Looks at each bridge item’s concept label (indexed into labels by BridgeItem::item_index) along with its source and target category names. Bridges whose label doesn’t match any cue remain relation: None.

pub fn relation_census(&self) -> HashMap<Option<RelationType>, usize>

Histogram of relation types across every bridge in the graph.

None is included as its own bucket so callers can see how many bridges remain unlabeled after annotation.

pub fn num_categories(&self) -> usize

Number of categories.

pub fn get_category(&self, name: &str) -> Option<&CategorySummary>

Look up a category by name.

pub fn category_neighbors( &self, category_name: &str, k: usize, ) -> Vec<&CategorySummary>

Get the k nearest neighbor categories to the given category.

pub fn bridge_items( &self, source_category: &str, target_category: &str, max_bridges: usize, ) -> Vec<&BridgeItem>

Get bridge items between two categories.

pub fn category_path( &self, source_category: &str, target_category: &str, ) -> Option<CategoryPath>

Find the shortest path between two categories through the category graph.

pub fn categories_near_embedding<P: Projection>( &self, embedding: &Embedding, projection: &P, max_angle: f64, ) -> Vec<(usize, f64)>

Find all categories whose centroid is within max_angle radians of the given embedding’s projected position.

pub fn categories_near_embedding_weighted<P: Projection>( &self, embedding: &Embedding, projection: &P, max_angle: f64, ) -> Vec<(usize, f64, f64, f64)>

Certainty-weighted category routing.

Like Self::categories_near_embedding but penalizes routes through low-certainty projection regions. The effective distance is scaled by 1 / sqrt(certainty), so poorly-projected queries don’t get routed to whatever random centroid happens to be angularly close in the distorted projection.

Returns (category_index, raw_angular_distance, effective_distance, certainty).

pub fn has_inner_sphere(&self, category_name: &str) -> bool

Whether a given category has an inner sphere.

pub fn get_inner_sphere(&self, category_name: &str) -> Option<&InnerSphere>

Get the inner sphere for a category, if one exists.

pub fn num_inner_spheres(&self) -> usize

Number of categories that have inner spheres.

pub fn drill_down_with_projection<P: Projection>( &self, category_name: &str, embedding: &Embedding, projection: &P, k: usize, ) -> Vec<DrillDownResult>

Drill down with an explicit outer projection for the fallback case.

When no inner sphere exists, the query is projected using the provided projection and compared against stored outer positions.

pub fn drill_down_group( &self, group_index: usize, embedding: &Embedding, k: usize, ) -> Vec<DrillDownResult>

Drill down into a domain group’s inner sphere. Returns an empty vec if the group index is unknown or has no inner sphere.

Used by the v2 default nearest() path: route to the closest group, then run k-NN against the group-level inner positions.

pub fn nearest_group(&self, pos: &SphericalPoint) -> Option<(usize, f64, f64)>

Index of the domain group whose centroid is nearest to pos, along with the angular distance to the second-nearest group’s centroid (or f64::INFINITY if there is only one group).

The default nearest() routing in SphereQLPipeline drills into the nearest group’s inner sphere only when nearest_dist / second_dist < group_routing_alpha; the second distance is returned alongside so the caller can apply that gate without recomputing.

pub fn inner_sphere_stats(&self) -> Vec<InnerSphereReport>

Report which categories have inner spheres, their projection type, and EVR metrics.

Trait Implementations

impl Clone for CategoryLayer

fn clone(&self) -> CategoryLayer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CategoryLayer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.