@agentdb/sdk/examples/vector-operations.js

JavaScript SDK for AgentDB database service

#!/usr/bin/env node

/**
 * Vector Operations Example
 * 
 * This example demonstrates how to use the AgentDB SDK for vector operations,
 * including creating vector buffers, inserting embeddings, and performing
 * similarity searches.
 */

import { DatabaseService, createVectorBuffer } from '../index.js';

// Configuration - replace with your actual values
const BASE_URL = process.env.AGENTDB_BASE_URL || 'https://api.agentdb.dev';
const API_KEY = process.env.AGENTDB_API_KEY || 'your-api-key-here';
const TOKEN = process.env.AGENTDB_TOKEN || 'your-uuid-token-here';

async function runVectorExample() {
  console.log('🚀 AgentDB SDK Vector Operations Example\n');

  try {
    // Create a service instance
    console.log('Creating DatabaseService...');
    const service = new DatabaseService(BASE_URL, API_KEY);

    // Create a connection to a database
    console.log('Creating connection to vector database...');
    const connection = service.connect(TOKEN, 'vector-example-db', 'sqlite');

    // Create a table for storing documents with embeddings
    console.log('Creating documents table with vector embeddings...');
    await connection.execute({
      sql: `CREATE TABLE IF NOT EXISTS documents (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        title TEXT NOT NULL,
        content TEXT NOT NULL,
        embedding BLOB,
        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
      )`,
      params: []
    });

    // Sample documents with their embeddings (in a real app, these would come from an embedding model)
    const sampleDocuments = [
      {
        title: 'Introduction to Machine Learning',
        content: 'Machine learning is a subset of artificial intelligence that focuses on algorithms that can learn from data.',
        embedding: [0.8, 0.2, 0.1, 0.9, 0.3, 0.7, 0.4, 0.6]
      },
      {
        title: 'Database Design Principles',
        content: 'Good database design involves normalization, indexing, and understanding relationships between entities.',
        embedding: [0.1, 0.8, 0.9, 0.2, 0.7, 0.3, 0.6, 0.4]
      },
      {
        title: 'Vector Search Fundamentals',
        content: 'Vector search enables finding similar items by comparing high-dimensional vectors using distance metrics.',
        embedding: [0.3, 0.7, 0.4, 0.6, 0.8, 0.2, 0.1, 0.9]
      },
      {
        title: 'Natural Language Processing',
        content: 'NLP combines computational linguistics with machine learning to help computers understand human language.',
        embedding: [0.7, 0.3, 0.2, 0.8, 0.4, 0.6, 0.9, 0.1]
      },
      {
        title: 'Data Science Workflow',
        content: 'Data science involves collecting, cleaning, analyzing, and visualizing data to extract insights.',
        embedding: [0.2, 0.6, 0.8, 0.4, 0.1, 0.9, 0.3, 0.7]
      }
    ];

    // Insert documents using createVectorBuffer utility
    console.log('Inserting sample documents with vector embeddings...');
    for (const doc of sampleDocuments) {
      const vectorBuffer = createVectorBuffer(doc.embedding);
      await connection.execute({
        sql: 'INSERT INTO documents (title, content, embedding) VALUES (?, ?, ?)',
        params: [doc.title, doc.content, vectorBuffer]
      });
    }
    console.log(`✅ Inserted ${sampleDocuments.length} documents with embeddings`);

    // Perform vector similarity search using cosine distance
    console.log('\n🔍 Performing vector similarity search...');
    
    // Query vector (similar to machine learning document)
    const queryVector = createVectorBuffer([0.8, 0.2, 0.1, 0.9, 0.3, 0.7, 0.4, 0.6]);
    
    const similarityResult = await connection.execute({
      sql: `SELECT 
        id,
        title,
        content,
        vec_distance_cosine(embedding, ?) as cosine_distance,
        (1 - vec_distance_cosine(embedding, ?)) as similarity_score
      FROM documents 
      ORDER BY cosine_distance 
      LIMIT 3`,
      params: [queryVector, queryVector]
    });

    console.log('📊 Top 3 most similar documents:');
    similarityResult.results[0].rows.forEach((row, index) => {
      console.log(`${index + 1}. "${row.title}"`);
      console.log(`   Similarity: ${(row.similarity_score * 100).toFixed(1)}%`);
      console.log(`   Content: ${row.content.substring(0, 80)}...`);
      console.log('');
    });

    // Demonstrate using arrays directly (server-side processing)
    console.log('🔄 Demonstrating direct array usage (server-side processing)...');
    const directArrayResult = await connection.execute({
      sql: `SELECT 
        title,
        vec_distance_l2(embedding, ?) as l2_distance
      FROM documents 
      ORDER BY l2_distance 
      LIMIT 2`,
      params: [[0.3, 0.7, 0.4, 0.6, 0.8, 0.2, 0.1, 0.9]]  // Direct array usage
    });

    console.log('📊 L2 distance results:');
    directArrayResult.results[0].rows.forEach((row, index) => {
      console.log(`${index + 1}. "${row.title}" (L2 distance: ${row.l2_distance.toFixed(4)})`);
    });

    // Demonstrate batch vector operations
    console.log('\n📦 Demonstrating batch vector operations...');
    const batchQueries = [
      {
        sql: 'SELECT COUNT(*) as total_documents FROM documents',
        params: []
      },
      {
        sql: 'SELECT AVG(vec_length(embedding)) as avg_vector_length FROM documents',
        params: []
      },
      {
        sql: `SELECT title, vec_length(embedding) as vector_dimensions 
              FROM documents 
              ORDER BY id 
              LIMIT 3`,
        params: []
      }
    ];

    const batchResult = await connection.execute(batchQueries);
    
    console.log(`📈 Total documents: ${batchResult.results[0].rows[0].total_documents}`);
    console.log(`📏 Average vector length: ${batchResult.results[1].rows[0].avg_vector_length.toFixed(2)}`);
    console.log('📋 Vector dimensions by document:');
    batchResult.results[2].rows.forEach(row => {
      console.log(`   "${row.title}": ${row.vector_dimensions} dimensions`);
    });

    console.log('\n✅ Vector operations example completed successfully!');
    console.log('\n💡 Key takeaways:');
    console.log('   • Use createVectorBuffer() to convert arrays to buffers for optimal performance');
    console.log('   • Arrays can be passed directly and will be processed server-side');
    console.log('   • Vector search supports cosine, L2, and other distance metrics');
    console.log('   • Batch operations can combine vector and regular queries efficiently');

  } catch (error) {
    console.error('❌ Error in vector operations example:', error.message);
    if (error.statusCode) {
      console.error('Status code:', error.statusCode);
    }
    if (error.response) {
      console.error('Response details:', error.response);
    }
  }
}

// Only run if this script is executed directly
if (import.meta.url === `file://${process.argv[1]}`) {
  runVectorExample().catch(error => {
    console.error('💥 Example failed:', error);
    process.exit(1);
  });
}

export { runVectorExample };