llama-index-postprocessor-obscate
Reversible PII redaction for LlamaIndex RAG. The question and the retrieved chunks are redacted before the LLM sees them, and the answer comes back with the real values restored. Your index and your citations stay untouched.
It is a thin wrapper over the Obscate HTTP API. Detection runs in the API, not in this package. Full docs: obscate.com/docs/llamaindex.
Known limitation: partial values come back wrong
If the model quotes only part of a redacted value ("your card ending in
7588", "the email starting with…"), restore can't fix it: it matches whole
tokens, and a fragment isn't one. With fpe this fails silently and
plausibly. The fake card looks like a real card, so its last four digits
look like real digits, and your user sees a confident, wrong statement about
their own data. Assistants paraphrase values like this all the time, so expect
it in normal use.
What we measured with real Claude (claude-haiku-5-5, a support-reply prompt,
3 runs each; a small test, not a guarantee):
| setup | replies stating wrong card digits |
|---|---|
fpe, plain prompt |
2 of 3 |
fpe + the instruction below in the system prompt |
0 of 3 |
tokenize, plain prompt |
0 of 3 |
For user-facing output where the model may paraphrase values:
- Add to your system prompt: "When you mention a card number, email or phone number, repeat it exactly and in full as given. Never abbreviate, mask or quote part of it."
- Or use
strategy="tokenize": models treat[CREDIT_CARD_1]as a unit and don't split it, and restore only touches tokens in its map.
Partial references are a boundary of any reversible-redaction approach, not only ours: once the model only sees a stand-in, a fragment of the stand-in can never map back to a fragment of the original.
Quickstart (under 5 minutes)
pip install "llama-index-postprocessor-obscate[examples]"
export OBSCATE_API_KEY=ob_... # free: 1,000 requests/month at https://obscate.com, no card
export ANTHROPIC_API_KEY=sk-ant-... # optional: without it the example uses a local stand-in LLM
python examples/quickstart.py
Real output (stand-in LLM, Obscate engine; redacted values differ per key):
1) Your question:
What does Ravi Kumar want, and what email should we reply to?
2) What the LLM receives:
Ticket 813: Priya Sharma (mlaem@bskcfsg.org) asked to change her delivery address.
Ticket 812: [PERSON:wdmvms3g…] (seab.yomog@tziwxuo.com, +91 45671 58378) was charged twice on card 7982 1772 2838 5004 ...
Query: What does [PERSON:wdmvms3g…] want, and what email should we reply to?
3) Restored answer for your user:
(stand-in LLM) From the tickets: Ticket 812: Ravi Kumar (ravi.kumar@example.com, +91 98765 43210) was charged twice ...
Look at line 2: "Priya Sharma" was not caught in that sentence, while "Ravi Kumar" was. That is typical. Emails, phones, cards and Indian IDs are near-perfect because they use patterns and checksums. Names and places come from an NER model and are best-effort. Test on your own data. (Detectors, benchmark.)
Use it
One step: wrap your query engine.
from llama_index.postprocessor.obscate import ObscateQueryEngine
qe = ObscateQueryEngine.wrap(index.as_query_engine(llm=llm)) # strategy="fpe" by default
print(qe.query("What did Ravi Kumar ask about?")) # answer restored
Or build it from parts with
ObscateQueryEngine.from_args(retriever, llm=llm, strategy="tokenize").
Retrieval runs on the original query against your own index. Only the
synthesis LLM sees redacted text. The query and all chunks go in one
Obscate request, so tokens are consistent: the same person gets the same
token in the question and in the chunks.
Node postprocessor, for pipelines you assemble yourself:
from llama_index.postprocessor.obscate import ObscatePostprocessor
obscate = ObscatePostprocessor() # fpe: restore needs no state
qe = index.as_query_engine(llm=llm, node_postprocessors=[obscate])
answer = obscate.restore(qe.query("Summarise ticket 812"))
A postprocessor can't change the question text, which still reaches the LLM
unredacted. Use ObscateQueryEngine when questions contain PII. With
tokenize/synthetic, the postprocessor keeps the last token map per thread
in memory, so call restore in the same thread before the next query.
String metadata the LLM would see (for example author) is redacted too.
Keys listed in excluded_llm_metadata_keys are not sent at all. Turn this off
with redact_metadata=False.
Strategies
fpe (default) keeps formats, for example valid-looking card numbers and
email-shaped addresses. Values that can't keep their format, such as names,
become bracketed [PERSON:…] tokens. Restoring fpe needs only your key.
tokenize ([EMAIL_1]) and synthetic (realistic fakes) restore from an
in-memory token map. mask, hash and partial are one-way, so the answer
stays redacted.
fpe caveat: an email, phone or ID the model invents (never redacted)
can't be told apart from an fpe token, and restore turns it into a different
value. Use tokenize if that matters.
Key versions are handled for you. The query engine restores with the
key_version its redaction returned, so a key rotation on Obscate's side
never breaks an answer. If you keep fpe output to restore later, keep
key_version with it.
What it does not cover
- Embeddings. Your embedding model sees raw text when you index and query. If it is a remote API, use a local embedding model or redact documents before indexing.
- Streaming. Answers are read to completion and then restored, because a token can be split across chunks.
- LlamaIndex's own DEBUG logs.
llama_index.core.indices.utilslogs retrieved chunk text at DEBUG level, which is upstream of this package. Keep thellama_indexlogger at INFO or above in production.
Cost, failure and self-hosting
- 1 Obscate request per query (1 unit per 100 KB). Restores are free. The free tier covers 1,000 queries a month (pricing).
- Fails closed. If Obscate errors, the LLM is not called and
ObscateErroris raised. - Set
OBSCATE_BASE_URLto use a self-hosted Obscate. The self-hosted edition is in pilot; ask contact@obscate.com.
Privacy
This package never logs, prints or writes the text, the detected values or
the token map. Errors carry the HTTP status and the API's fixed message only.
This is enforced by tests/test_llama_index_obscate.py::test_privacy_*.
Develop
pip install -e '.[test]' && pytest -q # unit tests against an in-process fake API (no network)
License: MIT.
Metadata
Release files for llama-index-postprocessor-obscate 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| llama_index_postprocessor_obscate-0.1.0.tar.gz | 17.1 kB | Without provenance | Details for llama_index_postprocessor_obscate-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| llama_index_postprocessor_obscate-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for llama_index_postprocessor_obscate-0.1.0-py3-none-any.whl |
Total release size: 30.6 kB
Release files / llama_index_postprocessor_obscate-0.1.0.tar.gz
| Download URL | llama_index_postprocessor_obscate-0.1.0.tar.gz |
|---|---|
| Size | 17.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ef34a200a9734b5386fcb1d8bae38f61a8ecdc10b7332ce4efd063d083eeec8
|
|
BLAKE2b-256 checksum How to use checksums |
831ca439b76f292f832f2c7dd92b342b8f88f40c5857d2e323192c4cb969d427
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / llama_index_postprocessor_obscate-0.1.0-py3-none-any.whl
| Download URL | llama_index_postprocessor_obscate-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4bae06320da7f39866c16583227df38ae962c37d21fbb9157db4b865b285591f
|
|
BLAKE2b-256 checksum How to use checksums |
688e1e38cdf04e9a3a12565cf3fa2709c02b38e8596233204d0d6ed6bca73f95
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for llama-index-postprocessor-obscate 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.