promptveil 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.
- promptveil-0.1.0/LICENSE +21 -0
- promptveil-0.1.0/PKG-INFO +413 -0
- promptveil-0.1.0/README.md +374 -0
- promptveil-0.1.0/promptveil/__init__.py +26 -0
- promptveil-0.1.0/promptveil/actions/__init__.py +6 -0
- promptveil-0.1.0/promptveil/actions/blocker.py +25 -0
- promptveil-0.1.0/promptveil/actions/masker.py +237 -0
- promptveil-0.1.0/promptveil/adapters/__init__.py +19 -0
- promptveil-0.1.0/promptveil/adapters/langchain_adapter.py +94 -0
- promptveil-0.1.0/promptveil/adapters/openai_adapter.py +88 -0
- promptveil-0.1.0/promptveil/config/__init__.py +5 -0
- promptveil-0.1.0/promptveil/config/loader.py +188 -0
- promptveil-0.1.0/promptveil/detector/__init__.py +7 -0
- promptveil-0.1.0/promptveil/detector/base.py +57 -0
- promptveil-0.1.0/promptveil/detector/india_detector.py +188 -0
- promptveil-0.1.0/promptveil/detector/regex_detector.py +138 -0
- promptveil-0.1.0/promptveil/detector/us_detector.py +76 -0
- promptveil-0.1.0/promptveil/exceptions.py +22 -0
- promptveil-0.1.0/promptveil/logger/__init__.py +5 -0
- promptveil-0.1.0/promptveil/logger/audit_logger.py +126 -0
- promptveil-0.1.0/promptveil/middleware/__init__.py +9 -0
- promptveil-0.1.0/promptveil/middleware/fastapi_middleware.py +101 -0
- promptveil-0.1.0/promptveil/policy/__init__.py +6 -0
- promptveil-0.1.0/promptveil/policy/engine.py +66 -0
- promptveil-0.1.0/promptveil/policy/models.py +47 -0
- promptveil-0.1.0/promptveil/profiles/__init__.py +71 -0
- promptveil-0.1.0/promptveil/profiles/base.py +25 -0
- promptveil-0.1.0/promptveil/profiles/eu_gdpr.py +28 -0
- promptveil-0.1.0/promptveil/profiles/india_dpdpa.py +39 -0
- promptveil-0.1.0/promptveil/profiles/us_hipaa.py +37 -0
- promptveil-0.1.0/promptveil/results.py +119 -0
- promptveil-0.1.0/promptveil/shield.py +395 -0
- promptveil-0.1.0/promptveil/vault.py +137 -0
- promptveil-0.1.0/promptveil.egg-info/PKG-INFO +413 -0
- promptveil-0.1.0/promptveil.egg-info/SOURCES.txt +51 -0
- promptveil-0.1.0/promptveil.egg-info/dependency_links.txt +1 -0
- promptveil-0.1.0/promptveil.egg-info/requires.txt +19 -0
- promptveil-0.1.0/promptveil.egg-info/top_level.txt +1 -0
- promptveil-0.1.0/pyproject.toml +71 -0
- promptveil-0.1.0/setup.cfg +4 -0
- promptveil-0.1.0/tests/test_adapters.py +240 -0
- promptveil-0.1.0/tests/test_confidence.py +181 -0
- promptveil-0.1.0/tests/test_config.py +90 -0
- promptveil-0.1.0/tests/test_detector.py +155 -0
- promptveil-0.1.0/tests/test_india_detector.py +314 -0
- promptveil-0.1.0/tests/test_masker.py +76 -0
- promptveil-0.1.0/tests/test_middleware.py +175 -0
- promptveil-0.1.0/tests/test_policy.py +69 -0
- promptveil-0.1.0/tests/test_profiles.py +165 -0
- promptveil-0.1.0/tests/test_regex_detector.py +385 -0
- promptveil-0.1.0/tests/test_results.py +134 -0
- promptveil-0.1.0/tests/test_shield.py +147 -0
- promptveil-0.1.0/tests/test_vault.py +198 -0
promptveil-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Total Tensor Labs
|
|
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,413 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: promptveil
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Privacy and safety middleware for LLM applications
|
|
5
|
+
Author: Total Tensor Labs
|
|
6
|
+
Maintainer: Total Tensor Labs
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Project-URL: Homepage, https://github.com/total-tensor-lab/PromptVeil
|
|
9
|
+
Project-URL: Repository, https://github.com/total-tensor-lab/PromptVeil
|
|
10
|
+
Project-URL: Issues, https://github.com/total-tensor-lab/PromptVeil/issues
|
|
11
|
+
Keywords: llm,pii,privacy,safety,middleware,redaction
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Security
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: PyYAML>=6.0
|
|
24
|
+
Provides-Extra: fastapi
|
|
25
|
+
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
|
|
26
|
+
Requires-Dist: starlette>=0.27.0; extra == "fastapi"
|
|
27
|
+
Provides-Extra: openai
|
|
28
|
+
Requires-Dist: openai>=1.0.0; extra == "openai"
|
|
29
|
+
Provides-Extra: langchain
|
|
30
|
+
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
|
|
31
|
+
Provides-Extra: dev
|
|
32
|
+
Requires-Dist: pytest>=7.4; extra == "dev"
|
|
33
|
+
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
|
|
34
|
+
Requires-Dist: pytest-cov>=4.1; extra == "dev"
|
|
35
|
+
Requires-Dist: fastapi>=0.100.0; extra == "dev"
|
|
36
|
+
Requires-Dist: starlette>=0.27.0; extra == "dev"
|
|
37
|
+
Requires-Dist: httpx>=0.24.0; extra == "dev"
|
|
38
|
+
Dynamic: license-file
|
|
39
|
+
|
|
40
|
+
# PromptVeil
|
|
41
|
+
|
|
42
|
+
> Privacy and safety middleware for LLM applications.
|
|
43
|
+
|
|
44
|
+
PromptVeil intercepts prompts **before** they reach an LLM API, detects
|
|
45
|
+
sensitive information (PII, secrets), applies configurable policies
|
|
46
|
+
(mask · block · allow), and produces structured JSON audit logs for compliance.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Features
|
|
51
|
+
|
|
52
|
+
| Capability | Detail |
|
|
53
|
+
|---|---|
|
|
54
|
+
| **PII detection** | Email, phone, credit card, API keys (regex, extensible) |
|
|
55
|
+
| **India PII** | Aadhaar (Verhoeff checksum), PAN, GSTIN, IFSC, Passport, Voter ID |
|
|
56
|
+
| **US PII** | SSN (segment-validated), US Passport, EIN |
|
|
57
|
+
| **Policy engine** | YAML-driven rules: `mask`, `block`, `allow`; per-rule confidence thresholds |
|
|
58
|
+
| **Masking** | Type-aware redaction (domain preserved for email, last-4 for cards) |
|
|
59
|
+
| **Blocking** | Raises `SensitiveDataError` before the prompt is forwarded |
|
|
60
|
+
| **Audit logging** | Structured JSON lines — raw values never logged |
|
|
61
|
+
| **Confidence scoring** | Each detected entity carries a `confidence` float; rules can require a minimum |
|
|
62
|
+
| **Rich scan results** | `scan_detailed()` returns `ScanResult` with `risk_score`, `risk_level`, and per-entity `EntityResult` |
|
|
63
|
+
| **Compliance profiles** | One-line activation of `india_dpdpa`, `eu_gdpr`, or `us_hipaa` rule packs |
|
|
64
|
+
| **Pseudonymization vault** | `scan_with_vault()` replaces PII with reversible `<TYPE_N>` tokens; restore after LLM response |
|
|
65
|
+
| **OpenAI adapter** | `wrap_openai(client, shield)` patches `chat.completions.create` in-place |
|
|
66
|
+
| **LangChain adapter** | `get_langchain_callback()` returns a `BaseCallbackHandler` that scans prompts automatically |
|
|
67
|
+
| **Plug-in detectors** | Subclass `BaseDetector` to add spaCy, ML models, custom patterns |
|
|
68
|
+
| **FastAPI middleware** | Drop-in Starlette/FastAPI middleware (optional extra) |
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Installation
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
# Core (only requires PyYAML)
|
|
76
|
+
pip install promptveil
|
|
77
|
+
|
|
78
|
+
# With FastAPI middleware support
|
|
79
|
+
pip install "promptveil[fastapi]"
|
|
80
|
+
|
|
81
|
+
# With OpenAI adapter
|
|
82
|
+
pip install "promptveil[openai]"
|
|
83
|
+
|
|
84
|
+
# With LangChain adapter
|
|
85
|
+
pip install "promptveil[langchain]"
|
|
86
|
+
|
|
87
|
+
# Everything
|
|
88
|
+
pip install "promptveil[fastapi,openai,langchain,dev]"
|
|
89
|
+
|
|
90
|
+
# Development (includes pytest)
|
|
91
|
+
pip install "promptveil[dev]"
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Requires **Python ≥ 3.10**.
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## Quick Start
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
from promptveil import Shield
|
|
102
|
+
|
|
103
|
+
shield = Shield(config_path="policy.yaml")
|
|
104
|
+
|
|
105
|
+
safe = shield.scan("Bill me at alice@example.com, card 4111-1111-1111-1111")
|
|
106
|
+
# ↑ raises SensitiveDataError — credit card is blocked by default policy
|
|
107
|
+
|
|
108
|
+
safe = shield.scan("Contact alice@example.com for the invoice.")
|
|
109
|
+
# → "Contact a***@example.com for the invoice."
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Activate a compliance profile in one line
|
|
113
|
+
|
|
114
|
+
```yaml
|
|
115
|
+
# policy.yaml
|
|
116
|
+
profile: india_dpdpa # or eu_gdpr / us_hipaa
|
|
117
|
+
# optional rule overrides go here under `rules:`
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
shield = Shield(config_path="policy.yaml") # profile detectors loaded automatically
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Rich scan result with risk scoring
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
result = shield.scan_detailed("Call me on +91 98765 43210")
|
|
128
|
+
print(result.risk_score) # e.g. 0.42
|
|
129
|
+
print(result.risk_level) # "MEDIUM"
|
|
130
|
+
print(result.safe_text) # sanitised prompt
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Reversible pseudonymization
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from promptveil import PseudonymVault
|
|
137
|
+
|
|
138
|
+
vault = PseudonymVault()
|
|
139
|
+
pseudo_text, vault = shield.scan_with_vault("Email alice@example.com", vault=vault)
|
|
140
|
+
# pseudo_text → "Email <EMAIL_1>"
|
|
141
|
+
llm_response = call_llm(pseudo_text) # LLM sees tokens, not PII
|
|
142
|
+
final = vault.restore(llm_response) # restore originals in the reply
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Drop-in OpenAI integration
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
import openai
|
|
149
|
+
from promptveil.adapters import wrap_openai
|
|
150
|
+
|
|
151
|
+
client = openai.OpenAI()
|
|
152
|
+
wrap_openai(client, shield=shield) # patches client in-place
|
|
153
|
+
|
|
154
|
+
# All subsequent calls are automatically scanned:
|
|
155
|
+
client.chat.completions.create(
|
|
156
|
+
model="gpt-4o",
|
|
157
|
+
messages=[{"role": "user", "content": prompt}],
|
|
158
|
+
)
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Policy Configuration (`policy.yaml`)
|
|
164
|
+
|
|
165
|
+
```yaml
|
|
166
|
+
version: "1.0"
|
|
167
|
+
default_action: allow # fallback: mask | block | allow
|
|
168
|
+
|
|
169
|
+
# Optional: activate a built-in compliance profile (india_dpdpa | eu_gdpr | us_hipaa)
|
|
170
|
+
# profile: eu_gdpr
|
|
171
|
+
|
|
172
|
+
rules:
|
|
173
|
+
- type: email
|
|
174
|
+
action: mask # a***@example.com
|
|
175
|
+
min_confidence: 0.8 # optional: only apply rule when confidence ≥ this value
|
|
176
|
+
- type: phone
|
|
177
|
+
action: mask # ***-***-5309
|
|
178
|
+
- type: credit_card
|
|
179
|
+
action: block # raises SensitiveDataError
|
|
180
|
+
- type: api_key
|
|
181
|
+
action: block # raises SensitiveDataError
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Built-in entity types: `email`, `phone`, `credit_card`, `api_key`,
|
|
185
|
+
`in_aadhaar`, `in_pan`, `in_phone`, `in_passport`, `in_voter_id`, `in_ifsc`, `in_gstin`,
|
|
186
|
+
`ssn`, `us_passport`, `us_ein`.
|
|
187
|
+
Custom detectors can introduce any additional type labels.
|
|
188
|
+
|
|
189
|
+
### Compliance Profiles
|
|
190
|
+
|
|
191
|
+
Profiles bundle a pre-configured `PolicyConfig` and the appropriate detectors
|
|
192
|
+
for a jurisdiction. Activate via the YAML `profile:` key or programmatically:
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
from promptveil.profiles import load_profile
|
|
196
|
+
|
|
197
|
+
profile = load_profile("us_hipaa") # or india_dpdpa / eu_gdpr
|
|
198
|
+
shield = Shield(config=profile.policy, detectors=profile.detectors)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
| Profile | Detectors | Key rules |
|
|
202
|
+
|---|---|---|
|
|
203
|
+
| `india_dpdpa` | `RegexDetector` + `IndiaDetector` | Aadhaar/PAN/Passport → BLOCK; phone/GSTIN/IFSC → MASK |
|
|
204
|
+
| `eu_gdpr` | `RegexDetector` | email/phone → MASK; credit card/API key → BLOCK |
|
|
205
|
+
| `us_hipaa` | `RegexDetector` + `USDetector` | SSN → BLOCK; email/phone/passport/EIN → MASK |
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## API Reference
|
|
210
|
+
|
|
211
|
+
### `Shield(config_path=…, config=…, detectors=…, logger=…)`
|
|
212
|
+
|
|
213
|
+
| Param | Type | Description |
|
|
214
|
+
|---|---|---|
|
|
215
|
+
| `config_path` | `str \| Path` | Path to a YAML policy file |
|
|
216
|
+
| `config` | `PolicyConfig` | Pre-built config (alternative to `config_path`) |
|
|
217
|
+
| `detectors` | `list[BaseDetector]` | Custom detector list; overrides profile detectors when provided |
|
|
218
|
+
| `logger` | `AuditLogger` | Custom audit logger (default: JSON → stdout) |
|
|
219
|
+
|
|
220
|
+
### `shield.scan(prompt: str) -> str`
|
|
221
|
+
|
|
222
|
+
Scans the prompt, applies policy rules, and returns a sanitised string.
|
|
223
|
+
Raises `SensitiveDataError` if a `block` rule fires.
|
|
224
|
+
|
|
225
|
+
### `shield.scan_response(response: str) -> str`
|
|
226
|
+
|
|
227
|
+
Same as `scan` but semantically applied to LLM output.
|
|
228
|
+
|
|
229
|
+
### `shield.scan_detailed(prompt: str) -> ScanResult`
|
|
230
|
+
|
|
231
|
+
Like `scan`, but returns a `ScanResult` dataclass instead of a plain string:
|
|
232
|
+
|
|
233
|
+
```python
|
|
234
|
+
@dataclass(frozen=True)
|
|
235
|
+
class ScanResult:
|
|
236
|
+
safe_text: str # sanitised prompt
|
|
237
|
+
entities: tuple[EntityResult] # per-entity detail
|
|
238
|
+
risk_score: float # 0.0 – 1.0 probabilistic risk
|
|
239
|
+
risk_level: str # NONE | LOW | MEDIUM | HIGH | CRITICAL
|
|
240
|
+
was_mutated: bool # True if any masking was applied
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
`risk_level` thresholds: NONE = 0.0, LOW < 0.30, MEDIUM < 0.60, HIGH < 0.85, CRITICAL ≥ 0.85.
|
|
244
|
+
|
|
245
|
+
### `shield.scan_with_vault(prompt: str, vault=None) -> tuple[str, PseudonymVault]`
|
|
246
|
+
|
|
247
|
+
Replaces each masked/blocked entity with a reversible token (`<EMAIL_1>`, `<PHONE_1>`, …).
|
|
248
|
+
Pass the returned `PseudonymVault` to `vault.restore(text)` to swap tokens back after the LLM response.
|
|
249
|
+
|
|
250
|
+
### `shield.add_detector(detector: BaseDetector)`
|
|
251
|
+
|
|
252
|
+
Register an additional detector at runtime.
|
|
253
|
+
|
|
254
|
+
### `PseudonymVault`
|
|
255
|
+
|
|
256
|
+
| Method | Description |
|
|
257
|
+
|---|---|
|
|
258
|
+
| `pseudonymize(text, entities)` | Replace entity spans with tokens (called internally by `scan_with_vault`) |
|
|
259
|
+
| `restore(text)` | Swap all tokens back to their original values |
|
|
260
|
+
| `get_token(value)` | Look up the token assigned to an original value |
|
|
261
|
+
| `token_map` | Read-only copy of the current `{token: original_value}` mapping |
|
|
262
|
+
| `clear()` | Reset the vault |
|
|
263
|
+
| `len(vault)` | Number of unique originals stored |
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
## Programmatic Config (no YAML file)
|
|
268
|
+
|
|
269
|
+
```python
|
|
270
|
+
from promptveil import Shield
|
|
271
|
+
from promptveil.policy.models import Action, PolicyConfig, Rule
|
|
272
|
+
|
|
273
|
+
config = PolicyConfig(
|
|
274
|
+
rules=[
|
|
275
|
+
Rule(type="email", action=Action.MASK, min_confidence=0.8),
|
|
276
|
+
Rule(type="api_key", action=Action.BLOCK),
|
|
277
|
+
],
|
|
278
|
+
default_action=Action.ALLOW,
|
|
279
|
+
)
|
|
280
|
+
shield = Shield(config=config)
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
`min_confidence` is optional (defaults to `0.0`). When a detector reports
|
|
284
|
+
`confidence < min_confidence` for an entity, the rule is skipped and
|
|
285
|
+
`default_action` applies instead.
|
|
286
|
+
|
|
287
|
+
---
|
|
288
|
+
|
|
289
|
+
## Custom Detectors
|
|
290
|
+
|
|
291
|
+
Subclass `BaseDetector` to add any detection logic:
|
|
292
|
+
|
|
293
|
+
```python
|
|
294
|
+
import re
|
|
295
|
+
from promptveil.detector.base import BaseDetector, DetectedEntity
|
|
296
|
+
|
|
297
|
+
class SSNDetector(BaseDetector):
|
|
298
|
+
_PATTERN = re.compile(r"\b\d{3}-\d{2}-\d{4}\b")
|
|
299
|
+
|
|
300
|
+
def detect(self, text: str) -> list[DetectedEntity]:
|
|
301
|
+
return [
|
|
302
|
+
DetectedEntity("ssn", m.group(), m.start(), m.end())
|
|
303
|
+
for m in self._PATTERN.finditer(text)
|
|
304
|
+
]
|
|
305
|
+
|
|
306
|
+
@property
|
|
307
|
+
def supported_types(self) -> list[str]:
|
|
308
|
+
return ["ssn"]
|
|
309
|
+
|
|
310
|
+
shield = Shield(
|
|
311
|
+
config=PolicyConfig(rules=[Rule(type="ssn", action=Action.MASK)]),
|
|
312
|
+
detectors=[SSNDetector()],
|
|
313
|
+
)
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## FastAPI Middleware
|
|
319
|
+
|
|
320
|
+
```python
|
|
321
|
+
from fastapi import FastAPI
|
|
322
|
+
from promptveil import Shield
|
|
323
|
+
from promptveil.middleware import PromptVeilMiddleware
|
|
324
|
+
|
|
325
|
+
app = FastAPI()
|
|
326
|
+
shield = Shield(config_path="policy.yaml")
|
|
327
|
+
app.add_middleware(PromptVeilMiddleware, shield=shield, prompt_field="prompt")
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
POST requests with `Content-Type: application/json` that contain the
|
|
331
|
+
`prompt_field` key are intercepted automatically. Blocked prompts receive a
|
|
332
|
+
`400` response with a structured error body.
|
|
333
|
+
|
|
334
|
+
---
|
|
335
|
+
|
|
336
|
+
## LangChain Adapter
|
|
337
|
+
|
|
338
|
+
```python
|
|
339
|
+
from promptveil.adapters import get_langchain_callback
|
|
340
|
+
|
|
341
|
+
CallbackClass = get_langchain_callback() # lazy-imported; requires langchain-core
|
|
342
|
+
callback = CallbackClass(shield)
|
|
343
|
+
|
|
344
|
+
llm.invoke(prompt, config={"callbacks": [callback]})
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
The callback implements `on_llm_start` (string prompts) and
|
|
348
|
+
`on_chat_model_start` (chat messages), scanning and mutating content
|
|
349
|
+
in-place before it reaches the model.
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
## Audit Log Format
|
|
354
|
+
|
|
355
|
+
Each log line is a self-contained JSON object:
|
|
356
|
+
|
|
357
|
+
```json
|
|
358
|
+
{
|
|
359
|
+
"event": "prompt_scan",
|
|
360
|
+
"timestamp": "2026-05-03T07:34:19.800456+00:00",
|
|
361
|
+
"prompt_length": 44,
|
|
362
|
+
"detections": 1,
|
|
363
|
+
"entities": [
|
|
364
|
+
{
|
|
365
|
+
"entity_type": "email",
|
|
366
|
+
"action": "mask",
|
|
367
|
+
"value_preview": "a***@example.com",
|
|
368
|
+
"position": {"start": 26, "end": 43}
|
|
369
|
+
}
|
|
370
|
+
]
|
|
371
|
+
}
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
Raw sensitive values are **never** stored in logs.
|
|
375
|
+
|
|
376
|
+
---
|
|
377
|
+
|
|
378
|
+
## Project Structure
|
|
379
|
+
|
|
380
|
+
```
|
|
381
|
+
promptveil/
|
|
382
|
+
├── __init__.py # Public API: Shield, exceptions
|
|
383
|
+
├── shield.py # Main Shield class — orchestration
|
|
384
|
+
├── exceptions.py # SensitiveDataError, ConfigurationError
|
|
385
|
+
├── config/
|
|
386
|
+
│ └── loader.py # YAML loader & validator
|
|
387
|
+
├── detector/
|
|
388
|
+
│ ├── base.py # BaseDetector ABC + DetectedEntity dataclass
|
|
389
|
+
│ └── regex_detector.py # Built-in regex patterns (email/phone/card/key)
|
|
390
|
+
├── policy/
|
|
391
|
+
│ ├── models.py # Action enum, Rule, PolicyConfig dataclasses
|
|
392
|
+
│ └── engine.py # PolicyEngine — entity → action lookup
|
|
393
|
+
├── actions/
|
|
394
|
+
│ ├── masker.py # Per-type masking + apply_masks()
|
|
395
|
+
│ └── blocker.py # block() — raises SensitiveDataError
|
|
396
|
+
├── logger/
|
|
397
|
+
│ └── audit_logger.py # Structured JSON audit logger
|
|
398
|
+
└── middleware/
|
|
399
|
+
└── fastapi_middleware.py # Optional Starlette/FastAPI middleware
|
|
400
|
+
policy.yaml # Example policy (mask email/phone, block card/key)
|
|
401
|
+
example_usage.py # Runnable demo
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
---
|
|
405
|
+
|
|
406
|
+
## Running Tests
|
|
407
|
+
|
|
408
|
+
```bash
|
|
409
|
+
uv run pytest -v
|
|
410
|
+
# or: python -m pytest -v
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
234 tests, < 1 s.
|