C++ SDK - Retrieval Context Protocol

The C++ SDK is header-only and type-theoretic: protocol invariants live in the type system and are proved at compile time — the build is the test runner.

Refinement types

TopK cannot be 0, ProtocolVersion is validated at construction, Score/Dimension are not interchangeable.

Typestate Client

Only constructible via a connect*() that runs the handshake; gated calls fail client-side with CapabilityMissing before any I/O.

Concept-gated Server<H>

A handler advertises capabilities and implements matching hooks; if constexpr dispatch makes an advertised-but-unimplemented method a typed error, never a crash.

Total Result<T>

Result<T> = std::expected<T, Error> everywhere — no exceptions for control flow. static_assert proofs ship in test_types.cpp.

Requirements

A C++23 compiler with std::expected (GCC 13+ or recent Clang). Header-only — just add sdk/cpp/include to your include path and #include "rcp.hpp".

Server

#include "rcp.hpp"
using namespace rcp;

struct Engine {
    PeerInfo info() const { return {"my-engine", "1.0"}; }
    Capabilities capabilities() const {
        return Capabilities{}
            .with_retrieve({{"maxK", 200}, {"modes", {"dense", "hybrid"}}})
            .with_embed(Dimension{384}, "bge-small-en");
    }
    Result<Json> retrieve(const Json& p) {
        auto hits = my_index.search(p.at("query"), p.value("k", 10));
        return Json{{"hits", hits}};
    }
    Result<Json> embed(const Json& p) {
        return Json{{"vectors", embed_all(p.at("inputs"))}};
    }
};

int main() { Server{Engine{}}.serve_stdio(); }   // or .serve_http(8000)

Which hooks you define is detected at compile time; a capability you advertise but don’t implement resolves to a typed CapabilityMissing, not a null pointer.

Client

auto r = Client::connect_stdio({"./my_engine"});
if (!r) { /* r.error().code / .message */ return 1; }
Client c = std::move(*r);

if (c.supports(Capability::Retrieve)) {
    auto k = TopK::make(3);                 // refinement type: make(0) fails
    auto hits = c.retrieve("eiffel tower", *k);
    if (hits) for (auto& h : *hits) std::printf("%s %.3f\n", h.id.c_str(), h.score.get());
}

Every call returns Result<T>; nothing throws across the API boundary.

Build & test

cd sdk/cpp
make test        # static_assert proofs + runtime checks
make examples    # example_server / client / selector / federation

Validate against the conformance suite:

python3 conformance/check.py -- ./sdk/cpp/example_server

Fusion & the vector codec

rcp/fusion.hpp and rcp/vectors.hpp are standalone, header-only, and tested — byte-for-byte identical to the Python, Node, and Rust SDKs. The live Federation delegates to the same rcp::fusion::rrf_fuse, so held-list fusion and fan-out fusion agree exactly:

using rcp::fusion::EngineList;

// Merge per-engine ranked lists (spec §16.3): deterministic tie-break,
// richest-body dedup, origin tags in meta.engine / meta.fusedScore.
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) when scores are comparable.

// Compact f32-base64 embedding codec (spec §7.3.1).
auto blob = rcp::vectors::encode_f32_base64(vector);          // std::string
auto back = rcp::vectors::decode_f32_base64(blob, /*dimension=*/1024);

See Federation and compact encoding.

The SDK also ships a Selector (pick one backend) and a Federation (fan out + RRF fuse) — see Federation.

Refinement types

Typestate Client

Concept-gated Server<H>

Total Result<T>

​Requirements

​Server

​Client

​Build & test

​Fusion & the vector codec

Requirements

Server

Client

Build & test

Fusion & the vector codec