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/masker.py ADDED
@@ -0,0 +1,282 @@
1
+ """Mask text and LLM payloads before they leave; restore them when replies come back."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ import json
7
+ import re
8
+ from collections import Counter
9
+ from dataclasses import dataclass, field
10
+ from typing import Any, Callable, Iterable, Literal, Optional, Sequence
11
+
12
+ from .dates import shift_date_text
13
+ from .detectors.base import Detector, fill_text, merge_entities
14
+ from .detectors.known import KnownEntities, KnownEntityDetector
15
+ from .detectors.regex import RegexDetector
16
+ from .entities import Entity, EntityType
17
+ from .vault import InMemoryVault, Vault
18
+
19
+
20
+ class PhiproxyError(Exception):
21
+ """Masking failed. Callers must not send the original content (fail closed)."""
22
+
23
+
24
+ class UnsupportedContentError(PhiproxyError):
25
+ """The payload holds content phiproxy cannot mask (images, audio, files)."""
26
+
27
+
28
+ @dataclass
29
+ class Policy:
30
+ # Clinician names are not patient identifiers under Safe Harbor and masking
31
+ # them hurts answers ("Dr. [PROVIDER_1] said..."), so they pass by default.
32
+ disabled_types: set[EntityType] = field(default_factory=lambda: {EntityType.PROVIDER})
33
+ # "token": dates become [DATE_n]. "shift": dates move by a per-session offset,
34
+ # keeping intervals intact; the reply is shifted back.
35
+ date_mode: Literal["token", "shift"] = "token"
36
+ day_first: bool = False # how to read 03/04/2026 (False = US month first)
37
+ allow_images: bool = False
38
+ allow_audio: bool = False
39
+ allow_files: bool = False
40
+
41
+
42
+ @dataclass
43
+ class MaskResult:
44
+ text: str
45
+ entities: list[Entity] # contains the original PHI - never log this
46
+
47
+ def summary(self) -> dict[str, int]:
48
+ """Counts per entity type; safe to log."""
49
+ return dict(Counter(e.type.value for e in self.entities))
50
+
51
+
52
+ _TYPE_ALTERNATION = "|".join(
53
+ sorted((t.value.replace("_", "[ _]?") for t in EntityType), key=len, reverse=True)
54
+ )
55
+ # Tolerant token matcher: [NAME_1], [name 1], [ NAME-1 ], NAME_1
56
+ _TOKEN_RE = re.compile(
57
+ rf"\[\s*(?P<t1>{_TYPE_ALTERNATION})[ _\-]?(?P<n1>\d+)\s*\]|\b(?P<t2>{_TYPE_ALTERNATION})_(?P<n2>\d+)\b",
58
+ re.IGNORECASE,
59
+ )
60
+
61
+ # Keys whose string values are structure, not content.
62
+ _STRUCTURAL_KEYS = {
63
+ "role", "type", "id", "tool_call_id", "tool_use_id", "model", "cache_control",
64
+ "media_type", "detail", "format", "index", "finish_reason", "object", "signature",
65
+ "stop_reason", "call_id", "status",
66
+ }
67
+ _STREAM_HOLD = 48 # chars held back while streaming so tokens/dates are never split
68
+
69
+
70
+ class Masker:
71
+ """Detects identifiers, swaps them for tokens, and swaps them back.
72
+
73
+ >>> m = Masker()
74
+ >>> r = m.mask("Call me at 416-555-0142", session_id="s1")
75
+ >>> r.text
76
+ 'Call me at [PHONE_1]'
77
+ >>> m.unmask("I will call [PHONE_1] today.", session_id="s1")
78
+ 'I will call 416-555-0142 today.'
79
+ """
80
+
81
+ def __init__(
82
+ self,
83
+ vault: Optional[Vault] = None,
84
+ detectors: Optional[Sequence[Detector]] = None,
85
+ policy: Optional[Policy] = None,
86
+ ):
87
+ self.vault: Vault = vault if vault is not None else InMemoryVault()
88
+ self.detectors: list[Detector] = list(detectors) if detectors is not None else [RegexDetector()]
89
+ self.policy = policy or Policy()
90
+ self._date_detector = RegexDetector(enabled={EntityType.DATE})
91
+
92
+ # ------------------------------------------------------------------ detect
93
+ def detect(self, text: str, known: Optional[KnownEntities] = None) -> list[Entity]:
94
+ detectors: list[Detector] = list(self.detectors)
95
+ if known is not None and not known.is_empty():
96
+ detectors.insert(0, KnownEntityDetector(known))
97
+ found: list[Entity] = []
98
+ for d in detectors:
99
+ found.extend(d.detect(text))
100
+ found = [e for e in found if e.type not in self.policy.disabled_types]
101
+ return fill_text(text, merge_entities(found))
102
+
103
+ # -------------------------------------------------------------------- mask
104
+ def mask(self, text: str, session_id: str, known: Optional[KnownEntities] = None) -> MaskResult:
105
+ try:
106
+ entities = self.detect(text, known)
107
+ out: list[str] = []
108
+ pos = 0
109
+ offset = None
110
+ for e in entities:
111
+ out.append(text[pos : e.start])
112
+ replacement = None
113
+ if e.type is EntityType.DATE and self.policy.date_mode == "shift":
114
+ if offset is None:
115
+ offset = self.vault.date_offset(session_id)
116
+ replacement = shift_date_text(e.text, offset, self.policy.day_first)
117
+ if replacement is None:
118
+ replacement = self.vault.token_for(session_id, e.type, e.value)
119
+ out.append(replacement)
120
+ pos = e.end
121
+ out.append(text[pos:])
122
+ return MaskResult("".join(out), entities)
123
+ except PhiproxyError:
124
+ raise
125
+ except Exception as exc: # fail closed
126
+ raise PhiproxyError(f"masking failed: {type(exc).__name__}") from exc
127
+
128
+ # ------------------------------------------------------------------ unmask
129
+ def unmask(self, text: str, session_id: str) -> str:
130
+ if not text:
131
+ return text
132
+ mapping = self.vault.mapping(session_id)
133
+
134
+ def repl(m: re.Match[str]) -> str:
135
+ t = (m.group("t1") or m.group("t2")).upper().replace(" ", "_")
136
+ if "_" not in t: # "HEALTHCARD" -> "HEALTH_CARD"
137
+ t = next((et.value for et in EntityType if et.value.replace("_", "") == t), t)
138
+ n = m.group("n1") or m.group("n2")
139
+ value = mapping.get(f"[{t}_{n}]")
140
+ return value if value is not None else m.group(0)
141
+
142
+ out = _TOKEN_RE.sub(repl, text) if mapping else text
143
+ if self.policy.date_mode == "shift":
144
+ out = self._shift_all_dates(out, session_id, direction=-1)
145
+ return out
146
+
147
+ def remask(self, text: str, session_id: str) -> str:
148
+ """Put tokens back over real values (e.g. before writing a reply to logs)."""
149
+ if not text:
150
+ return text
151
+ mapping = self.vault.mapping(session_id)
152
+ for token, value in sorted(mapping.items(), key=lambda kv: len(kv[1]), reverse=True):
153
+ if len(value) < 2:
154
+ continue
155
+ text = re.sub(r"(?<!\w)" + re.escape(value) + r"(?!\w)", token, text, flags=re.IGNORECASE)
156
+ if self.policy.date_mode == "shift":
157
+ text = self._shift_all_dates(text, session_id, direction=+1)
158
+ return text
159
+
160
+ def _shift_all_dates(self, text: str, session_id: str, direction: int) -> str:
161
+ dates = self._date_detector.detect(text)
162
+ if not dates:
163
+ return text
164
+ days = direction * self.vault.date_offset(session_id)
165
+ out, pos = [], 0
166
+ for e in merge_entities(dates):
167
+ shifted = shift_date_text(text[e.start : e.end], days, self.policy.day_first)
168
+ out.append(text[pos : e.start])
169
+ out.append(shifted if shifted is not None else text[e.start : e.end])
170
+ pos = e.end
171
+ out.append(text[pos:])
172
+ return "".join(out)
173
+
174
+ # ---------------------------------------------------------------- payloads
175
+ def mask_payload(self, obj: Any, session_id: str, known: Optional[KnownEntities] = None) -> Any:
176
+ """Mask every content string in a JSON-like payload (messages, content blocks,
177
+ tool calls, tool results). Returns a copy; raises on images/audio/files
178
+ unless the policy allows them (they then pass through *unmasked*)."""
179
+ return _walk(copy.deepcopy(obj), lambda s: self.mask(s, session_id, known).text, self.policy, masking=True)
180
+
181
+ def unmask_payload(self, obj: Any, session_id: str) -> Any:
182
+ return _walk(copy.deepcopy(obj), lambda s: self.unmask(s, session_id), self.policy, masking=False)
183
+
184
+ def stream_unmasker(self, session_id: str) -> "StreamUnmasker":
185
+ return StreamUnmasker(self, session_id)
186
+
187
+
188
+ def _walk(obj: Any, fn: Callable[[str], str], policy: Policy, masking: bool, key: Optional[str] = None,
189
+ parent: Optional[dict] = None) -> Any:
190
+ if isinstance(obj, str):
191
+ if key in _STRUCTURAL_KEYS:
192
+ return obj
193
+ if key == "name" and not (parent and "role" in parent):
194
+ return obj # tool/function name, not a participant name
195
+ if key == "arguments": # tool-call arguments are a JSON string
196
+ try:
197
+ parsed = json.loads(obj)
198
+ except ValueError:
199
+ return fn(obj)
200
+ return json.dumps(_walk(parsed, fn, policy, masking), ensure_ascii=False)
201
+ return fn(obj)
202
+ if isinstance(obj, dict):
203
+ kind = _media_kind(obj)
204
+ if kind is not None:
205
+ if not masking:
206
+ return obj
207
+ if kind == "text_document":
208
+ obj["source"] = _walk(obj["source"], fn, policy, masking, "source", obj)
209
+ return obj
210
+ allowed = {"image": policy.allow_images, "audio": policy.allow_audio, "file": policy.allow_files}[kind]
211
+ if not allowed:
212
+ raise UnsupportedContentError(f"payload contains {kind} content; blocked by policy")
213
+ return obj # allowed media passes through UNMASKED
214
+ for k in list(obj.keys()):
215
+ obj[k] = _walk(obj[k], fn, policy, masking, k, obj)
216
+ return obj
217
+ if isinstance(obj, list):
218
+ return [_walk(v, fn, policy, masking, key, parent) for v in obj]
219
+ return obj
220
+
221
+
222
+ _MEDIA_TYPES = {
223
+ "image_url": "image", "image": "image", "input_image": "image",
224
+ "input_audio": "audio", "audio": "audio",
225
+ "file": "file", "input_file": "file", "document": "file",
226
+ }
227
+
228
+
229
+ def _media_kind(part: dict) -> Optional[str]:
230
+ """Classify a content part by its declared type (OpenAI, Anthropic, Responses API)."""
231
+ t = part.get("type")
232
+ if not isinstance(t, str) or t not in _MEDIA_TYPES:
233
+ return None
234
+ src = part.get("source")
235
+ if t == "document" and isinstance(src, dict) and src.get("type") == "text" and isinstance(src.get("data"), str):
236
+ return "text_document" # Anthropic plain-text document: maskable
237
+ return _MEDIA_TYPES[t]
238
+
239
+
240
+ class StreamUnmasker:
241
+ """Unmask a streamed reply chunk by chunk without splitting a token or date.
242
+
243
+ Holds back the last few dozen characters until it is sure they do not
244
+ start a token. Call ``flush()`` when the stream ends.
245
+ """
246
+
247
+ def __init__(self, masker: Masker, session_id: str):
248
+ self.masker = masker
249
+ self.session_id = session_id
250
+ self._buf = ""
251
+
252
+ def feed(self, chunk: str) -> str:
253
+ if not chunk:
254
+ return ""
255
+ self._buf += chunk
256
+ cut = len(self._buf) - _STREAM_HOLD
257
+ if cut <= 0:
258
+ return ""
259
+ cut = self._safe_cut(cut)
260
+ out, self._buf = self._buf[:cut], self._buf[cut:]
261
+ return self.masker.unmask(out, self.session_id)
262
+
263
+ def flush(self) -> str:
264
+ out, self._buf = self._buf, ""
265
+ return self.masker.unmask(out, self.session_id)
266
+
267
+ def _safe_cut(self, cut: int) -> int:
268
+ spans: list[tuple[int, int]] = [m.span() for m in _TOKEN_RE.finditer(self._buf)]
269
+ lb = self._buf.rfind("[", 0, cut)
270
+ if lb != -1 and "]" not in self._buf[lb:cut]:
271
+ spans.append((lb, len(self._buf)))
272
+ if self.masker.policy.date_mode == "shift":
273
+ spans += [(e.start, e.end) for e in self.masker._date_detector.detect(self._buf)]
274
+ for s, e in sorted(spans):
275
+ if s < cut < e:
276
+ cut = s
277
+ return cut
278
+
279
+
280
+ def mask_texts(masker: Masker, texts: Iterable[str], session_id: str,
281
+ known: Optional[KnownEntities] = None) -> list[MaskResult]:
282
+ return [masker.mask(t, session_id, known) for t in texts]
phiproxy/vault.py ADDED
@@ -0,0 +1,182 @@
1
+ """Token vaults: the private mapping between tokens and real values.
2
+
3
+ Tokens are assigned sequentially per session (``[NAME_1]``, ``[NAME_2]``...).
4
+ They are *not* derived from the value (no hashing), so a token on its own carries
5
+ no information about the person - see 45 CFR 164.514(c) on re-identification codes.
6
+ The same value always gets the same token within a session, which keeps
7
+ multi-turn conversations coherent and keeps provider prompt caching working.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import re
13
+ import secrets
14
+ import threading
15
+ import time
16
+ from dataclasses import dataclass, field
17
+ from typing import Optional, Protocol
18
+
19
+ from .entities import EntityType
20
+
21
+
22
+ def normalize_value(entity_type: EntityType, value: str) -> str:
23
+ """Key used to decide whether two spans are 'the same value'."""
24
+ if entity_type in (EntityType.PHONE, EntityType.SSN, EntityType.SIN):
25
+ digits = re.sub(r"\D", "", value)
26
+ if entity_type is EntityType.PHONE and len(digits) == 11 and digits.startswith("1"):
27
+ digits = digits[1:]
28
+ return digits
29
+ if entity_type in (EntityType.HEALTH_CARD, EntityType.MRN, EntityType.ID,
30
+ EntityType.DONOR_ID, EntityType.ACCOUNT, EntityType.POSTAL_CODE):
31
+ return re.sub(r"[\s\-.]", "", value).upper()
32
+ return " ".join(value.split()).casefold()
33
+
34
+
35
+ def format_token(entity_type: EntityType, n: int) -> str:
36
+ return f"[{entity_type.value}_{n}]"
37
+
38
+
39
+ def random_date_offset(min_days: int = 7, max_days: int = 60) -> int:
40
+ """A non-zero day offset in [-max, -min] U [min, max]."""
41
+ days = min_days + secrets.randbelow(max_days - min_days + 1)
42
+ return days if secrets.randbelow(2) else -days
43
+
44
+
45
+ class Vault(Protocol):
46
+ def token_for(self, session_id: str, entity_type: EntityType, value: str) -> str:
47
+ """Return the session's token for this value, creating one if needed."""
48
+
49
+ def value_for(self, session_id: str, token: str) -> Optional[str]:
50
+ """Return the original value for a token, or None if unknown."""
51
+
52
+ def mapping(self, session_id: str) -> dict[str, str]:
53
+ """All token -> value pairs for a session."""
54
+
55
+ def date_offset(self, session_id: str) -> int:
56
+ """The session's date-shift offset in days (created on first use)."""
57
+
58
+ def forget(self, session_id: str) -> None:
59
+ """Delete a session's mapping."""
60
+
61
+
62
+ @dataclass
63
+ class _Session:
64
+ touched: float
65
+ value_to_token: dict[tuple[str, str], str] = field(default_factory=dict)
66
+ token_to_value: dict[str, str] = field(default_factory=dict)
67
+ counters: dict[str, int] = field(default_factory=dict)
68
+ date_offset: Optional[int] = None
69
+
70
+
71
+ class InMemoryVault:
72
+ """Process-local vault. Fine for a single process; use RedisVault behind replicas."""
73
+
74
+ def __init__(self, ttl_seconds: float = 24 * 3600, date_shift_days: tuple[int, int] = (7, 60)):
75
+ self.ttl = ttl_seconds
76
+ self.date_shift_days = date_shift_days
77
+ self._sessions: dict[str, _Session] = {}
78
+ self._lock = threading.Lock()
79
+
80
+ def _get(self, session_id: str) -> _Session:
81
+ now = time.monotonic()
82
+ # Cheap eviction on access.
83
+ expired = [k for k, s in self._sessions.items() if now - s.touched > self.ttl]
84
+ for k in expired:
85
+ del self._sessions[k]
86
+ s = self._sessions.get(session_id)
87
+ if s is None:
88
+ s = self._sessions[session_id] = _Session(touched=now)
89
+ s.touched = now
90
+ return s
91
+
92
+ def token_for(self, session_id: str, entity_type: EntityType, value: str) -> str:
93
+ key = (entity_type.value, normalize_value(entity_type, value))
94
+ with self._lock:
95
+ s = self._get(session_id)
96
+ tok = s.value_to_token.get(key)
97
+ if tok is None:
98
+ n = s.counters.get(entity_type.value, 0) + 1
99
+ s.counters[entity_type.value] = n
100
+ tok = format_token(entity_type, n)
101
+ s.value_to_token[key] = tok
102
+ s.token_to_value[tok] = value
103
+ return tok
104
+
105
+ def value_for(self, session_id: str, token: str) -> Optional[str]:
106
+ with self._lock:
107
+ return self._get(session_id).token_to_value.get(token)
108
+
109
+ def mapping(self, session_id: str) -> dict[str, str]:
110
+ with self._lock:
111
+ return dict(self._get(session_id).token_to_value)
112
+
113
+ def date_offset(self, session_id: str) -> int:
114
+ with self._lock:
115
+ s = self._get(session_id)
116
+ if s.date_offset is None:
117
+ s.date_offset = random_date_offset(*self.date_shift_days)
118
+ return s.date_offset
119
+
120
+ def forget(self, session_id: str) -> None:
121
+ with self._lock:
122
+ self._sessions.pop(session_id, None)
123
+
124
+
125
+ class RedisVault:
126
+ """Vault shared across processes/replicas. Requires ``pip install phiproxy[redis]``.
127
+
128
+ Keys (all expire after ``ttl_seconds`` of inactivity):
129
+ {prefix}:{session}:v2t hash "<TYPE>|<normalized>" -> token
130
+ {prefix}:{session}:t2v hash token -> original value
131
+ {prefix}:{session}:n hash TYPE -> counter
132
+ {prefix}:{session}:shift string day offset
133
+ Values are stored in plain text: protect Redis like the PHI store it is
134
+ (private network, TLS, auth, encryption at rest).
135
+ """
136
+
137
+ def __init__(self, client=None, url: Optional[str] = None, prefix: str = "phiproxy",
138
+ ttl_seconds: int = 24 * 3600, date_shift_days: tuple[int, int] = (7, 60)):
139
+ if client is None:
140
+ import redis # type: ignore[import-not-found]
141
+
142
+ client = redis.Redis.from_url(url or "redis://localhost:6379/0", decode_responses=True)
143
+ self.r = client
144
+ self.prefix = prefix
145
+ self.ttl = ttl_seconds
146
+ self.date_shift_days = date_shift_days
147
+
148
+ def _k(self, session_id: str, part: str) -> str:
149
+ return f"{self.prefix}:{session_id}:{part}"
150
+
151
+ def _touch(self, session_id: str) -> None:
152
+ for part in ("v2t", "t2v", "n", "shift"):
153
+ self.r.expire(self._k(session_id, part), self.ttl)
154
+
155
+ def token_for(self, session_id: str, entity_type: EntityType, value: str) -> str:
156
+ field_ = f"{entity_type.value}|{normalize_value(entity_type, value)}"
157
+ v2t = self._k(session_id, "v2t")
158
+ tok = self.r.hget(v2t, field_)
159
+ if tok is None:
160
+ n = self.r.hincrby(self._k(session_id, "n"), entity_type.value, 1)
161
+ candidate = format_token(entity_type, int(n))
162
+ if self.r.hsetnx(v2t, field_, candidate):
163
+ self.r.hset(self._k(session_id, "t2v"), candidate, value)
164
+ tok = candidate
165
+ else: # another replica assigned it first
166
+ tok = self.r.hget(v2t, field_)
167
+ self._touch(session_id)
168
+ return str(tok)
169
+
170
+ def value_for(self, session_id: str, token: str) -> Optional[str]:
171
+ return self.r.hget(self._k(session_id, "t2v"), token)
172
+
173
+ def mapping(self, session_id: str) -> dict[str, str]:
174
+ return dict(self.r.hgetall(self._k(session_id, "t2v")) or {})
175
+
176
+ def date_offset(self, session_id: str) -> int:
177
+ key = self._k(session_id, "shift")
178
+ self.r.set(key, random_date_offset(*self.date_shift_days), nx=True, ex=self.ttl)
179
+ return int(self.r.get(key))
180
+
181
+ def forget(self, session_id: str) -> None:
182
+ self.r.delete(*(self._k(session_id, p) for p in ("v2t", "t2v", "n", "shift")))
@@ -0,0 +1,208 @@
1
+ Metadata-Version: 2.5
2
+ Name: phiproxy
3
+ Version: 0.1.0a1
4
+ Summary: Your patients' stand-in on the way to any LLM, and back: reversible PHI masking proxy (LiteLLM guardrail + Python library).
5
+ Project-URL: Homepage, https://github.com/DecisionTreeTechnology/phiproxy
6
+ Project-URL: Issues, https://github.com/DecisionTreeTechnology/phiproxy/issues
7
+ Author: Decision Tree Technology
8
+ License-Expression: Apache-2.0
9
+ License-File: LICENSE
10
+ License-File: NOTICE
11
+ Keywords: de-identification,guardrail,hipaa,litellm,llm,phi,phipa,pii,privacy
12
+ Classifier: Development Status :: 2 - Pre-Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Healthcare Industry
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
17
+ Classifier: Topic :: Security
18
+ Requires-Python: >=3.10
19
+ Provides-Extra: dev
20
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
21
+ Requires-Dist: pytest>=8; extra == 'dev'
22
+ Provides-Extra: litellm
23
+ Requires-Dist: litellm>=1.70; extra == 'litellm'
24
+ Provides-Extra: presidio
25
+ Requires-Dist: presidio-analyzer>=2.2; extra == 'presidio'
26
+ Provides-Extra: redis
27
+ Requires-Dist: redis>=5; extra == 'redis'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # phiproxy
31
+
32
+ **Your patients' stand-in on the way to any LLM, and back.**
33
+
34
+ phiproxy is a proxy in two senses:
35
+
36
+ 1. **A proxy for the patient.** Before a prompt leaves your network, every identifier (name, date of birth, phone, health card number...) is replaced by a stand-in such as `[NAME_1]`. The AI provider only ever sees the stand-ins.
37
+ 2. **A proxy server.** It sits between your apps and every LLM provider as a [LiteLLM](https://github.com/BerriAI/litellm) guardrail, so there is one enforcement point for OpenAI, Anthropic, Azure, Bedrock and Gemini. It also works as a plain Python library.
38
+
39
+ When the reply comes back, phiproxy swaps the stand-ins for the real values, so your users and your tools see the right patient. The round trip is the point: the model can still reason about the conversation without ever seeing who it is about.
40
+
41
+ ```
42
+ "Hi, this is Sarah Chen, DOB 1990-03-05. Call me at 416-555-0142."
43
+ │ phiproxy (inside your network)
44
+ ▼
45
+ "Hi, this is [NAME_1], DOB [DATE_1]. Call me at [PHONE_1]." ──► any LLM provider
46
+ ▲
47
+ │ reply: "Thanks [NAME_1], we'll call [PHONE_1] today."
48
+ "Thanks Sarah Chen, we'll call 416-555-0142 today." ◄──
49
+ ```
50
+
51
+ > **Status: pre-alpha (0.1.0a1).** APIs will change. Do not rely on it as your only control.
52
+
53
+ ## Read this first
54
+
55
+ - **phiproxy reduces how much PHI reaches an LLM provider. It does not make an unapproved provider compliant.** No detector catches 100% of identifiers; every miss is a disclosure. Send PHI only to providers you have a BAA (HIPAA) or equivalent agreement (e.g. PHIPA agent agreement) with, and use phiproxy as an extra layer on top.
56
+ - Audio, images and files cannot be masked as text. phiproxy **blocks** them by default.
57
+ - Get privacy or legal review before relying on de-identification for any workload.
58
+
59
+ ## What makes it different
60
+
61
+ - **Your own records as a detector.** Pass the identifiers you already hold for the patient (name, DOB, phone, health card). Exact and one-typo matching against them catches lowercase names, nicknames in context and misspellings that pattern matching misses. On the benchmark below this lifts recall from 61% to 86%.
62
+ - **Stable tokens per conversation.** The same value gets the same token on every turn of a session, so the model can follow who is who and provider prompt caching keeps working. Tokens are sequential, not derived from the value (see 45 CFR 164.514(c)).
63
+ - **Fail closed.** If masking errors, or a request holds media the policy does not allow, the request is rejected and nothing is sent. Clients cannot switch the guardrail off through request metadata.
64
+ - **Clinic-specific identifiers.** Canadian health card numbers (OHIP, RAMQ), SIN, donor and embryo IDs, spoken numbers and dates from call transcripts.
65
+ - **Date shifting (optional).** Instead of `[DATE_1]`, move every date in a session by the same random offset. Intervals stay true (retrieval → transfer 5 days later) and the reply is shifted back.
66
+ - **Streaming and tool calls.** Tokens split across stream chunks are restored correctly; tool-call arguments are masked going out and restored coming back, so your tools receive real values.
67
+
68
+ ## Quick start: library
69
+
70
+ ```bash
71
+ pip install phiproxy # library
72
+ pip install "phiproxy[litellm]" # + LiteLLM guardrail
73
+ ```
74
+
75
+ ```python
76
+ from phiproxy import Masker, KnownEntities
77
+
78
+ masker = Masker()
79
+ known = KnownEntities(names=["Sarah Chen"], phones=["416-555-0142"], dates_of_birth=["1990-03-05"])
80
+
81
+ masked = masker.mask("hi it's sarah, dob march 5 1990", session_id="conv-42", known=known)
82
+ masked.text # 'hi it's [NAME_1], dob [DATE_1]'
83
+ masked.summary() # {'NAME': 1, 'DATE': 1} - safe to log; masked.entities is not
84
+
85
+ reply = call_your_llm(masked.text)
86
+ masker.unmask(reply, session_id="conv-42")
87
+ ```
88
+
89
+ Whole payloads (OpenAI or Anthropic message lists, tool calls, tool results):
90
+
91
+ ```python
92
+ safe_messages = masker.mask_payload(messages, session_id="conv-42", known=known)
93
+ restored = masker.unmask_payload(response_message, session_id="conv-42")
94
+ ```
95
+
96
+ Streaming:
97
+
98
+ ```python
99
+ u = masker.stream_unmasker("conv-42")
100
+ for chunk in stream:
101
+ print(u.feed(chunk), end="")
102
+ print(u.flush())
103
+ ```
104
+
105
+ ## Quick start: LiteLLM gateway
106
+
107
+ ```yaml
108
+ # config.yaml
109
+ guardrails:
110
+ - guardrail_name: phiproxy
111
+ litellm_params:
112
+ guardrail: phiproxy.integrations.litellm.PhiproxyGuardrail
113
+ mode: [pre_call, post_call]
114
+ default_on: true
115
+ redis_url: os.environ/PHIPROXY_REDIS_URL # optional; in-memory if unset
116
+
117
+ litellm_settings:
118
+ turn_off_message_logging: true # otherwise LiteLLM logs hold the restored reply
119
+ ```
120
+
121
+ Clients pass the conversation id and, optionally, known identifiers in `metadata`:
122
+
123
+ ```python
124
+ client.chat.completions.create(
125
+ model="gpt-4o",
126
+ messages=[...],
127
+ extra_body={"metadata": {
128
+ "session_id": "conv-42",
129
+ "phiproxy_known": {"names": ["Sarah Chen"], "phones": ["416-555-0142"]},
130
+ }},
131
+ )
132
+ ```
133
+
134
+ `phiproxy_known` is removed from the request before anything is forwarded. Instead of sending identifiers, you can configure `known_entities_provider: "yourapp.phi:lookup"`, an (async) function that receives `session_id` and `metadata` (e.g. a patient id) and returns them from your own system.
135
+
136
+ A ready-to-run gateway (LiteLLM + phiproxy + Redis vault) is in [`deploy/`](https://github.com/DecisionTreeTechnology/phiproxy/tree/main/deploy):
137
+
138
+ ```bash
139
+ cp deploy/.env.example deploy/.env # add provider keys
140
+ docker compose -f deploy/docker-compose.yml up --build
141
+ ```
142
+
143
+ `examples/e2e/run_e2e.py` runs the real LiteLLM proxy against a fake provider that records every request. It checks that the provider received only tokens, that the client got the PHI back (plain and streaming), that images are blocked and that client opt-out is ignored. It runs in CI.
144
+
145
+ ## What it detects
146
+
147
+ | Type | Examples | Layer |
148
+ |---|---|---|
149
+ | `NAME` | "this is Maria Lopez", "my husband Dave", any name from your records (any case, one typo) | regex context + known |
150
+ | `PHONE` | 416-555-0142, (416) 555 0142, +44 20 7946 0958, "four one six five five five…" | regex + known |
151
+ | `EMAIL`, `URL`, `IP_ADDRESS` | | regex |
152
+ | `DATE` | 2026-11-03, 11/3, March 5, 1990, Nov 8th, "march fifteenth 1988" (year alone is not masked) | regex + known DOB |
153
+ | `AGE` | ages over 89 only (Safe Harbor) | regex |
154
+ | `ADDRESS`, `POSTAL_CODE`, `ZIP` | 22 Elm Street apt 4, PO Box 12, M5V 2T6, TX 78701 | regex + known |
155
+ | `HEALTH_CARD`, `SIN`, `SSN` | OHIP 1234-567-890-AB, RAMQ, keyword + number, Luhn-checked SIN | regex + known |
156
+ | `MRN`, `ACCOUNT`, `DONOR_ID`, `ID` | "MRN: 00482913", "policy number: XK-99812", "donor D-4521" | regex + known |
157
+ | `PROVIDER` | "Dr. Patel" (passes by default, as clinician names are not patient identifiers; enable with `Policy(disabled_types=set())`) | regex |
158
+
159
+ Optional NER layer: `pip install phiproxy[presidio]` and add `PresidioDetector()` to the detector list. It runs in-process; nothing is sent anywhere to detect PHI.
160
+
161
+ ## Benchmark
162
+
163
+ `benchmark/` holds a synthetic **patient communications** set: SMS, web chat, call transcripts and referral notes, the kind of text clinics actually send to LLMs. Most existing de-identification work targets clinical notes instead. All people and numbers are invented. Run it with `python benchmark/score.py`.
164
+
165
+ v0 results (288 messages, 560 labelled spans):
166
+
167
+ | config | recall | missed |
168
+ |---|---|---|
169
+ | regex | 61.4% | 216 |
170
+ | regex + known entities | **85.7%** | 80 |
171
+
172
+ | recall by channel | regex | regex + known |
173
+ |---|---|---|
174
+ | SMS | 55% | 95% |
175
+ | web chat | 74% | 84% |
176
+ | call transcripts | 50% | 80% |
177
+ | referral notes | 63% | 79% |
178
+
179
+ **How to read this honestly:**
180
+ - v0 was written by the same team that wrote the detectors. Expect real-world recall to be **lower**. An independent, larger set is the next milestone, and contributions are welcome.
181
+ - Precision is reported as 100% on v0, but v0 has almost no non-PHI distractor text, so that number means little yet.
182
+ - Known misses today: **cities and workplaces** ("I live in Sudbury", "I work at the Tim Hortons on King") and **names not in your records written in lowercase** ("my husband ravi"). These need the NER layer or a local model, which is on the roadmap.
183
+
184
+ ## Deployment shapes
185
+
186
+ - **Gateway:** LiteLLM + phiproxy as one container inside your private network, Redis as the shared vault. Apps change only their base URL. This gives one enforcement and audit point.
187
+ - **Library:** call `mask` / `unmask` in your own code. It is the smallest footprint, but every code path must remember to call it.
188
+ - **Sidecar (planned):** a small HTTP wrapper for apps in other languages (.NET, Java, Node).
189
+
190
+ The vault holds real values. Protect Redis like the PHI store it is: private network, auth, TLS, short TTL, no persistence.
191
+
192
+ ## Roadmap
193
+
194
+ - Larger independent benchmark with distractor text, plus multilingual sets (French, Polish, Hebrew, Spanish)
195
+ - Local small-model detector for names, places and workplaces
196
+ - Gazetteer for cities and regions
197
+ - HTTP sidecar; Anthropic `/v1/messages` streaming
198
+ - Masked logging hook for LiteLLM
199
+
200
+ ## Contributing and security
201
+
202
+ See [CONTRIBUTING.md](https://github.com/DecisionTreeTechnology/phiproxy/blob/main/CONTRIBUTING.md) (DCO sign-off required). Report vulnerabilities and detection misses that could leak PHI privately, as described in [SECURITY.md](https://github.com/DecisionTreeTechnology/phiproxy/blob/main/SECURITY.md). **Never put real patient data in issues, tests or benchmark files.**
203
+
204
+ ## License
205
+
206
+ Apache-2.0. Copyright 2026 Decision Tree Technology.
207
+
208
+ Built by [Decision Tree Technology](https://decisiontree.tech/), the team behind [Fertiligent](https://fertiligent.ai/).