Metadata-Version: 2.4
Name: privaterag
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Summary: PrivateRAG Python SDK with Rust-backed local search and PIR retrieval.
Keywords: privacy,rag,pir,retrieval
Home-Page: https://github.com/erdkocak/PrivateRAG
Author: PrivateRAG maintainers
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/erdkocak/PrivateRAG/tree/main/docs
Project-URL: Homepage, https://github.com/erdkocak/PrivateRAG
Project-URL: Issues, https://github.com/erdkocak/PrivateRAG/issues
Project-URL: Repository, https://github.com/erdkocak/PrivateRAG

# 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:

```bash
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:

```bash
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.

```python
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.

