Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'
This commit is contained in:
ruv
289
vendor/ruvector/crates/ruvector-tiny-dancer-node/README.md
vendored
Normal file
289
vendor/ruvector/crates/ruvector-tiny-dancer-node/README.md
vendored
Normal file
@@ -0,0 +1,289 @@
|
||||
# Ruvector Tiny Dancer Node
|
||||
|
||||
[](https://www.npmjs.com/package/@ruvector/tiny-dancer-node)
|
||||
[](https://crates.io/crates/ruvector-tiny-dancer-node)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
||||
**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](https://github.com/ruvnet/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
|
||||
|
||||
```bash
|
||||
npm install @ruvector/tiny-dancer-node
|
||||
# or
|
||||
yarn add @ruvector/tiny-dancer-node
|
||||
# or
|
||||
pnpm add @ruvector/tiny-dancer-node
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Routing
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
| Platform | Architecture | Status |
|
||||
|----------|-------------|--------|
|
||||
| Linux | x64 | ✅ |
|
||||
| Linux | arm64 | ✅ |
|
||||
| macOS | x64 | ✅ |
|
||||
| macOS | arm64 (M1/M2) | ✅ |
|
||||
| Windows | x64 | ✅ |
|
||||
|
||||
## Building from Source
|
||||
|
||||
```bash
|
||||
# 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](../ruvector-tiny-dancer-core/)** - Core Rust implementation
|
||||
- **[ruvector-tiny-dancer-wasm](../ruvector-tiny-dancer-wasm/)** - WebAssembly bindings
|
||||
- **[@ruvector/core](https://www.npmjs.com/package/@ruvector/core)** - Core vector bindings
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Main README](../../README.md)** - Complete project overview
|
||||
- **[API Documentation](https://docs.rs/ruvector-tiny-dancer-node)** - Full API reference
|
||||
- **[GitHub Repository](https://github.com/ruvnet/ruvector)** - Source code
|
||||
|
||||
## License
|
||||
|
||||
**MIT License** - see [LICENSE](../../LICENSE) for details.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**Part of [Ruvector](https://github.com/ruvnet/ruvector) - Built by [rUv](https://ruv.io)**
|
||||
|
||||
[](https://github.com/ruvnet/ruvector)
|
||||
|
||||
[Documentation](https://docs.rs/ruvector-tiny-dancer-node) | [npm](https://www.npmjs.com/package/@ruvector/tiny-dancer-node) | [GitHub](https://github.com/ruvnet/ruvector)
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user