ruvector/docs/api/NODEJS_API.md

Ruvector Node.js API Reference

Complete API reference for ruvector npm package.

Installation

npm install ruvector
# or
yarn add ruvector

Table of Contents

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

VectorDB

Core vector database class.

Constructor

new VectorDB(options: DbOptions): VectorDB

Create a new vector database.

Parameters:

interface DbOptions {
    dimensions: number;
    storagePath: string;
    distanceMetric?: 'euclidean' | 'cosine' | 'dotProduct' | 'manhattan';
    hnsw?: HnswConfig;
    quantization?: QuantizationConfig;
    mmapVectors?: boolean;
}

Example:

const { VectorDB } = require('ruvector');

const db = new VectorDB({
    dimensions: 128,
    storagePath: './vectors.db',
    distanceMetric: 'cosine'
});

insert

async insert(entry: VectorEntry): Promise<string>

Insert a single vector.

Parameters:

interface VectorEntry {
    id?: string;
    vector: Float32Array;
    metadata?: Record<string, any>;
}

Returns: Promise resolving to vector ID

Example:

const id = await db.insert({
    vector: new Float32Array(128).fill(0.1),
    metadata: { text: 'Example document' }
});

console.log('Inserted:', id);

insertBatch

async insertBatch(entries: VectorEntry[]): Promise<string[]>

Insert multiple vectors efficiently.

Parameters: Array of vector entries

Returns: Promise resolving to array of IDs

Example:

const entries = Array.from({ length: 1000 }, (_, i) => ({
    id: `vec_${i}`,
    vector: new Float32Array(128).map(() => Math.random()),
    metadata: { index: i }
}));

const ids = await db.insertBatch(entries);
console.log(`Inserted ${ids.length} vectors`);

search

async search(query: SearchQuery): Promise<SearchResult[]>

Search for similar vectors.

Parameters:

interface SearchQuery {
    vector: Float32Array;
    k: number;
    filter?: any;
    includeVectors?: boolean;
    includeMetadata?: boolean;
}

Returns: Promise resolving to search results

Example:

const results = await db.search({
    vector: new Float32Array(128).fill(0.1),
    k: 10,
    includeMetadata: true
});

results.forEach(result => {
    console.log(`ID: ${result.id}, Distance: ${result.distance}`);
    console.log(`Metadata:`, result.metadata);
});

delete

async delete(id: string): Promise<void>

Delete a vector by ID.

Parameters: Vector ID string

Returns: Promise resolving when complete

Example:

await db.delete('vec_001');
console.log('Deleted vec_001');

update

async update(id: string, entry: VectorEntry): Promise<void>

Update an existing vector.

Parameters:

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

Returns: Promise resolving when complete

Example:

await db.update('vec_001', {
    vector: new Float32Array(128).fill(0.2),
    metadata: { updated: true }
});

count

count(): number

Get total number of vectors.

Returns: Number of vectors

Example:

const total = db.count();
console.log(`Total vectors: ${total}`);

AgenticDB

Extended API for AI agents.

Constructor

new AgenticDB(options: DbOptions): AgenticDB

Create AgenticDB instance.

Example:

const { AgenticDB } = require('ruvector');

const db = new AgenticDB({
    dimensions: 128,
    storagePath: './agenticdb.db'
});

Reflexion Memory

storeEpisode

async storeEpisode(
    task: string,
    actions: string[],
    observations: string[],
    critique: string
): Promise<string>

Store self-critique episode.

Parameters:

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

Returns: Episode ID

Example:

const episodeId = await db.storeEpisode(
    'Solve coding problem',
    ['Read problem', 'Write solution', 'Submit'],
    ['Tests failed', 'Edge case missed'],
    'Should test edge cases before submitting'
);

retrieveEpisodes

async retrieveEpisodes(
    queryEmbedding: Float32Array,
    k: number
): Promise<ReflexionEpisode[]>

Retrieve similar past episodes.

Parameters:

• queryEmbedding: Embedded critique or task
• k: Number of episodes

Returns: Similar episodes

Example:

const episodes = await db.retrieveEpisodes(critiqueEmbedding, 5);

episodes.forEach(ep => {
    console.log(`Task: ${ep.task}`);
    console.log(`Critique: ${ep.critique}`);
    console.log(`Actions: ${ep.actions.join(', ')}`);
});

Skill Library

createSkill

async createSkill(
    name: string,
    description: string,
    parameters: Record<string, string>,
    examples: string[]
): Promise<string>

Create a reusable skill.

Parameters:

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

Returns: Skill ID

Example:

const skillId = await db.createSkill(
    'authenticate_user',
    'Authenticate user with JWT token',
    {
        token: 'string',
        userId: 'string'
    },
    ['authenticate_user(token, userId)']
);

searchSkills

async searchSkills(
    queryEmbedding: Float32Array,
    k: number
): Promise<Skill[]>

Search for relevant skills.

Parameters:

• queryEmbedding: Embedded task description
• k: Number of skills

Returns: Relevant skills

Example:

const skills = await db.searchSkills(taskEmbedding, 3);

skills.forEach(skill => {
    console.log(`${skill.name}: ${skill.description}`);
    console.log(`Success rate: ${(skill.successRate * 100).toFixed(1)}%`);
    console.log(`Usage count: ${skill.usageCount}`);
});

Causal Memory

addCausalEdge

async addCausalEdge(
    causes: string[],
    effects: string[],
    confidence: number,
    context: string
): Promise<string>

Add cause-effect relationship.

Parameters:

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

Returns: Edge ID

Example:

const edgeId = await db.addCausalEdge(
    ['authenticate', 'validate_token'],
    ['access_granted'],
    0.95,
    'User authentication flow'
);

queryCausal

async queryCausal(
    queryEmbedding: Float32Array,
    k: number
): Promise<CausalQueryResult[]>

Query causal relationships.

Parameters:

• queryEmbedding: Embedded context
• k: Number of results

Returns: Causal edges with utility scores

Example:

const results = await db.queryCausal(contextEmbedding, 10);

results.forEach(result => {
    console.log(`${result.edge.causes.join(', ')} → ${result.edge.effects.join(', ')}`);
    console.log(`Confidence: ${result.edge.confidence}`);
    console.log(`Utility: ${result.utilityScore.toFixed(4)}`);
});

Learning Sessions

createLearningSession

async createLearningSession(
    algorithm: string,
    stateDim: number,
    actionDim: number
): Promise<string>

Create RL training session.

Parameters:

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

Returns: Session ID

Example:

const sessionId = await db.createLearningSession('PPO', 64, 4);

addExperience

async addExperience(
    sessionId: string,
    state: Float32Array,
    action: Float32Array,
    reward: number,
    nextState: Float32Array,
    done: boolean
): Promise<void>

Add experience to session.

Example:

await db.addExperience(
    sessionId,
    state,
    action,
    1.0,      // reward
    nextState,
    false     // not done
);

predictWithConfidence

async predictWithConfidence(
    sessionId: string,
    state: Float32Array
): Promise<Prediction>

Predict action with confidence intervals.

Returns:

interface Prediction {
    action: Float32Array;
    confidenceLower: number;
    confidenceUpper: number;
    meanConfidence: number;
}

Example:

const prediction = await db.predictWithConfidence(sessionId, state);

console.log('Action:', Array.from(prediction.action));
console.log(`Confidence: [${prediction.confidenceLower.toFixed(2)}, ${prediction.confidenceUpper.toFixed(2)}]`);

Types

VectorEntry

interface VectorEntry {
    id?: string;
    vector: Float32Array;
    metadata?: Record<string, any>;
}

SearchQuery

interface SearchQuery {
    vector: Float32Array;
    k: number;
    filter?: any;
    includeVectors?: boolean;
    includeMetadata?: boolean;
}

SearchResult

interface SearchResult {
    id: string;
    distance: number;
    vector?: Float32Array;
    metadata?: Record<string, any>;
}

ReflexionEpisode

interface ReflexionEpisode {
    id: string;
    task: string;
    actions: string[];
    observations: string[];
    critique: string;
    embedding: Float32Array;
    timestamp: number;
    metadata?: Record<string, any>;
}

Skill

interface Skill {
    id: string;
    name: string;
    description: string;
    parameters: Record<string, string>;
    examples: string[];
    embedding: Float32Array;
    usageCount: number;
    successRate: number;
    createdAt: number;
    updatedAt: number;
}

CausalEdge

interface CausalEdge {
    id: string;
    causes: string[];
    effects: string[];
    confidence: number;
    context: string;
    embedding: Float32Array;
    observations: number;
    timestamp: number;
}

Configuration

DbOptions

interface DbOptions {
    dimensions: number;
    storagePath: string;
    distanceMetric?: 'euclidean' | 'cosine' | 'dotProduct' | 'manhattan';
    hnsw?: HnswConfig;
    quantization?: QuantizationConfig;
    mmapVectors?: boolean;
}

HnswConfig

interface HnswConfig {
    m?: number;              // 16-64, default 32
    efConstruction?: number; // 100-400, default 200
    efSearch?: number;       // 50-500, default 100
    maxElements?: number;    // default 10_000_000
}

QuantizationConfig

interface QuantizationConfig {
    type: 'none' | 'scalar' | 'product' | 'binary';
    subspaces?: number;  // For product quantization
    k?: number;          // For product quantization
}

Advanced Features

HybridSearch

const { HybridSearch } = require('ruvector');

const hybrid = new HybridSearch(db, {
    vectorWeight: 0.7,
    bm25Weight: 0.3,
    k1: 1.5,
    b: 0.75
});

const results = await hybrid.search(
    queryVector,
    ['machine', 'learning'],
    10
);

FilteredSearch

const { FilteredSearch } = require('ruvector');

const filtered = new FilteredSearch(db, 'preFilter');

const results = await filtered.search(queryVector, 10, {
    and: [
        { field: 'category', op: 'eq', value: 'tech' },
        { field: 'score', op: 'gte', value: 0.8 }
    ]
});

MMRSearch

const { MMRSearch } = require('ruvector');

const mmr = new MMRSearch(db, {
    lambda: 0.5,
    diversityWeight: 0.3
});

const results = await mmr.search(queryVector, 20);

Error Handling

All async operations throw errors on failure:

try {
    const id = await db.insert(entry);
    console.log('Success:', id);
} catch (error) {
    if (error.message.includes('dimension mismatch')) {
        console.error('Wrong vector dimensions');
    } else {
        console.error('Error:', error.message);
    }
}

TypeScript Support

Full TypeScript type definitions included:

import { VectorDB, VectorEntry, SearchResult } from 'ruvector';

const db = new VectorDB({
    dimensions: 128,
    storagePath: './vectors.db'
});

const entry: VectorEntry = {
    vector: new Float32Array(128),
    metadata: { text: 'Example' }
};

const id: string = await db.insert(entry);
const results: SearchResult[] = await db.search({
    vector: new Float32Array(128),
    k: 10
});

Complete Examples

See examples/nodejs/ for complete working examples.