phiproxy 0.1.0a1__py3-none-any.whl
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.
- phiproxy/__init__.py +30 -0
- phiproxy/dates.py +128 -0
- phiproxy/detectors/__init__.py +5 -0
- phiproxy/detectors/base.py +73 -0
- phiproxy/detectors/known.py +235 -0
- phiproxy/detectors/presidio.py +64 -0
- phiproxy/detectors/regex.py +276 -0
- phiproxy/entities.py +65 -0
- phiproxy/integrations/__init__.py +1 -0
- phiproxy/integrations/litellm.py +304 -0
- phiproxy/masker.py +282 -0
- phiproxy/vault.py +182 -0
- phiproxy-0.1.0a1.dist-info/METADATA +208 -0
- phiproxy-0.1.0a1.dist-info/RECORD +17 -0
- phiproxy-0.1.0a1.dist-info/WHEEL +4 -0
- phiproxy-0.1.0a1.dist-info/licenses/LICENSE +202 -0
- phiproxy-0.1.0a1.dist-info/licenses/NOTICE +5 -0
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
"""Pattern-based detection for identifiers with a fixed shape.
|
|
2
|
+
|
|
3
|
+
Everything here runs locally with the standard library. Patterns aim for recall:
|
|
4
|
+
a false positive costs some answer quality, a false negative leaks PHI.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import re
|
|
10
|
+
from dataclasses import dataclass, field
|
|
11
|
+
from typing import Callable, Optional
|
|
12
|
+
|
|
13
|
+
from ..entities import Entity, EntityType
|
|
14
|
+
|
|
15
|
+
_MONTHS = (
|
|
16
|
+
"jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|june?|july?|aug(?:ust)?|"
|
|
17
|
+
"sep(?:t(?:ember)?)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?"
|
|
18
|
+
)
|
|
19
|
+
# Month words that are also ordinary English words; only count them when capitalized.
|
|
20
|
+
_AMBIGUOUS_MONTHS = {"may", "mar", "march", "jan", "june", "july", "aug", "sep", "dec"}
|
|
21
|
+
|
|
22
|
+
_US_STATES = (
|
|
23
|
+
"AL|AK|AZ|AR|CA|CO|CT|DE|FL|GA|HI|ID|IL|IN|IA|KS|KY|LA|ME|MD|MA|MI|MN|MS|MO|MT|NE|NV|"
|
|
24
|
+
"NH|NJ|NM|NY|NC|ND|OH|OK|OR|PA|RI|SC|SD|TN|TX|UT|VT|VA|WA|WV|WI|WY|DC"
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
_STREET_SUFFIX = (
|
|
28
|
+
"street|st|avenue|ave|road|rd|boulevard|blvd|drive|dr|lane|ln|court|ct|crescent|cres|"
|
|
29
|
+
"way|place|pl|terrace|ter|circle|cir|parkway|pkwy|highway|hwy|trail|trl|square|sq"
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
# Capitalized words that follow "this is", "Dr." etc. but are not names.
|
|
33
|
+
_NOT_NAMES = {
|
|
34
|
+
"monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday",
|
|
35
|
+
"january", "february", "march", "april", "may", "june", "july", "august",
|
|
36
|
+
"september", "october", "november", "december", "today", "tomorrow", "yesterday",
|
|
37
|
+
"hi", "hello", "hey", "thanks", "thank", "please", "yes", "no", "ok", "okay",
|
|
38
|
+
"the", "a", "an", "my", "your", "our", "it", "this", "that", "not", "just", "so",
|
|
39
|
+
"clinic", "office", "doctor", "nurse", "team", "everyone", "all", "regarding",
|
|
40
|
+
"urgent", "important", "about", "re", "fwd", "ivf", "iui", "fet",
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
_RELATIONS = (
|
|
44
|
+
"husband|wife|partner|spouse|boyfriend|girlfriend|fianc[eé]e?|son|daughter|"
|
|
45
|
+
"mom|mother|mum|dad|father|sister|brother|friend|donor|surrogate|carrier|"
|
|
46
|
+
"grandmother|grandfather|aunt|uncle|cousin|niece|nephew|boss|employer|coworker|colleague"
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
_NAME = r"[A-Z][a-zA-Z'\-]+(?:\s+[A-Z][a-zA-Z'\-]+)?"
|
|
50
|
+
|
|
51
|
+
_DIGIT_WORDS = "zero|oh|one|two|three|four|five|six|seven|eight|nine"
|
|
52
|
+
_ORDINAL_WORDS = (
|
|
53
|
+
"(?:twenty|thirty)[\\s\\-]?(?:first|second|third|fourth|fifth|sixth|seventh|eighth|ninth)|"
|
|
54
|
+
"first|second|third|fourth|fifth|sixth|seventh|eighth|ninth|tenth|eleventh|twelfth|"
|
|
55
|
+
"thirteenth|fourteenth|fifteenth|sixteenth|seventeenth|eighteenth|nineteenth|twentieth|thirtieth"
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _luhn_ok(digits: str) -> bool:
|
|
60
|
+
total = 0
|
|
61
|
+
for i, ch in enumerate(reversed(digits)):
|
|
62
|
+
d = int(ch)
|
|
63
|
+
if i % 2 == 1:
|
|
64
|
+
d *= 2
|
|
65
|
+
if d > 9:
|
|
66
|
+
d -= 9
|
|
67
|
+
total += d
|
|
68
|
+
return total % 10 == 0
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
@dataclass
|
|
72
|
+
class _Rule:
|
|
73
|
+
type: EntityType
|
|
74
|
+
pattern: re.Pattern[str]
|
|
75
|
+
group: int = 0 # which capture group is the identifier
|
|
76
|
+
check: Optional[Callable[[re.Match[str]], bool]] = None
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _digits(s: str) -> str:
|
|
80
|
+
return re.sub(r"\D", "", s)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _sin_check(m: re.Match[str]) -> bool:
|
|
84
|
+
d = _digits(m.group(0))
|
|
85
|
+
return len(d) == 9 and _luhn_ok(d)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _ssn_check(m: re.Match[str]) -> bool:
|
|
89
|
+
a, b, c = m.group(1), m.group(2), m.group(3)
|
|
90
|
+
return a not in ("000", "666") and not a.startswith("9") and b != "00" and c != "0000"
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _month_check(m: re.Match[str]) -> bool:
|
|
94
|
+
month = m.group("month")
|
|
95
|
+
return not (month.lower() in _AMBIGUOUS_MONTHS and month[0].islower())
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _name_check(m: re.Match[str]) -> bool:
|
|
99
|
+
first = m.group("name").split()[0].lower()
|
|
100
|
+
return first not in _NOT_NAMES
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _build_rules() -> list[_Rule]:
|
|
104
|
+
I = re.IGNORECASE
|
|
105
|
+
R: list[_Rule] = []
|
|
106
|
+
|
|
107
|
+
def add(t: EntityType, pat: str, flags: int = 0, group: int = 0, check=None) -> None:
|
|
108
|
+
R.append(_Rule(t, re.compile(pat, flags), group, check))
|
|
109
|
+
|
|
110
|
+
add(EntityType.EMAIL, r"\b[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}\b")
|
|
111
|
+
add(EntityType.URL, r"\bhttps?://[^\s<>\"')\]]+|\bwww\.[^\s<>\"')\]]+", I)
|
|
112
|
+
add(EntityType.IP_ADDRESS, r"\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b")
|
|
113
|
+
|
|
114
|
+
# Keyword-anchored identifiers. The keyword stays; only the value is masked.
|
|
115
|
+
add(
|
|
116
|
+
EntityType.HEALTH_CARD,
|
|
117
|
+
r"\b(?:ohip|health\s*card|hcn|health\s*(?:insurance\s*)?(?:number|no\.?|#)|phn|ramq|carte\s*soleil)"
|
|
118
|
+
r"(?:\s*(?:number|no\.?|#))?\s*(?:is|:|#)?\s*([A-Z]{0,4}[\s\-]?\d[\d\s\-]{6,24}\d(?:[\s\-]?[A-Z]{2})?)\b",
|
|
119
|
+
I,
|
|
120
|
+
group=1,
|
|
121
|
+
)
|
|
122
|
+
add(
|
|
123
|
+
EntityType.MRN,
|
|
124
|
+
r"\b(?:mrn|medical\s*record(?:\s*(?:number|no\.?|#))?|chart\s*(?:number|no\.?|#)|"
|
|
125
|
+
r"patient\s*(?:id|number|no\.?|#))\s*(?:is|:|#)?\s*([A-Z0-9][A-Z0-9\-]{3,19})\b",
|
|
126
|
+
I,
|
|
127
|
+
group=1,
|
|
128
|
+
)
|
|
129
|
+
add(
|
|
130
|
+
EntityType.DONOR_ID,
|
|
131
|
+
r"\b(?:donor|embryo|egg\s*bank|sperm\s*bank|straw)\s*(?:id|code|number|no\.?|#)\s*(?:is|:|#)?\s*"
|
|
132
|
+
r"([A-Z0-9][A-Z0-9\-]{2,19})\b",
|
|
133
|
+
I,
|
|
134
|
+
group=1,
|
|
135
|
+
)
|
|
136
|
+
# "donor D-4521", "donor #4521": no keyword, but the value has a digit.
|
|
137
|
+
add(
|
|
138
|
+
EntityType.DONOR_ID,
|
|
139
|
+
r"\b(?:donor|embryo)\s+#?\s*((?=[A-Z0-9\-]*\d)[A-Z]{0,4}-?\d[A-Z0-9\-]{2,15})\b",
|
|
140
|
+
I,
|
|
141
|
+
group=1,
|
|
142
|
+
)
|
|
143
|
+
add(
|
|
144
|
+
EntityType.ACCOUNT,
|
|
145
|
+
r"\b(?:account|acct|policy|member|insurance\s*id|claim)\s*(?:number|no\.?|#|id)?\s*(?:is|:|#)\s*"
|
|
146
|
+
r"([A-Z0-9][A-Z0-9\-]{3,24})\b",
|
|
147
|
+
I,
|
|
148
|
+
group=1,
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
# Quebec RAMQ: 4 letters + 8 digits.
|
|
152
|
+
add(EntityType.HEALTH_CARD, r"\b[A-Z]{4}\s?\d{4}\s?\d{4}\b")
|
|
153
|
+
# Ontario OHIP in its printed 4-3-3 grouping, optional 2-letter version code.
|
|
154
|
+
add(EntityType.HEALTH_CARD, r"\b\d{4}[\s\-]\d{3}[\s\-]\d{3}(?:[\s\-]?[A-Z]{2})?\b")
|
|
155
|
+
|
|
156
|
+
add(EntityType.SSN, r"\b(\d{3})-(\d{2})-(\d{4})\b", check=_ssn_check)
|
|
157
|
+
add(EntityType.SIN, r"\b\d{3}[\s\-]?\d{3}[\s\-]?\d{3}\b", check=_sin_check)
|
|
158
|
+
|
|
159
|
+
# North American phone numbers, any common formatting.
|
|
160
|
+
add(
|
|
161
|
+
EntityType.PHONE,
|
|
162
|
+
r"(?<![\w+])(?:\+?1[\s.\-]?)?(?:\(\d{3}\)|\d{3})[\s.\-]?\d{3}[\s.\-]?\d{4}\b"
|
|
163
|
+
r"(?:\s*(?:x|ext\.?)\s*\d{1,5})?",
|
|
164
|
+
I,
|
|
165
|
+
)
|
|
166
|
+
# International numbers written with a leading +.
|
|
167
|
+
add(EntityType.PHONE, r"(?<!\w)\+(?:[2-9]\d{0,2})[\s.\-]?\d(?:[\s.\-]?\d){6,12}\b")
|
|
168
|
+
|
|
169
|
+
# Numbers spoken digit by digit (call transcripts): "four one six five five five ..."
|
|
170
|
+
add(EntityType.PHONE, rf"\b(?:{_DIGIT_WORDS})(?:[\s,\-]+(?:{_DIGIT_WORDS})){{6,11}}\b", I)
|
|
171
|
+
|
|
172
|
+
# Dates. Year-only is not PHI under Safe Harbor, so it is not matched.
|
|
173
|
+
add(EntityType.DATE, r"\b\d{4}-\d{1,2}-\d{1,2}\b")
|
|
174
|
+
add(EntityType.DATE, r"\b\d{1,2}[/\-.]\d{1,2}[/\-.](?:\d{4}|\d{2})\b")
|
|
175
|
+
add(
|
|
176
|
+
EntityType.DATE,
|
|
177
|
+
rf"\b(?P<month>{_MONTHS})\.?\s+\d{{1,2}}(?:st|nd|rd|th)?(?:,?\s+\d{{4}})?\b",
|
|
178
|
+
I,
|
|
179
|
+
check=_month_check,
|
|
180
|
+
)
|
|
181
|
+
add(
|
|
182
|
+
EntityType.DATE,
|
|
183
|
+
rf"\b\d{{1,2}}(?:st|nd|rd|th)?\s+(?:of\s+)?(?P<month>{_MONTHS})\.?(?:,?\s+\d{{4}})?\b",
|
|
184
|
+
I,
|
|
185
|
+
check=_month_check,
|
|
186
|
+
)
|
|
187
|
+
# Spoken dates: "march fifteenth 1988", "the twenty first of may". A following
|
|
188
|
+
# ordinal word makes even lowercase "march"/"may" unambiguous.
|
|
189
|
+
add(
|
|
190
|
+
EntityType.DATE,
|
|
191
|
+
rf"\b(?P<month>{_MONTHS})\s+(?:the\s+)?(?:{_ORDINAL_WORDS})(?:,?\s+(?:\d{{4}}|(?:nineteen|twenty)[\w\s\-]{{3,20}}?(?=\W|$)))?",
|
|
192
|
+
I,
|
|
193
|
+
)
|
|
194
|
+
add(EntityType.DATE, rf"\b(?:{_ORDINAL_WORDS})\s+of\s+(?P<month>{_MONTHS})\b(?:,?\s+\d{{4}})?", I)
|
|
195
|
+
# Short numeric dates like 3/14 (no year).
|
|
196
|
+
add(EntityType.DATE, r"(?<![\d/])\b(?:0?[1-9]|1[0-2])/(?:0?[1-9]|[12]\d|3[01])\b(?![/\d])")
|
|
197
|
+
|
|
198
|
+
add(EntityType.AGE, r"\b(?:9\d|1[01]\d)\s*(?:-\s*)?(?:years?[\s\-]*old|yrs?|y/?o)\b", I)
|
|
199
|
+
|
|
200
|
+
add(
|
|
201
|
+
EntityType.ADDRESS,
|
|
202
|
+
rf"\b\d{{1,6}}\s+(?:[A-Za-z0-9'\-]+\s+){{0,3}}(?:{_STREET_SUFFIX})\b\.?"
|
|
203
|
+
r"(?:,?\s*(?:apt|apartment|unit|suite|ste|#)\.?\s*[A-Za-z0-9\-]+)?",
|
|
204
|
+
I,
|
|
205
|
+
)
|
|
206
|
+
add(EntityType.ADDRESS, r"\b(?:p\.?\s?o\.?\s*box|postal\s*box)\s*\d+\b", I)
|
|
207
|
+
|
|
208
|
+
# Canadian postal code.
|
|
209
|
+
add(
|
|
210
|
+
EntityType.POSTAL_CODE,
|
|
211
|
+
r"\b[ABCEGHJ-NPRSTVXY]\d[ABCEGHJ-NPRSTV-Z][\s\-]?\d[ABCEGHJ-NPRSTV-Z]\d\b",
|
|
212
|
+
I,
|
|
213
|
+
)
|
|
214
|
+
# US ZIP only with context (a bare 5-digit number is too ambiguous).
|
|
215
|
+
add(EntityType.ZIP, rf"\b(?:{_US_STATES})\s+(\d{{5}}(?:-\d{{4}})?)\b", group=1)
|
|
216
|
+
add(EntityType.ZIP, r"\bzip(?:\s*code)?\s*(?:is|:)?\s*(\d{5}(?:-\d{4})?)\b", I, group=1)
|
|
217
|
+
|
|
218
|
+
# Names introduced by context. Presidio or the known-entity list catch the rest.
|
|
219
|
+
add(
|
|
220
|
+
EntityType.NAME,
|
|
221
|
+
r"\b(?i:my\s+name\s+is|name'?s|this\s+is|it'?s|i\s+am|i'm|signed|regards|sincerely|"
|
|
222
|
+
r"thanks|thank\s+you|cheers)\s*,?\s+(?P<name>" + _NAME + r")",
|
|
223
|
+
group=0,
|
|
224
|
+
check=_name_check,
|
|
225
|
+
)
|
|
226
|
+
add(
|
|
227
|
+
EntityType.NAME,
|
|
228
|
+
r"\b(?i:my\s+(?:" + _RELATIONS + r")(?:'s\s+name\s+is|\s+is|,)?)\s+(?P<name>" + _NAME + r")",
|
|
229
|
+
group=0,
|
|
230
|
+
check=_name_check,
|
|
231
|
+
)
|
|
232
|
+
add(
|
|
233
|
+
EntityType.NAME,
|
|
234
|
+
r"\b(?i:patient|pt|client|for|from|to|dear|hi|hello|hey)\s*:?\s+(?P<name>" + _NAME + r")",
|
|
235
|
+
group=0,
|
|
236
|
+
check=_name_check,
|
|
237
|
+
)
|
|
238
|
+
add(
|
|
239
|
+
EntityType.PROVIDER,
|
|
240
|
+
r"\b(?:Dr|Doctor|Nurse|NP|RN|Mr|Mrs|Ms|Miss|Mx)\.?\s+(?P<name>" + _NAME + r")",
|
|
241
|
+
group=0,
|
|
242
|
+
check=_name_check,
|
|
243
|
+
)
|
|
244
|
+
return R
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
_RULES = _build_rules()
|
|
248
|
+
|
|
249
|
+
# Rules where only the named "name" group should be masked.
|
|
250
|
+
_NAME_GROUP_TYPES = {EntityType.NAME, EntityType.PROVIDER}
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
@dataclass
|
|
254
|
+
class RegexDetector:
|
|
255
|
+
"""Detects fixed-shape identifiers (phones, emails, dates, health card numbers, ...)."""
|
|
256
|
+
|
|
257
|
+
name: str = "regex"
|
|
258
|
+
enabled: Optional[set[EntityType]] = None # None = all
|
|
259
|
+
extra_rules: list[_Rule] = field(default_factory=list)
|
|
260
|
+
|
|
261
|
+
def detect(self, text: str) -> list[Entity]:
|
|
262
|
+
out: list[Entity] = []
|
|
263
|
+
for rule in [*_RULES, *self.extra_rules]:
|
|
264
|
+
if self.enabled is not None and rule.type not in self.enabled:
|
|
265
|
+
continue
|
|
266
|
+
for m in rule.pattern.finditer(text):
|
|
267
|
+
if rule.check is not None and not rule.check(m):
|
|
268
|
+
continue
|
|
269
|
+
if rule.type in _NAME_GROUP_TYPES and "name" in m.groupdict():
|
|
270
|
+
start, end = m.span("name")
|
|
271
|
+
else:
|
|
272
|
+
start, end = m.span(rule.group)
|
|
273
|
+
if end <= start:
|
|
274
|
+
continue
|
|
275
|
+
out.append(Entity(rule.type, start, end, text[start:end], self.name))
|
|
276
|
+
return out
|
phiproxy/entities.py
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
"""Entity types and the detected-span record."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from enum import Enum
|
|
7
|
+
from typing import Optional
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class EntityType(str, Enum):
|
|
11
|
+
"""What kind of identifier a span is.
|
|
12
|
+
|
|
13
|
+
The label is what appears inside a token, e.g. ``[NAME_1]``. Types map to the
|
|
14
|
+
HIPAA Safe Harbor identifier list (45 CFR 164.514(b)(2)) plus Canadian and
|
|
15
|
+
fertility-clinic identifiers.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
NAME = "NAME"
|
|
19
|
+
PROVIDER = "PROVIDER" # clinician name ("Dr. Smith"); off by default, see Policy
|
|
20
|
+
PHONE = "PHONE"
|
|
21
|
+
EMAIL = "EMAIL"
|
|
22
|
+
DATE = "DATE"
|
|
23
|
+
AGE = "AGE" # ages over 89 only (Safe Harbor)
|
|
24
|
+
ADDRESS = "ADDRESS"
|
|
25
|
+
POSTAL_CODE = "POSTAL_CODE"
|
|
26
|
+
ZIP = "ZIP"
|
|
27
|
+
SSN = "SSN"
|
|
28
|
+
SIN = "SIN" # Canadian Social Insurance Number
|
|
29
|
+
HEALTH_CARD = "HEALTH_CARD" # OHIP, RAMQ and other provincial health numbers
|
|
30
|
+
MRN = "MRN"
|
|
31
|
+
DONOR_ID = "DONOR_ID" # gamete donor / embryo identifiers
|
|
32
|
+
ACCOUNT = "ACCOUNT"
|
|
33
|
+
ID = "ID" # any other identifying number
|
|
34
|
+
URL = "URL"
|
|
35
|
+
IP_ADDRESS = "IP_ADDRESS"
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True)
|
|
39
|
+
class Entity:
|
|
40
|
+
"""A detected identifier inside a piece of text."""
|
|
41
|
+
|
|
42
|
+
type: EntityType
|
|
43
|
+
start: int
|
|
44
|
+
end: int
|
|
45
|
+
text: str
|
|
46
|
+
source: str # which detector found it: "known", "regex", "presidio", ...
|
|
47
|
+
score: float = 1.0
|
|
48
|
+
# Normalized value used for token assignment, e.g. the spelling from the
|
|
49
|
+
# patient record when the text had a typo. Defaults to the span text.
|
|
50
|
+
canonical: Optional[str] = None
|
|
51
|
+
|
|
52
|
+
def __post_init__(self) -> None:
|
|
53
|
+
if not (0 <= self.start < self.end):
|
|
54
|
+
raise ValueError(f"invalid span {self.start}:{self.end}")
|
|
55
|
+
|
|
56
|
+
def overlaps(self, other: "Entity") -> bool:
|
|
57
|
+
return self.start < other.end and other.start < self.end
|
|
58
|
+
|
|
59
|
+
@property
|
|
60
|
+
def value(self) -> str:
|
|
61
|
+
return self.canonical if self.canonical is not None else self.text
|
|
62
|
+
|
|
63
|
+
@property
|
|
64
|
+
def length(self) -> int:
|
|
65
|
+
return self.end - self.start
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Adapters for LLM gateways and SDKs. Each one imports its framework lazily."""
|
|
@@ -0,0 +1,304 @@
|
|
|
1
|
+
"""LiteLLM proxy guardrail: mask requests before they leave, unmask replies.
|
|
2
|
+
|
|
3
|
+
config.yaml::
|
|
4
|
+
|
|
5
|
+
guardrails:
|
|
6
|
+
- guardrail_name: phiproxy
|
|
7
|
+
litellm_params:
|
|
8
|
+
guardrail: phiproxy.integrations.litellm.PhiproxyGuardrail
|
|
9
|
+
mode: [pre_call, post_call]
|
|
10
|
+
default_on: true
|
|
11
|
+
redis_url: os.environ/PHIPROXY_REDIS_URL # optional; in-memory if unset
|
|
12
|
+
date_mode: token # or "shift"
|
|
13
|
+
|
|
14
|
+
litellm_settings:
|
|
15
|
+
turn_off_message_logging: true # keep unmasked replies out of LiteLLM logs
|
|
16
|
+
|
|
17
|
+
Per request, clients may send (in ``metadata``):
|
|
18
|
+
* ``session_id`` - keeps tokens stable across turns of one conversation
|
|
19
|
+
* ``phiproxy_known`` - identifiers you already hold, e.g.
|
|
20
|
+
``{"names": ["Sarah Chen"], "phones": ["416-555-0142"], "dates_of_birth": ["1990-03-05"]}``.
|
|
21
|
+
It is removed from the request before anything is forwarded.
|
|
22
|
+
|
|
23
|
+
Fail closed: if masking fails, or the request holds images/audio/files the
|
|
24
|
+
policy does not allow, the request is rejected and nothing is sent.
|
|
25
|
+
Clients cannot switch this guardrail off through request metadata unless
|
|
26
|
+
``allow_client_opt_out: true`` is configured.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
from __future__ import annotations
|
|
30
|
+
|
|
31
|
+
import importlib
|
|
32
|
+
import inspect
|
|
33
|
+
import logging
|
|
34
|
+
import os
|
|
35
|
+
import uuid
|
|
36
|
+
from typing import Any, AsyncGenerator, Callable, ClassVar, Optional
|
|
37
|
+
|
|
38
|
+
from litellm.integrations.custom_guardrail import CustomGuardrail, get_session_id_from_request_data
|
|
39
|
+
from litellm.types.guardrails import GuardrailEventHooks
|
|
40
|
+
|
|
41
|
+
from ..detectors.known import KnownEntities
|
|
42
|
+
from ..masker import Masker, PhiproxyError, Policy, StreamUnmasker
|
|
43
|
+
from ..vault import InMemoryVault, RedisVault
|
|
44
|
+
|
|
45
|
+
log = logging.getLogger("phiproxy")
|
|
46
|
+
|
|
47
|
+
# Request fields that carry conversation content, across the routes LiteLLM serves
|
|
48
|
+
# (chat/completions, /v1/messages, /v1/responses, text completions).
|
|
49
|
+
_CONTENT_KEYS = ("messages", "system", "input", "instructions", "prompt")
|
|
50
|
+
_SESSION_KEY = "phiproxy_session_id"
|
|
51
|
+
_KNOWN_KEY = "phiproxy_known"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _load_callable(path: str) -> Callable[..., Any]:
|
|
55
|
+
module, _, attr = path.replace(":", ".").rpartition(".")
|
|
56
|
+
return getattr(importlib.import_module(module), attr)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _as_bool(v: Any) -> bool:
|
|
60
|
+
return v if isinstance(v, bool) else str(v).strip().lower() in ("1", "true", "yes", "on")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
class PhiproxyGuardrail(CustomGuardrail):
|
|
64
|
+
use_native_lifecycle_hooks: ClassVar[bool] = True
|
|
65
|
+
|
|
66
|
+
def __init__(
|
|
67
|
+
self,
|
|
68
|
+
redis_url: Optional[str] = None,
|
|
69
|
+
date_mode: str = "token",
|
|
70
|
+
day_first: bool = False,
|
|
71
|
+
allow_images: bool = False,
|
|
72
|
+
allow_audio: bool = False,
|
|
73
|
+
allow_files: bool = False,
|
|
74
|
+
mask_provider_names: bool = False,
|
|
75
|
+
known_entities_provider: Optional[str] = None,
|
|
76
|
+
allow_client_opt_out: bool = False,
|
|
77
|
+
vault_ttl_seconds: int = 24 * 3600,
|
|
78
|
+
masker: Optional[Masker] = None,
|
|
79
|
+
**kwargs: Any,
|
|
80
|
+
):
|
|
81
|
+
kwargs.setdefault(
|
|
82
|
+
"supported_event_hooks", [GuardrailEventHooks.pre_call, GuardrailEventHooks.post_call]
|
|
83
|
+
)
|
|
84
|
+
super().__init__(**kwargs)
|
|
85
|
+
if masker is None:
|
|
86
|
+
policy = Policy(
|
|
87
|
+
date_mode="shift" if date_mode == "shift" else "token",
|
|
88
|
+
day_first=_as_bool(day_first),
|
|
89
|
+
allow_images=_as_bool(allow_images),
|
|
90
|
+
allow_audio=_as_bool(allow_audio),
|
|
91
|
+
allow_files=_as_bool(allow_files),
|
|
92
|
+
)
|
|
93
|
+
if _as_bool(mask_provider_names):
|
|
94
|
+
policy.disabled_types = set()
|
|
95
|
+
redis_url = redis_url or os.environ.get("PHIPROXY_REDIS_URL")
|
|
96
|
+
vault = (
|
|
97
|
+
RedisVault(url=redis_url, ttl_seconds=int(vault_ttl_seconds))
|
|
98
|
+
if redis_url
|
|
99
|
+
else InMemoryVault(ttl_seconds=float(vault_ttl_seconds))
|
|
100
|
+
)
|
|
101
|
+
masker = Masker(vault=vault, policy=policy)
|
|
102
|
+
self.masker = masker
|
|
103
|
+
self.allow_client_opt_out = _as_bool(allow_client_opt_out)
|
|
104
|
+
self._known_provider = _load_callable(known_entities_provider) if known_entities_provider else None
|
|
105
|
+
self._warned_raw_stream = False
|
|
106
|
+
|
|
107
|
+
# ----------------------------------------------------------------- helpers
|
|
108
|
+
def _runs_on(self, data: dict, event: GuardrailEventHooks) -> bool:
|
|
109
|
+
if self.allow_client_opt_out:
|
|
110
|
+
return bool(self.should_run_guardrail(data=data, event_type=event))
|
|
111
|
+
hooks = self.event_hook
|
|
112
|
+
if hooks is None:
|
|
113
|
+
return True
|
|
114
|
+
if isinstance(hooks, (list, tuple, set)):
|
|
115
|
+
return any(str(getattr(h, "value", h)) == event.value for h in hooks)
|
|
116
|
+
if isinstance(hooks, str) or hasattr(hooks, "value"):
|
|
117
|
+
return str(getattr(hooks, "value", hooks)) == event.value
|
|
118
|
+
return bool(self.should_run_guardrail(data=data, event_type=event)) # Mode objects
|
|
119
|
+
|
|
120
|
+
@staticmethod
|
|
121
|
+
def _metadata(data: dict) -> dict:
|
|
122
|
+
md = data.get("metadata")
|
|
123
|
+
if not isinstance(md, dict):
|
|
124
|
+
md = data["metadata"] = {}
|
|
125
|
+
return md
|
|
126
|
+
|
|
127
|
+
def _session_id(self, data: dict) -> str:
|
|
128
|
+
md = self._metadata(data)
|
|
129
|
+
sid = md.get(_SESSION_KEY) or get_session_id_from_request_data(data)
|
|
130
|
+
if not sid:
|
|
131
|
+
sid = f"req-{uuid.uuid4().hex}" # no session given: tokens are per request
|
|
132
|
+
md[_SESSION_KEY] = str(sid)
|
|
133
|
+
return str(sid)
|
|
134
|
+
|
|
135
|
+
async def _known(self, data: dict, session_id: str) -> Optional[KnownEntities]:
|
|
136
|
+
found: list[KnownEntities] = []
|
|
137
|
+
for container in (data.get("metadata"), data.get("litellm_metadata")):
|
|
138
|
+
if isinstance(container, dict) and _KNOWN_KEY in container:
|
|
139
|
+
raw = container.pop(_KNOWN_KEY) # never forward identifiers we were handed
|
|
140
|
+
if isinstance(raw, dict):
|
|
141
|
+
found.append(KnownEntities.from_dict(raw))
|
|
142
|
+
if self._known_provider is not None:
|
|
143
|
+
res = self._known_provider(session_id=session_id, metadata=dict(self._metadata(data)))
|
|
144
|
+
if inspect.isawaitable(res):
|
|
145
|
+
res = await res
|
|
146
|
+
if isinstance(res, dict):
|
|
147
|
+
res = KnownEntities.from_dict(res)
|
|
148
|
+
if isinstance(res, KnownEntities):
|
|
149
|
+
found.append(res)
|
|
150
|
+
if not found:
|
|
151
|
+
return None
|
|
152
|
+
merged = KnownEntities()
|
|
153
|
+
for k in found:
|
|
154
|
+
merged = KnownEntities(
|
|
155
|
+
names=[*merged.names, *k.names],
|
|
156
|
+
phones=[*merged.phones, *k.phones],
|
|
157
|
+
emails=[*merged.emails, *k.emails],
|
|
158
|
+
dates_of_birth=[*merged.dates_of_birth, *k.dates_of_birth],
|
|
159
|
+
identifiers=[*merged.identifiers, *k.identifiers],
|
|
160
|
+
addresses=[*merged.addresses, *k.addresses],
|
|
161
|
+
other={**merged.other, **k.other},
|
|
162
|
+
)
|
|
163
|
+
return merged
|
|
164
|
+
|
|
165
|
+
@staticmethod
|
|
166
|
+
def _reject(message: str) -> Exception:
|
|
167
|
+
try:
|
|
168
|
+
from fastapi import HTTPException # present in the LiteLLM proxy
|
|
169
|
+
|
|
170
|
+
return HTTPException(status_code=400, detail={"error": message, "guardrail": "phiproxy"})
|
|
171
|
+
except ImportError: # pragma: no cover
|
|
172
|
+
return ValueError(message)
|
|
173
|
+
|
|
174
|
+
# ------------------------------------------------------------------- hooks
|
|
175
|
+
async def async_pre_call_hook(self, user_api_key_dict: Any, cache: Any, data: dict, call_type: Any) -> dict:
|
|
176
|
+
if not self._runs_on(data, GuardrailEventHooks.pre_call):
|
|
177
|
+
return data
|
|
178
|
+
session_id = self._session_id(data)
|
|
179
|
+
try:
|
|
180
|
+
known = await self._known(data, session_id)
|
|
181
|
+
for key in _CONTENT_KEYS:
|
|
182
|
+
if key in data and data[key] is not None:
|
|
183
|
+
data[key] = self.masker.mask_payload(data[key], session_id, known)
|
|
184
|
+
except PhiproxyError as exc:
|
|
185
|
+
raise self._reject(f"phiproxy blocked the request: {exc}") from None
|
|
186
|
+
except Exception as exc: # fail closed on anything unexpected
|
|
187
|
+
raise self._reject(f"phiproxy could not mask the request ({type(exc).__name__})") from None
|
|
188
|
+
return data
|
|
189
|
+
|
|
190
|
+
async def async_post_call_success_hook(self, data: dict, user_api_key_dict: Any, response: Any) -> Any:
|
|
191
|
+
if not self._runs_on(data, GuardrailEventHooks.post_call):
|
|
192
|
+
return response
|
|
193
|
+
session_id = (data.get("metadata") or {}).get(_SESSION_KEY)
|
|
194
|
+
if not session_id:
|
|
195
|
+
return response
|
|
196
|
+
return self._unmask_response(response, session_id)
|
|
197
|
+
|
|
198
|
+
async def async_post_call_streaming_iterator_hook(
|
|
199
|
+
self, user_api_key_dict: Any, response: Any, request_data: dict
|
|
200
|
+
) -> AsyncGenerator[Any, None]:
|
|
201
|
+
session_id = ((request_data or {}).get("metadata") or {}).get(_SESSION_KEY)
|
|
202
|
+
if not session_id or not self._runs_on(request_data or {}, GuardrailEventHooks.post_call):
|
|
203
|
+
async for chunk in response:
|
|
204
|
+
yield chunk
|
|
205
|
+
return
|
|
206
|
+
|
|
207
|
+
unmaskers: dict[tuple, StreamUnmasker] = {}
|
|
208
|
+
|
|
209
|
+
def um(key: tuple) -> StreamUnmasker:
|
|
210
|
+
if key not in unmaskers:
|
|
211
|
+
unmaskers[key] = self.masker.stream_unmasker(session_id)
|
|
212
|
+
return unmaskers[key]
|
|
213
|
+
|
|
214
|
+
pending = None
|
|
215
|
+
async for chunk in response:
|
|
216
|
+
if isinstance(chunk, (bytes, str)):
|
|
217
|
+
if not self._warned_raw_stream:
|
|
218
|
+
log.warning("phiproxy: raw SSE stream passed through without unmasking")
|
|
219
|
+
self._warned_raw_stream = True
|
|
220
|
+
if pending is not None:
|
|
221
|
+
yield pending
|
|
222
|
+
pending = None
|
|
223
|
+
yield chunk
|
|
224
|
+
continue
|
|
225
|
+
for choice in getattr(chunk, "choices", None) or []:
|
|
226
|
+
delta = getattr(choice, "delta", None)
|
|
227
|
+
if delta is None:
|
|
228
|
+
continue
|
|
229
|
+
idx = getattr(choice, "index", 0) or 0
|
|
230
|
+
content = getattr(delta, "content", None)
|
|
231
|
+
if isinstance(content, str):
|
|
232
|
+
delta.content = um((idx, "content")).feed(content)
|
|
233
|
+
for tc in getattr(delta, "tool_calls", None) or []:
|
|
234
|
+
fn = getattr(tc, "function", None)
|
|
235
|
+
args = getattr(fn, "arguments", None) if fn is not None else None
|
|
236
|
+
if isinstance(args, str):
|
|
237
|
+
fn.arguments = um((idx, "tool", getattr(tc, "index", 0) or 0)).feed(args)
|
|
238
|
+
if pending is not None:
|
|
239
|
+
yield pending
|
|
240
|
+
pending = chunk
|
|
241
|
+
|
|
242
|
+
if pending is not None:
|
|
243
|
+
for (idx, kind, *rest), u in unmaskers.items():
|
|
244
|
+
tail = u.flush()
|
|
245
|
+
if not tail:
|
|
246
|
+
continue
|
|
247
|
+
choice = next((c for c in (getattr(pending, "choices", None) or [])
|
|
248
|
+
if (getattr(c, "index", 0) or 0) == idx), None)
|
|
249
|
+
delta = getattr(choice, "delta", None) if choice is not None else None
|
|
250
|
+
if delta is None:
|
|
251
|
+
continue
|
|
252
|
+
if kind == "content":
|
|
253
|
+
delta.content = (getattr(delta, "content", None) or "") + tail
|
|
254
|
+
else:
|
|
255
|
+
for tc in getattr(delta, "tool_calls", None) or []:
|
|
256
|
+
if (getattr(tc, "index", 0) or 0) == rest[0] and getattr(tc, "function", None):
|
|
257
|
+
tc.function.arguments = (tc.function.arguments or "") + tail
|
|
258
|
+
break
|
|
259
|
+
else:
|
|
260
|
+
log.warning("phiproxy: could not place the last tool-call argument fragment")
|
|
261
|
+
yield pending
|
|
262
|
+
|
|
263
|
+
# ------------------------------------------------------------- unmasking
|
|
264
|
+
def _unmask_response(self, response: Any, session_id: str) -> Any:
|
|
265
|
+
if isinstance(response, dict):
|
|
266
|
+
return self.masker.unmask_payload(response, session_id)
|
|
267
|
+
# OpenAI-shaped ModelResponse
|
|
268
|
+
for choice in getattr(response, "choices", None) or []:
|
|
269
|
+
msg = getattr(choice, "message", None)
|
|
270
|
+
if msg is None:
|
|
271
|
+
continue
|
|
272
|
+
for attr in ("content", "reasoning_content"):
|
|
273
|
+
val = getattr(msg, attr, None)
|
|
274
|
+
if isinstance(val, str):
|
|
275
|
+
setattr(msg, attr, self.masker.unmask(val, session_id))
|
|
276
|
+
for tc in getattr(msg, "tool_calls", None) or []:
|
|
277
|
+
fn = getattr(tc, "function", None)
|
|
278
|
+
if fn is not None and isinstance(getattr(fn, "arguments", None), str):
|
|
279
|
+
fn.arguments = self.masker.unmask_payload({"arguments": fn.arguments}, session_id)["arguments"]
|
|
280
|
+
# Anthropic-shaped (content blocks) or Responses API (output items)
|
|
281
|
+
for attr in ("content", "output"):
|
|
282
|
+
val = getattr(response, attr, None)
|
|
283
|
+
if isinstance(val, list):
|
|
284
|
+
try:
|
|
285
|
+
setattr(response, attr, self._unmask_objects(val, session_id))
|
|
286
|
+
except (AttributeError, TypeError):
|
|
287
|
+
pass
|
|
288
|
+
return response
|
|
289
|
+
|
|
290
|
+
def _unmask_objects(self, items: list, session_id: str) -> list:
|
|
291
|
+
out = []
|
|
292
|
+
for it in items:
|
|
293
|
+
if isinstance(it, (dict, list, str)):
|
|
294
|
+
out.append(self.masker.unmask_payload(it, session_id))
|
|
295
|
+
continue
|
|
296
|
+
for attr in ("text", "input", "arguments"):
|
|
297
|
+
val = getattr(it, attr, None)
|
|
298
|
+
if isinstance(val, (str, dict, list)):
|
|
299
|
+
setattr(it, attr, self.masker.unmask_payload(val, session_id))
|
|
300
|
+
inner = getattr(it, "content", None)
|
|
301
|
+
if isinstance(inner, list):
|
|
302
|
+
setattr(it, "content", self._unmask_objects(inner, session_id))
|
|
303
|
+
out.append(it)
|
|
304
|
+
return out
|