dearsky/wifi-densepose
1
0
Fork 0
Code Issues 20 Pull Requests 5 Actions Packages Projects Releases 1 Wiki Activity

Squashed 'vendor/ruvector/' content from commit b64c2172

Browse Source 
git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
This commit is contained in:
ruv
2026-02-28 14:39:40 -05:00
commit d803bfe2b1
7854 changed files with 3522914 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
npm/packages/tiny-dancer/README.md Normal file
View File

@@ -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

138
npm/packages/tiny-dancer/index.d.ts vendored Normal file
View File

@@ -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;

55
npm/packages/tiny-dancer/index.js Normal file
View File

@@ -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();

63
npm/packages/tiny-dancer/package.json Normal file
View File

@@ -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"
]
}

32
npm/packages/tiny-dancer/test.js Normal file
View File

@@ -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!');