llama-index-postprocessor-obscate 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- llama_index_postprocessor_obscate-0.1.0/.gitignore +12 -0
- llama_index_postprocessor_obscate-0.1.0/LICENSE +21 -0
- llama_index_postprocessor_obscate-0.1.0/PKG-INFO +177 -0
- llama_index_postprocessor_obscate-0.1.0/README.md +157 -0
- llama_index_postprocessor_obscate-0.1.0/examples/quickstart.py +100 -0
- llama_index_postprocessor_obscate-0.1.0/pyproject.toml +29 -0
- llama_index_postprocessor_obscate-0.1.0/src/llama_index/postprocessor/obscate/__init__.py +7 -0
- llama_index_postprocessor_obscate-0.1.0/src/llama_index/postprocessor/obscate/_client.py +306 -0
- llama_index_postprocessor_obscate-0.1.0/src/llama_index/postprocessor/obscate/base.py +242 -0
- llama_index_postprocessor_obscate-0.1.0/tests/fake_api.py +157 -0
- llama_index_postprocessor_obscate-0.1.0/tests/test_llama_index_obscate.py +164 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Skycast
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: llama-index-postprocessor-obscate
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Reversible PII redaction for LlamaIndex: redact retrieved nodes and queries before the LLM, restore the answer (Obscate API)
|
|
5
|
+
Project-URL: Homepage, https://obscate.com
|
|
6
|
+
Project-URL: Documentation, https://obscate.com/docs/llamaindex
|
|
7
|
+
Author: Skycast
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: dpdp,gdpr,llama-index,llamaindex,pii,privacy,rag,redaction
|
|
11
|
+
Requires-Python: >=3.10
|
|
12
|
+
Requires-Dist: httpx>=0.27
|
|
13
|
+
Requires-Dist: llama-index-core<0.15,>=0.12
|
|
14
|
+
Provides-Extra: examples
|
|
15
|
+
Requires-Dist: anthropic<2,>=0.75; extra == 'examples'
|
|
16
|
+
Requires-Dist: llama-index-llms-anthropic>=0.6; extra == 'examples'
|
|
17
|
+
Provides-Extra: test
|
|
18
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
# llama-index-postprocessor-obscate
|
|
22
|
+
|
|
23
|
+
Reversible PII redaction for LlamaIndex RAG. The question and the retrieved
|
|
24
|
+
chunks are redacted before the LLM sees them, and the answer comes back with
|
|
25
|
+
the real values restored. Your index and your citations stay untouched.
|
|
26
|
+
|
|
27
|
+
It is a thin wrapper over the [Obscate](https://obscate.com) HTTP API.
|
|
28
|
+
Detection runs in the API, not in this package. Full docs:
|
|
29
|
+
[obscate.com/docs/llamaindex](https://obscate.com/docs/llamaindex).
|
|
30
|
+
|
|
31
|
+
## Known limitation: partial values come back wrong
|
|
32
|
+
|
|
33
|
+
If the model quotes only **part** of a redacted value ("your card ending in
|
|
34
|
+
7588", "the email starting with…"), restore can't fix it: it matches whole
|
|
35
|
+
tokens, and a fragment isn't one. With `fpe` this fails **silently and
|
|
36
|
+
plausibly**. The fake card looks like a real card, so its last four digits
|
|
37
|
+
look like real digits, and your user sees a confident, wrong statement about
|
|
38
|
+
their own data. Assistants paraphrase values like this all the time, so expect
|
|
39
|
+
it in normal use.
|
|
40
|
+
|
|
41
|
+
What we measured with real Claude (`claude-haiku-5-5`, a support-reply prompt,
|
|
42
|
+
3 runs each; a small test, not a guarantee):
|
|
43
|
+
|
|
44
|
+
| setup | replies stating wrong card digits |
|
|
45
|
+
|---|---|
|
|
46
|
+
| `fpe`, plain prompt | 2 of 3 |
|
|
47
|
+
| `fpe` + the instruction below in the system prompt | 0 of 3 |
|
|
48
|
+
| `tokenize`, plain prompt | 0 of 3 |
|
|
49
|
+
|
|
50
|
+
For user-facing output where the model may paraphrase values:
|
|
51
|
+
|
|
52
|
+
- Add to your system prompt: *"When you mention a card number, email or phone
|
|
53
|
+
number, repeat it exactly and in full as given. Never abbreviate, mask or
|
|
54
|
+
quote part of it."*
|
|
55
|
+
- Or use `strategy="tokenize"`: models treat `[CREDIT_CARD_1]` as a unit and
|
|
56
|
+
don't split it, and restore only touches tokens in its map.
|
|
57
|
+
|
|
58
|
+
Partial references are a boundary of any reversible-redaction approach, not
|
|
59
|
+
only ours: once the model only sees a stand-in, a fragment of the stand-in can
|
|
60
|
+
never map back to a fragment of the original.
|
|
61
|
+
|
|
62
|
+
## Quickstart (under 5 minutes)
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pip install "llama-index-postprocessor-obscate[examples]"
|
|
66
|
+
export OBSCATE_API_KEY=ob_... # free: 1,000 requests/month at https://obscate.com, no card
|
|
67
|
+
export ANTHROPIC_API_KEY=sk-ant-... # optional: without it the example uses a local stand-in LLM
|
|
68
|
+
python examples/quickstart.py
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Real output (stand-in LLM, Obscate engine; redacted values differ per key):
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
1) Your question:
|
|
75
|
+
What does Ravi Kumar want, and what email should we reply to?
|
|
76
|
+
2) What the LLM receives:
|
|
77
|
+
Ticket 813: Priya Sharma (mlaem@bskcfsg.org) asked to change her delivery address.
|
|
78
|
+
Ticket 812: [PERSON:wdmvms3g…] (seab.yomog@tziwxuo.com, +91 45671 58378) was charged twice on card 7982 1772 2838 5004 ...
|
|
79
|
+
Query: What does [PERSON:wdmvms3g…] want, and what email should we reply to?
|
|
80
|
+
3) Restored answer for your user:
|
|
81
|
+
(stand-in LLM) From the tickets: Ticket 812: Ravi Kumar (ravi.kumar@example.com, +91 98765 43210) was charged twice ...
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Look at line 2: **"Priya Sharma" was not caught** in that sentence, while
|
|
85
|
+
"Ravi Kumar" was. That is typical. Emails, phones, cards and Indian IDs are
|
|
86
|
+
near-perfect because they use patterns and checksums. Names and places come
|
|
87
|
+
from an NER model and are best-effort. Test on your own data.
|
|
88
|
+
([Detectors](https://obscate.com/docs/detectors), [benchmark](https://obscate.com/docs/benchmark).)
|
|
89
|
+
|
|
90
|
+
## Use it
|
|
91
|
+
|
|
92
|
+
**One step: wrap your query engine.**
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from llama_index.postprocessor.obscate import ObscateQueryEngine
|
|
96
|
+
|
|
97
|
+
qe = ObscateQueryEngine.wrap(index.as_query_engine(llm=llm)) # strategy="fpe" by default
|
|
98
|
+
print(qe.query("What did Ravi Kumar ask about?")) # answer restored
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Or build it from parts with
|
|
102
|
+
`ObscateQueryEngine.from_args(retriever, llm=llm, strategy="tokenize")`.
|
|
103
|
+
Retrieval runs on the original query against your own index. Only the
|
|
104
|
+
synthesis LLM sees redacted text. The query and all chunks go in **one**
|
|
105
|
+
Obscate request, so tokens are consistent: the same person gets the same
|
|
106
|
+
token in the question and in the chunks.
|
|
107
|
+
|
|
108
|
+
**Node postprocessor, for pipelines you assemble yourself:**
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
from llama_index.postprocessor.obscate import ObscatePostprocessor
|
|
112
|
+
|
|
113
|
+
obscate = ObscatePostprocessor() # fpe: restore needs no state
|
|
114
|
+
qe = index.as_query_engine(llm=llm, node_postprocessors=[obscate])
|
|
115
|
+
answer = obscate.restore(qe.query("Summarise ticket 812"))
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
A postprocessor can't change the question text, which still reaches the LLM
|
|
119
|
+
unredacted. Use `ObscateQueryEngine` when questions contain PII. With
|
|
120
|
+
`tokenize`/`synthetic`, the postprocessor keeps the last token map per thread
|
|
121
|
+
in memory, so call `restore` in the same thread before the next query.
|
|
122
|
+
|
|
123
|
+
String metadata the LLM would see (for example `author`) is redacted too.
|
|
124
|
+
Keys listed in `excluded_llm_metadata_keys` are not sent at all. Turn this off
|
|
125
|
+
with `redact_metadata=False`.
|
|
126
|
+
|
|
127
|
+
## Strategies
|
|
128
|
+
|
|
129
|
+
`fpe` (default) keeps formats, for example valid-looking card numbers and
|
|
130
|
+
email-shaped addresses. Values that can't keep their format, such as names,
|
|
131
|
+
become bracketed `[PERSON:…]` tokens. Restoring fpe needs only your key.
|
|
132
|
+
`tokenize` (`[EMAIL_1]`) and `synthetic` (realistic fakes) restore from an
|
|
133
|
+
in-memory token map. `mask`, `hash` and `partial` are one-way, so the answer
|
|
134
|
+
stays redacted.
|
|
135
|
+
|
|
136
|
+
**fpe caveat:** an email, phone or ID the model *invents* (never redacted)
|
|
137
|
+
can't be told apart from an fpe token, and restore turns it into a different
|
|
138
|
+
value. Use `tokenize` if that matters.
|
|
139
|
+
|
|
140
|
+
**Key versions are handled for you.** The query engine restores with the
|
|
141
|
+
`key_version` its redaction returned, so a key rotation on Obscate's side
|
|
142
|
+
never breaks an answer. If you keep fpe output to restore later, keep
|
|
143
|
+
`key_version` with it.
|
|
144
|
+
|
|
145
|
+
## What it does not cover
|
|
146
|
+
|
|
147
|
+
- **Embeddings.** Your embedding model sees raw text when you index and query.
|
|
148
|
+
If it is a remote API, use a local embedding model or redact documents
|
|
149
|
+
before indexing.
|
|
150
|
+
- **Streaming.** Answers are read to completion and then restored, because a
|
|
151
|
+
token can be split across chunks.
|
|
152
|
+
- **LlamaIndex's own DEBUG logs.** `llama_index.core.indices.utils` logs
|
|
153
|
+
retrieved chunk text at DEBUG level, which is upstream of this package.
|
|
154
|
+
Keep the `llama_index` logger at INFO or above in production.
|
|
155
|
+
|
|
156
|
+
## Cost, failure and self-hosting
|
|
157
|
+
|
|
158
|
+
- 1 Obscate request per query (1 unit per 100 KB). Restores are free. The
|
|
159
|
+
free tier covers 1,000 queries a month ([pricing](https://obscate.com/pricing)).
|
|
160
|
+
- **Fails closed.** If Obscate errors, the LLM is not called and
|
|
161
|
+
`ObscateError` is raised.
|
|
162
|
+
- Set `OBSCATE_BASE_URL` to use a self-hosted Obscate. The self-hosted
|
|
163
|
+
edition is in pilot; ask contact@obscate.com.
|
|
164
|
+
|
|
165
|
+
## Privacy
|
|
166
|
+
|
|
167
|
+
This package never logs, prints or writes the text, the detected values or
|
|
168
|
+
the token map. Errors carry the HTTP status and the API's fixed message only.
|
|
169
|
+
This is enforced by `tests/test_llama_index_obscate.py::test_privacy_*`.
|
|
170
|
+
|
|
171
|
+
## Develop
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
pip install -e '.[test]' && pytest -q # unit tests against an in-process fake API (no network)
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
License: MIT.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# llama-index-postprocessor-obscate
|
|
2
|
+
|
|
3
|
+
Reversible PII redaction for LlamaIndex RAG. The question and the retrieved
|
|
4
|
+
chunks are redacted before the LLM sees them, and the answer comes back with
|
|
5
|
+
the real values restored. Your index and your citations stay untouched.
|
|
6
|
+
|
|
7
|
+
It is a thin wrapper over the [Obscate](https://obscate.com) HTTP API.
|
|
8
|
+
Detection runs in the API, not in this package. Full docs:
|
|
9
|
+
[obscate.com/docs/llamaindex](https://obscate.com/docs/llamaindex).
|
|
10
|
+
|
|
11
|
+
## Known limitation: partial values come back wrong
|
|
12
|
+
|
|
13
|
+
If the model quotes only **part** of a redacted value ("your card ending in
|
|
14
|
+
7588", "the email starting with…"), restore can't fix it: it matches whole
|
|
15
|
+
tokens, and a fragment isn't one. With `fpe` this fails **silently and
|
|
16
|
+
plausibly**. The fake card looks like a real card, so its last four digits
|
|
17
|
+
look like real digits, and your user sees a confident, wrong statement about
|
|
18
|
+
their own data. Assistants paraphrase values like this all the time, so expect
|
|
19
|
+
it in normal use.
|
|
20
|
+
|
|
21
|
+
What we measured with real Claude (`claude-haiku-5-5`, a support-reply prompt,
|
|
22
|
+
3 runs each; a small test, not a guarantee):
|
|
23
|
+
|
|
24
|
+
| setup | replies stating wrong card digits |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `fpe`, plain prompt | 2 of 3 |
|
|
27
|
+
| `fpe` + the instruction below in the system prompt | 0 of 3 |
|
|
28
|
+
| `tokenize`, plain prompt | 0 of 3 |
|
|
29
|
+
|
|
30
|
+
For user-facing output where the model may paraphrase values:
|
|
31
|
+
|
|
32
|
+
- Add to your system prompt: *"When you mention a card number, email or phone
|
|
33
|
+
number, repeat it exactly and in full as given. Never abbreviate, mask or
|
|
34
|
+
quote part of it."*
|
|
35
|
+
- Or use `strategy="tokenize"`: models treat `[CREDIT_CARD_1]` as a unit and
|
|
36
|
+
don't split it, and restore only touches tokens in its map.
|
|
37
|
+
|
|
38
|
+
Partial references are a boundary of any reversible-redaction approach, not
|
|
39
|
+
only ours: once the model only sees a stand-in, a fragment of the stand-in can
|
|
40
|
+
never map back to a fragment of the original.
|
|
41
|
+
|
|
42
|
+
## Quickstart (under 5 minutes)
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pip install "llama-index-postprocessor-obscate[examples]"
|
|
46
|
+
export OBSCATE_API_KEY=ob_... # free: 1,000 requests/month at https://obscate.com, no card
|
|
47
|
+
export ANTHROPIC_API_KEY=sk-ant-... # optional: without it the example uses a local stand-in LLM
|
|
48
|
+
python examples/quickstart.py
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Real output (stand-in LLM, Obscate engine; redacted values differ per key):
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
1) Your question:
|
|
55
|
+
What does Ravi Kumar want, and what email should we reply to?
|
|
56
|
+
2) What the LLM receives:
|
|
57
|
+
Ticket 813: Priya Sharma (mlaem@bskcfsg.org) asked to change her delivery address.
|
|
58
|
+
Ticket 812: [PERSON:wdmvms3g…] (seab.yomog@tziwxuo.com, +91 45671 58378) was charged twice on card 7982 1772 2838 5004 ...
|
|
59
|
+
Query: What does [PERSON:wdmvms3g…] want, and what email should we reply to?
|
|
60
|
+
3) Restored answer for your user:
|
|
61
|
+
(stand-in LLM) From the tickets: Ticket 812: Ravi Kumar (ravi.kumar@example.com, +91 98765 43210) was charged twice ...
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Look at line 2: **"Priya Sharma" was not caught** in that sentence, while
|
|
65
|
+
"Ravi Kumar" was. That is typical. Emails, phones, cards and Indian IDs are
|
|
66
|
+
near-perfect because they use patterns and checksums. Names and places come
|
|
67
|
+
from an NER model and are best-effort. Test on your own data.
|
|
68
|
+
([Detectors](https://obscate.com/docs/detectors), [benchmark](https://obscate.com/docs/benchmark).)
|
|
69
|
+
|
|
70
|
+
## Use it
|
|
71
|
+
|
|
72
|
+
**One step: wrap your query engine.**
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
from llama_index.postprocessor.obscate import ObscateQueryEngine
|
|
76
|
+
|
|
77
|
+
qe = ObscateQueryEngine.wrap(index.as_query_engine(llm=llm)) # strategy="fpe" by default
|
|
78
|
+
print(qe.query("What did Ravi Kumar ask about?")) # answer restored
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Or build it from parts with
|
|
82
|
+
`ObscateQueryEngine.from_args(retriever, llm=llm, strategy="tokenize")`.
|
|
83
|
+
Retrieval runs on the original query against your own index. Only the
|
|
84
|
+
synthesis LLM sees redacted text. The query and all chunks go in **one**
|
|
85
|
+
Obscate request, so tokens are consistent: the same person gets the same
|
|
86
|
+
token in the question and in the chunks.
|
|
87
|
+
|
|
88
|
+
**Node postprocessor, for pipelines you assemble yourself:**
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
from llama_index.postprocessor.obscate import ObscatePostprocessor
|
|
92
|
+
|
|
93
|
+
obscate = ObscatePostprocessor() # fpe: restore needs no state
|
|
94
|
+
qe = index.as_query_engine(llm=llm, node_postprocessors=[obscate])
|
|
95
|
+
answer = obscate.restore(qe.query("Summarise ticket 812"))
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
A postprocessor can't change the question text, which still reaches the LLM
|
|
99
|
+
unredacted. Use `ObscateQueryEngine` when questions contain PII. With
|
|
100
|
+
`tokenize`/`synthetic`, the postprocessor keeps the last token map per thread
|
|
101
|
+
in memory, so call `restore` in the same thread before the next query.
|
|
102
|
+
|
|
103
|
+
String metadata the LLM would see (for example `author`) is redacted too.
|
|
104
|
+
Keys listed in `excluded_llm_metadata_keys` are not sent at all. Turn this off
|
|
105
|
+
with `redact_metadata=False`.
|
|
106
|
+
|
|
107
|
+
## Strategies
|
|
108
|
+
|
|
109
|
+
`fpe` (default) keeps formats, for example valid-looking card numbers and
|
|
110
|
+
email-shaped addresses. Values that can't keep their format, such as names,
|
|
111
|
+
become bracketed `[PERSON:…]` tokens. Restoring fpe needs only your key.
|
|
112
|
+
`tokenize` (`[EMAIL_1]`) and `synthetic` (realistic fakes) restore from an
|
|
113
|
+
in-memory token map. `mask`, `hash` and `partial` are one-way, so the answer
|
|
114
|
+
stays redacted.
|
|
115
|
+
|
|
116
|
+
**fpe caveat:** an email, phone or ID the model *invents* (never redacted)
|
|
117
|
+
can't be told apart from an fpe token, and restore turns it into a different
|
|
118
|
+
value. Use `tokenize` if that matters.
|
|
119
|
+
|
|
120
|
+
**Key versions are handled for you.** The query engine restores with the
|
|
121
|
+
`key_version` its redaction returned, so a key rotation on Obscate's side
|
|
122
|
+
never breaks an answer. If you keep fpe output to restore later, keep
|
|
123
|
+
`key_version` with it.
|
|
124
|
+
|
|
125
|
+
## What it does not cover
|
|
126
|
+
|
|
127
|
+
- **Embeddings.** Your embedding model sees raw text when you index and query.
|
|
128
|
+
If it is a remote API, use a local embedding model or redact documents
|
|
129
|
+
before indexing.
|
|
130
|
+
- **Streaming.** Answers are read to completion and then restored, because a
|
|
131
|
+
token can be split across chunks.
|
|
132
|
+
- **LlamaIndex's own DEBUG logs.** `llama_index.core.indices.utils` logs
|
|
133
|
+
retrieved chunk text at DEBUG level, which is upstream of this package.
|
|
134
|
+
Keep the `llama_index` logger at INFO or above in production.
|
|
135
|
+
|
|
136
|
+
## Cost, failure and self-hosting
|
|
137
|
+
|
|
138
|
+
- 1 Obscate request per query (1 unit per 100 KB). Restores are free. The
|
|
139
|
+
free tier covers 1,000 queries a month ([pricing](https://obscate.com/pricing)).
|
|
140
|
+
- **Fails closed.** If Obscate errors, the LLM is not called and
|
|
141
|
+
`ObscateError` is raised.
|
|
142
|
+
- Set `OBSCATE_BASE_URL` to use a self-hosted Obscate. The self-hosted
|
|
143
|
+
edition is in pilot; ask contact@obscate.com.
|
|
144
|
+
|
|
145
|
+
## Privacy
|
|
146
|
+
|
|
147
|
+
This package never logs, prints or writes the text, the detected values or
|
|
148
|
+
the token map. Errors carry the HTTP status and the API's fixed message only.
|
|
149
|
+
This is enforced by `tests/test_llama_index_obscate.py::test_privacy_*`.
|
|
150
|
+
|
|
151
|
+
## Develop
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
pip install -e '.[test]' && pytest -q # unit tests against an in-process fake API (no network)
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
License: MIT.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
"""llama-index-postprocessor-obscate end-to-end: RAG where the LLM never sees the PII.
|
|
2
|
+
|
|
3
|
+
pip install "llama-index-postprocessor-obscate[examples]"
|
|
4
|
+
export OBSCATE_API_KEY=ob_... # free key: https://obscate.com
|
|
5
|
+
export ANTHROPIC_API_KEY=sk-ant-... # optional; without it a local stand-in LLM is used
|
|
6
|
+
python examples/quickstart.py
|
|
7
|
+
|
|
8
|
+
Costs: 1 Obscate request per query (free tier: 1,000/month) and one small LLM
|
|
9
|
+
call if ANTHROPIC_API_KEY is set. Embeddings use LlamaIndex's MockEmbedding, so
|
|
10
|
+
no embedding key is needed (retrieval is trivial with 3 documents).
|
|
11
|
+
"""
|
|
12
|
+
import os
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
from llama_index.core import Document, MockEmbedding, VectorStoreIndex
|
|
17
|
+
from llama_index.core.llms import CompletionResponse, CustomLLM, LLMMetadata
|
|
18
|
+
from llama_index.core.llms.callbacks import llm_completion_callback
|
|
19
|
+
|
|
20
|
+
from llama_index.postprocessor.obscate import ObscateQueryEngine
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def load_env() -> None:
|
|
24
|
+
"""Read KEY=VALUE lines from a .env here or in a parent folder (values never printed)."""
|
|
25
|
+
for d in [Path.cwd(), *Path(__file__).resolve().parents]:
|
|
26
|
+
f = d / ".env"
|
|
27
|
+
if f.is_file():
|
|
28
|
+
for line in f.read_text().splitlines():
|
|
29
|
+
if "=" in line and not line.lstrip().startswith("#"):
|
|
30
|
+
k, v = line.split("=", 1)
|
|
31
|
+
os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
|
|
32
|
+
return
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class StandInLLM(CustomLLM):
|
|
36
|
+
"""Offline stand-in: 'answers' by quoting the first context line it was given."""
|
|
37
|
+
@property
|
|
38
|
+
def metadata(self) -> LLMMetadata:
|
|
39
|
+
return LLMMetadata(model_name="stand-in")
|
|
40
|
+
|
|
41
|
+
@llm_completion_callback()
|
|
42
|
+
def complete(self, prompt: str, formatted: bool = False, **kw: Any) -> CompletionResponse:
|
|
43
|
+
ctx = [l for l in prompt.splitlines() if "charged" in l]
|
|
44
|
+
return CompletionResponse(text="(stand-in LLM) From the tickets: " + (ctx[0].strip() if ctx else "n/a"))
|
|
45
|
+
|
|
46
|
+
@llm_completion_callback()
|
|
47
|
+
def stream_complete(self, prompt: str, formatted: bool = False, **kw: Any):
|
|
48
|
+
yield self.complete(prompt)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class ShowPrompt(CustomLLM):
|
|
52
|
+
"""Demo only: prints the prompt exactly as the LLM provider receives it, then delegates."""
|
|
53
|
+
inner: Any = None
|
|
54
|
+
|
|
55
|
+
@property
|
|
56
|
+
def metadata(self) -> LLMMetadata:
|
|
57
|
+
return LLMMetadata(model_name="show-prompt")
|
|
58
|
+
|
|
59
|
+
@llm_completion_callback()
|
|
60
|
+
def complete(self, prompt: str, formatted: bool = False, **kw: Any) -> CompletionResponse:
|
|
61
|
+
print("2) What the LLM receives:\n" + "\n".join(" " + l for l in prompt.splitlines() if l.strip()))
|
|
62
|
+
return self.inner.complete(prompt, formatted=formatted, **kw)
|
|
63
|
+
|
|
64
|
+
@llm_completion_callback()
|
|
65
|
+
def stream_complete(self, prompt: str, formatted: bool = False, **kw: Any):
|
|
66
|
+
yield self.complete(prompt)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def get_llm():
|
|
70
|
+
if os.environ.get("ANTHROPIC_API_KEY"):
|
|
71
|
+
from llama_index.llms.anthropic import Anthropic
|
|
72
|
+
return Anthropic(model=os.environ.get("ANTHROPIC_MODEL", "claude-haiku-5-5"), max_tokens=1024)
|
|
73
|
+
print("(no ANTHROPIC_API_KEY: using a local stand-in LLM)")
|
|
74
|
+
return StandInLLM()
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def main() -> None:
|
|
78
|
+
load_env()
|
|
79
|
+
if not os.environ.get("OBSCATE_API_KEY"):
|
|
80
|
+
raise SystemExit("Set OBSCATE_API_KEY (free key at https://obscate.com) or put it in a .env file.")
|
|
81
|
+
docs = [
|
|
82
|
+
Document(text="Ticket 812: Ravi Kumar (ravi.kumar@example.com, +91 98765 43210) was charged "
|
|
83
|
+
"twice on card 4242 4242 4242 4242 and wants a refund."),
|
|
84
|
+
Document(text="Ticket 813: Priya Sharma (priya@example.org) asked to change her delivery address."),
|
|
85
|
+
Document(text="Refund policy: duplicate charges are refunded within 5 business days."),
|
|
86
|
+
]
|
|
87
|
+
index = VectorStoreIndex.from_documents(docs, embed_model=MockEmbedding(embed_dim=16))
|
|
88
|
+
llm = ShowPrompt(inner=get_llm())
|
|
89
|
+
|
|
90
|
+
# One step: wrap the normal query engine. strategy="fpe" by default.
|
|
91
|
+
qe = ObscateQueryEngine.wrap(index.as_query_engine(llm=llm, similarity_top_k=3))
|
|
92
|
+
|
|
93
|
+
question = "What does Ravi Kumar want, and what email should we reply to?"
|
|
94
|
+
print("1) Your question:\n ", question)
|
|
95
|
+
answer = qe.query(question)
|
|
96
|
+
print("3) Restored answer for your user:\n ", answer)
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
if __name__ == "__main__":
|
|
100
|
+
main()
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.25"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "llama-index-postprocessor-obscate"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Reversible PII redaction for LlamaIndex: redact retrieved nodes and queries before the LLM, restore the answer (Obscate API)"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [{ name = "Skycast" }]
|
|
13
|
+
keywords = ["llama-index", "llamaindex", "pii", "redaction", "privacy", "rag", "dpdp", "gdpr"]
|
|
14
|
+
dependencies = ["llama-index-core>=0.12,<0.15", "httpx>=0.27"]
|
|
15
|
+
|
|
16
|
+
[project.optional-dependencies]
|
|
17
|
+
# anthropic<2: llama-index-llms-anthropic 0.13.0 breaks on anthropic 2.x (MessageParam is a Union there)
|
|
18
|
+
examples = ["llama-index-llms-anthropic>=0.6", "anthropic>=0.75,<2"]
|
|
19
|
+
test = ["pytest>=8"]
|
|
20
|
+
|
|
21
|
+
[project.urls]
|
|
22
|
+
Homepage = "https://obscate.com"
|
|
23
|
+
Documentation = "https://obscate.com/docs/llamaindex"
|
|
24
|
+
|
|
25
|
+
[tool.hatch.build.targets.wheel]
|
|
26
|
+
packages = ["src/llama_index"]
|
|
27
|
+
|
|
28
|
+
[tool.pytest.ini_options]
|
|
29
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
"""Obscate reversible PII redaction for LlamaIndex."""
|
|
2
|
+
from ._client import ObscateClient, ObscateError, RestoreContext
|
|
3
|
+
from .base import ObscateNodeRedactor, ObscatePostprocessor, ObscateQueryEngine
|
|
4
|
+
|
|
5
|
+
__version__ = "0.1.0"
|
|
6
|
+
__all__ = ["ObscatePostprocessor", "ObscateQueryEngine", "ObscateNodeRedactor", "ObscateClient",
|
|
7
|
+
"ObscateError", "RestoreContext"]
|