@ruvector/router

Semantic router for AI agents - vector-based intent matching with HNSW indexing and SIMD acceleration.

Features

• Semantic Intent Matching: Route queries to intents based on meaning, not keywords
• HNSW Indexing: Fast approximate nearest neighbor search
• SIMD Optimized: Native Rust performance with vectorized operations
• Quantization: Memory-efficient storage for large intent sets
• Multi-Platform: Works on Linux, macOS, and Windows

Installation

npm install @ruvector/router

The package automatically installs the correct native binary for your platform.

Quick Start

import { SemanticRouter } from '@ruvector/router';

// Create router
const router = new SemanticRouter({ dimension: 384 });

// Add intents with example utterances
router.addIntent({
  name: 'weather',
  utterances: [
    'What is the weather today?',
    'Will it rain tomorrow?',
    'How hot will it be?'
  ],
  metadata: { handler: 'weather_agent' }
});

router.addIntent({
  name: 'greeting',
  utterances: [
    'Hello',
    'Hi there',
    'Good morning',
    'Hey'
  ],
  metadata: { handler: 'greeting_agent' }
});

router.addIntent({
  name: 'help',
  utterances: [
    'I need help',
    'Can you assist me?',
    'What can you do?'
  ],
  metadata: { handler: 'help_agent' }
});

// Route a query
const results = await router.route('What will the weather be like this weekend?');

console.log(results[0].intent);   // 'weather'
console.log(results[0].score);    // 0.92
console.log(results[0].metadata); // { handler: 'weather_agent' }

API Reference

SemanticRouter

Main class for semantic routing.

Constructor

new SemanticRouter(config: RouterConfig)

RouterConfig: | Property | Type | Default | Description | |----------|------|---------|-------------| | dimension | number | required | Embedding dimension size | | metric | string | 'cosine' | Distance metric: 'cosine', 'euclidean', 'dot' | | m | number | 16 | HNSW M parameter | | efConstruction | number | 200 | HNSW ef_construction | | quantization | boolean | false | Enable memory-efficient quantization |

Methods

addIntent(intent: Intent): void

Add an intent to the router.

router.addIntent({
  name: 'booking',
  utterances: ['Book a flight', 'Reserve a hotel'],
  metadata: { department: 'travel' }
});

route(query: string | Float32Array, k?: number): Promise<RouteResult[]>

Route a query to matching intents.

const results = await router.route('I want to book a vacation');
// [{ intent: 'booking', score: 0.89, metadata: {...} }]

routeWithEmbedding(embedding: Float32Array, k?: number): RouteResult[]

Route with a pre-computed embedding (synchronous).

const embedding = await getEmbedding('query text');
const results = router.routeWithEmbedding(embedding, 3);

removeIntent(name: string): boolean

Remove an intent from the router.

getIntents(): string[]

Get all registered intent names.

clear(): void

Remove all intents.

save(path: string): Promise<void>

Persist router state to disk.

load(path: string): Promise<void>

Load router state from disk.

Types

Intent

interface Intent {
  name: string;                        // Unique intent identifier
  utterances: string[];                // Example utterances
  embedding?: Float32Array | number[]; // Pre-computed embedding
  metadata?: Record<string, unknown>;  // Custom metadata
}

RouteResult

interface RouteResult {
  intent: string;                      // Matched intent name
  score: number;                       // Similarity score (0-1)
  metadata?: Record<string, unknown>;  // Intent metadata
}

Use Cases

Chatbot Intent Detection

const router = new SemanticRouter({ dimension: 384 });

// Define intents
const intents = [
  { name: 'faq', utterances: ['What are your hours?', 'How do I contact support?'] },
  { name: 'order', utterances: ['Track my order', 'Where is my package?'] },
  { name: 'return', utterances: ['I want to return this', 'How do I get a refund?'] }
];

intents.forEach(i => router.addIntent(i));

// Handle user message
async function handleMessage(text: string) {
  const [result] = await router.route(text);

  switch(result.intent) {
    case 'faq': return handleFAQ(text);
    case 'order': return handleOrder(text);
    case 'return': return handleReturn(text);
    default: return handleUnknown(text);
  }
}

Multi-Agent Orchestration

const agents = {
  'code': new CodeAgent(),
  'research': new ResearchAgent(),
  'creative': new CreativeAgent()
};

const router = new SemanticRouter({ dimension: 768 });

router.addIntent({
  name: 'code',
  utterances: ['Write code', 'Debug this', 'Implement a function'],
  metadata: { agent: 'code' }
});

router.addIntent({
  name: 'research',
  utterances: ['Find information', 'Search for', 'Look up'],
  metadata: { agent: 'research' }
});

// Route task to best agent
async function routeTask(task: string) {
  const [result] = await router.route(task);
  const agent = agents[result.metadata.agent];
  return agent.execute(task);
}

Platform Support

| Platform | Architecture | Package | |----------|--------------|---------| | Linux | x64 | @ruvector/router-linux-x64-gnu | | Linux | ARM64 | @ruvector/router-linux-arm64-gnu | | macOS | x64 | @ruvector/router-darwin-x64 | | macOS | ARM64 | @ruvector/router-darwin-arm64 | | Windows | x64 | @ruvector/router-win32-x64-msvc |

Performance

• Routing: < 1ms per query with HNSW
• Throughput: 100,000+ routes/second
• Memory: ~1KB per intent + embeddings

Related Packages

• @ruvector/core - Vector database
• @ruvector/tiny-dancer - Neural routing
• @ruvector/gnn - Graph Neural Networks

License

MIT