JSPM

@aigentic/router

0.1.31
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 19
  • Score
    100M100P100Q65547F
  • License MIT

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

Package Exports

  • @aigentic/router
  • @aigentic/router/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@aigentic/router) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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

License

MIT