Semantic Search

const results = await toolIndex.search('reset a billing password');

for (const result of results) {
  console.log(`${result.metadata.toolName} (${result.score.toFixed(2)})`);
}

const matches = await toolIndex.search('reset a billing password', {
  topK: 5,                    // Maximum results (default: 10)
  threshold: 0.45,            // Minimum similarity (default: 0.3)
  filter: (metadata) =>       // Metadata filter function
    metadata.owner === 'billing' &&
    !metadata.tags.includes('deprecated'),
  includeVector: false,       // Include raw vectors in results
});

interface SearchResult<T extends DocumentMetadata> {
  id: string;           // Document ID
  score: number;        // Similarity score (0-1)
  metadata: T;          // Document metadata
  vector?: number[];    // Embedding vector (if includeVector: true)
}

// Filter by owner
const results = await toolIndex.search('user management', {
  filter: (m) => m.owner === 'users',
});

// Filter by tag
const results = await toolIndex.search('payment', {
  filter: (m) => m.tags.includes('billing'),
});

// Exclude deprecated
const results = await toolIndex.search('list items', {
  filter: (m) => !m.deprecated,
});

const results = await toolIndex.search('sensitive operation', {
  filter: (metadata) => {
    // Must be owned by specific teams
    const allowedOwners = ['billing', 'users', 'orders'];
    if (!allowedOwners.includes(metadata.owner)) return false;

    // Must not be deprecated
    if (metadata.deprecated) return false;

    // Must not be destructive OR user has elevated permissions
    if (metadata.risk === 'destructive' && !userHasPermission) return false;

    return true;
  },
});

// Strict matching - only highly relevant results
const strict = await toolIndex.search(query, { threshold: 0.7 });

// Moderate matching - good balance
const moderate = await toolIndex.search(query, { threshold: 0.5 });

// Loose matching - include tangentially related
const loose = await toolIndex.search(query, { threshold: 0.3 });

// Get all tools by owner (no semantic ranking)
const billingTools = toolIndex.filter(
  (metadata) => metadata.owner === 'billing'
);

// Get all deprecated tools
const deprecated = toolIndex.filter(
  (metadata) => metadata.deprecated === true
);

// Good - only fetch what you'll display
const results = await toolIndex.search(query, { topK: 5 });

// Wasteful - fetching more than needed
const results = await toolIndex.search(query, { topK: 1000 });

// Filter first, then rank - more efficient
const results = await toolIndex.search(query, {
  filter: (m) => m.owner === 'billing',
  topK: 10,
});

const db = new VectoriaDB({
  useHNSW: true,
  hnsw: { efSearch: 50 },
});

import { QueryValidationError } from 'vectoriadb';

try {
  const results = await toolIndex.search(query, { topK: -1 });
} catch (error) {
  if (error instanceof QueryValidationError) {
    console.error('Invalid search parameters:', error.message);
  }
}