Federation & Selector

RCP is point-to-point: one server answers for its own index. Querying all the engines you can reach is a client concern, layered on the core methods with zero new server obligations. There are two routing models, both drivable from a single rcp.json registry.

Model	Use it when	API
Selector	you have several backends and each query should hit exactly one — pick it by id, by required capability, or by priority with liveness fallback (lazy connect)	`Selector.load("rcp.json").select_capable(cap)`
Federation	you want to query all reachable engines concurrently and fuse the ranked lists with Reciprocal Rank Fusion (origin-tagged hits)	`Federation::from_registry_file("rcp.json")`

The registry — `rcp.json`

{
  "engines": [
    { "id": "docs", "transport": "stdio", "command": ["python3", "docs_server.py"], "priority": 10 },
    { "id": "web",  "transport": "http",  "url": "http://127.0.0.1:8000/rcp", "weight": 1.5 },
    { "id": "code", "transport": "stdio", "command": ["rcp-code-engine"], "required": false }
  ]
}

string

required

A client-local label used to tag fused hits by origin (meta.engine).

"stdio" | "http"

required

With command (stdio) or url (http).

integer

default:"0"

Higher wins for Selector’s primary → secondary fallback.

float

default:"1.0"

Scales the engine’s contribution during fusion.

boolean

default:"false"

If true, a connect/query failure fails the whole federated query instead of being skipped.

Discovery composes with the catalog capability: a registry entry can point at an aggregator that enumerates further engines via catalog/list.

Selector — pick one of many

When you have several backends but each query should hit exactly one, a Selector chooses it for you from the rcp.json registry. It connects lazily — listing ten candidates opens zero connections until you call a select_* method, and then only to the winner. There are three selection policies:

Method	Picks	On failure
`select(id)`	the one engine with that id	returns an error naming the unknown id
`select_primary()`	the highest-priority engine that answers	walks down the priority order to the next live engine
`select_capable(cap)`	the highest-priority live engine that advertises `cap`	skips engines that answer but lack the capability, and dead ones, until one qualifies

Both select_primary and select_capable give you priority + liveness fallback for free: a multi-backend deployment stays up when a backend dies, without the client writing any failover glue. priority in the registry (higher wins) sets the order they’re tried.

sel = rcp.Selector.load("rcp.json")

c = sel.select("docs")                            # a specific engine by id
c = sel.select_primary()                          # highest-priority live engine
c = sel.select_capable(rcp.Capability.Retrieve)   # highest-priority live engine that can retrieve

for h in c.retrieve("query", k=5):
    print(h["id"], h["score"])

const sel = rcp.Selector.load("rcp.json");

const c1 = await sel.select("docs");                            // by id
const c2 = await sel.selectPrimary();                          // highest-priority live
const c3 = await sel.selectCapable(rcp.Capability.Retrieve);   // highest-priority live + can retrieve

for (const h of await c3.retrieve("query", 5)) console.log(h.id, h.score);

let sel = rcp::Selector::load("rcp.json")?;

let c = sel.select("docs")?;                          // by id
let c = sel.select_primary()?;                        // highest-priority live
let c = sel.select_capable(rcp::Capability::Retrieve)?; // highest-priority live + can retrieve

auto sel = rcp::Selector::from_registry_file("rcp.json").value();

auto c = sel.select("docs");                             // by id
auto c = sel.select_primary();                           // highest-priority live
auto c = sel.select_capable(rcp::Capability::Retrieve);  // highest-priority live + can retrieve
// each returns Result<Client>: .value() is the connected client, .error() the failure

Use select_capable as the default in a mixed fleet: it is the “any live backend that can do X, best one first” query, so a client never has to hard-code which engine owns which capability.

Federation — fuse many

A federated retrieve(query, k) fans out retrieve to every engine that advertises it, concurrently. Engines lacking the capability are skipped (not an error); a slow non-required engine is dropped after a client-side deadline so one bad backend can’t stall the query.

Reciprocal Rank Fusion

The default and recommended fusion is RRF (Cormack et al. 2009), which needs only ranks — not comparable scores — so it is robust across heterogeneous engines:

RRF(d) = Σ_engine  weight_engine / (rrfK + rank_engine(d))          rrfK default 60

where rank_engine(d) is the 1-based position of document d in that engine’s list (engines that didn’t return d contribute nothing). The fused list is sorted by descending RRF(d) and truncated to k.

Never fuse raw scores directly — scores from different scorers are not comparable. If you must use weighted score fusion, min-max normalise per engine to [0,1] first. RRF is preferred by default precisely because it sidesteps this footgun.

Determinism & dedup

Tie-breaking is deterministic: order by (1) higher fused score, then (2) higher summed weight, then (3) lexicographically smaller stringified id — a total order independent of engine response arrival.
Deduplication keys on the stringified Hit.id. When two hits collapse, the fused hit SHOULD keep the richest body and merge meta. Each fused hit carries its origin in meta.engine.

The fusion primitive — `rrf_fuse`

You don’t need the full Federation facade to fuse. Every reference SDK exports the fusion algorithm as a standalone, tested function over ranked lists you already hold — a cache, a replay, two hand-issued retrieve calls — so no adopter re-derives §16.3 (and re-derives it subtly wrong). All four are byte-for-byte identical: same tie-break, same richest-body dedup, same origin tagging in meta.engine and meta.fusedScore.

fused = rcp.rrf_fuse(
    {"dense": dense_hits, "sparse": sparse_hits},   # engine id -> ranked list
    k=10,
    weights={"dense": 1.0, "sparse": 0.7},          # optional per-engine weights
)
# rcp.weighted_fuse(...) instead when engine scores ARE comparable
# (it min-max normalises per engine first).
for h in fused:
    print(h["id"], h["meta"]["engine"], h["meta"]["fusedScore"])

const fused = rcp.rrfFuse(
  { dense: denseHits, sparse: sparseHits },
  { k: 10, weights: { dense: 1.0, sparse: 0.7 } },
);
// rcp.weightedFuse(lists, { k, weights }) for comparable scores.

use rcp::fusion;
let fused = fusion::rrf_fuse(
    &[("dense", &dense_hits), ("sparse", &sparse_hits)],
    Some(10),                    // k
    fusion::RRF_K_DEFAULT,       // 60
    Some(&weights),              // Option<&HashMap<String, f64>>
);
// fusion::weighted_fuse(&engines, k, weights) for comparable scores.

using rcp::fusion::EngineList;
std::vector<EngineList> engines = {
    {"dense", dense_hits, 1.0}, {"sparse", sparse_hits, 0.7}};
auto fused = rcp::fusion::rrf_fuse(engines, /*k=*/10);
// rcp::fusion::weighted_fuse(engines, k) for comparable scores.
// The live Federation delegates to this same function.

The default rrfK is 60 (rcp.RRF_K_DEFAULT / fusion::RRF_K_DEFAULT). The live C++ Federation calls the very same rcp::fusion::rrf_fuse, so fan-out fusion and held-list fusion agree exactly.

One command: fan out and fuse

examples/example_federation.py is spec §16 made runnable in a single process — it spawns two genuinely independent engine subprocesses (each its own corpus), fans one query out to both, and fuses their rankings with rcp.rrf_fuse:

python3 examples/example_federation.py
# [papers] returned 2: ['p-rrf', 'p-colbert']
# [web   ] returned 1: ['w-rrf']
#
# fused top-3 (RRF, weights={'papers': 1.0, 'web': 0.7}):
#   1. p-rrf      engine=papers  fusedScore=0.01639
#   2. p-colbert  engine=papers  fusedScore=0.01613
#   3. w-rrf      engine=web     fusedScore=0.01148

No servers to start, no ports, no config — the whole federation lives and dies with the process.

Federated capabilities

A client’s effective capability set over a federation is the union of its engines’ capabilities (it can embed if any engine can); its guaranteed set is the intersection. A federated retrieve runs against the subset advertising retrieve; a federated graph op against those advertising it. Reference SDKs expose both a per-engine handle and a Federation facade.

Get Started

Core Concepts

Methods

Features

Operating a Server

The registry — `rcp.json`

Selector — pick one of many

Federation — fuse many

Reciprocal Rank Fusion

Determinism & dedup

The fusion primitive — `rrf_fuse`

One command: fan out and fuse

Federated capabilities

​The registry — rcp.json

​Selector — pick one of many

​Federation — fuse many

​Reciprocal Rank Fusion

​Determinism & dedup

​The fusion primitive — rrf_fuse

​One command: fan out and fuse

​Federated capabilities

The registry — `rcp.json`

Selector — pick one of many

Federation — fuse many

Reciprocal Rank Fusion

Determinism & dedup

The fusion primitive — `rrf_fuse`

One command: fan out and fuse

Federated capabilities