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.
Files changed (53) hide show
  1. promptveil-0.1.0/LICENSE +21 -0
  2. promptveil-0.1.0/PKG-INFO +413 -0
  3. promptveil-0.1.0/README.md +374 -0
  4. promptveil-0.1.0/promptveil/__init__.py +26 -0
  5. promptveil-0.1.0/promptveil/actions/__init__.py +6 -0
  6. promptveil-0.1.0/promptveil/actions/blocker.py +25 -0
  7. promptveil-0.1.0/promptveil/actions/masker.py +237 -0
  8. promptveil-0.1.0/promptveil/adapters/__init__.py +19 -0
  9. promptveil-0.1.0/promptveil/adapters/langchain_adapter.py +94 -0
  10. promptveil-0.1.0/promptveil/adapters/openai_adapter.py +88 -0
  11. promptveil-0.1.0/promptveil/config/__init__.py +5 -0
  12. promptveil-0.1.0/promptveil/config/loader.py +188 -0
  13. promptveil-0.1.0/promptveil/detector/__init__.py +7 -0
  14. promptveil-0.1.0/promptveil/detector/base.py +57 -0
  15. promptveil-0.1.0/promptveil/detector/india_detector.py +188 -0
  16. promptveil-0.1.0/promptveil/detector/regex_detector.py +138 -0
  17. promptveil-0.1.0/promptveil/detector/us_detector.py +76 -0
  18. promptveil-0.1.0/promptveil/exceptions.py +22 -0
  19. promptveil-0.1.0/promptveil/logger/__init__.py +5 -0
  20. promptveil-0.1.0/promptveil/logger/audit_logger.py +126 -0
  21. promptveil-0.1.0/promptveil/middleware/__init__.py +9 -0
  22. promptveil-0.1.0/promptveil/middleware/fastapi_middleware.py +101 -0
  23. promptveil-0.1.0/promptveil/policy/__init__.py +6 -0
  24. promptveil-0.1.0/promptveil/policy/engine.py +66 -0
  25. promptveil-0.1.0/promptveil/policy/models.py +47 -0
  26. promptveil-0.1.0/promptveil/profiles/__init__.py +71 -0
  27. promptveil-0.1.0/promptveil/profiles/base.py +25 -0
  28. promptveil-0.1.0/promptveil/profiles/eu_gdpr.py +28 -0
  29. promptveil-0.1.0/promptveil/profiles/india_dpdpa.py +39 -0
  30. promptveil-0.1.0/promptveil/profiles/us_hipaa.py +37 -0
  31. promptveil-0.1.0/promptveil/results.py +119 -0
  32. promptveil-0.1.0/promptveil/shield.py +395 -0
  33. promptveil-0.1.0/promptveil/vault.py +137 -0
  34. promptveil-0.1.0/promptveil.egg-info/PKG-INFO +413 -0
  35. promptveil-0.1.0/promptveil.egg-info/SOURCES.txt +51 -0
  36. promptveil-0.1.0/promptveil.egg-info/dependency_links.txt +1 -0
  37. promptveil-0.1.0/promptveil.egg-info/requires.txt +19 -0
  38. promptveil-0.1.0/promptveil.egg-info/top_level.txt +1 -0
  39. promptveil-0.1.0/pyproject.toml +71 -0
  40. promptveil-0.1.0/setup.cfg +4 -0
  41. promptveil-0.1.0/tests/test_adapters.py +240 -0
  42. promptveil-0.1.0/tests/test_confidence.py +181 -0
  43. promptveil-0.1.0/tests/test_config.py +90 -0
  44. promptveil-0.1.0/tests/test_detector.py +155 -0
  45. promptveil-0.1.0/tests/test_india_detector.py +314 -0
  46. promptveil-0.1.0/tests/test_masker.py +76 -0
  47. promptveil-0.1.0/tests/test_middleware.py +175 -0
  48. promptveil-0.1.0/tests/test_policy.py +69 -0
  49. promptveil-0.1.0/tests/test_profiles.py +165 -0
  50. promptveil-0.1.0/tests/test_regex_detector.py +385 -0
  51. promptveil-0.1.0/tests/test_results.py +134 -0
  52. promptveil-0.1.0/tests/test_shield.py +147 -0
  53. promptveil-0.1.0/tests/test_vault.py +198 -0
@@ -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.