ruvector/crates/ruvector-postgres/docs/ROUTING_QUICK_REFERENCE.md

Tiny Dancer Routing - Quick Reference

One-Minute Setup

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

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

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

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

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

{
  "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

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

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

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

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

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

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

-- Check reasoning
SELECT (ruvector_route(emb, 'balanced', NULL))::jsonb->>'reasoning';

-- View alternatives
SELECT (ruvector_route(emb, 'balanced', NULL))::jsonb->'alternatives';

Agent not appearing

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

   SELECT ruvector_route(emb, 'balanced', '{"max_cost": 0.1}'::jsonb);
   

2. Update metrics after each request

   SELECT ruvector_update_agent_metrics(agent, latency, success, quality);
   

3. Monitor agent health

   SELECT * FROM ruvector_list_agents()
   WHERE success_rate < 0.9 OR avg_latency_ms > 1000;
   

4. Use capability filters

   SELECT ruvector_route(emb, 'quality',
       '{"required_capabilities": ["coding"]}'::jsonb);
   

5. Track costs

   SELECT SUM(cost) FROM request_completions
   WHERE completed_at > NOW() - INTERVAL '1 day';
   

Examples by Use Case

High-Volume Processing (Cost-Optimized)

SELECT ruvector_route(emb, 'cost', '{"max_cost": 0.005}'::jsonb);

Real-Time Chat (Latency-Optimized)

SELECT ruvector_route(emb, 'latency', '{"max_latency_ms": 200}'::jsonb);

Critical Analysis (Quality-Optimized)

SELECT ruvector_route(emb, 'quality', '{"min_quality": 0.95}'::jsonb);

Production Workload (Balanced)

SELECT ruvector_route(emb, 'balanced', '{
    "max_cost": 0.05,
    "max_latency_ms": 1000,
    "min_quality": 0.85
}'::jsonb);

Code Generation

SELECT ruvector_route(emb, 'quality',
    '{"required_capabilities": ["coding", "debugging"]}'::jsonb);

Quick Debugging

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

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