Skip to main content

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.utils logs retrieved chunk text at DEBUG level, which is upstream of this package. Keep the llama_index logger 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 ObscateError is raised.
  • Set OBSCATE_BASE_URL to 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)

Source distribution for llama-index-postprocessor-obscate 0.1.0
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)

Table of built distributions (wheels) for llama-index-postprocessor-obscate 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page