Struct HyperbolicEmbedding 

pub struct HyperbolicEmbedding { /* private fields */ }

Hyperbolic embedding manager for hierarchical data.

Provides a convenient interface for storing and querying hierarchical embeddings in Poincaré ball space.

Implementations

impl HyperbolicEmbedding

pub fn new(config: HyperbolicConfig) -> Self

Create a new hyperbolic embedding manager.

pub fn from_pairs(pairs: Vec<(String, Vec<f32>)>) -> Self

Build a HyperbolicEmbedding from pre-existing (id, vector) pairs.

Useful for restoring from a serialized source (e.g. SQLite dream_state). The vectors are stored as-is — call sites must ensure they were previously projected to the Poincaré ball.

pub fn with_dimensions(dimensions: usize) -> Self

Create with default configuration.

pub fn add(&mut self, id: &str, euclidean: &[f32])

Add a Euclidean vector as a named embedding.

Converts to Poincaré ball coordinates.

pub fn add_child( &mut self, parent_id: &str, child_id: &str, child_euclidean: &[f32], )

Add a parent-child relationship using Möbius addition.

The child is placed at parent ⊕ child_euclidean, which naturally positions it farther from the origin along the parent’s direction.

pub fn get(&self, id: &str) -> Option<&[f32]>

Get the hyperbolic embedding for a given id.

pub fn nearest_neighbors(&self, query_id: &str, k: usize) -> Vec<(String, f32)>

Find the k nearest neighbors in hyperbolic space.

Returns (id, distance) pairs sorted by distance.

pub fn search(&self, query: &[f32], k: usize) -> Vec<(String, f32)>

Find nearest neighbors for an arbitrary Euclidean query.

pub fn hierarchical_distance(&self, id_a: &str, id_b: &str) -> f32

Compute the hierarchical distance between two embeddings.

In hierarchical data, nodes deeper in the tree are farther from the origin. This function returns the hyperbolic distance plus a depth penalty.

pub fn len(&self) -> usize

Returns the number of stored embeddings.

pub fn is_empty(&self) -> bool

Returns true if no embeddings stored.

pub fn ids(&self) -> Vec<&str>

Returns all embedding ids.

pub fn all_embeddings(&self) -> &[(String, Vec<f32>)]

Returns all embeddings as (id, vector) pairs.

pub fn search_memories( &self, query_euclidean: &[f32], k: usize, ) -> Vec<(String, f32)>

Find memories near a query in hyperbolic space.

Returns (memory_id, hyperbolic_distance) pairs. Useful for hierarchical navigation: memories close to the root are general; those near the boundary are specific.

pub fn hierarchical_rank(&self) -> Vec<(String, f32)>

Get the hierarchical depth rank of all memories.

Memories closer to the origin are more general/root-level. Memories farther from origin are more specific/leaf-level.

Returns (id, depth) pairs sorted by depth ascending.

pub fn depth(&self, id: &str) -> f32

Get the hyperbolic distance of a point from the origin.

Points closer to the origin are “higher” in the hierarchy.

pub fn rank_by_depth(&self) -> Vec<(String, f32)>

Rank all embeddings by depth (origin distance).

Returns (id, depth) pairs sorted by depth ascending. Items with lower depth are closer to the root of the hierarchy.