Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
2026-02-28 14:39:40 -05:00
commit d803bfe2b1
7854 changed files with 3522914 additions and 0 deletions
--- a/crates/ruvector-postgres/docs/ROUTING_QUICK_REFERENCE.md
+++ b/crates/ruvector-postgres/docs/ROUTING_QUICK_REFERENCE.md
@@ -0,0 +1,396 @@
+# Tiny Dancer Routing - Quick Reference
+
+## One-Minute Setup
+
+```sql
+-- Register your first agent
+SELECT ruvector_register_agent(
+    'gpt-4',                    -- name
+    'llm',                      -- type
+    ARRAY['coding'],            -- capabilities
+    0.03,                       -- cost per request
+    500.0,                      -- latency (ms)
+    0.95                        -- quality (0-1)
+);
+
+-- Route a request
+SELECT ruvector_route(
+    embedding_vector,           -- your 384-dim embedding
+    'balanced',                 -- optimize for: cost|latency|quality|balanced
+    NULL                        -- constraints (optional)
+);
+```
+
+## Common Commands
+
+### Register Agents
+
+```sql
+-- Simple registration
+SELECT ruvector_register_agent(name, type, capabilities, cost, latency, quality);
+
+-- Full configuration
+SELECT ruvector_register_agent_full('{
+    "name": "claude-3",
+    "agent_type": "llm",
+    "capabilities": ["coding", "writing"],
+    "cost_model": {"per_request": 0.025},
+    "performance": {"avg_latency_ms": 400, "quality_score": 0.93}
+}'::jsonb);
+```
+
+### Route Requests
+
+```sql
+-- Cost-optimized
+SELECT ruvector_route(emb, 'cost', NULL);
+
+-- Quality-optimized
+SELECT ruvector_route(emb, 'quality', NULL);
+
+-- Latency-optimized
+SELECT ruvector_route(emb, 'latency', NULL);
+
+-- Balanced (default)
+SELECT ruvector_route(emb, 'balanced', NULL);
+```
+
+### Add Constraints
+
+```sql
+-- Max cost
+SELECT ruvector_route(emb, 'quality', '{"max_cost": 0.01}'::jsonb);
+
+-- Max latency
+SELECT ruvector_route(emb, 'balanced', '{"max_latency_ms": 500}'::jsonb);
+
+-- Min quality
+SELECT ruvector_route(emb, 'cost', '{"min_quality": 0.8}'::jsonb);
+
+-- Required capability
+SELECT ruvector_route(emb, 'balanced',
+    '{"required_capabilities": ["coding"]}'::jsonb);
+
+-- Multiple constraints
+SELECT ruvector_route(emb, 'balanced', '{
+    "max_cost": 0.05,
+    "max_latency_ms": 1000,
+    "min_quality": 0.85,
+    "required_capabilities": ["coding", "analysis"],
+    "excluded_agents": ["slow-agent"]
+}'::jsonb);
+```
+
+### Manage Agents
+
+```sql
+-- List all
+SELECT * FROM ruvector_list_agents();
+
+-- Get specific agent
+SELECT ruvector_get_agent('gpt-4');
+
+-- Find by capability
+SELECT * FROM ruvector_find_agents_by_capability('coding', 5);
+
+-- Update metrics
+SELECT ruvector_update_agent_metrics('gpt-4', 450.0, true, 0.92);
+
+-- Deactivate
+SELECT ruvector_set_agent_active('gpt-4', false);
+
+-- Remove
+SELECT ruvector_remove_agent('old-agent');
+
+-- Statistics
+SELECT ruvector_routing_stats();
+```
+
+## Response Format
+
+```json
+{
+  "agent_name": "gpt-4",
+  "confidence": 0.87,
+  "estimated_cost": 0.03,
+  "estimated_latency_ms": 500.0,
+  "expected_quality": 0.95,
+  "similarity_score": 0.82,
+  "reasoning": "Selected gpt-4 for highest quality...",
+  "alternatives": [
+    {
+      "name": "claude-3",
+      "score": 0.85,
+      "reason": "0.02 lower quality"
+    }
+  ]
+}
+```
+
+## Extract Specific Fields
+
+```sql
+-- Get agent name
+SELECT (ruvector_route(emb, 'balanced', NULL))::jsonb->>'agent_name';
+
+-- Get cost
+SELECT (ruvector_route(emb, 'cost', NULL))::jsonb->>'estimated_cost';
+
+-- Get full decision
+SELECT
+    (route)::jsonb->>'agent_name' AS agent,
+    ((route)::jsonb->>'confidence')::float AS confidence,
+    ((route)::jsonb->>'estimated_cost')::float AS cost
+FROM (
+    SELECT ruvector_route(emb, 'balanced', NULL) AS route
+    FROM requests WHERE id = 1
+) r;
+```
+
+## Common Patterns
+
+### Smart Routing by Priority
+
+```sql
+SELECT ruvector_route(
+    embedding,
+    CASE priority
+        WHEN 'critical' THEN 'quality'
+        WHEN 'low' THEN 'cost'
+        ELSE 'balanced'
+    END,
+    CASE priority
+        WHEN 'critical' THEN '{"min_quality": 0.95}'::jsonb
+        ELSE NULL
+    END
+) FROM requests;
+```
+
+### Batch Processing
+
+```sql
+SELECT
+    id,
+    (ruvector_route(embedding, 'cost', '{"max_cost": 0.01}'::jsonb))::jsonb->>'agent_name' AS agent
+FROM requests
+WHERE processed = false
+LIMIT 1000;
+```
+
+### With Capability Filter
+
+```sql
+SELECT ruvector_route(
+    embedding,
+    'quality',
+    jsonb_build_object(
+        'required_capabilities',
+        CASE task_type
+            WHEN 'coding' THEN ARRAY['coding']
+            WHEN 'writing' THEN ARRAY['writing']
+            ELSE ARRAY[]::text[]
+        END
+    )
+) FROM requests;
+```
+
+### Cost Tracking
+
+```sql
+-- Daily costs
+SELECT
+    DATE(completed_at),
+    agent_name,
+    COUNT(*) AS requests,
+    SUM(cost) AS total_cost
+FROM request_completions
+GROUP BY 1, 2
+ORDER BY 1 DESC, total_cost DESC;
+```
+
+## Agent Types
+
+- `llm` - Language models
+- `embedding` - Embedding models
+- `specialized` - Task-specific
+- `vision` - Vision models
+- `audio` - Audio models
+- `multimodal` - Multi-modal
+- `custom` - User-defined
+
+## Optimization Targets
+
+| Target | Optimizes | Use Case |
+|--------|-----------|----------|
+| `cost` | Minimize cost | High-volume, budget-constrained |
+| `latency` | Minimize response time | Real-time applications |
+| `quality` | Maximize quality | Critical tasks |
+| `balanced` | Balance all factors | General purpose |
+
+## Constraints Reference
+
+| Constraint | Type | Description |
+|------------|------|-------------|
+| `max_cost` | float | Maximum cost per request |
+| `max_latency_ms` | float | Maximum latency in ms |
+| `min_quality` | float | Minimum quality (0-1) |
+| `required_capabilities` | array | Required capabilities |
+| `excluded_agents` | array | Agents to exclude |
+
+## Performance Metrics
+
+| Metric | Description | Updated By |
+|--------|-------------|------------|
+| `avg_latency_ms` | Average response time | `update_agent_metrics` |
+| `quality_score` | Quality rating (0-1) | `update_agent_metrics` |
+| `success_rate` | Success ratio (0-1) | `update_agent_metrics` |
+| `total_requests` | Total processed | Auto-incremented |
+| `p95_latency_ms` | 95th percentile | Auto-calculated |
+| `p99_latency_ms` | 99th percentile | Auto-calculated |
+
+## Troubleshooting
+
+### No agents match constraints
+
+```sql
+-- Check available agents
+SELECT * FROM ruvector_list_agents() WHERE is_active = true;
+
+-- Relax constraints
+SELECT ruvector_route(emb, 'balanced', '{"max_cost": 1.0}'::jsonb);
+```
+
+### Unexpected routing decisions
+
+```sql
+-- Check reasoning
+SELECT (ruvector_route(emb, 'balanced', NULL))::jsonb->>'reasoning';
+
+-- View alternatives
+SELECT (ruvector_route(emb, 'balanced', NULL))::jsonb->'alternatives';
+```
+
+### Agent not appearing
+
+```sql
+-- Verify registration
+SELECT ruvector_get_agent('agent-name');
+
+-- Check active status
+SELECT is_active FROM ruvector_list_agents() WHERE name = 'agent-name';
+
+-- Reactivate
+SELECT ruvector_set_agent_active('agent-name', true);
+```
+
+## Best Practices
+
+1. **Always set constraints in production**
+   ```sql
+   SELECT ruvector_route(emb, 'balanced', '{"max_cost": 0.1}'::jsonb);
+   ```
+
+2. **Update metrics after each request**
+   ```sql
+   SELECT ruvector_update_agent_metrics(agent, latency, success, quality);
+   ```
+
+3. **Monitor agent health**
+   ```sql
+   SELECT * FROM ruvector_list_agents()
+   WHERE success_rate < 0.9 OR avg_latency_ms > 1000;
+   ```
+
+4. **Use capability filters**
+   ```sql
+   SELECT ruvector_route(emb, 'quality',
+       '{"required_capabilities": ["coding"]}'::jsonb);
+   ```
+
+5. **Track costs**
+   ```sql
+   SELECT SUM(cost) FROM request_completions
+   WHERE completed_at > NOW() - INTERVAL '1 day';
+   ```
+
+## Examples by Use Case
+
+### High-Volume Processing (Cost-Optimized)
+```sql
+SELECT ruvector_route(emb, 'cost', '{"max_cost": 0.005}'::jsonb);
+```
+
+### Real-Time Chat (Latency-Optimized)
+```sql
+SELECT ruvector_route(emb, 'latency', '{"max_latency_ms": 200}'::jsonb);
+```
+
+### Critical Analysis (Quality-Optimized)
+```sql
+SELECT ruvector_route(emb, 'quality', '{"min_quality": 0.95}'::jsonb);
+```
+
+### Production Workload (Balanced)
+```sql
+SELECT ruvector_route(emb, 'balanced', '{
+    "max_cost": 0.05,
+    "max_latency_ms": 1000,
+    "min_quality": 0.85
+}'::jsonb);
+```
+
+### Code Generation
+```sql
+SELECT ruvector_route(emb, 'quality',
+    '{"required_capabilities": ["coding", "debugging"]}'::jsonb);
+```
+
+## Quick Debugging
+
+```sql
+-- Check if routing is working
+SELECT ruvector_routing_stats();
+
+-- List active agents
+SELECT name, capabilities FROM ruvector_list_agents() WHERE is_active;
+
+-- Test simple route
+SELECT ruvector_route(ARRAY[0.1]::float4[] || ARRAY(SELECT 0::float4 FROM generate_series(1,383)), 'balanced', NULL);
+
+-- View agent details
+SELECT jsonb_pretty(ruvector_get_agent('gpt-4'));
+
+-- Clear and restart (testing only)
+-- SELECT ruvector_clear_agents();
+```
+
+## Integration Example
+
+```sql
+-- Complete workflow
+CREATE TABLE my_requests (
+    id SERIAL PRIMARY KEY,
+    query TEXT,
+    embedding vector(384)
+);
+
+-- Route and execute
+WITH routing AS (
+    SELECT
+        r.id,
+        r.query,
+        (ruvector_route(
+            r.embedding::float4[],
+            'balanced',
+            '{"max_cost": 0.05}'::jsonb
+        ))::jsonb AS decision
+    FROM my_requests r
+    WHERE id = 1
+)
+SELECT
+    id,
+    decision->>'agent_name' AS agent,
+    decision->>'reasoning' AS why,
+    ((decision->>'confidence')::float * 100)::int AS confidence_pct
+FROM routing;
+```