Struct Singularity 

pub struct Singularity<H: Hypervector = HVec10240> {
    pub config: SingularityConfig,
    pub namespaces: HashMap<String, NamespaceState<H>>,
    pub cache_metrics: Arc<CacheMetrics>,
    /* private fields */
}

Fields

config: SingularityConfig

namespaces: HashMap<String, NamespaceState<H>>

cache_metrics: Arc<CacheMetrics>

Implementations

impl Singularity

pub fn neighbors( &self, ns: &str, id: &str, min_strength: f32, ) -> Vec<(String, f32)>

Get direct neighbors of a concept with edge strengths.

Returns outbound associations with strength >= min_strength.

pub fn bfs( &self, ns: &str, start: &str, config: &TraversalConfig, ) -> Result<Vec<(String, u32)>>

Get incoming associations for a concept.

Returns concepts that have associations pointing to this concept. Breadth-first traversal from a starting concept.

Returns nodes reachable within config.max_depth hops, along with their depths. Nodes are returned in BFS order.

pub fn shortest_path( &self, ns: &str, from: &str, to: &str, config: &TraversalConfig, ) -> Result<Option<Vec<String>>>

Find the minimum-cost path between two concepts using weighted Dijkstra.

Edge cost is -ln(strength), so stronger associations have lower cost. A strength of 1.0 has cost 0.0; a strength of 0.1 has cost ~2.3. Strength values ≤ 0 are treated as cost f32::MAX (effectively unreachable).

Returns None if no path exists within config.max_depth hops. Use Self::shortest_path_hops for unweighted (fewest-hop) traversal.

pub fn shortest_path_hops( &self, ns: &str, from: &str, to: &str, config: &TraversalConfig, ) -> Result<Option<Vec<String>>>

Find the fewest-hop path between two concepts using unweighted BFS.

Returns the path with the minimum number of hops, ignoring edge strengths. Use Self::shortest_path for strength-weighted (Dijkstra) traversal.

Returns None if no path exists within config.max_depth hops.

impl<H: Hypervector + 'static> Singularity<H>

pub fn new(config: SingularityConfig) -> Self

pub fn new_with_metrics( config: SingularityConfig, cache_metrics: Arc<CacheMetrics>, ) -> Self

pub fn with_config(config: SingularityConfig) -> Self

pub fn with_config_and_backend( config: SingularityConfig, backend: IndexBackend, ) -> Self

pub fn with_config_backend_and_metrics( config: SingularityConfig, backend: IndexBackend, cache_metrics: Arc<CacheMetrics>, ) -> Self

pub fn get_namespace(&self, ns: &str) -> Option<&NamespaceState<H>>

pub fn ensure_namespace(&mut self, ns: &str) -> Result<&mut NamespaceState<H>>

Ensure a namespace exists, creating its ANN index if needed.

Returns Err(MemoryError::InvalidInput) when the configured ANN backend cannot be constructed (e.g. invalid HNSW/LSH parameters).

pub fn get_namespace_mut(&mut self, ns: &str) -> Result<&mut NamespaceState<H>>

Mutable access to a namespace, creating it if absent.

Breaking change (0.3.x → next): returns Result instead of a bare &mut NamespaceState. Prefer Self::ensure_namespace. Invalid ANN backend configuration propagates as MemoryError::InvalidInput rather than panicking. Migration: use ? or handle the Result at call sites.

pub fn inject(&mut self, ns: &str, concept: Concept<H>) -> Result<()>

pub fn update(&mut self, ns: &str, id: &str, vector: H) -> Result<()>

pub fn delete(&mut self, ns: &str, id: &str) -> Result<()>

pub fn clear(&mut self, ns: &str)

pub fn get(&self, ns: &str, id: &str) -> Option<&Concept<H>>

pub fn associate( &mut self, ns: &str, from: &str, to: &str, strength: f32, ) -> Result<()>

pub fn disassociate(&mut self, ns: &str, from: &str, to: &str) -> Result<()>

pub fn get_associations(&self, ns: &str, id: &str) -> Vec<(String, f32)>

pub fn get_associations_with_decay( &self, ns: &str, id: &str, curve: DecayCurve, ) -> Vec<(String, f32)>

Get associations with decay curve applied.

pub fn incoming_associations(&self, ns: &str, id: &str) -> Vec<(String, f32)>

pub fn incoming_associations_with_decay( &self, ns: &str, id: &str, curve: DecayCurve, ) -> Vec<(String, f32)>

Get incoming associations with decay curve applied.

pub fn all_concepts(&self, ns: &str) -> Vec<Concept<H>>

pub fn all_associations(&self, ns: &str) -> Vec<(String, String, f32)>

pub fn all_associations_with_decay( &self, ns: &str, curve: DecayCurve, ) -> Vec<(String, String, f32)>

Get all associations with decay curve applied.

pub fn len(&self, ns: &str) -> usize

pub fn is_empty(&self, ns: &str) -> bool

pub fn cache_metrics_snapshot(&self, ns: &str) -> CacheMetricsSnapshot

pub fn invalidate_cache(&self, ns: &str)

pub fn index_stats(&self, ns: &str) -> IndexStats

pub const fn retrieval_config(&self) -> &RetrievalConfig

impl<H: Hypervector + 'static> Singularity<H>

pub fn reinforce_association( &mut self, ns: &str, from: &str, to: &str, ) -> Result<()>

Reinforce an association by resetting its created_at timestamp to now. This effectively refreshes the association so decay starts over.

pub fn prune_decayed_associations( &mut self, ns: &str, curve: DecayCurve, threshold: f32, ) -> usize

Prune associations whose decayed strength falls below threshold. Returns the number of associations removed.

Missing namespaces are a no-op (returns 0) so prune never creates an empty namespace solely to count removals.

impl Singularity

pub fn bundle_concepts_strict( &self, ns: &str, ids: &[String], ) -> Result<HVec10240>

Bundle multiple concepts into a single hypervector.

pub fn update_metadata( &mut self, ns: &str, id: &str, metadata: HashMap<String, Value>, ) -> Result<()>

pub fn clear_associations(&mut self, ns: &str, id: &str) -> Result<()>

impl Singularity

pub fn set_retrieval_config(&mut self, config: RetrievalConfig) -> Result<()>

Set the retrieval configuration.

pub fn last_retrieval_stats(&self, ns: &str) -> RetrievalStats

Get the retrieval configuration. Get statistics from the last retrieval operation.

impl Singularity

pub fn find_similar( &self, ns: &str, query: &HVec10240, top_k: usize, ) -> Vec<(String, f32)>

Find similar concepts using cosine similarity

pub fn find_similar_arc( &self, ns: &str, query: &HVec10240, top_k: usize, ) -> Arc<[(String, f32)]>

Find similar concepts and return cached results as Arc<[_]>.

pub fn find_similar_cached( &self, ns: &str, query: &HVec10240, top_k: usize, ) -> Arc<[(String, f32)]>

Find similar concepts, returning cached results as Arc<[_]>.

Retrieval pipeline:

1. Cache lookup (bypassed when top_k > max_cached_top_k)
2. ANN index lookup (skipped for BruteForce backend)
3. Candidate generation (graph → bucket → exact scan fallback)

pub fn find_similar_filtered( &self, ns: &str, query: &HVec10240, top_k: usize, filter: &MetadataFilter, ) -> Arc<[(String, f32)]>

Find similar concepts with metadata filtering.

impl Singularity

pub fn purge_expired(&mut self, ns: &str) -> usize

Purge all expired concepts from memory.

Returns the number of concepts removed.

pub fn purge_expired_cascading(&mut self, ns: &str, cascading: bool) -> usize

Purge expired concepts, optionally cascading through associations.

pub fn is_expired(&self, ns: &str, id: &str) -> bool

Check if a concept is expired.

pub fn active_concept_ids(&self, ns: &str) -> Vec<String>

Get all non-expired concept IDs.