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.
@@ -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