oxirs_embed/
lib.rs

1//! # OxiRS Embed: Advanced Knowledge Graph Embeddings
2//!
3//! [![Version](https://img.shields.io/badge/version-0.3.1-blue)](https://github.com/cool-japan/oxirs/releases)
4//! [![docs.rs](https://docs.rs/oxirs-embed/badge.svg)](https://docs.rs/oxirs-embed)
5//!
6//! **Status**: Production Release (v0.3.1)
7//! **Stability**: Public APIs are stable. Production-ready with comprehensive testing.
8//!
9//! State-of-the-art knowledge graph embedding methods including TransE, DistMult, ComplEx,
10//! and RotatE models, enhanced with biomedical AI, GPU acceleration, and specialized text processing.
11//!
12//! ## Key Features
13//!
14//! ### 🧬 Biomedical AI
15//! - Specialized biomedical knowledge graph embeddings
16//! - Gene-disease association prediction
17//! - Drug-target interaction modeling
18//! - Pathway analysis and protein interactions
19//! - Domain-specific text embeddings (SciBERT, BioBERT, etc.)
20//!
21//! ### 🚀 GPU Acceleration
22//! - Advanced GPU memory pooling and management
23//! - Intelligent tensor caching
24//! - Mixed precision training and inference
25//! - Multi-stream parallel processing
26//! - Pipeline parallelism for large-scale training
27//!
28//! ### 🤖 Advanced Models
29//! - Traditional KG embeddings (TransE, DistMult, ComplEx, RotatE, etc.)
30//! - Graph Neural Networks (GCN, GraphSAGE, GAT)
31//! - Transformer-based embeddings with fine-tuning
32//! - Ontology-aware embeddings with reasoning
33//!
34//! ### 📊 Production-Ready
35//! - Comprehensive evaluation and benchmarking
36//! - Model registry and version management
37//! - Intelligent caching and optimization
38//! - API server for deployment
39//!
40//! ## Quick Start
41//!
42//! ```rust,no_run
43//! use oxirs_embed::{TransE, ModelConfig, Triple, NamedNode, EmbeddingModel};
44//!
45//! # async fn example() -> anyhow::Result<()> {
46//! // Create a knowledge graph embedding model
47//! let config = ModelConfig::default().with_dimensions(128);
48//! let mut model = TransE::new(config);
49//!
50//! // Add knowledge triples
51//! let triple = Triple::new(
52//!     NamedNode::new("http://example.org/alice")?,
53//!     NamedNode::new("http://example.org/knows")?,
54//!     NamedNode::new("http://example.org/bob")?,
55//! );
56//! model.add_triple(triple)?;
57//!
58//! // Train the model
59//! let stats = model.train(Some(100)).await?;
60//! println!("Training completed: {stats:?}");
61//! # Ok(())
62//! # }
63//! ```
64//!
65//! ## Biomedical Example
66//!
67//! ```rust,no_run
68//! use oxirs_embed::{BiomedicalEmbedding, BiomedicalEmbeddingConfig, EmbeddingModel};
69//!
70//! # async fn example() -> anyhow::Result<()> {
71//! // Create biomedical embedding model
72//! let config = BiomedicalEmbeddingConfig::default();
73//! let mut model = BiomedicalEmbedding::new(config);
74//!
75//! // Add biomedical knowledge
76//! model.add_gene_disease_association("BRCA1", "breast_cancer", 0.95);
77//! model.add_drug_target_interaction("aspirin", "COX1", 0.92);
78//!
79//! // Train and predict
80//! model.train(Some(100)).await?;
81//! let predictions = model.predict_gene_disease_associations("BRCA1", 5)?;
82//! # Ok(())
83//! # }
84//! ```
85//!
86//! ## GPU Acceleration Example
87//!
88//! ```rust,ignore
89//! use oxirs_embed::{GpuAccelerationConfig, GpuAccelerationManager};
90//!
91//! # async fn example() -> anyhow::Result<()> {
92//! // Configure GPU acceleration
93//! let config = GpuAccelerationConfig {
94//!     enabled: true,
95//!     mixed_precision: true,
96//!     tensor_caching: true,
97//!     multi_stream: true,
98//!     num_streams: 4,
99//!     ..Default::default()
100//! };
101//!
102//! let mut gpu_manager = GpuAccelerationManager::new(config);
103//!
104//! // Use accelerated embedding generation
105//! let entities = vec!["entity1".to_string(), "entity2".to_string()];
106//! let embeddings = gpu_manager.accelerated_embedding_generation(
107//!     entities,
108//!     |entity| { /* compute embedding */ vec![0.0; 128].into() }
109//! ).await?;
110//! # Ok(())
111//! # }
112//! ```
113//!
114//! ## Examples
115//!
116//! See the `examples/` directory for comprehensive demonstrations:
117//! - `biomedical_embedding_demo.rs` - Biomedical AI capabilities
118//! - `gpu_acceleration_demo.rs` - GPU acceleration features  
119//! - `integrated_ai_platform_demo.rs` - Complete AI platform showcase
120
121#![allow(dead_code)]
122
123pub mod ab_testing;
124pub mod acceleration;
125pub mod adaptive_learning;
126pub mod advanced_profiler;
127pub mod alignment;
128#[cfg(feature = "api-server")]
129pub mod api;
130pub mod application_tasks;
131pub mod batch_processing;
132pub mod biomedical_embeddings;
133pub mod caching;
134pub mod causal_representation_learning;
135pub mod causal_representation_learning_eval;
136pub mod causal_representation_learning_model;
137mod causal_representation_learning_tests;
138pub mod causal_representation_learning_types;
139pub mod cloud_integration;
140pub mod clustering;
141pub mod community_detection;
142pub mod compression;
143pub mod contextual;
144pub mod continual_learning;
145pub(crate) mod continual_learning_strategies;
146#[cfg(test)]
147mod continual_learning_tests;
148pub(crate) mod continual_learning_trainer;
149pub mod continual_learning_types;
150pub mod cross_domain_transfer;
151pub mod cross_module_performance;
152pub mod cross_module_performance_profiler;
153pub mod cross_module_performance_reporter;
154mod cross_module_performance_tests;
155pub mod cross_module_performance_types;
156pub mod delta;
157pub mod diffusion_embeddings;
158pub mod distributed_training;
159pub mod embed_compression;
160pub mod enterprise_knowledge;
161pub mod enterprise_knowledge_analyzer;
162pub mod enterprise_knowledge_analyzer_helpers;
163pub mod enterprise_knowledge_config;
164pub mod enterprise_knowledge_customer;
165pub mod enterprise_knowledge_employee;
166pub mod enterprise_knowledge_engine;
167pub mod enterprise_knowledge_product;
168#[cfg(test)]
169mod enterprise_knowledge_tests;
170pub mod entity_linking;
171pub mod evaluation;
172pub mod evolutionary_nas;
173pub mod evolutionary_nas_eval;
174pub mod evolutionary_nas_evolution;
175mod evolutionary_nas_tests;
176pub mod evolutionary_nas_types;
177pub mod federated_learning;
178pub mod fine_tuning;
179#[cfg(feature = "gpu")]
180pub mod gpu_acceleration;
181pub mod graph_models;
182pub mod graphql_api;
183pub mod inference;
184pub mod integration;
185pub mod interpretability;
186pub mod kg_completion;
187pub mod link_prediction;
188pub mod mamba_attention;
189pub mod memory_augmented_networks;
190pub mod memory_nets_controller;
191pub mod memory_nets_ops;
192pub mod memory_nets_tests;
193pub mod mixed_precision;
194pub mod model_registry;
195pub mod model_selection;
196pub mod models;
197pub mod monitoring;
198pub mod monitoring_health;
199pub mod monitoring_metrics;
200pub mod monitoring_tests;
201pub mod multimodal;
202pub mod neural_symbolic_integration;
203pub mod neural_symbolic_integration_engine;
204pub mod neural_symbolic_integration_loss;
205mod neural_symbolic_integration_tests;
206pub mod neural_symbolic_integration_types;
207pub mod neuro_evolution;
208pub mod novel_arch_impl;
209#[cfg(test)]
210mod novel_arch_tests;
211pub mod novel_arch_types;
212pub mod novel_architectures;
213pub mod performance_profiler;
214pub mod persistence;
215pub mod quantization;
216pub mod real_time_fine_tuning;
217pub mod real_time_optimization;
218pub mod research_networks;
219// pub mod revolutionary_optimization; // Disabled - awaiting scirs2-core API stabilization
220pub mod sparql_extension;
221pub mod storage_backend;
222pub mod temporal_embeddings;
223pub mod training;
224pub mod training_online;
225pub mod utils;
226pub mod utils_io;
227pub mod utils_math;
228mod utils_tests;
229pub mod utils_types;
230pub mod validation;
231pub mod vector_search;
232pub mod vision_language_graph;
233pub mod visualization;
234// v1.1.0: Contrastive learning loss functions
235pub mod contrastive_learning;
236
237// v1.1.0: Procrustes alignment for embedding space alignment across models/languages
238pub mod procrustes_alignment;
239
240// v1.1.0: LRU embedding cache with memory-bounded eviction and per-model invalidation
241pub mod embedding_cache;
242
243// v1.1.0 round 5: PCA-based dimensionality reduction for embedding vectors
244pub mod dimensionality_reducer;
245
246// v1.1.0 round 6: Full PCA reducer with fit/transform/inverse_transform and power-iteration eigenvectors
247pub mod pca_reducer;
248
249// v1.1.0 round 7: Fine-tuner with triplet/contrastive/cosine loss
250pub mod fine_tuner;
251
252// v1.1.0 round 10: In-memory vector store with namespace support
253pub mod vector_store;
254
255// v1.1.0 round 11: Cross-encoder re-ranker for embedding search
256pub mod cross_encoder;
257
258// v1.1.0 round 12: Linear embedding projection layer (dimensionality reduction/expansion)
259pub mod projection_layer;
260pub use projection_layer::{ActivationFn, InitMethod, ProjectionLayer, ProjectionMatrix};
261
262// v1.1.0 round 13: In-memory embedding store with label-based lookup
263pub mod embedding_store;
264
265// v1.1.0 round 12: BPE / WordPiece tokenizer with special tokens and batch encoding
266pub mod tokenizer;
267
268// v1.1.0 round 11: Embedding aggregation strategies (mean/max/CLS/attention pooling)
269pub mod embedding_aggregator;
270
271// v1.1.0 round 13: Result reranking (cross-encoder, BM25, reciprocal rank fusion)
272pub mod reranker;
273
274// v1.1.0 round 14: ANN index hyperparameter search (HNSW/IVF grid expansion + Pareto front)
275pub mod index_optimizer;
276
277// v1.1.0 round 15: Batch text encoding pipeline with chunking and pooling
278pub mod batch_encoder;
279
280// v0.3.0: Ensemble embedding aggregation (Voting, WeightedAverage, Stacking meta-learner)
281pub mod ensemble;
282
283// v1.1.0 round 16: Random projection for embedding dimensionality reduction
284pub mod embedding_compressor;
285
286// v0.3.0 / v1.0.0: Model zoo with pretrained (and synthetic-seed) embedding models
287pub mod model_zoo;
288pub use model_zoo::{sha256_hex, ModelManifest, ModelZoo, ModelZooError, ModelZooLoader};
289
290// Import Vector from oxirs-vec for type compatibility across the ecosystem
291pub use oxirs_vec::Vector as VecVector;
292
293// Adaptive Learning System exports
294pub use adaptive_learning::{
295    AdaptationMetrics, AdaptationStrategy, AdaptiveLearningConfig, AdaptiveLearningSystem,
296    QualityFeedback,
297};
298
299use anyhow::Result;
300use chrono::{DateTime, Utc};
301use serde::{Deserialize, Serialize};
302use std::collections::HashMap;
303use std::ops::{Add, Sub};
304use uuid::Uuid;
305
306/// Compatibility wrapper for Vector that provides the old interface
307/// while using the sophisticated oxirs-vec Vector internally
308#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
309pub struct Vector {
310    pub values: Vec<f32>,
311    pub dimensions: usize,
312    #[serde(skip)]
313    inner: Option<VecVector>,
314}
315
316impl Vector {
317    pub fn new(values: Vec<f32>) -> Self {
318        let dimensions = values.len();
319        Self {
320            values,
321            dimensions,
322            inner: None,
323        }
324    }
325
326    /// Get or create the inner VecVector
327    fn get_inner(&self) -> VecVector {
328        // Create a new VecVector from values if needed
329        if let Some(ref inner) = self.inner {
330            inner.clone()
331        } else {
332            VecVector::new(self.values.clone())
333        }
334    }
335
336    /// Update internal state when values change
337    fn sync_internal(&mut self) {
338        self.dimensions = self.values.len();
339        self.inner = None; // Will be recreated on next access
340    }
341
342    /// Create from ndarray Array1
343    pub fn from_array1(array: &scirs2_core::ndarray_ext::Array1<f32>) -> Self {
344        Self::new(array.to_vec())
345    }
346
347    /// Convert to ndarray Array1
348    pub fn to_array1(&self) -> scirs2_core::ndarray_ext::Array1<f32> {
349        scirs2_core::ndarray_ext::Array1::from_vec(self.values.clone())
350    }
351
352    /// Element-wise mapping
353    pub fn mapv<F>(&self, f: F) -> Self
354    where
355        F: Fn(f32) -> f32,
356    {
357        Self::new(self.values.iter().copied().map(f).collect())
358    }
359
360    /// Sum of all elements
361    pub fn sum(&self) -> f32 {
362        self.values.iter().sum()
363    }
364
365    /// Square root of the sum
366    pub fn sqrt(&self) -> f32 {
367        self.sum().sqrt()
368    }
369
370    /// Get the inner VecVector for advanced operations
371    pub fn inner(&self) -> VecVector {
372        self.get_inner()
373    }
374
375    /// Convert into the inner VecVector
376    pub fn into_inner(self) -> VecVector {
377        self.inner.unwrap_or_else(|| VecVector::new(self.values))
378    }
379
380    /// Create from VecVector with optimized memory allocation
381    pub fn from_vec_vector(vec_vector: VecVector) -> Self {
382        let values = vec_vector.as_f32().to_vec();
383        let dimensions = values.len();
384        Self {
385            values,
386            dimensions,
387            inner: Some(vec_vector),
388        }
389    }
390
391    /// Create vector with pre-allocated capacity for performance
392    pub fn with_capacity(capacity: usize) -> Self {
393        Self {
394            values: Vec::with_capacity(capacity),
395            dimensions: 0,
396            inner: None,
397        }
398    }
399
400    /// Extend vector with optimized memory reallocation
401    pub fn extend_optimized(&mut self, other_values: &[f32]) {
402        // Reserve capacity to avoid multiple reallocations
403        self.values.reserve(other_values.len());
404        self.values.extend_from_slice(other_values);
405        self.sync_internal();
406    }
407
408    /// Shrink vector memory to fit actual size
409    pub fn shrink_to_fit(&mut self) {
410        self.values.shrink_to_fit();
411        self.sync_internal();
412    }
413
414    /// Get memory usage in bytes
415    pub fn memory_usage(&self) -> usize {
416        self.values.capacity() * std::mem::size_of::<f32>() + std::mem::size_of::<Self>()
417    }
418}
419
420// Arithmetic operations for Vector (compatibility with old interface)
421impl Add for &Vector {
422    type Output = Vector;
423
424    fn add(self, other: &Vector) -> Vector {
425        // Use the sophisticated vector addition from oxirs-vec
426        if let (Some(self_inner), Some(other_inner)) = (&self.inner, &other.inner) {
427            if let Ok(result) = self_inner.add(other_inner) {
428                return Vector::from_vec_vector(result);
429            }
430        }
431        // Fallback to element-wise addition for compatibility
432        assert_eq!(
433            self.values.len(),
434            other.values.len(),
435            "Vector dimensions must match"
436        );
437        let result_values: Vec<f32> = self
438            .values
439            .iter()
440            .zip(other.values.iter())
441            .map(|(a, b)| a + b)
442            .collect();
443        Vector::new(result_values)
444    }
445}
446
447impl Sub for &Vector {
448    type Output = Vector;
449
450    fn sub(self, other: &Vector) -> Vector {
451        // Use the sophisticated vector subtraction from oxirs-vec
452        if let (Some(self_inner), Some(other_inner)) = (&self.inner, &other.inner) {
453            if let Ok(result) = self_inner.subtract(other_inner) {
454                return Vector::from_vec_vector(result);
455            }
456        }
457        // Fallback to element-wise subtraction for compatibility
458        assert_eq!(
459            self.values.len(),
460            other.values.len(),
461            "Vector dimensions must match"
462        );
463        let result_values: Vec<f32> = self
464            .values
465            .iter()
466            .zip(other.values.iter())
467            .map(|(a, b)| a - b)
468            .collect();
469        Vector::new(result_values)
470    }
471}
472
473/// Triple structure for RDF triples
474#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
475pub struct Triple {
476    pub subject: NamedNode,
477    pub predicate: NamedNode,
478    pub object: NamedNode,
479}
480
481impl Triple {
482    pub fn new(subject: NamedNode, predicate: NamedNode, object: NamedNode) -> Self {
483        Self {
484            subject,
485            predicate,
486            object,
487        }
488    }
489}
490
491/// Named node for RDF resources
492#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
493pub struct NamedNode {
494    pub iri: String,
495}
496
497impl NamedNode {
498    pub fn new(iri: &str) -> Result<Self> {
499        Ok(Self {
500            iri: iri.to_string(),
501        })
502    }
503}
504
505impl std::fmt::Display for NamedNode {
506    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
507        write!(f, "{}", self.iri)
508    }
509}
510
511/// Configuration for embedding models
512#[derive(Debug, Clone, Serialize, Deserialize)]
513pub struct ModelConfig {
514    pub dimensions: usize,
515    pub learning_rate: f64,
516    pub l2_reg: f64,
517    pub max_epochs: usize,
518    pub batch_size: usize,
519    pub negative_samples: usize,
520    pub seed: Option<u64>,
521    pub use_gpu: bool,
522    pub model_params: HashMap<String, f64>,
523}
524
525impl Default for ModelConfig {
526    fn default() -> Self {
527        Self {
528            dimensions: 100,
529            learning_rate: 0.01,
530            l2_reg: 0.0001,
531            max_epochs: 1000,
532            batch_size: 1000,
533            negative_samples: 10,
534            seed: None,
535            use_gpu: false,
536            model_params: HashMap::new(),
537        }
538    }
539}
540
541impl ModelConfig {
542    pub fn with_dimensions(mut self, dimensions: usize) -> Self {
543        self.dimensions = dimensions;
544        self
545    }
546
547    pub fn with_learning_rate(mut self, learning_rate: f64) -> Self {
548        self.learning_rate = learning_rate;
549        self
550    }
551
552    pub fn with_max_epochs(mut self, max_epochs: usize) -> Self {
553        self.max_epochs = max_epochs;
554        self
555    }
556
557    pub fn with_seed(mut self, seed: u64) -> Self {
558        self.seed = Some(seed);
559        self
560    }
561
562    pub fn with_batch_size(mut self, batch_size: usize) -> Self {
563        self.batch_size = batch_size;
564        self
565    }
566}
567
568/// Training statistics
569#[derive(Debug, Clone, Serialize, Deserialize)]
570pub struct TrainingStats {
571    pub epochs_completed: usize,
572    pub final_loss: f64,
573    pub training_time_seconds: f64,
574    pub convergence_achieved: bool,
575    pub loss_history: Vec<f64>,
576}
577
578/// Model statistics
579#[derive(Debug, Clone, Serialize, Deserialize)]
580pub struct ModelStats {
581    pub num_entities: usize,
582    pub num_relations: usize,
583    pub num_triples: usize,
584    pub dimensions: usize,
585    pub is_trained: bool,
586    pub model_type: String,
587    pub creation_time: DateTime<Utc>,
588    pub last_training_time: Option<DateTime<Utc>>,
589}
590
591impl Default for ModelStats {
592    fn default() -> Self {
593        Self {
594            num_entities: 0,
595            num_relations: 0,
596            num_triples: 0,
597            dimensions: 0,
598            is_trained: false,
599            model_type: "unknown".to_string(),
600            creation_time: Utc::now(),
601            last_training_time: None,
602        }
603    }
604}
605
606/// Embedding errors
607#[derive(Debug, thiserror::Error)]
608pub enum EmbeddingError {
609    #[error("Model not trained")]
610    ModelNotTrained,
611    #[error("Entity not found: {entity}")]
612    EntityNotFound { entity: String },
613    #[error("Relation not found: {relation}")]
614    RelationNotFound { relation: String },
615    #[error("Other error: {0}")]
616    Other(#[from] anyhow::Error),
617}
618
619/// Basic embedding model trait
620#[async_trait::async_trait]
621pub trait EmbeddingModel: Send + Sync {
622    fn config(&self) -> &ModelConfig;
623    fn model_id(&self) -> &Uuid;
624    fn model_type(&self) -> &'static str;
625    fn add_triple(&mut self, triple: Triple) -> Result<()>;
626    async fn train(&mut self, epochs: Option<usize>) -> Result<TrainingStats>;
627    fn get_entity_embedding(&self, entity: &str) -> Result<Vector>;
628    fn get_relation_embedding(&self, relation: &str) -> Result<Vector>;
629    fn score_triple(&self, subject: &str, predicate: &str, object: &str) -> Result<f64>;
630    fn predict_objects(
631        &self,
632        subject: &str,
633        predicate: &str,
634        k: usize,
635    ) -> Result<Vec<(String, f64)>>;
636    fn predict_subjects(
637        &self,
638        predicate: &str,
639        object: &str,
640        k: usize,
641    ) -> Result<Vec<(String, f64)>>;
642    fn predict_relations(
643        &self,
644        subject: &str,
645        object: &str,
646        k: usize,
647    ) -> Result<Vec<(String, f64)>>;
648    fn get_entities(&self) -> Vec<String>;
649    fn get_relations(&self) -> Vec<String>;
650    fn get_stats(&self) -> ModelStats;
651    fn save(&self, path: &str) -> Result<()>;
652    fn load(&mut self, path: &str) -> Result<()>;
653    fn clear(&mut self);
654    fn is_trained(&self) -> bool;
655
656    /// Encode text strings into embeddings
657    async fn encode(&self, texts: &[String]) -> Result<Vec<Vec<f32>>>;
658}
659
660// Re-export main types
661pub use acceleration::{AdaptiveEmbeddingAccelerator, GpuEmbeddingAccelerator};
662#[cfg(feature = "api-server")]
663pub use api::{start_server, ApiConfig, ApiState};
664pub use batch_processing::{
665    BatchJob, BatchProcessingConfig, BatchProcessingManager, BatchProcessingResult,
666    BatchProcessingStats, IncrementalConfig, JobProgress, JobStatus, OutputFormat,
667    PartitioningStrategy, RetryConfig,
668};
669pub use biomedical_embeddings::{
670    BiomedicalEmbedding, BiomedicalEmbeddingConfig, BiomedicalEntityType, BiomedicalRelationType,
671    FineTuningConfig, PreprocessingRule, SpecializedTextConfig, SpecializedTextEmbedding,
672    SpecializedTextModel,
673};
674pub use caching::{CacheConfig, CacheManager, CachedEmbeddingModel};
675pub use causal_representation_learning::{
676    CausalDiscoveryAlgorithm, CausalDiscoveryConfig, CausalGraph, CausalRepresentationConfig,
677    CausalRepresentationModel, ConstraintSettings, CounterfactualConfig, CounterfactualQuery,
678    DisentanglementConfig, DisentanglementMethod, ExplanationType, IndependenceTest,
679    InterventionConfig, ScoreSettings, StructuralCausalModelConfig,
680};
681pub use cloud_integration::{
682    AWSSageMakerService, AutoScalingConfig, AzureMLService, BackupConfig, CloudIntegrationConfig,
683    CloudIntegrationManager, CloudProvider, CloudService, ClusterStatus, CostEstimate,
684    CostOptimizationResult, CostOptimizationStrategy, DeploymentConfig, DeploymentResult,
685    DeploymentStatus, EndpointInfo, FunctionInvocationResult, GPUClusterConfig, GPUClusterResult,
686    LifecyclePolicy, OptimizationAction, PerformanceTier, ReplicationType,
687    ServerlessDeploymentResult, ServerlessFunctionConfig, ServerlessStatus, StorageConfig,
688    StorageResult, StorageStatus, StorageType,
689};
690pub use compression::{
691    CompressedModel, CompressionStats, CompressionTarget, DistillationConfig,
692    ModelCompressionManager, NASConfig, OptimizationTarget, PruningConfig, PruningMethod,
693    QuantizationConfig, QuantizationMethod,
694};
695// pub use contextual::{
696//     ContextualConfig, ContextualEmbeddingModel, EmbeddingContext,
697// };
698pub use continual_learning::{
699    ArchitectureConfig, BoundaryDetection, ConsolidationConfig, ContinualLearningConfig,
700    ContinualLearningModel, MemoryConfig, MemoryType, MemoryUpdateStrategy, RegularizationConfig,
701    ReplayConfig, ReplayMethod, TaskConfig, TaskDetection, TaskSwitching,
702};
703pub use cross_module_performance::{
704    CoordinatorConfig, CrossModulePerformanceCoordinator, GlobalPerformanceMetrics, ModuleMetrics,
705    ModulePerformanceMonitor, OptimizationCache, PerformanceSnapshot, PredictivePerformanceEngine,
706    ResourceAllocator, ResourceTracker,
707};
708pub use delta::{
709    ChangeRecord, ChangeStatistics, ChangeType, DeltaConfig, DeltaManager, DeltaResult, DeltaStats,
710    IncrementalStrategy,
711};
712pub use enterprise_knowledge::{
713    BehaviorMetrics, CareerPredictions, Category, CategoryHierarchy, CategoryPerformance,
714    ColdStartStrategy, CommunicationFrequency, CommunicationPreferences, CustomerEmbedding,
715    CustomerPreferences, CustomerRatings, CustomerSegment, Department, DepartmentPerformance,
716    EmployeeEmbedding, EnterpriseConfig, EnterpriseKnowledgeAnalyzer, EnterpriseMetrics,
717    ExperienceLevel, FeatureType, MarketAnalysis, OrganizationalStructure,
718    PerformanceMetrics as EnterprisePerformanceMetrics, ProductAvailability, ProductEmbedding,
719    ProductFeature, ProductRecommendation, Project, ProjectOutcome, ProjectParticipation,
720    ProjectPerformance, ProjectStatus, Purchase, PurchaseChannel, RecommendationConfig,
721    RecommendationEngine, RecommendationEngineType, RecommendationPerformance,
722    RecommendationReason, SalesMetrics, Skill, SkillCategory, Team, TeamPerformance,
723};
724pub use evaluation::{
725    compute_filtered_rank,
726    hits_at_k,
727    mean_rank,
728    mean_reciprocal_rank,
729    AnalogicalReasoningBenchmark,
730    AnalogyQuad,
731    EmbeddingClusteringMetrics,
732    EmbeddingEvaluator,
733    EvalSplit,
734    EvaluationMetrics,
735    // KGC evaluation framework
736    EvaluationTriple,
737    KgcDataset,
738    KgcEvaluationSuite,
739    KgcEvaluator,
740    KgcEvaluatorConfig,
741    QueryAnsweringEvaluator,
742    QueryEvaluationConfig,
743    QueryEvaluationResults,
744    QueryMetric,
745    QueryResult,
746    QueryTemplate,
747    QueryType,
748    ReasoningChain,
749    ReasoningEvaluationConfig,
750    ReasoningEvaluationResults,
751    ReasoningRule,
752    ReasoningStep,
753    ReasoningTaskEvaluator,
754    ReasoningType,
755    TypeSpecificResults,
756};
757pub use federated_learning::{
758    AggregationEngine, AggregationStrategy, AuthenticationConfig, AuthenticationMethod,
759    CertificateConfig, ClippingMechanisms, ClippingMethod, CommunicationConfig,
760    CommunicationManager, CommunicationProtocol, CompressionAlgorithm, CompressionConfig,
761    CompressionEngine, ConvergenceMetrics, ConvergenceStatus, DataSelectionStrategy,
762    DataStatistics, EncryptionScheme, FederatedConfig, FederatedCoordinator,
763    FederatedEmbeddingModel, FederatedMessage, FederatedRound, FederationStats, GlobalModelState,
764    HardwareAccelerator, KeyManager, LocalModelState, LocalTrainingStats, LocalUpdate,
765    MetaLearningConfig, NoiseGenerator, NoiseMechanism, OutlierAction, OutlierDetection,
766    OutlierDetectionMethod, Participant, ParticipantCapabilities, ParticipantStatus,
767    PersonalizationConfig, PersonalizationStrategy, PrivacyAccountant, PrivacyConfig,
768    PrivacyEngine, PrivacyMetrics, PrivacyParams, RoundMetrics, RoundStatus, SecurityConfig,
769    SecurityFeature, SecurityManager, TrainingConfig, VerificationEngine, VerificationMechanism,
770    VerificationResult, WeightingScheme,
771};
772#[cfg(feature = "gpu")]
773pub use gpu_acceleration::{
774    GpuAccelerationConfig, GpuAccelerationManager, GpuMemoryPool, GpuPerformanceStats,
775    MixedPrecisionProcessor, MultiStreamProcessor, TensorCache,
776};
777pub use graphql_api::{
778    create_schema, BatchEmbeddingInput, BatchEmbeddingResult, BatchStatus, DistanceMetric,
779    EmbeddingFormat, EmbeddingQueryInput, EmbeddingResult, EmbeddingSchema, GraphQLContext,
780    ModelInfo, ModelType, SimilarityResult, SimilaritySearchInput,
781};
782pub use kg_completion::{BatchedTrainingLoop, KgCompletionTask, NegativeSampler, TrainingBatch};
783pub use models::{
784    AggregationType, ComplEx, DistMult, GNNConfig, GNNEmbedding, GNNType, HoLE, HoLEConfig,
785    PoolingStrategy, RotatE, TransE, TransformerConfig, TransformerEmbedding, TransformerType,
786};
787
788// v0.3.1: Triple-based inductive GraphSAGE embedder (Hamilton et al. 2017)
789pub use models::{GraphSageEmbedder, GraphSageEmbedderConfig};
790
791// v0.3.1: Multi-head GAT embedder (Veličković et al. 2018)
792pub use models::{GatEmbedder, GatEmbedderConfig};
793
794pub use contextual::{
795    AccessibilityPreferences, ComplexityLevel, ContextualConfig, ContextualEmbeddingModel,
796    DomainContext, EmbeddingContext, PerformanceRequirements, PriorityLevel, PrivacySettings,
797    QueryContext, QueryType as ContextualQueryType, ResponseFormat, TaskConstraints, TaskContext,
798    TaskType, UserContext, UserHistory, UserPreferences,
799};
800pub use distributed_training::{
801    AggregationMethod, AllReduceStrategy, CommunicationBackend, DataParallelTrainer,
802    DistributedEmbeddingTrainer, DistributedStrategy, DistributedTrainingConfig,
803    DistributedTrainingCoordinator, DistributedTrainingSample, DistributedTrainingStats,
804    FaultToleranceConfig, GradientAggregator, GradientCompressor, ModelShardManager, ModelUpdate,
805    ParameterServer, ParameterServerConfig, ParameterServerStats, ShardAssignment, ShardSnapshot,
806    ShardingStrategy, SparseGradient, TripleSample, UpdateMode, Worker, WorkerConfig, WorkerInfo,
807    WorkerLoss, WorkerStatus, WorkerUpdate,
808};
809#[cfg(feature = "conve")]
810pub use models::{ConvE, ConvEConfig};
811pub use monitoring::{
812    Alert, AlertSeverity, AlertThresholds, AlertType, CacheMetrics, ConsoleAlertHandler,
813    DriftMetrics, ErrorEvent, ErrorMetrics, ErrorSeverity, LatencyMetrics, MonitoringConfig,
814    PerformanceMetrics as MonitoringPerformanceMetrics, PerformanceMonitor, QualityAssessment,
815    QualityMetrics, ResourceMetrics, SlackAlertHandler, ThroughputMetrics,
816};
817pub use multimodal::{
818    AlignmentNetwork, AlignmentObjective, ContrastiveConfig, CrossDomainConfig, CrossModalConfig,
819    KGEncoder, MultiModalEmbedding, MultiModalStats, TextEncoder,
820};
821pub use neural_symbolic_integration::{
822    ConstraintSatisfactionConfig, ConstraintType, KnowledgeIntegrationConfig, KnowledgeRule,
823    LogicIntegrationConfig, LogicProgrammingConfig, LogicalFormula, NeuralSymbolicConfig,
824    NeuralSymbolicModel, NeuroSymbolicArchitectureConfig, OntologicalConfig, ReasoningEngine,
825    RuleBasedConfig, SymbolicReasoningConfig,
826};
827pub use novel_architectures::{
828    ActivationType, ArchitectureParams, ArchitectureState, ArchitectureType, CurvatureComputation,
829    CurvatureMethod, CurvatureType, DynamicsConfig, EntanglementStructure, EquivarianceGroup,
830    FlowType, GeometricConfig, GeometricParams, GeometricSpace, GeometricState,
831    GraphTransformerParams, GraphTransformerState, HyperbolicDistance, HyperbolicInit,
832    HyperbolicManifold, HyperbolicParams, HyperbolicState, IntegrationScheme, IntegrationStats,
833    ManifoldLearning, ManifoldMethod, ManifoldOptimizer, NeuralODEParams, NeuralODEState,
834    NovelArchitectureConfig, NovelArchitectureModel, ODERegularization, ODESolverType,
835    ParallelTransport, QuantumGateSet, QuantumMeasurement, QuantumNoise, QuantumParams,
836    QuantumState, StabilityConstraints, StructuralBias, TimeEvolution, TransportMethod,
837};
838pub use research_networks::{
839    AuthorEmbedding, Citation, CitationNetwork, CitationType, Collaboration, CollaborationNetwork,
840    NetworkMetrics, PaperSection, PublicationEmbedding, PublicationType, ResearchCommunity,
841    ResearchNetworkAnalyzer, ResearchNetworkConfig, TopicModel, TopicModelingConfig,
842};
843pub use sparql_extension::{
844    ExpandedQuery, Expansion, ExpansionType, QueryStatistics as SparqlQueryStatistics,
845    SparqlExtension, SparqlExtensionConfig,
846};
847pub use storage_backend::{
848    DiskBackend, EmbeddingMetadata, EmbeddingVersion, MemoryBackend, StorageBackend,
849    StorageBackendConfig, StorageBackendManager, StorageBackendType, StorageStats,
850};
851pub use temporal_embeddings::{
852    TemporalEmbeddingConfig, TemporalEmbeddingModel, TemporalEvent, TemporalForecast,
853    TemporalGranularity, TemporalScope, TemporalStats, TemporalTriple,
854};
855pub use vision_language_graph::{
856    AggregationFunction, CNNConfig, CrossAttentionConfig, DomainAdaptationConfig,
857    DomainAdaptationMethod, EpisodeConfig, FewShotConfig, FewShotMethod, FusionStrategy,
858    GraphArchitecture, GraphEncoder, GraphEncoderConfig, JointTrainingConfig, LanguageArchitecture,
859    LanguageEncoder, LanguageEncoderConfig, LanguageTransformerConfig, MetaLearner,
860    ModalityEncoding, MultiModalTransformer, MultiModalTransformerConfig, NormalizationType,
861    PoolingType, PositionEncodingType, ReadoutFunction, TaskCategory, TaskSpecificParams,
862    TrainingObjective, TransferLearningConfig, TransferStrategy, ViTConfig, VisionArchitecture,
863    VisionEncoder, VisionEncoderConfig, VisionLanguageGraphConfig, VisionLanguageGraphModel,
864    VisionLanguageGraphStats, ZeroShotConfig, ZeroShotMethod,
865};
866
867#[cfg(feature = "tucker")]
868pub use models::TuckER;
869
870#[cfg(feature = "quatd")]
871pub use models::QuatD;
872
873// Re-export model registry types
874pub use crate::model_registry::{
875    ModelRegistry, ModelVersion, ResourceAllocation as ModelResourceAllocation,
876};
877
878// Re-export model selection types
879pub use crate::model_selection::{
880    DatasetCharacteristics, MemoryRequirement, ModelComparison, ModelComparisonEntry,
881    ModelRecommendation, ModelSelector, ModelType as SelectionModelType, TrainingTime, UseCaseType,
882};
883
884// Re-export performance profiler types
885pub use crate::performance_profiler::{
886    OperationStats, OperationTimer, OperationType, PerformanceProfiler, PerformanceReport,
887};
888
889// Re-export revolutionary optimization types
890// Temporarily disabled - awaiting scirs2-core v0.2.0 API stabilization
891/*
892pub use revolutionary_optimization::{
893    AdvancedMemoryConfig, EmbeddingOptimizationResult, OptimizationPriority, OptimizationStatistics,
894    OptimizationStrategy, PerformanceTargets, QuantumOptimizationStrategy,
895    RevolutionaryEmbeddingOptimizer, RevolutionaryEmbeddingOptimizerFactory,
896    RevolutionaryOptimizationConfig, SimilarityComputationMethod, SimilarityOptimizationResult,
897    StreamingOptimizationConfig,
898};
899*/
900
901/// Convenience functions for quick setup and common operations
902pub mod quick_start {
903    use super::*;
904    use crate::models::TransE;
905
906    /// Create a TransE model with sensible defaults for experimentation
907    pub fn create_simple_transe_model() -> TransE {
908        let config = ModelConfig::default()
909            .with_dimensions(128)
910            .with_learning_rate(0.01)
911            .with_max_epochs(100);
912        TransE::new(config)
913    }
914
915    /// Create a biomedical embedding model for life sciences applications
916    pub fn create_biomedical_model() -> BiomedicalEmbedding {
917        let config = BiomedicalEmbeddingConfig::default();
918        BiomedicalEmbedding::new(config)
919    }
920
921    /// Parse a triple from simple string format "subject predicate object"
922    pub fn parse_triple_from_string(triple_str: &str) -> Result<Triple> {
923        let parts: Vec<&str> = triple_str.split_whitespace().collect();
924        if parts.len() != 3 {
925            return Err(anyhow::anyhow!(
926                "Triple must have exactly 3 parts separated by spaces"
927            ));
928        }
929
930        // Helper function to convert short names to full URIs
931        let expand_uri = |s: &str| -> String {
932            if s.starts_with("http://") || s.starts_with("https://") {
933                s.to_string()
934            } else {
935                format!("http://example.org/{s}")
936            }
937        };
938
939        Ok(Triple::new(
940            NamedNode::new(&expand_uri(parts[0]))?,
941            NamedNode::new(&expand_uri(parts[1]))?,
942            NamedNode::new(&expand_uri(parts[2]))?,
943        ))
944    }
945
946    /// Helper to add multiple triples from string format
947    pub fn add_triples_from_strings<T: EmbeddingModel>(
948        model: &mut T,
949        triple_strings: &[&str],
950    ) -> Result<usize> {
951        let mut count = 0;
952        for triple_str in triple_strings {
953            let triple = parse_triple_from_string(triple_str)?;
954            model.add_triple(triple)?;
955            count += 1;
956        }
957        Ok(count)
958    }
959
960    /// Quick function to compute cosine similarity between two embedding vectors
961    pub fn cosine_similarity(a: &[f64], b: &[f64]) -> Result<f64> {
962        if a.len() != b.len() {
963            return Err(anyhow::anyhow!(
964                "Vector dimensions don't match: {} vs {}",
965                a.len(),
966                b.len()
967            ));
968        }
969
970        let dot_product: f64 = a.iter().zip(b.iter()).map(|(x, y)| x * y).sum();
971        let norm_a: f64 = a.iter().map(|x| x * x).sum::<f64>().sqrt();
972        let norm_b: f64 = b.iter().map(|x| x * x).sum::<f64>().sqrt();
973
974        if norm_a == 0.0 || norm_b == 0.0 {
975            return Ok(0.0);
976        }
977
978        Ok(dot_product / (norm_a * norm_b))
979    }
980
981    /// Generate sample knowledge graph data for testing and prototyping
982    pub fn generate_sample_kg_data(
983        num_entities: usize,
984        num_relations: usize,
985    ) -> Vec<(String, String, String)> {
986        #[allow(unused_imports)]
987        use scirs2_core::random::{Random, RngExt};
988
989        let mut random = Random::default();
990        let mut triples = Vec::new();
991
992        let entities: Vec<String> = (0..num_entities)
993            .map(|i| format!("http://example.org/entity_{i}"))
994            .collect();
995
996        let relations: Vec<String> = (0..num_relations)
997            .map(|i| format!("http://example.org/relation_{i}"))
998            .collect();
999
1000        // Generate random triples (avoid self-loops)
1001        for _ in 0..(num_entities * 2) {
1002            let subject_idx = random.random_range(0..entities.len());
1003            let relation_idx = random.random_range(0..relations.len());
1004            let object_idx = random.random_range(0..entities.len());
1005
1006            let subject = entities[subject_idx].clone();
1007            let relation = relations[relation_idx].clone();
1008            let object = entities[object_idx].clone();
1009
1010            if subject != object {
1011                triples.push((subject, relation, object));
1012            }
1013        }
1014
1015        triples
1016    }
1017
1018    /// Quick performance measurement utility
1019    pub fn quick_performance_test<F>(
1020        name: &str,
1021        iterations: usize,
1022        operation: F,
1023    ) -> std::time::Duration
1024    where
1025        F: Fn(),
1026    {
1027        let start = std::time::Instant::now();
1028        for _ in 0..iterations {
1029            operation();
1030        }
1031        let duration = start.elapsed();
1032
1033        println!(
1034            "Performance test '{name}': {iterations} iterations in {duration:?} ({:.2} ops/sec)",
1035            iterations as f64 / duration.as_secs_f64()
1036        );
1037
1038        duration
1039    }
1040
1041    // Revolutionary optimizer functions temporarily disabled - awaiting scirs2-core v0.2.0 API stabilization
1042    /*
1043    /// Create a revolutionary embedding optimizer with quantum focus
1044    pub async fn create_quantum_optimizer() -> anyhow::Result<RevolutionaryEmbeddingOptimizer> {
1045        RevolutionaryEmbeddingOptimizerFactory::create_quantum_focused()
1046            .await
1047            .map_err(|e| anyhow::anyhow!("Failed to create quantum optimizer: {}", e))
1048    }
1049
1050    /// Create a revolutionary embedding optimizer with streaming focus
1051    pub async fn create_streaming_optimizer() -> anyhow::Result<RevolutionaryEmbeddingOptimizer> {
1052        RevolutionaryEmbeddingOptimizerFactory::create_streaming_focused()
1053            .await
1054            .map_err(|e| anyhow::anyhow!("Failed to create streaming optimizer: {}", e))
1055    }
1056
1057    /// Create a revolutionary embedding optimizer with GPU focus
1058    pub async fn create_gpu_optimizer() -> anyhow::Result<RevolutionaryEmbeddingOptimizer> {
1059        RevolutionaryEmbeddingOptimizerFactory::create_gpu_focused()
1060            .await
1061            .map_err(|e| anyhow::anyhow!("Failed to create GPU optimizer: {}", e))
1062    }
1063
1064    /// Create a balanced revolutionary embedding optimizer
1065    pub async fn create_balanced_optimizer() -> anyhow::Result<RevolutionaryEmbeddingOptimizer> {
1066        RevolutionaryEmbeddingOptimizerFactory::create_balanced()
1067            .await
1068            .map_err(|e| anyhow::anyhow!("Failed to create balanced optimizer: {}", e))
1069    }
1070    */
1071
1072    /// Quick performance test with revolutionary optimization
1073    pub async fn quick_revolutionary_performance_test<F, Fut>(
1074        name: &str,
1075        iterations: usize,
1076        async_operation: F,
1077    ) -> std::time::Duration
1078    where
1079        F: Fn() -> Fut,
1080        Fut: std::future::Future<Output = ()>,
1081    {
1082        let start = std::time::Instant::now();
1083        for _ in 0..iterations {
1084            async_operation().await;
1085        }
1086        let duration = start.elapsed();
1087
1088        println!(
1089            "Revolutionary performance test '{name}': {iterations} iterations in {duration:?} ({:.2} ops/sec)",
1090            iterations as f64 / duration.as_secs_f64()
1091        );
1092
1093        duration
1094    }
1095}
1096
1097#[cfg(test)]
1098mod quick_start_tests {
1099    use super::*;
1100    use crate::quick_start::*;
1101
1102    #[test]
1103    fn test_create_simple_transe_model() {
1104        let model = create_simple_transe_model();
1105        let config = model.config();
1106        assert_eq!(config.dimensions, 128);
1107        assert_eq!(config.learning_rate, 0.01);
1108        assert_eq!(config.max_epochs, 100);
1109    }
1110
1111    #[test]
1112    fn test_parse_triple_from_string() {
1113        let triple_str = "http://example.org/alice http://example.org/knows http://example.org/bob";
1114        let triple = parse_triple_from_string(triple_str).expect("should succeed");
1115        assert_eq!(triple.subject.iri, "http://example.org/alice");
1116        assert_eq!(triple.predicate.iri, "http://example.org/knows");
1117        assert_eq!(triple.object.iri, "http://example.org/bob");
1118    }
1119
1120    #[test]
1121    fn test_parse_triple_from_string_invalid() {
1122        let triple_str = "http://example.org/alice http://example.org/knows";
1123        let result = parse_triple_from_string(triple_str);
1124        assert!(result.is_err());
1125    }
1126
1127    #[test]
1128    fn test_add_triples_from_strings() {
1129        let mut model = create_simple_transe_model();
1130        let triple_strings = [
1131            "http://example.org/alice http://example.org/knows http://example.org/bob",
1132            "http://example.org/bob http://example.org/likes http://example.org/music",
1133        ];
1134
1135        let count = add_triples_from_strings(&mut model, &triple_strings).expect("should succeed");
1136        assert_eq!(count, 2);
1137    }
1138
1139    #[test]
1140    fn test_cosine_similarity() {
1141        let a = vec![1.0, 0.0, 0.0];
1142        let b = vec![1.0, 0.0, 0.0];
1143        let similarity = cosine_similarity(&a, &b).expect("should succeed");
1144        assert!((similarity - 1.0).abs() < 1e-10);
1145
1146        let c = vec![0.0, 1.0, 0.0];
1147        let similarity2 = cosine_similarity(&a, &c).expect("should succeed");
1148        assert!((similarity2 - 0.0).abs() < 1e-10);
1149
1150        // Test different dimensions should fail
1151        let d = vec![1.0, 0.0];
1152        assert!(cosine_similarity(&a, &d).is_err());
1153    }
1154
1155    #[test]
1156    fn test_generate_sample_kg_data() {
1157        let triples = generate_sample_kg_data(5, 3);
1158        assert!(!triples.is_empty());
1159
1160        // Check that all subjects and objects are in the expected format
1161        for (subject, relation, object) in &triples {
1162            assert!(subject.starts_with("http://example.org/entity_"));
1163            assert!(relation.starts_with("http://example.org/relation_"));
1164            assert!(object.starts_with("http://example.org/entity_"));
1165            assert_ne!(subject, object); // No self-loops
1166        }
1167    }
1168
1169    #[test]
1170    fn test_quick_performance_test() {
1171        let duration = quick_performance_test("test_operation", 100, || {
1172            // Simple operation for testing
1173            let _sum: i32 = (1..10).sum();
1174        });
1175
1176        // In release mode, operations can be extremely fast
1177        // Just verify the function completes and returns a valid duration
1178        let _nanos = duration.as_nanos();
1179    }
1180}
oxirs_embed/lib.rs

oxirs_embed/
lib.rs
