Ruvector Tiny Dancer Node

Node.js bindings for Tiny Dancer neural routing via NAPI-RS.

ruvector-tiny-dancer-node provides native Node.js bindings for production-grade AI agent routing. Run FastGRNN neural inference at native speed for intelligent request routing in server-side applications. Part of the Ruvector ecosystem.

Why Tiny Dancer Node?

• Native Performance: Rust speed in Node.js
• Production Ready: Battle-tested in high-throughput systems
• Async/Await: Non-blocking inference operations
• TypeScript: Complete type definitions included
• Multi-Threaded: Leverage all CPU cores

Features

Core Capabilities

• Neural Inference: FastGRNN model execution
• Model Training: Train custom routing models
• Feature Engineering: Request feature extraction
• Persistent Storage: SQLite-backed model storage
• Batch Processing: Efficient batch inference

Advanced Features

• Model Versioning: Manage multiple model versions
• A/B Testing: Route comparison and testing
• Metrics: Performance and accuracy tracking
• Hot Reload: Update models without restart
• Distributed: Coordinate across instances

Installation

npm install @ruvector/tiny-dancer-node
# or
yarn add @ruvector/tiny-dancer-node
# or
pnpm add @ruvector/tiny-dancer-node

Quick Start

Basic Routing

import { TinyDancer, RouteRequest } from '@ruvector/tiny-dancer-node';

// Create router instance
const router = new TinyDancer({
  modelPath: './models/router.db',
});

// Initialize
await router.init();

// Route request
const result = await router.route({
  query: "What is the weather like today?",
  context: {
    userId: "user-123",
    sessionLength: 5,
  },
  agents: ["weather", "general", "calendar"],
});

console.log(`Route to: ${result.agent} (confidence: ${result.confidence})`);

Model Training

import { TinyDancer, TrainingData } from '@ruvector/tiny-dancer-node';

const router = new TinyDancer();
await router.init();

// Prepare training data
const trainingData: TrainingData[] = [
  {
    query: "What's the weather?",
    correctAgent: "weather",
    context: { category: "weather" },
  },
  {
    query: "Schedule a meeting",
    correctAgent: "calendar",
    context: { category: "scheduling" },
  },
  // ... more examples
];

// Train model
const result = await router.train({
  data: trainingData,
  epochs: 100,
  learningRate: 0.001,
  validationSplit: 0.2,
});

console.log(`Training accuracy: ${result.accuracy}`);
console.log(`Validation accuracy: ${result.validationAccuracy}`);

// Save model
await router.saveModel('./models/custom-router.bin');

Performance Monitoring

import { TinyDancer } from '@ruvector/tiny-dancer-node';

const router = new TinyDancer({ enableMetrics: true });
await router.init();

// Route with metrics
const result = await router.route(request);

// Get performance metrics
const metrics = router.getMetrics();
console.log(`Average latency: ${metrics.avgLatencyMs}ms`);
console.log(`P99 latency: ${metrics.p99LatencyMs}ms`);
console.log(`Requests/sec: ${metrics.requestsPerSecond}`);
console.log(`Cache hit rate: ${metrics.cacheHitRate}`);

API Reference

TinyDancer Class

class TinyDancer {
  constructor(config?: TinyDancerConfig);

  // Lifecycle
  init(): Promise<void>;
  close(): Promise<void>;

  // Routing
  route(request: RouteRequest): Promise<RouteResult>;
  routeBatch(requests: RouteRequest[]): Promise<RouteResult[]>;

  // Training
  train(options: TrainOptions): Promise<TrainResult>;
  loadModel(path: string): Promise<void>;
  saveModel(path: string): Promise<void>;

  // Scoring
  scoreAgents(request: RouteRequest): Promise<AgentScore[]>;

  // Metrics
  getMetrics(): RouterMetrics;
  resetMetrics(): void;
}

Types

interface TinyDancerConfig {
  modelPath?: string;
  enableMetrics?: boolean;
  cacheSize?: number;
  numThreads?: number;
}

interface RouteRequest {
  query: string;
  context?: Record<string, any>;
  agents: string[];
  constraints?: RouteConstraints;
}

interface RouteResult {
  agent: string;
  confidence: number;
  scores: Record<string, number>;
  latencyMs: number;
}

interface TrainOptions {
  data: TrainingData[];
  epochs: number;
  learningRate: number;
  validationSplit?: number;
  batchSize?: number;
}

interface TrainResult {
  accuracy: number;
  validationAccuracy: number;
  loss: number;
  epochs: number;
  trainingTimeMs: number;
}

interface RouterMetrics {
  totalRequests: number;
  avgLatencyMs: number;
  p50LatencyMs: number;
  p99LatencyMs: number;
  requestsPerSecond: number;
  cacheHitRate: number;
}

Express Integration

import express from 'express';
import { TinyDancer } from '@ruvector/tiny-dancer-node';

const app = express();
const router = new TinyDancer();

app.use(express.json());

app.post('/route', async (req, res) => {
  const result = await router.route({
    query: req.body.query,
    context: req.body.context,
    agents: ['agent-a', 'agent-b', 'agent-c'],
  });

  res.json(result);
});

app.listen(3000);

Platform Support

Building from Source

# Clone repository
git clone https://github.com/ruvnet/ruvector.git
cd ruvector/crates/ruvector-tiny-dancer-node

# Install dependencies
npm install

# Build native module
npm run build

# Run tests
npm test

Related Packages

• ruvector-tiny-dancer-core - Core Rust implementation
• ruvector-tiny-dancer-wasm - WebAssembly bindings
• @ruvector/core - Core vector bindings

Documentation

• Main README - Complete project overview
• API Documentation - Full API reference
• GitHub Repository - Source code

License

MIT License - see LICENSE for details.