privaterag

Python client SDK facade for PrivateRAG.

The package provides lightweight public API types, public-cache initialization, native Rust retrieval primitives, and end-to-end HTTP PIR retrieval:

• PrivateRAGClient
• ClientConfig
• RetrievalOptions
• RetrievalResult
• RetrievedChunk
• SearchHit
• PreparedRetrievalQuery
• typed SDK exceptions

PrivateRAGClient.from_manifest(...) downloads and validates the public client cache from a v0 retrieval server. It requests only manifest.json, checksums.json, index/*, pir/scheme.json, and pir/client_hint.bin.

Install:

pip install privaterag

Prebuilt wheels include the Rust/PyO3 native extension as privaterag._native, so normal installs do not need Rust when a wheel is available for the target platform.

For local workspace development, native operations can be built with PyO3/maturin:

cd python/privaterag
maturin develop

After the native extension is installed, PrivateRAGClient.search_by_embedding(...), PrivateRAGClient.prepare_retrieval_query_by_embedding(...), and PrivateRAGClient.decode_retrieval_response(...) call the Rust public-cache client. PrivateRAGClient.retrieve(...) embeds locally, prepares a padded BatchedPirQuery, posts only that JSON envelope to /pir/query, and decodes the BatchedPirResponse locally.

from privaterag import PrivateRAGClient


client = PrivateRAGClient.from_manifest(
    "http://127.0.0.1:8080/manifest.json",
    embed_query=embed_query,
)

results = client.retrieve("What is the policy?", top_k=2)
context = results.to_context()

top_k must be positive. Configured or per-call retrieval_count must be positive and greater than or equal to top_k; otherwise retrieval fails before the SDK posts a PIR request. For the supported simplepir-rs-v0-1000-1k profile, the supported v0 shape is exactly top_k=2 and retrieval_count=4; other shapes fail closed until fresh evidence expands the profile. See ../../docs/padding_policy.md.

See ../../docs/client_api.md for the client API and privacy boundary.