rcp-protocol 1.0.0__tar.gz

rcp_protocol-1.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,116 @@
+# 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/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rcp-protocol"
+version = "1.0.0"
+description = "Retrieval Context Protocol — native Python SDK (pure standard library, no dependencies)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "RCP Working Group" }]
+keywords = ["rcp", "rag", "retrieval", "protocol", "json-rpc", "mcp", "acp"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+[tool.setuptools]
+packages = ["rcp"]
+
+[project.urls]
+Homepage = "https://rcp-6d6ef6d5.mintlify.site/"
+Documentation = "https://rcp-6d6ef6d5.mintlify.site/"
+Specification = "https://github.com/1ay1/rcp/blob/main/spec/rcp-1.0.md"
+Source = "https://github.com/1ay1/rcp"
+Changelog = "https://rcp-6d6ef6d5.mintlify.site/reference/changelog"
+Issues = "https://github.com/1ay1/rcp/issues"

rcp_protocol-1.0.0/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_protocol-1.0.0/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 {}