rcp/lib.rs
1//! rcp — the Retrieval Context Protocol, a native Rust SDK.
2//!
3//! Zero dependencies (Rust standard library only). RCP is an open, versioned
4//! JSON-RPC protocol so any RAG engine — any language, any vendor — can expose
5//! embed / rerank / retrieve / graph / index / catalog, and any client can
6//! consume it uniformly. This SDK speaks the exact same wire format as the C++,
7//! Python, and Node.js SDKs, so a Rust client and a C++/Python/Node server (or
8//! vice-versa) interoperate byte-for-byte.
9//!
10//! # Client
11//!
12//! ```no_run
13//! use rcp::Capability;
14//! let mut c = rcp::connect_stdio(&["python3", "my_server.py"])?;
15//! if c.supports(Capability::Retrieve) {
16//! for hit in c.retrieve("eiffel tower", 3)? {
17//! println!("{} {}", hit.id, hit.score);
18//! }
19//! }
20//! # Ok::<(), rcp::RcpError>(())
21//! ```
22//!
23//! # Server
24//!
25//! ```no_run
26//! use rcp::{Server, Method, Capability, Json, obj};
27//! let mut s = rcp::Server::new();
28//! s.set_info("my-engine", "1.0");
29//! s.advertise(Capability::Retrieve, obj(&[("maxK", 100.into())]));
30//! s.on(Method::RETRIEVE, |params| {
31//! let q = params.get_str("query").unwrap_or("");
32//! Ok(obj(&[("hits", vec![obj(&[("id", "d1".into()), ("score", 0.9.into()), ("text", q.into())])].into())]))
33//! });
34//! s.serve_stdio();
35//! ```
36
37mod client;
38pub mod filter;
39pub mod fusion;
40mod json;
41mod selector;
42mod server;
43mod transport;
44mod types;
45pub mod vectors;
46
47pub use client::{Client, Hit, SearchResult};
48pub use filter::Filter;
49pub use json::{obj, Json};
50pub use selector::{EngineSpec, Selector};
51pub use server::{make_log_notification, make_progress_notification, Server};
52pub use transport::{HttpTransport, StdioTransport, Transport};
53pub use types::{
54 cap_for_method, negotiate_version, Capability, Errc, Method, RcpError, MIN_PROTOCOL_VERSION,
55 PROTOCOL_VERSION,
56};
57
58/// The SDK version.
59pub const VERSION: &str = "1.0.0";
60
61/// Spawn an RCP server subprocess and connect. `argv` e.g. `["python3", "srv.py"]`.
62pub fn connect_stdio<S: AsRef<str>>(argv: &[S]) -> Result<Client, RcpError> {
63 Client::connect_stdio(argv)
64}
65
66/// Connect to an HTTP RCP server, e.g. `"http://127.0.0.1:8000/rcp"`.
67pub fn connect_http(base_url: &str) -> Result<Client, RcpError> {
68 Client::connect_http(base_url)
69}