Skip to main content

Crate rcp

Crate rcp 

Source
Expand description

rcp — the Retrieval Context Protocol, a native Rust SDK.

Zero dependencies (Rust standard library only). RCP is an open, versioned JSON-RPC protocol so any RAG engine — any language, any vendor — can expose embed / rerank / retrieve / graph / index / catalog, and any client can consume it uniformly. This SDK speaks the exact same wire format as the C++, Python, and Node.js SDKs, so a Rust client and a C++/Python/Node server (or vice-versa) interoperate byte-for-byte.

§Client

use rcp::Capability;
let mut c = rcp::connect_stdio(&["python3", "my_server.py"])?;
if c.supports(Capability::Retrieve) {
    for hit in c.retrieve("eiffel tower", 3)? {
        println!("{} {}", hit.id, hit.score);
    }
}

§Server

use rcp::{Server, Method, Capability, Json, obj};
let mut s = rcp::Server::new();
s.set_info("my-engine", "1.0");
s.advertise(Capability::Retrieve, obj(&[("maxK", 100.into())]));
s.on(Method::RETRIEVE, |params| {
    let q = params.get_str("query").unwrap_or("");
    Ok(obj(&[("hits", vec![obj(&[("id", "d1".into()), ("score", 0.9.into()), ("text", q.into())])].into())]))
});
s.serve_stdio();

Re-exports§

pub use filter::Filter;

Modules§

filter
Build and validate RCP metadata filter trees (spec §8).
fusion
fusion.rs — federation fusion for RCP/1 (spec §16.3), the reference impl.
vectors
vectors.rs — compact dense-vector codec for RCP/1 (spec §7.3.1).

Structs§

Client
A connected RCP client.
EngineSpec
How to reach one backend. Inert until selected; exactly one of argv (stdio) or url (HTTP) is set.
Errc
RCP/1 error codes (spec §12). -326xx are JSON-RPC; -320xx are RCP-specific.
Hit
One retrieval hit. id/score/text are always present (id coerced to a string); every optional spec §7.7 field is surfaced when the server sent it — confidence (normalised [0,1]), unit/level (granularity & abstraction), provenance (graph/tree lineage), trust (provenance + safety), and per-stage scores. raw is the untouched JSON object for anything else.
HttpTransport
Minimal HTTP/1.1 client: POST the request to <base_url>/<method>. The server ignores the path and dispatches on the body’s method. Maps HTTP 429 → RateLimited and 503 → BackendUnavailable (spec §5.2).
Method
RCP/1 method names (spec §9). String constants — usable anywhere a method name is expected (server.on(Method::RETRIEVE, …) or server.on("retrieve", …)).
RcpError
An RCP protocol or transport error.
SearchResult
The full result of search: hits plus telemetry and an optional page cursor.
Selector
A registry of candidate engines; selection connects and returns a Client.
Server
An RCP/1 server.
StdioTransport
Newline-delimited JSON over a subprocess’ stdio. Replies are correlated by JSON-RPC id; server notifications (frames carrying method) and stray mismatched-id replies are skipped (spec §4.7).

Enums§

Capability
The capability lattice (spec §7.2). Each variant maps to a wire JSON key.
Json
A JSON value.

Constants§

MIN_PROTOCOL_VERSION
The lowest protocol version this SDK will accept.
PROTOCOL_VERSION
The protocol version this SDK speaks.
VERSION
The SDK version.

Traits§

Transport
One JSON-RPC request → one reply.

Functions§

cap_for_method
Which capability gates which method (spec §7.2 / §9).
connect_http
Connect to an HTTP RCP server, e.g. "http://127.0.0.1:8000/rcp".
connect_stdio
Spawn an RCP server subprocess and connect. argv e.g. ["python3", "srv.py"].
make_log_notification
Build a notifications/log frame (spec §17.1) to write to the output stream.
make_progress_notification
Build a notifications/progress frame (spec §9) during a long retrieve.
negotiate_version
min(peer, ours), clamped — mirrors rcp::negotiate_version.
obj
Build a Json::Object from key/value pairs.