RUST_API.md

Ruvector Rust API Reference

Complete API reference for ruvector-core crate.

Table of Contents

1. VectorDB
2. AgenticDB
3. Types
4. Configuration
5. Advanced Features
6. Error Handling

VectorDB

Core vector database with HNSW indexing.

Creation

use ruvector_core::{VectorDB, DbOptions};

pub fn new(options: DbOptions) -> Result<Self>

Create a new vector database.

Parameters:

• options: Database configuration

Returns: Result<VectorDB, RuvectorError>

Example:

let mut options = DbOptions::default();
options.dimensions = 128;
options.storage_path = "./vectors.db".to_string();

let db = VectorDB::new(options)?;

open

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Open an existing database.

Parameters:

• path: Path to database directory

Returns: Result<VectorDB, RuvectorError>

Example:

let db = VectorDB::open("./vectors.db")?;

insert

pub fn insert(&self, entry: VectorEntry) -> Result<VectorId>

Insert a single vector.

Parameters:

• entry: Vector entry with optional ID and metadata

Returns: Result<VectorId, RuvectorError> - ID of inserted vector

Example:

let entry = VectorEntry {
    id: None,  // Auto-generate
    vector: vec![0.1; 128],
    metadata: None,
};

let id = db.insert(entry)?;

insert_batch

pub fn insert_batch(&self, entries: Vec<VectorEntry>) -> Result<Vec<VectorId>>

Insert multiple vectors efficiently.

Parameters:

• entries: Vector of entries to insert

Returns: Result<Vec<VectorId>, RuvectorError> - IDs of inserted vectors

Time Complexity: O(n log m) where n is batch size, m is existing vectors

Example:

let entries: Vec<VectorEntry> = (0..1000)
    .map(|i| VectorEntry {
        id: Some(format!("vec_{}", i)),
        vector: vec![0.1; 128],
        metadata: None,
    })
    .collect();

let ids = db.insert_batch(entries)?;
assert_eq!(ids.len(), 1000);

search

pub fn search(&self, query: &SearchQuery) -> Result<Vec<SearchResult>>

Search for similar vectors.

Parameters:

• query: Search query with vector, k, filters

Returns: Result<Vec<SearchResult>, RuvectorError> - Top-k results

Time Complexity: O(log n) with HNSW

Example:

let query = SearchQuery {
    vector: vec![0.1; 128],
    k: 10,
    filter: None,
    include_vectors: false,
};

let results = db.search(&query)?;

for result in results {
    println!("ID: {}, Distance: {}", result.id, result.distance);
}

delete

pub fn delete(&self, id: &VectorId) -> Result<()>

Delete a vector by ID.

Parameters:

• id: Vector ID to delete

Returns: Result<(), RuvectorError>

Example:

db.delete(&"vec_001".to_string())?;

update

pub fn update(&self, id: &VectorId, entry: VectorEntry) -> Result<()>

Update an existing vector.

Parameters:

• id: Vector ID to update
• entry: New vector data

Returns: Result<(), RuvectorError>

Example:

let new_entry = VectorEntry {
    id: Some("vec_001".to_string()),
    vector: vec![0.2; 128],
    metadata: Some(HashMap::from([
        ("updated".into(), json!(true))
    ])),
};

db.update(&"vec_001".to_string(), new_entry)?;

count

pub fn count(&self) -> usize

Get total number of vectors.

Returns: Number of vectors in database

Example:

let total = db.count();
println!("Total vectors: {}", total);

AgenticDB

Extended API with specialized agent memory tables.

Creation

use ruvector_core::{AgenticDB, DbOptions};

pub fn new(options: DbOptions) -> Result<Self>

Create AgenticDB instance.

Example:

let db = AgenticDB::new(DbOptions::default())?;

Reflexion Memory

store_episode

pub fn store_episode(
    &self,
    task: String,
    actions: Vec<String>,
    observations: Vec<String>,
    critique: String,
) -> Result<String>

Store a self-critique episode.

Parameters:

• task: Task description
• actions: Actions taken
• observations: Observations made
• critique: Self-generated critique

Returns: Episode ID

Example:

let id = db.store_episode(
    "Solve coding problem".into(),
    vec!["Read problem".into(), "Write solution".into()],
    vec!["Tests failed".into()],
    "Should test edge cases first".into(),
)?;

retrieve_episodes

pub fn retrieve_episodes(
    &self,
    query_embedding: Vec<f32>,
    k: usize,
) -> Result<Vec<ReflexionEpisode>>

Retrieve similar past episodes.

Parameters:

• query_embedding: Embedded critique or task
• k: Number of episodes to retrieve

Returns: Similar episodes

Example:

let episodes = db.retrieve_episodes(critique_embedding, 5)?;

for ep in episodes {
    println!("Task: {}", ep.task);
    println!("Critique: {}", ep.critique);
}

Skill Library

create_skill

pub fn create_skill(
    &self,
    name: String,
    description: String,
    parameters: HashMap<String, String>,
    examples: Vec<String>,
) -> Result<String>

Create a reusable skill.

Parameters:

• name: Skill name
• description: What the skill does
• parameters: Required parameters
• examples: Usage examples

Returns: Skill ID

Example:

let id = db.create_skill(
    "authenticate_user".into(),
    "Authenticate user with JWT token".into(),
    HashMap::from([
        ("token".into(), "string".into()),
        ("user_id".into(), "string".into()),
    ]),
    vec!["authenticate_user(token, user_id)".into()],
)?;

search_skills

pub fn search_skills(
    &self,
    query_embedding: Vec<f32>,
    k: usize,
) -> Result<Vec<Skill>>

Search for relevant skills.

Parameters:

• query_embedding: Embedded task description
• k: Number of skills to retrieve

Returns: Relevant skills

Example:

let skills = db.search_skills(task_embedding, 3)?;

for skill in skills {
    println!("Skill: {} - {}", skill.name, skill.description);
    println!("Success rate: {:.1}%", skill.success_rate * 100.0);
}

Causal Memory

add_causal_edge

pub fn add_causal_edge(
    &self,
    causes: Vec<String>,
    effects: Vec<String>,
    confidence: f64,
    context: String,
) -> Result<String>

Add cause-effect relationship.

Parameters:

• causes: Cause actions/states (hypergraph: multiple causes)
• effects: Effect actions/states (hypergraph: multiple effects)
• confidence: Confidence score (0-1)
• context: Context description

Returns: Edge ID

Example:

let id = db.add_causal_edge(
    vec!["authenticate".into(), "validate_token".into()],
    vec!["access_granted".into()],
    0.95,
    "User authentication flow".into(),
)?;

query_causal

pub fn query_causal(
    &self,
    query_embedding: Vec<f32>,
    k: usize,
) -> Result<Vec<CausalQueryResult>>

Query causal relationships.

Parameters:

• query_embedding: Embedded context
• k: Number of results

Returns: Causal edges with utility scores

Example:

let results = db.query_causal(context_embedding, 10)?;

for result in results {
    println!("Causes: {:?} → Effects: {:?}", result.edge.causes, result.edge.effects);
    println!("Utility: {:.4}", result.utility_score);
}

Learning Sessions

create_learning_session

pub fn create_learning_session(
    &self,
    algorithm: String,
    state_dim: usize,
    action_dim: usize,
) -> Result<String>

Create RL training session.

Parameters:

• algorithm: RL algorithm (Q-Learning, DQN, PPO, etc.)
• state_dim: State dimensionality
• action_dim: Action dimensionality

Returns: Session ID

Example:

let session_id = db.create_learning_session(
    "PPO".into(),
    64,  // state_dim
    4,   // action_dim
)?;

add_experience

pub fn add_experience(
    &self,
    session_id: &str,
    state: Vec<f32>,
    action: Vec<f32>,
    reward: f64,
    next_state: Vec<f32>,
    done: bool,
) -> Result<()>

Add experience to session.

Parameters:

• session_id: Session ID
• state: Current state
• action: Action taken
• reward: Reward received
• next_state: Next state
• done: Episode finished?

Returns: Result<(), RuvectorError>

Example:

db.add_experience(
    &session_id,
    state,
    action,
    1.0,  // reward
    next_state,
    false,  // not done
)?;

predict_with_confidence

pub fn predict_with_confidence(
    &self,
    session_id: &str,
    state: Vec<f32>,
) -> Result<Prediction>

Predict action with confidence intervals.

Parameters:

• session_id: Session ID
• state: Current state

Returns: Prediction with confidence bounds

Example:

let prediction = db.predict_with_confidence(&session_id, state)?;

println!("Action: {:?}", prediction.action);
println!("Confidence: [{:.2}, {:.2}]",
    prediction.confidence_lower,
    prediction.confidence_upper
);

Types

VectorEntry

pub struct VectorEntry {
    pub id: Option<String>,
    pub vector: Vec<f32>,
    pub metadata: Option<HashMap<String, serde_json::Value>>,
}

Entry for inserting vectors.

SearchQuery

pub struct SearchQuery {
    pub vector: Vec<f32>,
    pub k: usize,
    pub filter: Option<serde_json::Value>,
    pub include_vectors: bool,
}

Query for searching vectors.

SearchResult

pub struct SearchResult {
    pub id: String,
    pub distance: f32,
    pub vector: Option<Vec<f32>>,
    pub metadata: Option<HashMap<String, serde_json::Value>>,
}

Search result with ID, distance, and optional data.

DistanceMetric

pub enum DistanceMetric {
    Euclidean,   // L2 distance
    Cosine,      // 1 - cosine_similarity
    DotProduct,  // -dot_product (for maximization)
    Manhattan,   // L1 distance
}

Distance metrics for similarity calculation.

Configuration

DbOptions

pub struct DbOptions {
    pub dimensions: usize,
    pub storage_path: String,
    pub distance_metric: DistanceMetric,
    pub hnsw: HnswConfig,
    pub quantization: QuantizationConfig,
    pub mmap_vectors: bool,
}

Database configuration options.

HnswConfig

pub struct HnswConfig {
    pub m: usize,               // Connections per node (16-64)
    pub ef_construction: usize, // Build quality (100-400)
    pub ef_search: usize,       // Search quality (50-500)
    pub max_elements: usize,    // Maximum vectors
}

HNSW index configuration.

QuantizationConfig

pub enum QuantizationConfig {
    None,
    Scalar,                            // 4x compression
    Product { subspaces: usize, k: usize }, // 8-16x compression
    Binary,                            // 32x compression
}

Quantization configuration.

Advanced Features

HybridSearch

Combine vector similarity with keyword search.

use ruvector_core::{HybridSearch, HybridConfig};

let config = HybridConfig {
    vector_weight: 0.7,
    bm25_weight: 0.3,
    k1: 1.5,
    b: 0.75,
};

let hybrid = HybridSearch::new(&db, config)?;
let results = hybrid.search(&query_vector, &["keywords"], 10)?;

FilteredSearch

Apply metadata filters.

use ruvector_core::{FilteredSearch, FilterExpression, FilterStrategy};

let filtered = FilteredSearch::new(&db, FilterStrategy::PreFilter);

let filter = FilterExpression::And(vec![
    FilterExpression::Eq("category".into(), json!("tech")),
    FilterExpression::Gte("score".into(), json!(0.8)),
]);

let results = filtered.search(&query, 10, Some(filter))?;

MMRSearch

Maximal Marginal Relevance for diversity.

use ruvector_core::{MMRSearch, MMRConfig};

let config = MMRConfig {
    lambda: 0.5,  // Balance relevance vs diversity
    diversity_weight: 0.3,
};

let mmr = MMRSearch::new(&db, config)?;
let results = mmr.search(&query, 20)?;

ConformalPredictor

Uncertainty quantification.

use ruvector_core::{ConformalPredictor, ConformalConfig};

let mut predictor = ConformalPredictor::new(ConformalConfig {
    alpha: 0.1,  // 90% confidence
    calibration_size: 1000,
});

predictor.calibrate(&calibration_data)?;
let prediction = predictor.predict(&query, &db)?;

Error Handling

RuvectorError

pub enum RuvectorError {
    DimensionMismatch { expected: usize, got: usize },
    StorageError(String),
    IndexError(String),
    SerializationError(String),
    IoError(std::io::Error),
    // ... more variants
}

All operations return Result<T, RuvectorError>.

Example:

match db.insert(entry) {
    Ok(id) => println!("Inserted: {}", id),
    Err(RuvectorError::DimensionMismatch { expected, got }) => {
        eprintln!("Wrong dimensions: expected {}, got {}", expected, got);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Complete API Documentation

For complete auto-generated API docs:

cargo doc --no-deps --open

Or visit: https://docs.rs/ruvector-core