ChromaDB Agent Router

Local semantic message routing for multi-agent systems. Routes messages to the correct agent based on embeddings + keyword + context scoring. No external API...

Security Scan

The skill's code and instructions mostly match its stated purpose (local routing with ChromaDB), but there are mismatches in declared installs/dependencies and a few implementation choices (disk cache, missing dependency declarations, bold accuracy claims) that don't add up and warrant caution.

Purpose & Capability

Name/description align with required runtime (python3 + chromadb + numpy). The code implements a local ChromaDB-based router and exposes a localhost REST API, which is coherent with the stated purpose. However, the SKILL.md's metadata lists only chromadb and numpy as Python deps while the API wrapper requires additional packages (starlette, uvicorn) that are not declared—this is an inconsistency.

Instruction Scope

Runtime instructions (start API, POST /route) and the included code stay within routing functionality. The skill does create a local REST endpoint and writes a ChromaDB persistent cache under /tmp/semantic_router_cache/, both of which are documented in SKILL.md. The code does not read environment variables or unrelated system files.

Install Mechanism

SKILL.md contains a pip install step for chromadb and numpy (reasonable). But router-api.py and runtime require starlette and uvicorn (and possibly other transitives) which are not declared in the install metadata—this mismatch can cause broken installs or surprise network installs at runtime. Installing PyPI packages is moderate risk but acceptable if the exact packages/versions are declared; here they are not.

Credentials

The skill requests no environment variables, no credentials, and does not access system configs beyond writing a cache directory under /tmp. That level of access is proportionate to a local embedding indexer.

Persistence & Privilege

The skill persistently stores embeddings to /tmp/semantic_router_cache/chromadb (documented). It runs a local HTTP server bound to 127.0.0.1 (not public). 'always' is false. Storing cache on disk and running a localhost API are reasonable for this purpose but users should be aware of on-disk persistence of embeddings and route data.

What to consider before installing

This skill appears to implement a local ChromaDB-based router and mostly matches its description, but proceed with caution. Before installing: 1) Note the SKILL.md only declares chromadb and numpy, yet the API needs starlette and uvicorn — verify and install the full dependency list in a virtualenv (or container) rather than system-wide. 2) The skill writes embeddings to /tmp/semantic_router_cache; decide whether persisting embeddings on-disk is acceptable for your environment. 3) The router runs a localhost HTTP server (bound to 127.0.0.1) — that's safer than binding publicly, but confirm you don't expose the port via proxy or firewall. 4) The README claims '100% accuracy' on a small benchmark — treat that as an unverified marketing claim and validate with your own test dataset. 5) If you plan to use this in production or with sensitive data, run it in an isolated environment (container/VM) and pin package versions from trusted sources. Install only the packages you audit, and review or test the EXAMPLE_ROUTES to ensure no unintended routing of sensitive queries.

Semantic Router — Local Agent Message Routing

Route messages to the correct agent in a multi-agent system using a 3-layer scoring architecture:

1. Embedding similarity (ChromaDB) — semantic understanding
2. Keyword scoring — exact domain matches
3. Action verb stratification — "deploy" always → ops, "secure" → security

Why This Exists

Most agent routers either:

• Call external APIs (latency, cost, privacy)
• Use simple keyword matching (inaccurate)
• Don't understand French/English bilingual queries

This router runs entirely locally in ~1.5ms per query with 100% accuracy.

Quick Start

1. Define Your Routes

Create a routes configuration file (JSON or Python dict):

ROUTES = {
    "ops": {
        "agent": "orion",
        "descriptions": [
            "Deploy and manage infrastructure and Docker containers",
            "Install, configure, and restart services",
            "DevOps operations, CI/CD, deployment pipelines",
        ],
        "keywords": ["deploy", "install", "docker", "compose", "container", "restart"],
        "action_verbs": ["déploie", "installe", "configure", "redémarre"],
    },
    "security": {
        "agent": "aegis",
        "descriptions": [
            "Security audits, vulnerability scanning, hardening",
            "Firewall rules, SSL certificates, access control",
        ],
        "keywords": ["security", "firewall", "ssl", "vulnerability"],
        "action_verbs": ["sécurise", "hardened"],
    },
    # ... add more routes
}

2. Initialize and Route

from semantic_router import SemanticRouter

router = SemanticRouter(routes_config="routes.json")
router.initialize()  # Builds ChromaDB index (~6s cold start, then cached)

result = router.route("Deploy the new monitoring stack on the homelab")
# → {"route": "ops", "agent": "orion", "confidence": 0.94}

3. Use in OpenClaw

# Start the API server
python3 scripts/router-api.py --port 8321

# Route a message
curl -X POST http://localhost:8321/route \
  -H "Content-Type: application/json" \
  -d '{"message": "Check the firewall logs for suspicious activity"}'

Architecture

Input Message
    │
    ├─► French Normalization (accent handling, verb mapping)
    │
    ├─► Layer 1: Embedding Similarity (ChromaDB)
    │   └─ cosine similarity against route descriptions
    │
    ├─► Layer 2: Keyword Scoring
    │   └─ exact/substring match with keyword-stealing avoidance
    │
    ├─► Layer 3: Action Verb Stratification
    │   └─ ops verbs → always override topic
    │   └─ topic verbs → override but route-specific
    │   └─ weak verbs → let embeddings decide
    │
    └─► Weighted Fusion → Route Selection

Scoring Formula

final_score = (0.4 × centroid_sim) + (0.3 × max_example_sim) + (0.3 × keyword_score) + action_boost

Where action_boost is additive for matched action verbs, allowing override of embedding scores.

Key Design Decisions

1. No external API — Everything runs locally via ChromaDB + default embeddings
2. Keyword stealing prevention — A keyword appears in exactly ONE route
3. French normalization before action detection — Normalize accents but detect verbs on original text
4. Cache to disk — Embeddings persist in /tmp/semantic_router_cache/
5. Action verb stratification — The breakthrough from 92.7% to 100%

API Endpoints

Endpoint	Method	Description
/route	POST	Route a single message
/batch	POST	Route multiple messages
/benchmark	POST	Run accuracy benchmark
/stats	GET	Usage statistics
/routes	GET	List configured routes
/health	GET	Health check

Performance

Metric	Value
Accuracy (benchmark)	100% (41/41 messages)
Query latency	~1.5ms (cached)
Cold start	~6s (embed routes)
Memory	~50MB
ARM64 compatible	✅ (tested on Raspberry Pi 5)

Use Cases

• Multi-agent orchestration — Route user messages to specialized agents
• Message bus routing — Front-load balancer for agent mesh networks
• Intent classification — Classify support tickets, requests, commands
• Bilingual routing — French/English queries handled natively

Files

semantic-router/
├── SKILL.md              ← This file
├── scripts/
│   ├── semantic_router.py    ← Core router library
│   └── router-api.py         ← REST API wrapper
└── references/
    └── ROUTING-RESEARCH.md   ← Design notes and benchmarks

License

MIT — Use freely, attribution appreciated.