Agent Router v2

Narrow before you search. Every tool has its own universe.

The v1 router ran vector similarity over the entire 12,000-node graph for every query. That's why "Find CTOs" returned a VC firm. Vector search has no concept of what kind of thing you're looking for.

v2 attaches a label-based cluster filter to every tool. The filter runs before the vector search, so cosine similarity only ever scores candidates of the right type.

The filter is cheap (single Cypher pass over :Label indexes, <30ms on current graph size). Every agent response now includes cluster.filter, cluster.candidate_pool, and cluster.strategy so downstream UI and QA know what universe was searched.

Vector similarity is one signal, not the only signal.

v1 collapsed all ranking into 1 - cosine_distance. That's fine for "which string looks like this string." It's useless for "which person should I actually talk to."

v2 scores every candidate row on four orthogonal dimensions, weights them by tool profile, and sums to a composite_score. The full breakdown lands on the row so the synth LLM (and any downstream consumer) can inspect the reasoning.

The four dimensions

Weight profiles (table: ranker_weights)

Profiles are DB-driven. Edit a row, the ranker picks up the new weights on the next request (no redeploy). This is how we'll tune based on feedback.

Worked example — Adar Arnon (composite 0.945)

rank_breakdown: {
  relevance:    0.900,   // close cosine match to "CTO AI"
  authority:    1.000,   // title matches C-Suite pattern
  recency:      0.500,   // stub
  connectivity: 1.000    // >10 edges (investors + co-workers)
}
weights (find_talent profile):
  rel=0.30, auth=0.35, rec=0.05, conn=0.30

composite = 0.30*0.900 + 0.35*1.000 + 0.05*0.500 + 0.30*1.000
          = 0.270 + 0.350 + 0.025 + 0.300
          = 0.945

Contrast Eric Iverson at 0.735: same authority (1.0), lower relevance (0.6), lower connectivity (0.7). The decomposition tells you why a row ranked where it did. That's the hook that makes feedback meaningful — when a user thumbs-down, we know which dimension was wrong and can adjust the weight profile for that tool.

Every decision the agent makes is now a database row.

The ranker is only useful if we can close the loop. v2 ships the full ledger: every query writes a trace, every thumbs-up/down attaches to that trace, and a reader endpoint gives you the whole story back by ID.

The three tables

The three endpoints

# 1. Run a query
curl -X POST https://xh2o-yths-38lt.n7c.xano.io/api:LITebdJ-/robert-lab/agent \
  -H "Content-Type: application/json" \
  -d '{"task":"Find me a CTO at an AI startup"}'
# → {trace_id: "a7c3...", ranked_rows: [...], cluster: {...}}

# 2. Thumbs-up on Adar Arnon
curl -X POST https://xh2o-yths-38lt.n7c.xano.io/api:LITebdJ-/robert-lab/feedback \
  -H "Content-Type: application/json" \
  -d '{"trace_id":"a7c3...","rating":1,"notes":"exactly right"}'

# 3. Read the trace back (audit / RL feed)
curl "https://xh2o-yths-38lt.n7c.xano.io/api:LITebdJ-/robert-lab/trace?trace_id=a7c3..."
# → {trace: {...}, feedback: [{rating:1, notes:"exactly right"}, ...]}

Why this matters: the feedback data is structured. Each thumbs-down carries its rank_breakdown — we can see that a bad row scored high on authority but the user disagreed, then nudge the authority weight down for that tool profile. That's the "RL-ready" part. No ML pipeline needed on day one — just a nightly aggregation job that pushes new weights into ranker_weights.

The response schema got a lot more honest.

v1 returned a bare list of rows. You had to trust that the ranking was sensible because you couldn't see anything about how the rows got picked. v2 returns the audit trail inline.

{
  "result": {
    "summary": "...",
    "findings": [
      { "name": "Good Company VC",
        "score": 0.812 },
      { "name": "Sequoia Capital",
        "score": 0.798 },
      { "name": "AI investing",
        "score": 0.774 }
    ]
  }
}

{
  "trace_id": "a7c3-...",
  "tool_used": "find_talent",
  "cluster": {
    "filter": "Person ∧ C-Suite",
    "candidate_pool": 1760,
    "strategy": "label_prefilter"
  },
  "ranker_weights": {
    "profile": "find_talent",
    "relevance": 0.30,
    "authority": 0.35,
    "recency":   0.05,
    "connectivity": 0.30
  },
  "ranked_rows": [
    { "name": "Adar Arnon",
      "composite_score": 0.945,
      "rank_breakdown": {
        "relevance": 0.90,
        "authority": 1.00,
        "recency":   0.50,
        "connectivity": 1.00
      }
    },
    { "name": "Adam Brown",
      "composite_score": 0.855,
      "rank_breakdown": {...} }
    /* ...ordered by composite desc */
  ],
  "latency_ms": 1872
}

Every downstream consumer — the copilot UI, QA scripts, the feedback loop, future RL — reads the same structured trace. No more guessing why a row ranked where it did.

The v1 router fails the second you ask something real

These are live responses from the v1 endpoint, Apr 16 afternoon. Every probe is a reasonable question a user in the Orbiter UI would type. Every one surfaces a category error.

The diagnosis in one sentence

Left: one-stage pipeline — query collapses straight into vector similarity over every node, output is whatever happens to be close in embedding space.
Right: four-stage pipeline — label & edge filters narrow the candidate set before vector search runs, ranker fuses multiple signals.

8,000+ contacts. Top-300 suggestion cutoff. Something has to give.

Mark's been saying this for weeks in different words: "you can't take 8,000 people and return 300 suggestions". The cost isn't just compute — the cost is relevance collapse. Vector search over 8,000 nodes for a Series-A-founder query returns noise, because everything vaguely related to "founder" or "series A" is in the neighborhood.

Label-based pre-filter: instead of vector-searching 8,000 dim-lit nodes, the router runs a structural Cypher filter first (label, edge type, time window), and vector search runs only over the ~150 nodes that actually qualify. The ontology Mark expanded (14 indexes, new c_suite label) is the fuel for this stage.

Mark already built the hard part. The graph has labels for c_suite, VC_Firm, Funding_Round, SubDomainExpertise, and more. There are 14 indexes. None of them are used by v1's graph_query tool — it always calls db.idx.vector.queryNodes with no structural WHERE clause. We're vector-searching through a universe we could have filtered to 2% of its size with one Cypher pattern.

Five stages, not three. The two new ones do the heavy lifting.

Left to right: intent classification → label/edge pre-filter (the "cluster" stage) → vector search over the narrowed candidate set → multi-factor ranker → synthesis with drafted artifacts. v1 only has stages 1, 3, and 5.

Not reinforcement learning yet. The instrumentation that makes it possible.

The loop: results surface to user → thumbs-up/down/notes on specific recommendations → written to agent_feedback keyed by trace_id → periodic offline job fits ranker weights (relevance / authority / recency / connectivity) to maximize approval rate → new weights go live on next query. Same pattern as the content engine's stage_traces + quality_scores + user_feedback + pipeline/revise system Robert shipped in March.

Mark flagged this directly: "I thought we were setting ourselves up for reinforcement learning basically to figure out what does lead to the best results." He's right that v1 isn't set up for it. The honest answer: we don't need RL yet. We need the data RL would eat.

Proposed tables (mirrors the content-engine pattern)

Endpoints to add

The one thing v1 got right — and why v2 keeps it

The investor → company relationship in Orbiter's graph is indirect. You traverse through a Funding_Round node. A naive kNN on "investor" returns Funding_Round names. Multi-hop retrieves the actual Company — and bouncing back through the round gives you co-investors for warm-path intros.

MATCH (seed)
OPTIONAL MATCH (seed)-[:INVESTED_IN|LEAD_INVESTED_IN]->(fr:Funding_Round)
OPTIONAL MATCH (fr)<-[:RAISED]-(company:Company)
OPTIONAL MATCH (fr)<-[:INVESTED_IN]-(co:VC_Firm|Person)  WHERE co <> seed
RETURN seed.name,
       collect(DISTINCT {company: company.name, round: fr.series}) AS portfolio,
       collect(DISTINCT co.name)[..5] AS co_investors

This pattern survives v2 — the cluster stage just decides what seed is allowed to be (a VC_Firm with ≥ 1 deal in the target sector, not "any node close in embedding space").

Honest inventory of what's built, what's next

Small, shippable, in order

1. Walk the 4 failing probes live. Confirm the diagnosis in his words, not mine. Five minutes. If he disagrees, stop.
2. Review the 14 indexes + c_suite label. Have Mark show which labels map to which tool's pre-filter. This is the 30-minute discussion that unblocks the cluster stage.
3. Decide ranker weight defaults, per tool. For find_investors, recency of deals probably dominates. For find_talent, authority + warm-path. Get his first-pass intuitions on paper — those become the initial weights.
4. Commit to the trace + feedback tables. Lift the content-engine schema. Robert builds the two endpoints (/agent/feedback, /agent/trace/:id) Friday morning.
5. Install Snappy MCP for Mark. So he can iterate on the tool prompts + pre-filter Cypher himself without going through Robert.
6. LSI dog food. Re-run the 2,000 medical-tech attendees through v2 once cluster stage is live. Compare recall/precision vs v1. This is the honest number that tells us if we moved.

Every stage is visible. Every score is visible. Every call gets a trace ID.

orbiter-agent-demo.pages.dev — paste a query (or click one of the seeded examples), watch each stage light up in order. The demo exposes the bits that v1's response didn't: intent + confidence, cluster Cypher + node count, vector hits with raw cosine, ranker score breakdown, synthesized output. Thumbs-up/down buttons are live — they write to a local log today, swap to /agent/feedback the moment that endpoint exists.

Saved for Mark + future Robert

• Groq wraps JSON in markdown fences. Always |replace:"```json":"" |replace:"```":"" |trim before |json_decode.
• Runtime json_decode failures surface with the same message as compile-time syntax errors ("Error parsing JSON: Syntax error"). Deceiving.
• elseif / else must be on their own line after the closing } of the previous branch, not same-line.
• util.template_engine + {{$var.name}} silently stringifies objects as [object Object]. Use |json_encode + |concat chain instead.
• FalkorDB vector search requires vecf32() wrapper — production semantic-question was broken until Robert wrapped the embedding in vecf32().
• $output. (trailing dot) in a response block is a XanoScript syntax error — must use explicit field references.