Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/npm/packages/tiny-dancer/README.md

@@ -0,0 +1,209 @@
+# @ruvector/tiny-dancer
+
+Neural router for AI agent orchestration - FastGRNN-based intelligent routing with circuit breaker, uncertainty estimation, and hot-reload.
+
+## Features
+
+- **FastGRNN Neural Routing**: Efficient gated recurrent network for fast inference
+- **Uncertainty Estimation**: Know when the router is confident vs. uncertain
+- **Circuit Breaker**: Automatic fallback when routing fails repeatedly
+- **Hot-Reload**: Update models without restarting the application
+- **SIMD Optimized**: Native Rust performance with SIMD acceleration
+- **Multi-Platform**: Works on Linux, macOS, and Windows
+
+## Installation
+
+```bash
+npm install @ruvector/tiny-dancer
+```
+
+The package automatically installs the correct native binary for your platform.
+
+## Quick Start
+
+```typescript
+import { Router } from '@ruvector/tiny-dancer';
+
+// Create router with configuration
+const router = new Router({
+  modelPath: './models/fastgrnn.safetensors',
+  confidenceThreshold: 0.85,
+  maxUncertainty: 0.15,
+  enableCircuitBreaker: true,
+  circuitBreakerThreshold: 5
+});
+
+// Route a query to the best candidate
+const response = await router.route({
+  queryEmbedding: new Float32Array([0.1, 0.2, 0.3, ...]),
+  candidates: [
+    { id: 'gpt-4', embedding: new Float32Array([...]), successRate: 0.95 },
+    { id: 'claude-3', embedding: new Float32Array([...]), successRate: 0.92 },
+    { id: 'gemini', embedding: new Float32Array([...]), successRate: 0.88 }
+  ]
+});
+
+// Get the best routing decision
+const best = response.decisions[0];
+console.log(`Route to: ${best.candidateId}`);
+console.log(`Confidence: ${best.confidence}`);
+console.log(`Use lightweight: ${best.useLightweight}`);
+console.log(`Inference time: ${response.inferenceTimeUs}μs`);
+```
+
+## API Reference
+
+### `Router`
+
+Main class for neural routing.
+
+#### Constructor
+
+```typescript
+new Router(config: RouterConfig)
+```
+
+**RouterConfig:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `modelPath` | string | required | Path to FastGRNN model file |
+| `confidenceThreshold` | number | 0.85 | Minimum confidence for routing |
+| `maxUncertainty` | number | 0.15 | Maximum uncertainty allowed |
+| `enableCircuitBreaker` | boolean | true | Enable fault tolerance |
+| `circuitBreakerThreshold` | number | 5 | Failures before circuit opens |
+| `enableQuantization` | boolean | true | Enable memory-efficient quantization |
+| `databasePath` | string | undefined | Optional persistence path |
+
+#### Methods
+
+##### `route(request: RoutingRequest): Promise<RoutingResponse>`
+
+Route a query to the best candidate.
+
+```typescript
+const response = await router.route({
+  queryEmbedding: new Float32Array([...]),
+  candidates: [{ id: 'model-1', embedding: new Float32Array([...]) }],
+  metadata: '{"context": "user-query"}'
+});
+```
+
+##### `reloadModel(): Promise<void>`
+
+Hot-reload the model from disk.
+
+```typescript
+await router.reloadModel();
+```
+
+##### `circuitBreakerStatus(): boolean | null`
+
+Check if the circuit breaker is closed (healthy) or open (unhealthy).
+
+```typescript
+const isHealthy = router.circuitBreakerStatus();
+```
+
+### Types
+
+#### `Candidate`
+
+```typescript
+interface Candidate {
+  id: string;                    // Unique identifier
+  embedding: Float32Array;       // Vector embedding
+  metadata?: string;             // JSON metadata
+  createdAt?: number;            // Timestamp
+  accessCount?: number;          // Usage count
+  successRate?: number;          // Historical success (0-1)
+}
+```
+
+#### `RoutingDecision`
+
+```typescript
+interface RoutingDecision {
+  candidateId: string;           // Which candidate to use
+  confidence: number;            // Confidence score (0-1)
+  useLightweight: boolean;       // Use fast/lightweight model
+  uncertainty: number;           // Uncertainty estimate (0-1)
+}
+```
+
+#### `RoutingResponse`
+
+```typescript
+interface RoutingResponse {
+  decisions: RoutingDecision[];  // Ranked decisions
+  inferenceTimeUs: number;       // Inference time (μs)
+  candidatesProcessed: number;   // Number processed
+  featureTimeUs: number;         // Feature engineering time (μs)
+}
+```
+
+## Use Cases
+
+### LLM Model Routing
+
+Route queries to the most appropriate language model:
+
+```typescript
+const router = new Router({ modelPath: './models/llm-router.safetensors' });
+
+const response = await router.route({
+  queryEmbedding: await embedQuery("Explain quantum computing"),
+  candidates: [
+    { id: 'gpt-4', embedding: gpt4Embedding, successRate: 0.95 },
+    { id: 'gpt-3.5-turbo', embedding: gpt35Embedding, successRate: 0.85 },
+    { id: 'claude-instant', embedding: claudeInstantEmbedding, successRate: 0.88 }
+  ]
+});
+
+// Use lightweight model for simple queries
+if (response.decisions[0].useLightweight) {
+  return callModel('gpt-3.5-turbo', query);
+} else {
+  return callModel(response.decisions[0].candidateId, query);
+}
+```
+
+### Agent Orchestration
+
+Route tasks to specialized AI agents:
+
+```typescript
+const agents = [
+  { id: 'code-agent', embedding: codeEmbedding, successRate: 0.92 },
+  { id: 'research-agent', embedding: researchEmbedding, successRate: 0.89 },
+  { id: 'creative-agent', embedding: creativeEmbedding, successRate: 0.91 }
+];
+
+const best = (await router.route({ queryEmbedding, candidates: agents })).decisions[0];
+await agents[best.candidateId].execute(task);
+```
+
+## Platform Support
+
+| Platform | Architecture | Package |
+|----------|--------------|---------|
+| Linux | x64 | `@ruvector/tiny-dancer-linux-x64-gnu` |
+| Linux | ARM64 | `@ruvector/tiny-dancer-linux-arm64-gnu` |
+| macOS | x64 | `@ruvector/tiny-dancer-darwin-x64` |
+| macOS | ARM64 | `@ruvector/tiny-dancer-darwin-arm64` |
+| Windows | x64 | `@ruvector/tiny-dancer-win32-x64-msvc` |
+
+## Performance
+
+- **Inference**: < 100μs per routing decision
+- **Throughput**: 10,000+ routes/second
+- **Memory**: ~10MB base + model size
+
+## Related Packages
+
+- [`@ruvector/core`](https://www.npmjs.com/package/@ruvector/core) - Vector database
+- [`@ruvector/gnn`](https://www.npmjs.com/package/@ruvector/gnn) - Graph Neural Networks
+- [`@ruvector/graph-node`](https://www.npmjs.com/package/@ruvector/graph-node) - Hypergraph database
+
+## License
+
+MIT

vendor/ruvector/npm/packages/tiny-dancer/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Router configuration for Tiny Dancer neural routing
+ */
+export interface RouterConfig {
+  /** Path to the FastGRNN model file (safetensors format) */
+  modelPath: string;
+  /** Confidence threshold for routing decisions (0.0 to 1.0, default: 0.85) */
+  confidenceThreshold?: number;
+  /** Maximum uncertainty before falling back (0.0 to 1.0, default: 0.15) */
+  maxUncertainty?: number;
+  /** Enable circuit breaker for fault tolerance (default: true) */
+  enableCircuitBreaker?: boolean;
+  /** Number of failures before circuit opens (default: 5) */
+  circuitBreakerThreshold?: number;
+  /** Enable quantization for memory efficiency (default: true) */
+  enableQuantization?: boolean;
+  /** Optional database path for persistence */
+  databasePath?: string;
+}
+
+/**
+ * Candidate for routing evaluation
+ */
+export interface Candidate {
+  /** Unique identifier for the candidate */
+  id: string;
+  /** Embedding vector (Float32Array or number[]) */
+  embedding: Float32Array | number[];
+  /** Optional metadata as JSON string */
+  metadata?: string;
+  /** Creation timestamp (Unix epoch milliseconds) */
+  createdAt?: number;
+  /** Number of times this candidate was accessed */
+  accessCount?: number;
+  /** Historical success rate (0.0 to 1.0) */
+  successRate?: number;
+}
+
+/**
+ * Routing request containing query and candidates
+ */
+export interface RoutingRequest {
+  /** Query embedding to route */
+  queryEmbedding: Float32Array | number[];
+  /** Candidates to evaluate for routing */
+  candidates: Candidate[];
+  /** Optional request metadata as JSON string */
+  metadata?: string;
+}
+
+/**
+ * Individual routing decision for a candidate
+ */
+export interface RoutingDecision {
+  /** ID of the candidate */
+  candidateId: string;
+  /** Confidence score (0.0 to 1.0) */
+  confidence: number;
+  /** Whether to use lightweight/fast model */
+  useLightweight: boolean;
+  /** Uncertainty estimate (0.0 to 1.0) */
+  uncertainty: number;
+}
+
+/**
+ * Response from a routing operation
+ */
+export interface RoutingResponse {
+  /** Ranked routing decisions */
+  decisions: RoutingDecision[];
+  /** Total inference time in microseconds */
+  inferenceTimeUs: number;
+  /** Number of candidates processed */
+  candidatesProcessed: number;
+  /** Feature engineering time in microseconds */
+  featureTimeUs: number;
+}
+
+/**
+ * Tiny Dancer neural router for intelligent AI agent routing
+ *
+ * @example
+ * ```typescript
+ * import { Router } from '@ruvector/tiny-dancer';
+ *
+ * const router = new Router({
+ *   modelPath: './models/fastgrnn.safetensors',
+ *   confidenceThreshold: 0.85,
+ *   enableCircuitBreaker: true
+ * });
+ *
+ * const response = await router.route({
+ *   queryEmbedding: new Float32Array([0.1, 0.2, ...]),
+ *   candidates: [
+ *     { id: 'gpt4', embedding: new Float32Array([...]) },
+ *     { id: 'claude', embedding: new Float32Array([...]) }
+ *   ]
+ * });
+ *
+ * console.log('Best route:', response.decisions[0].candidateId);
+ * ```
+ */
+export class Router {
+  /**
+   * Create a new neural router
+   * @param config Router configuration
+   */
+  constructor(config: RouterConfig);
+
+  /**
+   * Route a request through the neural routing system
+   * @param request Routing request with query and candidates
+   * @returns Promise resolving to routing decisions
+   */
+  route(request: RoutingRequest): Promise<RoutingResponse>;
+
+  /**
+   * Hot-reload the model from disk
+   * @returns Promise resolving when reload is complete
+   */
+  reloadModel(): Promise<void>;
+
+  /**
+   * Check circuit breaker status
+   * @returns true if circuit is closed (healthy), false if open
+   */
+  circuitBreakerStatus(): boolean | null;
+}
+
+/**
+ * Get the version of the Tiny Dancer library
+ */
+export function version(): string;
+
+/**
+ * Test function to verify bindings are working
+ */
+export function hello(): string;

vendor/ruvector/npm/packages/tiny-dancer/index.js

@@ -0,0 +1,55 @@
+const { platform, arch } = process;
+const path = require('path');
+
+// Platform mapping for @ruvector/tiny-dancer
+const platformMap = {
+  'linux': {
+    'x64': { package: '@ruvector/tiny-dancer-linux-x64-gnu', file: 'ruvector-tiny-dancer.linux-x64-gnu.node' },
+    'arm64': { package: '@ruvector/tiny-dancer-linux-arm64-gnu', file: 'ruvector-tiny-dancer.linux-arm64-gnu.node' }
+  },
+  'darwin': {
+    'x64': { package: '@ruvector/tiny-dancer-darwin-x64', file: 'ruvector-tiny-dancer.darwin-x64.node' },
+    'arm64': { package: '@ruvector/tiny-dancer-darwin-arm64', file: 'ruvector-tiny-dancer.darwin-arm64.node' }
+  },
+  'win32': {
+    'x64': { package: '@ruvector/tiny-dancer-win32-x64-msvc', file: 'ruvector-tiny-dancer.win32-x64-msvc.node' }
+  }
+};
+
+function loadNativeModule() {
+  const platformInfo = platformMap[platform]?.[arch];
+
+  if (!platformInfo) {
+    throw new Error(
+      `Unsupported platform: ${platform}-${arch}\n` +
+      `@ruvector/tiny-dancer native module is available for:\n` +
+      `- Linux (x64, ARM64)\n` +
+      `- macOS (x64, ARM64)\n` +
+      `- Windows (x64)\n\n` +
+      `Install the package for your platform:\n` +
+      `  npm install @ruvector/tiny-dancer`
+    );
+  }
+
+  // Try local .node file first (for development and bundled packages)
+  try {
+    const localPath = path.join(__dirname, platformInfo.file);
+    return require(localPath);
+  } catch (localError) {
+    // Fall back to platform-specific package
+    try {
+      return require(platformInfo.package);
+    } catch (error) {
+      if (error.code === 'MODULE_NOT_FOUND') {
+        throw new Error(
+          `Native module not found for ${platform}-${arch}\n` +
+          `Please install: npm install ${platformInfo.package}\n` +
+          `Or reinstall @ruvector/tiny-dancer to get optional dependencies`
+        );
+      }
+      throw error;
+    }
+  }
+}
+
+module.exports = loadNativeModule();

vendor/ruvector/npm/packages/tiny-dancer/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@ruvector/tiny-dancer",
+  "version": "0.1.17",
+  "description": "Neural router for AI agent orchestration - FastGRNN-based intelligent routing with circuit breaker, uncertainty estimation, and hot-reload",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "author": "ruv.io Team <info@ruv.io> (https://ruv.io)",
+  "homepage": "https://ruv.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ruvnet/ruvector.git",
+    "directory": "npm/packages/tiny-dancer"
+  },
+  "bugs": {
+    "url": "https://github.com/ruvnet/ruvector/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build:napi": "napi build --platform --release --cargo-cwd ../../../crates/ruvector-tiny-dancer-node",
+    "test": "node test.js",
+    "publish:platforms": "node scripts/publish-platforms.js"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0"
+  },
+  "optionalDependencies": {
+    "@ruvector/tiny-dancer-linux-x64-gnu": "0.1.15",
+    "@ruvector/tiny-dancer-linux-arm64-gnu": "0.1.17",
+    "@ruvector/tiny-dancer-darwin-x64": "0.1.15",
+    "@ruvector/tiny-dancer-darwin-arm64": "0.1.15",
+    "@ruvector/tiny-dancer-win32-x64-msvc": "0.1.15"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "neural-router",
+    "ai-routing",
+    "agent-orchestration",
+    "fastgrnn",
+    "circuit-breaker",
+    "uncertainty-estimation",
+    "hot-reload",
+    "llm-routing",
+    "model-routing",
+    "native",
+    "napi",
+    "rust",
+    "simd",
+    "fast",
+    "performance",
+    "ruv",
+    "ruvector"
+  ]
+}

vendor/ruvector/npm/packages/tiny-dancer/test.js

@@ -0,0 +1,32 @@
+const tinyDancer = require('./index.js');
+
+console.log('Testing @ruvector/tiny-dancer...');
+
+// Test version function
+try {
+  const ver = tinyDancer.version();
+  console.log(`✓ version(): ${ver}`);
+} catch (e) {
+  console.error('✗ version() failed:', e.message);
+}
+
+// Test hello function
+try {
+  const msg = tinyDancer.hello();
+  console.log(`✓ hello(): ${msg}`);
+} catch (e) {
+  console.error('✗ hello() failed:', e.message);
+}
+
+// Test Router class exists
+try {
+  if (typeof tinyDancer.Router === 'function') {
+    console.log('✓ Router class available');
+  } else {
+    console.log('✗ Router class not found');
+  }
+} catch (e) {
+  console.error('✗ Router check failed:', e.message);
+}
+
+console.log('\nAll basic tests completed!');