@ruvector/router

@ruvector/router

Semantic router for AI agents providing vector-based intent matching with HNSW indexing and SIMD acceleration for sub-millisecond routing decisions across task categories.

Quick Command Reference

Installation

Hub install (recommended): npx ruvector@latest includes this package. Standalone: npx @ruvector/router@latest See Installation Guide for the full ecosystem.

Core API

SemanticRouter Constructor

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

const router = new SemanticRouter({
  dimensions: 384,
  metric: 'cosine',
  threshold: 0.7,
  embeddingModel: 'all-MiniLM-L6-v2',
  defaultRoute: 'fallback',
  efSearch: 100,
});

Constructor Options:

Route Management

// Add route with example utterances (auto-embedded)
await router.addRoute('greeting', ['hello', 'hi', 'good morning', 'hey there']);
await router.addRoute('farewell', ['goodbye', 'bye', 'see you later']);
await router.addRoute('help', ['I need help', 'can you assist me', 'support']);

// Add route with pre-computed vectors
await router.addRouteVectors('custom', vectors, { metadata: { priority: 1 } });

// Remove a route
router.removeRoute('greeting');

// List all routes
const routes = router.getRoutes();
// [{ name: 'greeting', utterances: 4 }, { name: 'farewell', utterances: 3 }]

Routing

// Route a single input
const match = await router.route('hello there');
// { route: 'greeting', score: 0.92, metadata: {} }

// Route with top-K candidates
const matches = await router.routeTopK('can you help me', 3);
// [{ route: 'help', score: 0.89 }, { route: 'greeting', score: 0.45 }]

// Route with raw vector
const match = await router.routeVector(queryVector);

// Batch route multiple inputs
const results = await router.routeBatch(['hello', 'bye', 'help me']);

Route Result:

interface RouteMatch {
  route: string;
  score: number;
  metadata?: Record<string, any>;
}

Configuration

router.setThreshold(0.8);                          // Adjust threshold
router.setDefaultRoute('unknown');                 // Set fallback
router.setEfSearch(200);                           // Adjust accuracy

Common Patterns

Intent-Based Chatbot Router

const router = new SemanticRouter({ threshold: 0.75 });
await router.addRoute('greeting', ['hello', 'hi', 'hey']);
await router.addRoute('order_status', ['where is my order', 'track package']);
await router.addRoute('complaint', ['problem with order', 'wrong item']);
await router.addRoute('general', ['tell me about', 'what is']);

const match = await router.route(userMessage);
switch (match.route) {
  case 'greeting': return handleGreeting();
  case 'order_status': return handleOrderStatus();
  case 'complaint': return handleComplaint();
  default: return handleGeneral();
}

Agent Task Dispatch

const router = new SemanticRouter({ threshold: 0.6 });
await router.addRoute('code_review', ['review this code', 'check for bugs']);
await router.addRoute('testing', ['write tests', 'unit test', 'test coverage']);
await router.addRoute('docs', ['write documentation', 'update readme']);

const match = await router.route(taskDescription);
dispatchToAgent(match.route, task);

Multi-Language Support

await router.addRoute('greeting', [
  'hello', 'hi',           // English
  'bonjour', 'salut',      // French
  'hola', 'buenos dias',   // Spanish
]);
// Multilingual embedding model handles cross-language matching

Key Options

RAN DDD Context

Bounded Context: RANO Optimization

References

• API reference: See references/commands.md
• Full README
• npm