rcp-protocol 1.0.0__py3-none-any.whl

rcp/__init__.py

@@ -0,0 +1,66 @@
+"""rcp — the Retrieval Context Protocol, a native Python SDK.
+
+Pure Python, zero dependencies (standard library only): no compiler, no C++, no
+build step to ``pip install``. 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 type-theoretic C++ SDK, so a Python client and
+a C++ server (or vice-versa) interoperate byte-for-byte.
+
+Client (connects to any RCP server, over a subprocess or HTTP):
+
+    import rcp
+    c = rcp.connect_stdio(["python3", "my_server.py"])
+    print(c.server, c.capabilities)
+    if c.supports(rcp.Capability.Retrieve):
+        for hit in c.retrieve("eiffel tower", k=3):
+            print(hit["id"], hit["score"])
+
+Server (expose a Python RAG engine as an RCP server):
+
+    import rcp
+    s = rcp.Server()
+    s.set_info("my-engine", "1.0")
+    s.advertise(rcp.Capability.Retrieve, {"maxK": 100, "modes": ["hybrid"]})
+
+    @s.on("retrieve")
+    def _(params):
+        hits = my_index.search(params["query"], params.get("k", 10))
+        return {"hits": [{"id": h.id, "score": h.score, "text": h.text} for h in hits]}
+
+    s.serve_stdio()
+"""
+from ._client import Client
+from ._selector import EngineSpec, Selector
+from ._server import Server, make_log_notification, make_progress_notification
+from ._transport import HttpTransport, StdioTransport
+from ._types import (
+    PROTOCOL_VERSION,
+    Capability,
+    Errc,
+    Method,
+    RcpError,
+    negotiate_version,
+)
+
+__all__ = [
+    "Client", "Server", "Selector", "EngineSpec", "Capability", "PROTOCOL_VERSION",
+    "Method", "Errc", "RcpError", "connect_stdio", "connect_http",
+    "make_log_notification", "make_progress_notification",
+    "StdioTransport", "HttpTransport", "negotiate_version",
+]
+__version__ = "1.0.0"
+
+
+def connect_stdio(argv, **kwargs) -> Client:
+    """Spawn an RCP server subprocess and connect. `argv` e.g. ["python3","srv.py"]."""
+    c = Client()
+    c.connect_stdio(list(argv))
+    return c
+
+
+def connect_http(base_url: str, **kwargs) -> Client:
+    """Connect to an HTTP RCP server, e.g. "http://127.0.0.1:8000/rcp"."""
+    c = Client()
+    c.connect_http(base_url)
+    return c

rcp/_client.py

@@ -0,0 +1,222 @@
+"""RCP client — connect to any RCP server (subprocess or HTTP), then typed calls.
+
+Mirrors the C++ ``rcp::Client`` (``sdk/cpp/include/rcp/client.hpp``): connecting
+performs the ``initialize`` handshake and caches the negotiated protocol version,
+server identity, and capabilities. Every typed call is **capability-gated** — a
+call to a feature the server never advertised raises before any round-trip.
+
+Errors raise :class:`RcpError` (a ``RuntimeError``) with ``str(e)`` of the form
+``"[RCP <code>] <message>"``.
+"""
+from __future__ import annotations
+
+import json
+
+from ._transport import HttpTransport, StdioTransport
+from ._types import (
+    MIN_PROTOCOL_VERSION,
+    PROTOCOL_VERSION,
+    Capability,
+    Errc,
+    Method,
+    RcpError,
+    cap_key,
+)
+
+_CLIENT_INFO = {"name": "rcp-python", "version": "1.0"}
+
+
+def _hit_to_dict(h) -> dict:
+    """Normalise one retrieval Hit to ``{id, score, text[, citation]}`` — the
+    canonical hit shape (id coerced to str, extra fields dropped)."""
+    if not isinstance(h, dict):
+        return {"id": "", "score": 0.0, "text": str(h)}
+    raw_id = h.get("id", "")
+    hit_id = raw_id if isinstance(raw_id, str) else json.dumps(raw_id, separators=(",", ":"))
+    out = {"id": hit_id, "score": float(h.get("score", 0.0)), "text": h.get("text", "")}
+    if h.get("citation") is not None:
+        out["citation"] = h["citation"]
+    return out
+
+
+class Client:
+    """A connected RCP client. Obtain one via :func:`rcp.connect_stdio` /
+    :func:`rcp.connect_http`, or construct and call ``connect_stdio`` /
+    ``connect_http`` directly — either style works."""
+
+    def __init__(self):
+        self._transport = None
+        self._next_id = 0
+        self._protocol_version = PROTOCOL_VERSION
+        self._server = {"name": "unknown", "version": "0"}
+        self._caps: dict = {}
+
+    # ── connection ──────────────────────────────────────────────────────────
+    def connect_stdio(self, argv) -> "Client":
+        self._transport = StdioTransport.spawn(list(argv))
+        self._handshake()
+        return self
+
+    def connect_http(self, base_url: str) -> "Client":
+        self._transport = HttpTransport(base_url)
+        self._handshake()
+        return self
+
+    def _handshake(self) -> None:
+        res = self._request(Method.INITIALIZE, {
+            "protocolVersion": PROTOCOL_VERSION,
+            "client": dict(_CLIENT_INFO),
+            "capabilities": {},
+        })
+        pv = res.get("protocolVersion", PROTOCOL_VERSION)
+        if not isinstance(pv, int) or pv < MIN_PROTOCOL_VERSION:
+            raise RcpError(Errc.VERSION_MISMATCH, "server offered no usable protocol version")
+        self._protocol_version = pv
+        srv = res.get("server", {}) or {}
+        self._server = {"name": srv.get("name", "unknown"), "version": srv.get("version", "0")}
+        self._caps = res.get("capabilities", {}) or {}
+
+    # ── introspection ───────────────────────────────────────────────────────
+    @property
+    def protocol_version(self) -> int:
+        return self._protocol_version
+
+    @property
+    def server(self) -> dict:
+        return self._server
+
+    @property
+    def capabilities(self) -> dict:
+        return self._caps
+
+    def supports(self, capability) -> bool:
+        return self._caps.get(cap_key(capability)) is not None
+
+    # ── typed, capability-gated calls ───────────────────────────────────────
+    def embed(self, texts, kind=None):
+        """Dense embeddings → ``list[list[float]]``. ``kind`` ("query"|"document")
+        selects asymmetric pooling."""
+        self._gate(Capability.Embed)
+        p = {"inputs": list(texts)}
+        if kind:
+            p["kind"] = kind
+        r = self._request(Method.EMBED, p)
+        vecs = r.get("vectors", r) if isinstance(r, dict) else r
+        return [[float(x) for x in row] for row in vecs]
+
+    def embed_sparse(self, texts):
+        """Learned-sparse (SPLADE) terms → raw result ``{sparse: [...]}``."""
+        self._gate(Capability.SparseEmbed)
+        return self._request(Method.EMBED_SPARSE, {"inputs": list(texts)})
+
+    def embed_multi(self, inputs):
+        """Per-token multi-vector (ColBERT/ColPali) → ``{matrices, dimension}``."""
+        self._gate(Capability.MultiVector)
+        return self._request(Method.EMBED_MULTI, {"inputs": list(inputs)})
+
+    def rerank(self, query, passages):
+        """Cross-encoder rerank → ``list[float]`` scores (one per passage)."""
+        self._gate(Capability.Rerank)
+        r = self._request(Method.RERANK, {"query": query, "passages": list(passages)})
+        scores = r.get("scores", r) if isinstance(r, dict) else r
+        return [float(x) for x in scores]
+
+    def search(self, query, k=10, opts=None):
+        """Full retrieve → ``{hits, usage, next_cursor}`` (spec §7.6)."""
+        self._gate(Capability.Retrieve)
+        if k < 1:
+            raise RcpError(Errc.INVALID_PARAMS, "value must be >= 1")
+        p = dict(opts) if opts else {}
+        p["query"] = query
+        p["k"] = k
+        r = self._request(Method.RETRIEVE, p)
+        hits = r.get("hits", []) if isinstance(r, dict) else []
+        return {
+            "hits": [_hit_to_dict(h) for h in hits],
+            "usage": (r.get("usage", {}) if isinstance(r, dict) else {}),
+            "next_cursor": (r.get("nextCursor") if isinstance(r, dict) else None),
+        }
+
+    def retrieve(self, query, k=10, opts=None):
+        """Convenience over :meth:`search` → just the ``list[dict]`` of hits."""
+        return self.search(query, k, opts)["hits"]
+
+    def graph(self, op, params=None):
+        """GraphRAG op ("local"|"global"|...) → raw result dict (spec §7.9)."""
+        self._gate(Capability.Graph)
+        p = dict(params) if params else {}
+        p["op"] = op
+        return self._request(Method.GRAPH, p)
+
+    def transform(self, query, method):
+        """Query transform (HyDE, expansion, ...) → raw result (spec §7.8)."""
+        self._gate(Capability.Transform)
+        return self._request(Method.TRANSFORM, {"query": query, "method": method})
+
+    def index_add(self, params=None):
+        """Add documents to the corpus (spec §7.10). ``params`` e.g. ``{documents:[...]}``."""
+        self._gate(Capability.Index)
+        return self._request(Method.INDEX_ADD, dict(params) if params else {})
+
+    def index_delete(self, params=None):
+        """Delete documents by id (spec §7.11). ``params`` e.g. ``{ids:[...]}``."""
+        self._gate(Capability.Index)
+        return self._request(Method.INDEX_DELETE, dict(params) if params else {})
+
+    def catalog(self):
+        """List available sub-indexes / collections (spec §7.12)."""
+        self._gate(Capability.Catalog)
+        return self._request(Method.CATALOG_LIST, {})
+
+    def info(self):
+        """Re-fetch server identity + capabilities without re-initialising."""
+        r = self._request(Method.INFO, {})
+        srv = r.get("server", {}) or {}
+        self._server = {"name": srv.get("name", "unknown"), "version": srv.get("version", "0")}
+        self._caps = r.get("capabilities", {}) or {}
+        return r
+
+    def call(self, method, params=None):
+        """Escape hatch: invoke an arbitrary method with raw params."""
+        return self._request(method, params if params is not None else {})
+
+    def ping(self, nonce=None):
+        """Liveness check; echoes ``{nonce}`` if a nonce is given (spec §9)."""
+        p = {}
+        if nonce is not None:
+            p["nonce"] = nonce
+        return self._request(Method.PING, p)
+
+    def shutdown(self) -> None:
+        """Politely ask the server to stop, then close the transport. Never raises."""
+        if self._transport is None:
+            return
+        try:
+            self._request(Method.SHUTDOWN, {})
+        except RcpError:
+            pass
+        finally:
+            self._transport.close()
+            self._transport = None
+
+    # ── internals ───────────────────────────────────────────────────────────
+    def _gate(self, capability) -> None:
+        if not self.supports(capability):
+            raise RcpError(Errc.CAPABILITY_MISSING,
+                           f"server does not advertise '{cap_key(capability)}'")
+
+    def _request(self, method, params):
+        if self._transport is None:
+            raise RcpError(Errc.BACKEND_UNAVAILABLE, "client is not connected")
+        self._next_id += 1
+        reply = self._transport.call({
+            "jsonrpc": "2.0", "id": self._next_id, "method": method, "params": params,
+        })
+        if isinstance(reply, dict):
+            err = reply.get("error")
+            if err is not None:
+                raise RcpError(err.get("code", Errc.INTERNAL_ERROR),
+                               err.get("message", "error"), err.get("data"))
+            if "result" in reply:
+                return reply["result"]
+        return {}

rcp/_selector.py

@@ -0,0 +1,143 @@
+"""RCP Selector — choose ONE backend from several reachable engines.
+
+Mirrors ``rcp::Selector`` (``sdk/cpp/include/rcp/selector.hpp``): you list
+candidate engines (by hand or from an ``rcp.json`` registry) and pick one — by
+id, by required capability, or by priority with liveness fallback. Connection is
+**lazy**: an engine is dialled only when actually selected. The result is a
+fully-connected :class:`~rcp._client.Client`.
+"""
+from __future__ import annotations
+
+import json
+
+from ._client import Client
+from ._types import Errc, RcpError, cap_key
+
+
+class EngineSpec:
+    """How to reach one backend. Inert until selected; exactly one of ``argv``
+    (stdio subprocess) or ``url`` (HTTP) is set."""
+
+    def __init__(self, id, argv=None, url="", priority=0, weight=1.0, required=False):
+        self.id = id
+        self.argv = list(argv) if argv else []
+        self.url = url
+        self.priority = priority
+        self.weight = weight
+        self.required = required
+
+    def open(self) -> Client:
+        c = Client()
+        if self.argv:
+            return c.connect_stdio(self.argv)
+        if self.url:
+            return c.connect_http(self.url)
+        raise RcpError(Errc.INVALID_PARAMS, f"engine '{self.id}' has no transport")
+
+    @staticmethod
+    def from_json(entry) -> "EngineSpec":
+        """Parse one registry entry (spec §16.1). ``transport`` is "stdio" (needs
+        ``command``) or "http" (needs ``url``); inferred if omitted."""
+        if not isinstance(entry, dict) or "id" not in entry:
+            raise RcpError(Errc.INVALID_PARAMS, "registry entry needs an 'id'")
+        transport = entry.get("transport", "")
+        command = entry.get("command") or entry.get("argv")
+        url = entry.get("url", "")
+        spec = EngineSpec(
+            id=entry.get("id", ""),
+            priority=entry.get("priority", 0),
+            weight=entry.get("weight", 1.0),
+            required=entry.get("required", False),
+        )
+        if transport == "stdio" or (not transport and command):
+            if not isinstance(command, list) or not command:
+                raise RcpError(Errc.INVALID_PARAMS,
+                               f"stdio engine '{spec.id}' needs a 'command' array")
+            spec.argv = [str(x) for x in command]
+        elif transport == "http" or (not transport and url):
+            if not url:
+                raise RcpError(Errc.INVALID_PARAMS, f"http engine '{spec.id}' needs a 'url'")
+            spec.url = url
+        else:
+            raise RcpError(Errc.INVALID_PARAMS,
+                           f"engine '{spec.id}' has no usable transport")
+        return spec
+
+
+class Selector:
+    """Registry of candidate engines; selection connects and returns a Client."""
+
+    def __init__(self):
+        self._specs: list[EngineSpec] = []
+
+    # ── construction ────────────────────────────────────────────────────────
+    @staticmethod
+    def load(path: str) -> "Selector":
+        """Build a Selector from a registry JSON file."""
+        with open(path, "r", encoding="utf-8") as f:
+            return Selector.loads(f.read())
+
+    @staticmethod
+    def loads(text: str) -> "Selector":
+        """Build a Selector from a registry JSON string
+        (``{"engines": [ ... ]}``)."""
+        try:
+            doc = json.loads(text)
+        except ValueError as e:
+            raise RcpError(Errc.PARSE_ERROR, f"invalid registry JSON: {e}")
+        engines = doc.get("engines", []) if isinstance(doc, dict) else []
+        sel = Selector()
+        for entry in engines:
+            sel._specs.append(EngineSpec.from_json(entry))
+        return sel
+
+    def add_stdio(self, id, argv, priority=0) -> "Selector":
+        self._specs.append(EngineSpec(id, argv=list(argv), priority=priority))
+        return self
+
+    def add_http(self, id, url, priority=0) -> "Selector":
+        self._specs.append(EngineSpec(id, url=url, priority=priority))
+        return self
+
+    @property
+    def size(self) -> int:
+        return len(self._specs)
+
+    # ── selection ───────────────────────────────────────────────────────────
+    def select(self, id) -> Client:
+        """Connect the engine with the given id (or raise if unknown)."""
+        for spec in self._specs:
+            if spec.id == id:
+                return spec.open()
+        raise RcpError(Errc.INVALID_PARAMS, f"no engine with id '{id}'")
+
+    def select_primary(self) -> Client:
+        """Connect the highest-priority engine that answers (liveness fallback)."""
+        last = None
+        for spec in self._by_priority():
+            try:
+                return spec.open()
+            except RcpError as e:
+                last = e
+        raise last or RcpError(Errc.BACKEND_UNAVAILABLE, "no engines configured")
+
+    def select_capable(self, capability) -> Client:
+        """Connect the highest-priority engine that answers AND advertises
+        ``capability``."""
+        last = None
+        for spec in self._by_priority():
+            try:
+                c = spec.open()
+            except RcpError as e:
+                last = e
+                continue
+            if c.supports(capability):
+                return c
+            c.shutdown()
+            last = RcpError(Errc.CAPABILITY_MISSING,
+                            f"engine '{spec.id}' lacks '{cap_key(capability)}'")
+        raise last or RcpError(Errc.BACKEND_UNAVAILABLE, "no capable engine")
+
+    def _by_priority(self) -> list[EngineSpec]:
+        # Stable sort by descending priority (Python's sort is stable).
+        return sorted(self._specs, key=lambda s: s.priority, reverse=True)

rcp/_server.py

@@ -0,0 +1,269 @@
+"""RCP server — expose a Python RAG engine as an RCP/1 server.
+
+Mirrors the C++ ``rcp::Server`` (``sdk/cpp/include/rcp/server.hpp``): it owns the
+JSON-RPC framing, the ``initialize`` handshake, capability gating, and error
+mapping; you provide method handlers (``on``) and identity/capabilities
+(``set_info`` / ``advertise``).
+
+Dispatch rules replicated exactly:
+
+* ``initialize`` / ``info`` / ``ping`` / ``shutdown`` / ``notifications/cancel``
+  are ungated and answer before initialize.
+* A gated method before ``initialize`` → **-32001** NotInitialized.
+* A method whose capability is unadvertised or whose handler is unregistered →
+  **-32003** CapabilityMissing.
+* An unknown method → **-32004** UnknownMethod. A malformed request → **-32600**.
+* Batches (JSON array) yield one response per request; notifications drop out.
+"""
+from __future__ import annotations
+
+import json
+import socket
+
+from ._types import (
+    CAP_FOR_METHOD,
+    MIN_PROTOCOL_VERSION,
+    PROTOCOL_VERSION,
+    Capability,
+    Errc,
+    Method,
+    RcpError,
+    cap_key,
+    negotiate_version,
+)
+
+_COMPACT = (",", ":")
+_KNOWN_METHODS = set(CAP_FOR_METHOD)
+
+
+def _dumps(obj) -> str:
+    return json.dumps(obj, separators=_COMPACT)
+
+
+def _ok(id_, result) -> dict:
+    return {"jsonrpc": "2.0", "id": id_, "result": result}
+
+
+def _err(id_, code: int, message: str, data=None) -> dict:
+    error = {"code": code, "message": message}
+    if data is not None:
+        error["data"] = data
+    return {"jsonrpc": "2.0", "id": id_, "error": error}
+
+
+def make_log_notification(level: str, message: str, data=None) -> str:
+    """Build a ``notifications/log`` frame (spec §17.1) for a server to emit on
+    its output stream. ``level`` ∈ debug|info|notice|warning|error."""
+    params = {"level": level, "message": message}
+    if data is not None:
+        params["data"] = data
+    return _dumps({"jsonrpc": "2.0", "method": Method.LOG, "params": params})
+
+
+def make_progress_notification(token, progress: float, stage: str = "", partial=None) -> str:
+    """Build a ``notifications/progress`` frame (spec §9) during a long retrieve.
+    ``token`` echoes the request's ``_meta.progressToken``; ``progress`` is 0..1."""
+    params = {"progressToken": token, "progress": progress}
+    if stage:
+        params["stage"] = stage
+    if partial is not None:
+        params["partial"] = partial
+    return _dumps({"jsonrpc": "2.0", "method": Method.PROGRESS, "params": params})
+
+
+class Server:
+    """An RCP/1 server. Register handlers with :meth:`on` (usable as a decorator),
+    then serve over stdio or HTTP — or drive :meth:`handle` directly for tests."""
+
+    def __init__(self):
+        self._info = {"name": "unknown", "version": "0"}
+        self._caps: dict = {}          # wire JSON key -> metadata object
+        self._handlers: dict = {}      # method string -> callable(params) -> result
+        self._initialized = False
+
+    # ── configuration ───────────────────────────────────────────────────────
+    def set_info(self, name: str, version: str) -> None:
+        self._info = {"name": str(name), "version": str(version)}
+
+    def advertise(self, capability, meta=None) -> None:
+        """Advertise a capability with optional metadata (stored under its wire
+        key). Advertising is independent of registering a handler; a gated call
+        needs both or it is CapabilityMissing."""
+        self._caps[cap_key(capability)] = {} if meta is None else meta
+
+    def on(self, method, fn=None):
+        """Register a handler for ``method``. Works as a decorator
+        (``@s.on("retrieve")``) or directly (``s.on("retrieve", fn)``). The
+        handler takes the params dict and returns the result object."""
+        name = method.value if isinstance(method, Capability) else str(method)
+        if name not in _KNOWN_METHODS:
+            raise ValueError(f"unknown method hook: {name!r} "
+                             f"(expected one of {sorted(_KNOWN_METHODS)})")
+        if fn is None:
+            def deco(f):
+                self._handlers[name] = f
+                return f
+            return deco
+        self._handlers[name] = fn
+        return fn
+
+    # ── dispatch ─────────────────────────────────────────────────────────────
+    def handle(self, request):
+        """Handle one JSON-RPC request object → reply dict, or ``None`` for a
+        notification that warrants no response. Never raises."""
+        id_ = request.get("id") if isinstance(request, dict) else None
+        if not isinstance(request, dict) or not isinstance(request.get("method"), str):
+            return _err(id_, Errc.INVALID_REQUEST, "missing 'method'")
+        m = request["method"]
+        params = request["params"] if "params" in request else {}
+
+        if m == Method.INITIALIZE:
+            self._initialized = True
+            neg = negotiate_version(params.get("protocolVersion", PROTOCOL_VERSION)
+                                    if isinstance(params, dict) else PROTOCOL_VERSION)
+            if neg < MIN_PROTOCOL_VERSION:
+                return _err(id_, Errc.VERSION_MISMATCH, "no common version")
+            return _ok(id_, self._info_result(neg))
+        if m == Method.INFO:
+            return _ok(id_, self._info_result(PROTOCOL_VERSION))
+        if m == Method.PING:
+            has_nonce = isinstance(params, dict) and "nonce" in params
+            return _ok(id_, {"nonce": params["nonce"]} if has_nonce else {})
+        if m == Method.CANCEL:
+            return None  # cancellation is a notification: never answered
+        if m == Method.SHUTDOWN:
+            return _ok(id_, {})
+
+        if not self._initialized:
+            return _err(id_, Errc.NOT_INITIALIZED, "call 'initialize' first")
+
+        return self._dispatch(id_, m, params if isinstance(params, dict) else {})
+
+    def _dispatch(self, id_, m, params):
+        cap = CAP_FOR_METHOD.get(m)
+        if cap is None:
+            return _err(id_, Errc.UNKNOWN_METHOD, f"unknown method '{m}'")
+        fn = self._handlers.get(m)
+        if fn is None:
+            return _err(id_, Errc.CAPABILITY_MISSING, f"'{m}' not implemented")
+        if self._caps.get(cap.value) is None:
+            return _err(id_, Errc.CAPABILITY_MISSING, f"capability '{cap.value}' not supported")
+        try:
+            result = fn(params)
+        except RcpError as e:
+            return _err(id_, e.code, e.message, e.data)
+        except Exception as e:  # a handler bug is an Internal error, never a crash
+            return _err(id_, Errc.INTERNAL_ERROR, str(e))
+        return _ok(id_, result if result is not None else {})
+
+    def handle_line(self, line: str) -> str:
+        """Parse a JSON line, dispatch (single or batch), and return the reply
+        string ("" when there is no response, e.g. an all-notification batch)."""
+        try:
+            msg = json.loads(line)
+        except ValueError as e:
+            return _dumps(_err(None, Errc.PARSE_ERROR, str(e)))
+
+        if isinstance(msg, list):
+            if not msg:
+                return _dumps(_err(None, Errc.INVALID_REQUEST, "empty batch"))
+            out = []
+            for el in msg:
+                reply = self.handle(el)
+                if reply is not None:
+                    out.append(reply)
+            return _dumps(out) if out else ""
+
+        reply = self.handle(msg)
+        return _dumps(reply) if reply is not None else ""
+
+    def _info_result(self, version: int) -> dict:
+        return {
+            "protocolVersion": version,
+            "server": dict(self._info),
+            "capabilities": dict(self._caps),
+        }
+
+    # ── serving ──────────────────────────────────────────────────────────────
+    def serve_stdio(self) -> None:
+        """Serve newline-delimited JSON-RPC over stdin/stdout until shutdown/EOF."""
+        import sys
+
+        stdin = sys.stdin.buffer
+        stdout = sys.stdout.buffer
+        for raw in stdin:
+            line = raw.decode("utf-8", "replace").strip()
+            if not line:
+                continue
+            is_shutdown = False
+            try:
+                parsed = json.loads(line)
+                is_shutdown = isinstance(parsed, dict) and parsed.get("method") == Method.SHUTDOWN
+            except ValueError:
+                pass
+            reply = self.handle_line(line)
+            if reply:
+                try:
+                    stdout.write((reply + "\n").encode("utf-8"))
+                    stdout.flush()
+                except (BrokenPipeError, OSError):
+                    break  # peer gone
+            if is_shutdown:
+                break
+
+    def serve_http(self, port: int) -> None:
+        """Serve JSON-RPC over minimal HTTP/1.1 on ``127.0.0.1:port``. A response
+        returns 200; a notification (no reply) returns 204. Loops until killed."""
+        srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        srv.bind(("127.0.0.1", port))
+        srv.listen(16)
+        try:
+            while True:
+                conn, _ = srv.accept()
+                try:
+                    self._serve_http_conn(conn)
+                except OSError:
+                    pass
+                finally:
+                    conn.close()
+        finally:
+            srv.close()
+
+    def _serve_http_conn(self, conn: socket.socket) -> None:
+        conn.settimeout(30.0)
+        buf = b""
+        while b"\r\n\r\n" not in buf:
+            chunk = conn.recv(4096)
+            if not chunk:
+                return
+            buf += chunk
+        head, _, rest = buf.partition(b"\r\n\r\n")
+        length = 0
+        for hl in head.split(b"\r\n")[1:]:
+            name, _, value = hl.partition(b":")
+            if name.strip().lower() == b"content-length":
+                try:
+                    length = int(value.strip())
+                except ValueError:
+                    length = 0
+        body = rest
+        while len(body) < length:
+            chunk = conn.recv(4096)
+            if not chunk:
+                break
+            body += chunk
+        text = body[:length].decode("utf-8", "replace") if length else (body.decode("utf-8", "replace") or "{}")
+        if not text.strip():
+            text = "{}"
+        reply = self.handle_line(text)
+        if reply:
+            payload = reply.encode("utf-8")
+            resp = (b"HTTP/1.1 200 OK\r\n"
+                    b"Content-Type: application/json\r\n"
+                    b"Content-Length: " + str(len(payload)).encode() + b"\r\n"
+                    b"Connection: close\r\n\r\n" + payload)
+        else:
+            resp = (b"HTTP/1.1 204 No Content\r\n"
+                    b"Connection: close\r\n\r\n")
+        conn.sendall(resp)

rcp/_transport.py

@@ -0,0 +1,146 @@
+"""RCP transports — the request/reply seam (subprocess pipe or HTTP/1.1).
+
+A transport is a total function ``dict -> dict``: send one JSON-RPC request
+object, return the reply object. Two concrete transports mirror the C++ SDK
+(``sdk/cpp/include/rcp/transport.hpp``):
+
+* :class:`StdioTransport` — newline-delimited JSON over a child's stdin/stdout.
+* :class:`HttpTransport`   — minimal HTTP/1.1 POST to ``<base>/<method>``.
+
+Failures raise :class:`RcpError` with the same typed codes as the C++ SDK, so a
+caller sees ``[RCP -32010] ...`` whether the fault was local or remote.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import urllib.parse
+from http.client import HTTPConnection
+
+from ._types import Errc, RcpError
+
+_COMPACT = (",", ":")  # compact JSON separators, matching nlohmann's dump()
+
+
+def _dumps(obj) -> str:
+    return json.dumps(obj, separators=_COMPACT)
+
+
+class StdioTransport:
+    """Newline-delimited JSON over a subprocess' stdio.
+
+    The client writes ``json + "\\n"`` and reads reply lines, **skipping** any
+    server-initiated notification (a frame carrying ``method``) and any stray
+    reply whose ``id`` does not match the request (spec §4.7).
+    """
+
+    def __init__(self, proc: subprocess.Popen):
+        self._proc = proc
+
+    @classmethod
+    def spawn(cls, argv) -> "StdioTransport":
+        argv = list(argv)
+        try:
+            proc = subprocess.Popen(
+                argv, stdin=subprocess.PIPE, stdout=subprocess.PIPE, bufsize=0,
+            )
+        except OSError as e:
+            raise RcpError(Errc.BACKEND_UNAVAILABLE, f"cannot spawn {argv!r}: {e}")
+        return cls(proc)
+
+    def call(self, request: dict) -> dict:
+        line = (_dumps(request) + "\n").encode("utf-8")
+        try:
+            self._proc.stdin.write(line)
+            self._proc.stdin.flush()
+        except (BrokenPipeError, OSError):
+            raise RcpError(Errc.BACKEND_UNAVAILABLE, "write to server failed")
+
+        want_id = request.get("id")
+        while True:
+            raw = self._proc.stdout.readline()
+            if not raw:
+                raise RcpError(Errc.BACKEND_UNAVAILABLE, "server closed the connection")
+            try:
+                reply = json.loads(raw)
+            except ValueError as e:
+                raise RcpError(Errc.PARSE_ERROR, str(e))
+            if isinstance(reply, dict):
+                # Skip a server-initiated notification (has "method", no reply id
+                # to match) and a mismatched-id reply from an earlier request.
+                if "method" in reply:
+                    continue
+                if want_id is not None and "id" in reply and reply["id"] != want_id:
+                    continue
+            return reply
+
+    def close(self) -> None:
+        proc = self._proc
+        if proc.poll() is not None:
+            return
+        for stream in (proc.stdin, proc.stdout):
+            try:
+                if stream is not None:
+                    stream.close()
+            except OSError:
+                pass
+        try:
+            proc.terminate()
+            proc.wait(timeout=2)
+        except Exception:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+
+
+class 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``; the path
+    is a human-readable convenience (e.g. ``POST /rcp/retrieve``). Maps HTTP 429
+    → RateLimited and 503 → BackendUnavailable (spec §5.2).
+    """
+
+    def __init__(self, base_url: str, timeout: float = 30.0):
+        self._base = base_url.rstrip("/")
+        self._timeout = timeout
+
+    def call(self, request: dict) -> dict:
+        method = request.get("method", "")
+        url = self._base + "/" + method
+        parts = urllib.parse.urlsplit(url)
+        if parts.scheme != "http":
+            raise RcpError(Errc.INVALID_PARAMS, f"unsupported URL scheme '{parts.scheme}'")
+        path = parts.path or "/"
+        if parts.query:
+            path += "?" + parts.query
+        body = _dumps(request).encode("utf-8")
+
+        conn = HTTPConnection(parts.hostname or "127.0.0.1", parts.port or 80,
+                              timeout=self._timeout)
+        try:
+            conn.request("POST", path, body=body,
+                         headers={"Content-Type": "application/json",
+                                  "Content-Length": str(len(body))})
+            resp = conn.getresponse()
+            status = resp.status
+            data = resp.read()
+        except OSError as e:
+            raise RcpError(Errc.BACKEND_UNAVAILABLE, f"HTTP request failed: {e}")
+        finally:
+            conn.close()
+
+        if status == 429:
+            raise RcpError(Errc.RATE_LIMITED, "HTTP 429")
+        if status == 503:
+            raise RcpError(Errc.BACKEND_UNAVAILABLE, "HTTP 503")
+        if (status < 200 or status >= 300) and not data.strip():
+            raise RcpError(Errc.BACKEND_UNAVAILABLE, f"HTTP {status}")
+        try:
+            return json.loads(data)
+        except ValueError as e:
+            raise RcpError(Errc.PARSE_ERROR, str(e))
+
+    def close(self) -> None:  # HTTP is connectionless here; nothing to hold open.
+        pass

rcp/_types.py

@@ -0,0 +1,124 @@
+"""Core RCP/1 wire vocabulary — protocol version, capabilities, methods, errors.
+
+Pure Python, no dependencies. The values here mirror the type-theoretic C++ SDK
+(``sdk/cpp/include/rcp/{types,protocol}.hpp``) byte-for-byte on the wire, so a
+Python client and a C++ server (or vice-versa) speak the exact same JSON-RPC.
+"""
+from __future__ import annotations
+
+import enum
+
+# Protocol version negotiation (spec §7.1). We speak exactly version 1.
+PROTOCOL_VERSION = 1
+MIN_PROTOCOL_VERSION = 1
+
+
+def negotiate_version(theirs) -> int:
+    """min(peer, ours), clamped — mirrors rcp::negotiate_version."""
+    try:
+        t = int(theirs)
+    except (TypeError, ValueError):
+        t = PROTOCOL_VERSION
+    return t if t < PROTOCOL_VERSION else PROTOCOL_VERSION
+
+
+class Capability(enum.Enum):
+    """The capability lattice (spec §7.2). ``.value`` is the wire JSON key, so a
+    capability check is a total match on a typed enum, never string-poking."""
+    Embed = "embed"
+    SparseEmbed = "sparseEmbed"
+    MultiVector = "multiVector"
+    Rerank = "rerank"
+    Retrieve = "retrieve"
+    Transform = "transform"
+    Graph = "graph"
+    Index = "index"
+    Catalog = "catalog"
+
+
+class Method:
+    """RCP/1 method names (spec §9). String constants — usable anywhere a wire
+    method name is expected (``s.on(Method.RETRIEVE)`` or ``s.on("retrieve")``)."""
+    INITIALIZE = "initialize"
+    INFO = "info"
+    EMBED = "embed"
+    EMBED_SPARSE = "embed/sparse"
+    EMBED_MULTI = "embed/multi"
+    RERANK = "rerank"
+    RETRIEVE = "retrieve"
+    TRANSFORM = "query/transform"
+    GRAPH = "graph"
+    INDEX_ADD = "index/add"
+    INDEX_DELETE = "index/delete"
+    CATALOG_LIST = "catalog/list"
+    CANCEL = "notifications/cancel"
+    PROGRESS = "notifications/progress"
+    LOG = "notifications/log"
+    PING = "ping"
+    SHUTDOWN = "shutdown"
+
+
+class Errc:
+    """RCP/1 error codes (spec §12). -326xx are JSON-RPC; -320xx are RCP-specific."""
+    PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+    NOT_INITIALIZED = -32001
+    VERSION_MISMATCH = -32002
+    CAPABILITY_MISSING = -32003
+    UNKNOWN_METHOD = -32004
+    OPTION_UNSUPPORTED = -32005
+    CANCELLED = -32006
+    BACKEND_UNAVAILABLE = -32010
+    RATE_LIMITED = -32011
+
+
+class RcpError(RuntimeError):
+    """An RCP protocol or transport error, raised by client calls.
+
+    Subclasses ``RuntimeError`` so existing ``except RuntimeError`` handlers keep
+    working; ``str(e)`` is ``"[RCP <code>] <message>"`` (stable and greppable).
+    Carries the structured ``data`` payload (spec §12) plus retry hints.
+    """
+
+    def __init__(self, code: int, message: str, data=None):
+        super().__init__(f"[RCP {code}] {message}")
+        self.code = code
+        self.message = message
+        self.data = data
+
+    def retryable(self) -> bool:
+        """RateLimited / BackendUnavailable are transient by default; an explicit
+        ``data.retryable`` overrides the code-based default (spec §12)."""
+        if isinstance(self.data, dict) and isinstance(self.data.get("retryable"), bool):
+            return self.data["retryable"]
+        return self.code in (Errc.RATE_LIMITED, Errc.BACKEND_UNAVAILABLE)
+
+    def retry_after_ms(self) -> int:
+        """Server-suggested backoff in ms (``data.retryAfterMs``), or -1."""
+        if isinstance(self.data, dict) and isinstance(self.data.get("retryAfterMs"), int):
+            return self.data["retryAfterMs"]
+        return -1
+
+
+# Which capability gates which method (spec §7.2 / §9). Used by both the client
+# (pre-flight gating) and the server (dispatch gating).
+CAP_FOR_METHOD = {
+    Method.EMBED: Capability.Embed,
+    Method.EMBED_SPARSE: Capability.SparseEmbed,
+    Method.EMBED_MULTI: Capability.MultiVector,
+    Method.RERANK: Capability.Rerank,
+    Method.RETRIEVE: Capability.Retrieve,
+    Method.TRANSFORM: Capability.Transform,
+    Method.GRAPH: Capability.Graph,
+    Method.INDEX_ADD: Capability.Index,
+    Method.INDEX_DELETE: Capability.Index,
+    Method.CATALOG_LIST: Capability.Catalog,
+}
+
+
+def cap_key(capability) -> str:
+    """Wire JSON key for a Capability enum member (or a raw string passthrough)."""
+    return capability.value if isinstance(capability, Capability) else str(capability)

rcp_protocol-1.0.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: rcp-protocol
+Version: 1.0.0
+Summary: Retrieval Context Protocol — native Python SDK (pure standard library, no dependencies)
+Author: RCP Working Group
+License-Expression: MIT
+Project-URL: Homepage, https://rcp-6d6ef6d5.mintlify.site/
+Project-URL: Documentation, https://rcp-6d6ef6d5.mintlify.site/
+Project-URL: Specification, https://github.com/1ay1/rcp/blob/main/spec/rcp-1.0.md
+Project-URL: Source, https://github.com/1ay1/rcp
+Project-URL: Changelog, https://rcp-6d6ef6d5.mintlify.site/reference/changelog
+Project-URL: Issues, https://github.com/1ay1/rcp/issues
+Keywords: rcp,rag,retrieval,protocol,json-rpc,mcp,acp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rcp — Retrieval Context Protocol, Python SDK
+
+A **native, pure-standard-library** Python SDK for
+[RCP](https://rcp-6d6ef6d5.mintlify.site/) — the open, versioned JSON-RPC
+protocol that lets any RAG engine expose
+`embed` / `rerank` / `retrieve` / `graph` / `index` / `catalog`, and any client
+consume it uniformly.
+
+No dependencies, no compiler, no build step — just `subprocess`, `http`, `socket`,
+and `json` from the standard library. It speaks the exact same wire format as the
+[C++](../cpp), [Node.js](../node), and [Rust](../rust) SDKs, so a Python client
+and a C++/Node/Rust server (or vice-versa) interoperate byte-for-byte.
+
+## Install
+
+```sh
+pip install rcp-protocol
+```
+
+Requires Python ≥ 3.9. The import name is `rcp`:
+
+```python
+import rcp
+```
+
+## Client
+
+Connect to any RCP server over a subprocess (stdio) or HTTP, then make typed,
+capability-gated calls.
+
+```python
+import rcp
+
+c = rcp.connect_stdio(["python3", "my_server.py"])
+# or: c = rcp.connect_http("http://127.0.0.1:8000/rcp")
+
+print(c.server(), c.protocol_version(), list(c.capabilities()))
+
+if c.supports(rcp.Capability.Retrieve):
+    for hit in c.retrieve("eiffel tower", k=3):
+        print(hit["id"], hit["score"], hit["text"])
+
+if c.supports(rcp.Capability.Embed):
+    (vec,) = c.embed(["hello world"])
+    print("dim", len(vec))
+
+c.shutdown()
+```
+
+A call to a capability the server never advertised raises **before** any I/O:
+
+```python
+try:
+    c.rerank("q", ["a", "b"])
+except rcp.RcpError as e:
+    # e.code == rcp.Errc.CAPABILITY_MISSING  (-32003)
+    ...
+```
+
+Client methods: `embed`, `embed_sparse`, `embed_multi`, `rerank`, `retrieve`,
+`search` (returns `hits` + `usage` + `nextCursor`), `graph`, `transform`,
+`index_add`, `index_delete`, `catalog`, `info`, `ping`, `call`, `shutdown`.
+
+## Server
+
+Expose a Python RAG engine as an RCP server.
+
+```python
+import rcp
+
+s = rcp.Server()
+s.set_info("my-engine", "1.0")
+s.advertise(rcp.Capability.Retrieve, {"maxK": 100, "modes": ["hybrid"]})
+
+@s.on(rcp.Method.RETRIEVE)
+def _(params):
+    hits = my_index.search(params["query"], params.get("k", 10))
+    return {"hits": [{"id": h.id, "score": h.score, "text": h.text} for h in hits]}
+
+s.serve_stdio()          # or: s.serve_http(8000)
+```
+
+The `Server` owns the `initialize` handshake, capability gating, JSON-RPC framing
+and batching, and error mapping. It answers `initialize` / `info` / `ping` /
+`shutdown` itself; a gated call before `initialize` is `-32001`, an unadvertised
+or unimplemented method is `-32003`, an unknown method is `-32004`.
+
+## Selecting a backend
+
+Pick one engine from a registry — by id, by required capability, or by priority
+with liveness fallback. Connection is lazy.
+
+```python
+sel = rcp.Selector.loads('''{
+  "engines": [
+    {"id": "docs", "transport": "stdio", "command": ["python3", "server.py"], "priority": 10},
+    {"id": "web",  "transport": "http",  "url": "http://127.0.0.1:8000/rcp",   "priority": 5}
+  ]
+}''')
+
+c = sel.select_capable(rcp.Capability.Retrieve)
+```
+
+## Examples & tests
+
+```sh
+python3 examples/example_server.py            # stdio (default)
+python3 examples/example_server.py --http 8000
+python3 examples/example_client.py            # drives the example server
+
+python3 test_bindings.py                      # smoke test incl. Python client ↔ C++ server
+```
+
+## License
+
+MIT © 2026 Ayush Bhat.

rcp_protocol-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+rcp/__init__.py,sha256=N8uA_Zn2CHlUTDy2t9P61As6fFtLkzxR843ALveRUCc,2288
+rcp/_client.py,sha256=oUX7HB0GwRY3GI1R8VFqbfYuQ7qk__jFdOXFzqv6DlE,9267
+rcp/_selector.py,sha256=fo2RZIJBbFh3lL9AYzmBqM1AfRmr1cRc6F6lyr_jEi8,5825
+rcp/_server.py,sha256=GVy4nR5AwyuHMA5AMLNghdhWtJV85lAxGEB33T1Rdv0,11066
+rcp/_transport.py,sha256=90MxHyHk6oFhWQbtiJkpmkPnxv56qiH3K15MJ5U726E,5287
+rcp/_types.py,sha256=t1kWDWUkMX_INbdQKLYJDLD1tai6cxOoKh3YOIdiPUk,4306
+rcp_protocol-1.0.0.dist-info/licenses/LICENSE,sha256=z64CEQ5xJIj69_97LLH5UTFFKIfX7T-3hLUWRtfGt9U,1067
+rcp_protocol-1.0.0.dist-info/METADATA,sha256=yGAG72Dp5uWWFzMo-P2PfWHZGB8bHiXNDJ-MBMRl1t4,4508
+rcp_protocol-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+rcp_protocol-1.0.0.dist-info/top_level.txt,sha256=1fy4Y26VJuryrN2s_38oW3KxNMz6lD6MaNUZW8tKPiE,4
+rcp_protocol-1.0.0.dist-info/RECORD,,

rcp_protocol-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rcp_protocol-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayush Bhat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rcp_protocol-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rcp