medguardx-core 1.0.0__tar.gz

medguardx_core-1.0.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.pyc
+venv/
+.venv/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+testenv/
+
+# Node / Next
+node_modules/
+.next/
+out/
+
+# Data & secrets
+*.db
+*.db-wal
+*.db-shm
+.env
+!.env.example
+
+# OS / editor
+.DS_Store
+*.mov
+
+# TS build info
+*.tsbuildinfo

medguardx_core-1.0.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: medguardx-core
+Version: 1.0.0
+Summary: Context-aware PII/PHI detection and masking engine for healthcare data. Stateless, model-configurable, framework-agnostic.
+Project-URL: Homepage, https://github.com/adarshcod30/MedGuardX
+Project-URL: Repository, https://github.com/adarshcod30/MedGuardX
+Project-URL: Issues, https://github.com/adarshcod30/MedGuardX/issues
+Author-email: Adarsh Dwivedi <23ucs509@lnmiit.ac.in>
+License: Apache-2.0
+Keywords: anonymization,dpdp,gdpr,healthcare,hipaa,masking,phi,pii,presidio
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Requires-Dist: presidio-analyzer>=2.2.354
+Requires-Dist: presidio-anonymizer>=2.2.354
+Requires-Dist: spacy<3.9,>=3.7
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: trf
+Requires-Dist: spacy-transformers>=1.3; extra == 'trf'
+Description-Content-Type: text/markdown
+
+# medguardx-core
+
+Context-aware **PII/PHI detection and masking** for healthcare data — a stateless,
+model-configurable, framework-agnostic Python engine. This is the reusable core of
+[MedGuardX](https://github.com/adarshcod30/MedGuardX); embed it in any project.
+
+## Why
+
+- **Stateless & safe to embed** — text and context in, masked text out. No auth, no
+  database, no global state. Your app owns storage, identity, and audit.
+- **Bring your own model** — any installed spaCy English pipeline works
+  (`en_core_web_sm` / `md` / `lg` / `trf`). Pick your accuracy/RAM trade-off.
+- **Model-independent structured IDs** — Aadhaar (Verhoeff-validated), PAN, MRN,
+  credit cards, IBAN, IP are matched by format, so they work identically on every
+  model.
+- **Deterministic, leak-proof masking** — overlapping detections are resolved by a
+  fixed priority, and no strategy ever leaves part of a detected identifier visible.
+
+## Install
+
+```bash
+pip install medguardx-core
+python -m spacy download en_core_web_md   # recommended default
+# other options: en_core_web_sm (smallest) · en_core_web_lg (best statistical)
+# for the transformer model: pip install "medguardx-core[trf]" && python -m spacy download en_core_web_trf
+```
+
+The engine is model-agnostic — install any spaCy English pipeline and pass its name
+to `EngineConfig(model=...)`. (Model wheels aren't declared as dependencies because
+spaCy models aren't on PyPI; `spacy download` is the standard way to fetch them.)
+
+## Quickstart
+
+```python
+from medguardx import MedGuardEngine, EngineConfig, Role, Purpose
+
+engine = MedGuardEngine(EngineConfig(model="en_core_web_md"))
+
+result = engine.process(
+    "Patient John Smith, Aadhaar 2341 2341 2346, card 4111 1111 1111 1111.",
+    role=Role.NURSE, purpose=Purpose.TREATMENT, consent=False,
+)
+
+print(result.masking_strategy if False else result.strategy.value)  # partial_mask
+print(result.masked_text)
+# Patient [NAME_REDACTED], Aadhaar [AADHAAR_REDACTED], card [CARD ****1111].
+```
+
+Compose the steps yourself when you need to:
+
+```python
+entities = engine.detect(text)                       # list[PIIEntity]
+strategy, rule = engine.evaluate_policy(Role.DOCTOR, Purpose.RESEARCH, consent=False)
+masked = engine.mask(text, entities, strategy)
+```
+
+## Configuration
+
+`EngineConfig(model=..., score_threshold=..., entities=[...], enable_custom_recognizers=True)`.
+
+`DATE_TIME` is intentionally **not** in the default entity set — as a high-confidence
+span it used to shadow phone numbers and Aadhaar. Add it back explicitly if you need
+date masking.
+
+## Custom policy
+
+```python
+from medguardx import PolicyEngine, MedGuardEngine, Role, Purpose, MaskingStrategy
+
+rules = {(Role.COMPANY, Purpose.TREATMENT, True): (MaskingStrategy.PARTIAL_MASK, "vendor SLA")}
+engine = MedGuardEngine(policy=PolicyEngine(rules=rules))   # deny-by-default for the rest
+```
+
+## Masking strategies
+
+| Strategy | Behaviour |
+|---|---|
+| `full_access` | text returned unchanged |
+| `partial_mask` | identifiers redacted; card/phone/email keep a minimal safe hint |
+| `full_anonymize` | every identifier replaced with a typed `[TYPE_REDACTED]` token |
+| `deny` | access refused; no data returned |
+
+## Ingestion (optional)
+
+`medguardx.ingestion.extract_text(filename, bytes)` pulls text from plain text, PDF
+(`pdfplumber`), images (`pytesseract`), and HL7 (`hl7apy`). Those extractors import
+their heavy deps lazily.
+
+## License
+
+Apache-2.0.

medguardx_core-1.0.0/README.md

@@ -0,0 +1,91 @@
+# medguardx-core
+
+Context-aware **PII/PHI detection and masking** for healthcare data — a stateless,
+model-configurable, framework-agnostic Python engine. This is the reusable core of
+[MedGuardX](https://github.com/adarshcod30/MedGuardX); embed it in any project.
+
+## Why
+
+- **Stateless & safe to embed** — text and context in, masked text out. No auth, no
+  database, no global state. Your app owns storage, identity, and audit.
+- **Bring your own model** — any installed spaCy English pipeline works
+  (`en_core_web_sm` / `md` / `lg` / `trf`). Pick your accuracy/RAM trade-off.
+- **Model-independent structured IDs** — Aadhaar (Verhoeff-validated), PAN, MRN,
+  credit cards, IBAN, IP are matched by format, so they work identically on every
+  model.
+- **Deterministic, leak-proof masking** — overlapping detections are resolved by a
+  fixed priority, and no strategy ever leaves part of a detected identifier visible.
+
+## Install
+
+```bash
+pip install medguardx-core
+python -m spacy download en_core_web_md   # recommended default
+# other options: en_core_web_sm (smallest) · en_core_web_lg (best statistical)
+# for the transformer model: pip install "medguardx-core[trf]" && python -m spacy download en_core_web_trf
+```
+
+The engine is model-agnostic — install any spaCy English pipeline and pass its name
+to `EngineConfig(model=...)`. (Model wheels aren't declared as dependencies because
+spaCy models aren't on PyPI; `spacy download` is the standard way to fetch them.)
+
+## Quickstart
+
+```python
+from medguardx import MedGuardEngine, EngineConfig, Role, Purpose
+
+engine = MedGuardEngine(EngineConfig(model="en_core_web_md"))
+
+result = engine.process(
+    "Patient John Smith, Aadhaar 2341 2341 2346, card 4111 1111 1111 1111.",
+    role=Role.NURSE, purpose=Purpose.TREATMENT, consent=False,
+)
+
+print(result.masking_strategy if False else result.strategy.value)  # partial_mask
+print(result.masked_text)
+# Patient [NAME_REDACTED], Aadhaar [AADHAAR_REDACTED], card [CARD ****1111].
+```
+
+Compose the steps yourself when you need to:
+
+```python
+entities = engine.detect(text)                       # list[PIIEntity]
+strategy, rule = engine.evaluate_policy(Role.DOCTOR, Purpose.RESEARCH, consent=False)
+masked = engine.mask(text, entities, strategy)
+```
+
+## Configuration
+
+`EngineConfig(model=..., score_threshold=..., entities=[...], enable_custom_recognizers=True)`.
+
+`DATE_TIME` is intentionally **not** in the default entity set — as a high-confidence
+span it used to shadow phone numbers and Aadhaar. Add it back explicitly if you need
+date masking.
+
+## Custom policy
+
+```python
+from medguardx import PolicyEngine, MedGuardEngine, Role, Purpose, MaskingStrategy
+
+rules = {(Role.COMPANY, Purpose.TREATMENT, True): (MaskingStrategy.PARTIAL_MASK, "vendor SLA")}
+engine = MedGuardEngine(policy=PolicyEngine(rules=rules))   # deny-by-default for the rest
+```
+
+## Masking strategies
+
+| Strategy | Behaviour |
+|---|---|
+| `full_access` | text returned unchanged |
+| `partial_mask` | identifiers redacted; card/phone/email keep a minimal safe hint |
+| `full_anonymize` | every identifier replaced with a typed `[TYPE_REDACTED]` token |
+| `deny` | access refused; no data returned |
+
+## Ingestion (optional)
+
+`medguardx.ingestion.extract_text(filename, bytes)` pulls text from plain text, PDF
+(`pdfplumber`), images (`pytesseract`), and HL7 (`hl7apy`). Those extractors import
+their heavy deps lazily.
+
+## License
+
+Apache-2.0.

medguardx_core-1.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "medguardx-core"
+version = "1.0.0"
+description = "Context-aware PII/PHI detection and masking engine for healthcare data. Stateless, model-configurable, framework-agnostic."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Adarsh Dwivedi", email = "23ucs509@lnmiit.ac.in" }]
+keywords = ["pii", "phi", "healthcare", "masking", "anonymization", "presidio", "hipaa", "dpdp", "gdpr"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Linguistic",
+]
+
+dependencies = [
+    "presidio-analyzer>=2.2.354",
+    "presidio-anonymizer>=2.2.354",
+    "spacy>=3.7,<3.9",
+]
+
+# The engine is model-agnostic: after install, choose any spaCy English pipeline
+# with `python -m spacy download en_core_web_{sm,md,lg,trf}` and pass its name to
+# EngineConfig(model=...). Model wheels are NOT declared as dependencies because
+# PyPI forbids direct-URL requirements and spaCy models are not on PyPI.
+[project.optional-dependencies]
+# The transformer pipeline (en_core_web_trf) additionally needs spacy-transformers.
+trf = ["spacy-transformers>=1.3"]
+dev = ["pytest>=7", "pytest-cov>=4", "build>=1.0", "twine>=5.0"]
+
+[project.urls]
+Homepage = "https://github.com/adarshcod30/MedGuardX"
+Repository = "https://github.com/adarshcod30/MedGuardX"
+Issues = "https://github.com/adarshcod30/MedGuardX/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/medguardx"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

medguardx_core-1.0.0/src/medguardx/__init__.py

@@ -0,0 +1,40 @@
+"""MedGuardX core -- context-aware PII/PHI detection and masking.
+
+Public API::
+
+    from medguardx import (
+        MedGuardEngine, EngineConfig, ProcessResult,
+        PolicyEngine, PIIEntity,
+        Role, Purpose, MaskingStrategy,
+    )
+"""
+from __future__ import annotations
+
+from .config import DEFAULT_ENTITIES, EngineConfig
+from .detection import Detector, PIIEntity, resolve_overlaps
+from .engine import MedGuardEngine, ProcessResult
+from .enums import MaskingStrategy, Purpose, Role
+from .ingestion import ExtractionError, extract_text
+from .masking import mask_text
+from .policy import DEFAULT_RULES, PolicyEngine
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "MedGuardEngine",
+    "EngineConfig",
+    "ProcessResult",
+    "Detector",
+    "PIIEntity",
+    "resolve_overlaps",
+    "PolicyEngine",
+    "DEFAULT_RULES",
+    "DEFAULT_ENTITIES",
+    "ExtractionError",
+    "extract_text",
+    "mask_text",
+    "Role",
+    "Purpose",
+    "MaskingStrategy",
+    "__version__",
+]

medguardx_core-1.0.0/src/medguardx/config.py

@@ -0,0 +1,81 @@
+"""Engine configuration.
+
+Everything an integrator might want to tune lives here. The most important knob
+is ``model``: any installed spaCy English pipeline works (en_core_web_sm / md /
+lg / trf). Nothing else in the engine changes when you swap it -- structured
+identifiers are matched by regex recognizers that are model-independent.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+# Entities detected by default.
+#
+# NOTE: DATE_TIME is deliberately EXCLUDED from the default set. In the old build
+# spaCy tagged nearly every digit run (phone numbers, Aadhaar, card numbers) as a
+# high-confidence DATE_TIME, which hijacked the span and defeated the specialized
+# recognizers -- the root cause of "some data gets masked, some not". Integrators
+# who genuinely need date masking can add it back explicitly.
+DEFAULT_ENTITIES: List[str] = [
+    "PERSON",
+    "PHONE_NUMBER",
+    "EMAIL_ADDRESS",
+    "CREDIT_CARD",
+    "IBAN_CODE",
+    "IP_ADDRESS",
+    "LOCATION",
+    "NRP",
+    "MEDICAL_LICENSE",
+    "URL",
+    "US_SSN",
+    # Custom, model-independent recognizers:
+    "IN_AADHAAR",
+    "IN_PAN",
+    "MEDICAL_RECORD_NUMBER",
+]
+
+# Overlap-resolution priority. When two detections overlap, the one with the
+# higher priority wins regardless of raw score. More specific / structured
+# identifiers rank above generic linguistic ones so a phone number never loses to
+# a stray PERSON or DATE_TIME span. Higher number = higher priority.
+ENTITY_PRIORITY = {
+    "IN_AADHAAR": 100,
+    "IN_PAN": 100,
+    "US_SSN": 100,
+    "CREDIT_CARD": 95,
+    "IBAN_CODE": 95,
+    "MEDICAL_RECORD_NUMBER": 90,
+    "MEDICAL_LICENSE": 85,
+    "EMAIL_ADDRESS": 80,
+    "PHONE_NUMBER": 75,
+    "IP_ADDRESS": 70,
+    "URL": 40,
+    "PERSON": 60,
+    "LOCATION": 55,
+    "NRP": 50,
+    "DATE_TIME": 20,
+}
+
+
+@dataclass
+class EngineConfig:
+    """Configuration for a :class:`~medguardx.engine.MedGuardEngine`.
+
+    Attributes:
+        model: Name of the installed spaCy pipeline to use. Pick per your
+            accuracy/RAM trade-off: ``en_core_web_sm`` (~50MB, weakest),
+            ``en_core_web_md`` (~120MB, recommended default), ``en_core_web_lg``
+            (~600MB, best statistical), ``en_core_web_trf`` (transformer, highest
+            accuracy, heaviest).
+        score_threshold: Minimum confidence for a detection to be kept.
+        entities: Which entity types to detect.
+        enable_custom_recognizers: Register the Aadhaar/PAN/MRN recognizers.
+        default_language: Language code passed to Presidio.
+    """
+
+    model: str = "en_core_web_md"
+    score_threshold: float = 0.35
+    entities: List[str] = field(default_factory=lambda: list(DEFAULT_ENTITIES))
+    enable_custom_recognizers: bool = True
+    default_language: str = "en"

medguardx_core-1.0.0/src/medguardx/detection.py

@@ -0,0 +1,132 @@
+"""PII/PHI detection built on Microsoft Presidio.
+
+Two things here fix the old build's inconsistent masking:
+
+1. The spaCy model is configurable (``EngineConfig.model``) instead of hardcoded.
+2. Overlapping detections are resolved by a deterministic priority pass, so a
+   specialized entity (phone, Aadhaar, card) can never be shadowed by a generic
+   high-score span. In the old build the winner was whatever Presidio happened to
+   score highest, which varied with phrasing -- the source of the flakiness.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Dict, List, Optional
+
+from .config import ENTITY_PRIORITY, EngineConfig
+
+
+@dataclass
+class PIIEntity:
+    """A single detected entity with its exact span in the source text."""
+
+    entity_type: str
+    start: int
+    end: int
+    score: float
+    text: str
+
+    def to_dict(self) -> Dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: Dict) -> "PIIEntity":
+        return cls(
+            entity_type=d["entity_type"],
+            start=int(d["start"]),
+            end=int(d["end"]),
+            score=float(d["score"]),
+            text=d.get("text", ""),
+        )
+
+
+class Detector:
+    """Lazily-initialised Presidio analyzer wrapper.
+
+    The heavy analyzer/model load happens on first use, not at import time, so
+    importing :mod:`medguardx` stays cheap.
+    """
+
+    def __init__(self, config: Optional[EngineConfig] = None) -> None:
+        self.config = config or EngineConfig()
+        self._analyzer = None
+
+    def _get_analyzer(self):
+        if self._analyzer is not None:
+            return self._analyzer
+
+        from presidio_analyzer import AnalyzerEngine, RecognizerRegistry
+        from presidio_analyzer.nlp_engine import NlpEngineProvider
+
+        provider = NlpEngineProvider(
+            nlp_configuration={
+                "nlp_engine_name": "spacy",
+                "models": [{"lang_code": self.config.default_language, "model_name": self.config.model}],
+            }
+        )
+        nlp_engine = provider.create_engine()
+
+        registry = RecognizerRegistry()
+        registry.load_predefined_recognizers(languages=[self.config.default_language])
+        if self.config.enable_custom_recognizers:
+            from .recognizers import build_custom_recognizers
+
+            for recognizer in build_custom_recognizers():
+                registry.add_recognizer(recognizer)
+
+        self._analyzer = AnalyzerEngine(
+            nlp_engine=nlp_engine,
+            registry=registry,
+            supported_languages=[self.config.default_language],
+        )
+        return self._analyzer
+
+    def detect(self, text: str, entities: Optional[List[str]] = None) -> List[PIIEntity]:
+        """Detect PII entities in ``text`` and return a non-overlapping, sorted list."""
+        if not text or not text.strip():
+            return []
+
+        analyzer = self._get_analyzer()
+        raw = analyzer.analyze(
+            text=text,
+            language=self.config.default_language,
+            entities=entities or self.config.entities,
+            score_threshold=self.config.score_threshold,
+        )
+
+        found = [
+            PIIEntity(
+                entity_type=r.entity_type,
+                start=r.start,
+                end=r.end,
+                score=round(float(r.score), 2),
+                text=text[r.start : r.end],
+            )
+            for r in raw
+        ]
+        return resolve_overlaps(found)
+
+
+def resolve_overlaps(entities: List[PIIEntity]) -> List[PIIEntity]:
+    """Collapse overlapping spans, keeping the highest-priority entity per region.
+
+    Priority is decided first by :data:`ENTITY_PRIORITY` (so a PHONE_NUMBER beats
+    a DATE_TIME even at lower raw score), then by score, then by span length. The
+    result is deterministic: the same text always yields the same masking.
+    """
+    if not entities:
+        return []
+
+    def rank(e: PIIEntity):
+        return (ENTITY_PRIORITY.get(e.entity_type, 30), e.score, e.end - e.start)
+
+    # Strongest candidates first; greedily accept ones that don't overlap an
+    # already-accepted (higher-ranked) span.
+    ordered = sorted(entities, key=rank, reverse=True)
+    accepted: List[PIIEntity] = []
+    for cand in ordered:
+        if not any(cand.start < a.end and a.start < cand.end for a in accepted):
+            accepted.append(cand)
+
+    accepted.sort(key=lambda e: e.start)
+    return accepted

medguardx_core-1.0.0/src/medguardx/engine.py

@@ -0,0 +1,101 @@
+"""The public MedGuardX engine -- a stateless facade over detection, policy and masking.
+
+Typical use::
+
+    from medguardx import MedGuardEngine, EngineConfig, Role, Purpose
+
+    engine = MedGuardEngine(EngineConfig(model="en_core_web_md"))
+    result = engine.process(
+        "Patient John Smith, Aadhaar 2341 2341 2341, card 4111 1111 1111 1111.",
+        role=Role.NURSE, purpose=Purpose.TREATMENT, consent=False,
+    )
+    print(result.masked_text)
+
+The engine holds no data and does no I/O -- integrators own storage, auth and
+audit. That statelessness is deliberate: it is what makes the engine safe to
+embed anywhere.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .config import EngineConfig
+from .detection import Detector, PIIEntity
+from .enums import MaskingStrategy, Purpose, Role, coerce_purpose, coerce_role
+from .masking import mask_text
+from .policy import PolicyEngine
+
+
+@dataclass
+class ProcessResult:
+    """Outcome of :meth:`MedGuardEngine.process`."""
+
+    original_text: str
+    masked_text: str
+    entities: List[PIIEntity]
+    strategy: MaskingStrategy
+    policy_rule: str
+    denied: bool = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.denied = self.strategy == MaskingStrategy.DENY
+
+    def to_dict(self) -> dict:
+        return {
+            "original_text": self.original_text,
+            "masked_text": self.masked_text,
+            "entities": [e.to_dict() for e in self.entities],
+            "masking_strategy": self.strategy.value,
+            "policy_rule": self.policy_rule,
+            "entities_masked": 0 if self.strategy == MaskingStrategy.FULL_ACCESS else len(self.entities),
+            "denied": self.denied,
+        }
+
+
+class MedGuardEngine:
+    """Detect -> evaluate policy -> mask, in one call or as separate steps."""
+
+    def __init__(
+        self,
+        config: Optional[EngineConfig] = None,
+        policy: Optional[PolicyEngine] = None,
+    ) -> None:
+        self.config = config or EngineConfig()
+        self.detector = Detector(self.config)
+        self.policy = policy or PolicyEngine()
+
+    # --- composable steps -------------------------------------------------------
+    def detect(self, text: str) -> List[PIIEntity]:
+        return self.detector.detect(text)
+
+    def evaluate_policy(self, role, purpose, consent: bool):
+        return self.policy.evaluate(role, purpose, consent)
+
+    def mask(self, text: str, entities: List[PIIEntity], strategy: MaskingStrategy) -> str:
+        return mask_text(text, entities, strategy)
+
+    # --- one-shot ---------------------------------------------------------------
+    def process(
+        self,
+        text: str,
+        role,
+        purpose,
+        consent: bool = False,
+        entities: Optional[List[PIIEntity]] = None,
+    ) -> ProcessResult:
+        """Run the full pipeline. Pass pre-computed ``entities`` to skip detection."""
+        role = coerce_role(role)
+        purpose = coerce_purpose(purpose)
+        strategy, rule = self.policy.evaluate(role, purpose, consent)
+
+        if strategy == MaskingStrategy.DENY:
+            return ProcessResult(text, "", [], strategy, rule)
+
+        detected = entities if entities is not None else self.detect(text)
+        masked = self.mask(text, detected, strategy)
+        return ProcessResult(text, masked, detected, strategy, rule)
+
+    def warm_up(self) -> None:
+        """Eagerly load the model (useful at service startup)."""
+        self.detector._get_analyzer()

medguardx_core-1.0.0/src/medguardx/enums.py

@@ -0,0 +1,47 @@
+"""Core enumerations shared across the MedGuardX engine.
+
+These are intentionally plain ``str`` enums so they serialize cleanly to JSON and
+compare equal to their string values -- an integrator can pass ``"nurse"`` or
+``Role.NURSE`` interchangeably.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Role(str, Enum):
+    """Who is requesting the data."""
+
+    DOCTOR = "doctor"
+    NURSE = "nurse"
+    RESEARCHER = "researcher"
+    PATIENT = "patient"
+    COMPANY = "company"
+    ADMIN = "admin"
+
+
+class Purpose(str, Enum):
+    """Why the data is being requested."""
+
+    TREATMENT = "treatment"
+    RESEARCH = "research"
+    BILLING = "billing"
+    LEGAL = "legal"
+    PERSONAL = "personal"
+
+
+class MaskingStrategy(str, Enum):
+    """How much of the data the requester is allowed to see."""
+
+    FULL_ACCESS = "full_access"
+    PARTIAL_MASK = "partial_mask"
+    FULL_ANONYMIZE = "full_anonymize"
+    DENY = "deny"
+
+
+def coerce_role(value) -> "Role":
+    return value if isinstance(value, Role) else Role(str(value).lower())
+
+
+def coerce_purpose(value) -> "Purpose":
+    return value if isinstance(value, Purpose) else Purpose(str(value).lower())

medguardx_core-1.0.0/src/medguardx/ingestion.py

@@ -0,0 +1,104 @@
+"""Multi-format text extraction: plain text, PDF, image (OCR), HL7.
+
+Optional heavy dependencies (pdfplumber, pytesseract/Pillow, hl7apy) are imported
+lazily and degrade gracefully, so installing the core engine does not force an
+OCR/PDF toolchain on integrators who only mask plain text.
+"""
+from __future__ import annotations
+
+import io
+import os
+from typing import Tuple
+
+
+class ExtractionError(RuntimeError):
+    """Raised when text cannot be extracted from an uploaded file.
+
+    Distinct from "no text found": this signals a real failure (corrupt file, a
+    missing OCR engine, etc.) so callers can reject the upload rather than
+    silently storing an error string as the record's content.
+    """
+
+
+def detect_file_type(filename: str, content: bytes) -> str:
+    ext = os.path.splitext(filename or "")[1].lower()
+    if ext in (".hl7", ".adt"):
+        return "hl7"
+    if ext == ".pdf":
+        return "pdf"
+    if ext in (".png", ".jpg", ".jpeg", ".tiff", ".bmp"):
+        return "image"
+    preview = content[:200].decode("utf-8", errors="ignore")
+    if "MSH|" in preview:
+        return "hl7"
+    return "text"
+
+
+def extract_text_from_pdf(content: bytes) -> str:
+    try:
+        import pdfplumber
+
+        with pdfplumber.open(io.BytesIO(content)) as pdf:
+            pages = [page.extract_text() or "" for page in pdf.pages]
+        return "\n".join(pages).strip()
+    except Exception as exc:  # pragma: no cover - depends on optional dep
+        raise ExtractionError(f"PDF extraction failed: {exc}") from exc
+
+
+def extract_text_from_image(content: bytes) -> str:
+    try:
+        import tempfile
+
+        import pytesseract
+        from PIL import Image
+    except Exception as exc:  # pragma: no cover - optional deps not installed
+        raise ExtractionError("OCR dependencies (pytesseract/Pillow) are not installed.") from exc
+
+    try:
+        img = Image.open(io.BytesIO(content))
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as fh:
+            img.save(fh.name)
+            try:
+                return pytesseract.image_to_string(fh.name).strip()
+            finally:
+                os.unlink(fh.name)
+    except pytesseract.TesseractNotFoundError as exc:  # pragma: no cover
+        raise ExtractionError(
+            "OCR engine (tesseract) is not available in this deployment. "
+            "Image files are not supported here; use text, PDF, or HL7."
+        ) from exc
+    except Exception as exc:  # pragma: no cover - depends on optional dep
+        raise ExtractionError(f"OCR failed: {exc}") from exc
+
+
+def parse_hl7(content: bytes) -> str:
+    text = content.decode("utf-8", errors="ignore")
+    try:
+        from hl7apy.parser import parse_message
+
+        msg = parse_message(text.replace("\n", "\r"))
+        segments = []
+        for seg in msg.children:
+            fields = []
+            for field in seg.children:
+                try:
+                    fields.append(f"{field.name}: {field.value}")
+                except Exception:
+                    pass
+            if fields:
+                segments.append(f"[{seg.name}] " + " | ".join(fields))
+        return "\n".join(segments) if segments else text
+    except Exception:  # pragma: no cover - depends on optional dep
+        return text
+
+
+def extract_text(filename: str, content: bytes) -> Tuple[str, str]:
+    """Return ``(extracted_text, file_type)`` for an uploaded file."""
+    file_type = detect_file_type(filename, content)
+    if file_type == "pdf":
+        return extract_text_from_pdf(content), file_type
+    if file_type == "image":
+        return extract_text_from_image(content), file_type
+    if file_type == "hl7":
+        return parse_hl7(content), file_type
+    return content.decode("utf-8", errors="ignore"), file_type

medguardx_core-1.0.0/src/medguardx/masking.py

@@ -0,0 +1,107 @@
+"""Deterministic, leak-proof masking.
+
+The old build delegated to Presidio's anonymizer with a DEFAULT operator that
+masked only the first 8 characters -- so a 19-digit card came back as
+``********1 1111 1111`` and IPs/IBANs leaked their tails. Here we do span
+replacement ourselves over the already-de-overlapped entity list, replacing from
+right to left so indices stay valid. The invariant is simple and testable: for
+any strategy other than FULL_ACCESS, the original entity substring never survives
+in the output.
+"""
+from __future__ import annotations
+
+from typing import Callable, Dict, List
+
+from .detection import PIIEntity
+from .enums import MaskingStrategy
+
+# Human-readable label per entity type, used in redaction tokens.
+_LABELS: Dict[str, str] = {
+    "PERSON": "NAME",
+    "PHONE_NUMBER": "PHONE",
+    "EMAIL_ADDRESS": "EMAIL",
+    "CREDIT_CARD": "CARD",
+    "IBAN_CODE": "IBAN",
+    "IP_ADDRESS": "IP",
+    "LOCATION": "LOCATION",
+    "URL": "URL",
+    "NRP": "NRP",
+    "US_SSN": "SSN",
+    "MEDICAL_LICENSE": "MED_LICENSE",
+    "MEDICAL_RECORD_NUMBER": "MRN",
+    "IN_AADHAAR": "AADHAAR",
+    "IN_PAN": "PAN",
+    "DATE_TIME": "DATE",
+}
+
+DENY_MESSAGE = "[ACCESS DENIED - Insufficient permissions]"
+
+
+def _label(entity_type: str) -> str:
+    return _LABELS.get(entity_type, entity_type)
+
+
+def _redact(entity: PIIEntity) -> str:
+    return f"[{_label(entity.entity_type)}_REDACTED]"
+
+
+# --- Partial-mask reveal helpers -------------------------------------------------
+# Partial masking trades a *small, bounded* amount of the original for downstream
+# utility (e.g. matching a card by its last 4). Every helper below reveals at most
+# a safe suffix and masks everything else; none can leave the majority visible.
+
+def _reveal_last(value: str, keep: int, ch: str = "*") -> str:
+    digits = [c for c in value if c.isalnum()]
+    if len(digits) <= keep:
+        return ch * len(digits)
+    return ch * (len(digits) - keep) + "".join(digits[-keep:])
+
+
+def _partial_card(entity: PIIEntity) -> str:
+    return f"[CARD ****{_reveal_last(entity.text, 4)[-4:]}]"
+
+
+def _partial_phone(entity: PIIEntity) -> str:
+    return f"[PHONE ****{_reveal_last(entity.text, 2)[-2:]}]"
+
+
+def _partial_email(entity: PIIEntity) -> str:
+    local, _, domain = entity.text.partition("@")
+    if not domain:
+        return "[EMAIL_MASKED]"
+    hint = (local[:1] + "***") if local else "***"
+    return f"{hint}@{domain}"
+
+
+# Types that get a partial reveal under PARTIAL_MASK. Everything else is fully
+# redacted even under partial masking -- safe by default.
+_PARTIAL_OPERATORS: Dict[str, Callable[[PIIEntity], str]] = {
+    "CREDIT_CARD": _partial_card,
+    "PHONE_NUMBER": _partial_phone,
+    "EMAIL_ADDRESS": _partial_email,
+}
+
+
+def _mask_token(entity: PIIEntity, strategy: MaskingStrategy) -> str:
+    if strategy == MaskingStrategy.PARTIAL_MASK and entity.entity_type in _PARTIAL_OPERATORS:
+        return _PARTIAL_OPERATORS[entity.entity_type](entity)
+    return _redact(entity)
+
+
+def mask_text(text: str, entities: List[PIIEntity], strategy: MaskingStrategy) -> str:
+    """Apply ``strategy`` to ``text`` given its detected ``entities``."""
+    if strategy == MaskingStrategy.FULL_ACCESS:
+        return text
+    if strategy == MaskingStrategy.DENY:
+        return DENY_MESSAGE
+    if not entities:
+        return text
+
+    # Replace right-to-left so earlier spans keep their original indices.
+    ordered = sorted(entities, key=lambda e: e.start, reverse=True)
+    out = text
+    for e in ordered:
+        if e.start < 0 or e.end > len(out) or e.start >= e.end:
+            continue  # stale/invalid span -- skip rather than corrupt the text
+        out = out[: e.start] + _mask_token(e, strategy) + out[e.end :]
+    return out

medguardx_core-1.0.0/src/medguardx/policy.py

@@ -0,0 +1,73 @@
+"""Context-aware policy engine.
+
+Maps ``(role, purpose, consent)`` to a masking strategy plus a human-readable
+rationale. The default matrix is the healthcare policy MedGuardX ships with;
+integrators can subclass :class:`PolicyEngine` or pass a custom ``rules`` dict to
+encode their own governance without touching detection or masking.
+"""
+from __future__ import annotations
+
+from typing import Dict, Optional, Tuple
+
+from .enums import MaskingStrategy, Purpose, Role, coerce_purpose, coerce_role
+
+PolicyKey = Tuple[Role, Purpose, bool]
+PolicyValue = Tuple[MaskingStrategy, str]
+
+_FA = MaskingStrategy.FULL_ACCESS
+_PM = MaskingStrategy.PARTIAL_MASK
+_AN = MaskingStrategy.FULL_ANONYMIZE
+_DN = MaskingStrategy.DENY
+
+DEFAULT_RULES: Dict[PolicyKey, PolicyValue] = {
+    # Doctors
+    (Role.DOCTOR, Purpose.TREATMENT, True): (_FA, "Doctor requesting treatment records with patient consent: full access granted."),
+    (Role.DOCTOR, Purpose.TREATMENT, False): (_PM, "Doctor requesting treatment records without consent: partial access (identifiers masked)."),
+    (Role.DOCTOR, Purpose.RESEARCH, True): (_PM, "Doctor requesting research data with consent: partial access (identifiers masked)."),
+    (Role.DOCTOR, Purpose.RESEARCH, False): (_AN, "Doctor requesting research data without consent: anonymized access only."),
+    # Nurses
+    (Role.NURSE, Purpose.TREATMENT, True): (_PM, "Nurse requesting treatment records with consent: partial access (identifiers masked)."),
+    (Role.NURSE, Purpose.TREATMENT, False): (_PM, "Nurse requesting treatment records without consent: partial access (identifiers masked)."),
+    (Role.NURSE, Purpose.RESEARCH, True): (_AN, "Nurse requesting research data with consent: anonymized access only."),
+    # Researchers
+    (Role.RESEARCHER, Purpose.RESEARCH, True): (_AN, "Researcher requesting research data with consent: anonymized access only."),
+    (Role.RESEARCHER, Purpose.RESEARCH, False): (_AN, "Researcher requesting research data without consent: anonymized access only."),
+    # Patients (own records)
+    (Role.PATIENT, Purpose.PERSONAL, True): (_FA, "Patient accessing personal records: full access."),
+    (Role.PATIENT, Purpose.PERSONAL, False): (_FA, "Patient accessing personal records: full access."),
+    (Role.PATIENT, Purpose.TREATMENT, True): (_FA, "Patient accessing treatment records: full access."),
+    (Role.PATIENT, Purpose.TREATMENT, False): (_FA, "Patient accessing treatment records: full access."),
+    (Role.PATIENT, Purpose.BILLING, True): (_FA, "Patient accessing billing records: full access."),
+    (Role.PATIENT, Purpose.BILLING, False): (_FA, "Patient accessing billing records: full access."),
+    (Role.PATIENT, Purpose.LEGAL, True): (_FA, "Patient retrieving records for legal reasons: full access."),
+    (Role.PATIENT, Purpose.LEGAL, False): (_FA, "Patient retrieving records for legal reasons: full access."),
+    # Companies
+    (Role.COMPANY, Purpose.RESEARCH, True): (_AN, "Company requesting research data with consent: anonymized access only."),
+    (Role.COMPANY, Purpose.BILLING, True): (_PM, "Company requesting billing records with consent: partial access (identifiers masked)."),
+    # Admins (governance / break-glass, still logged upstream)
+    (Role.ADMIN, Purpose.LEGAL, True): (_FA, "Admin performing authorized legal retrieval: full access."),
+    (Role.ADMIN, Purpose.LEGAL, False): (_FA, "Admin performing authorized legal retrieval: full access."),
+}
+
+
+class PolicyEngine:
+    """Evaluates access policy. Deny-by-default for any unmapped combination."""
+
+    def __init__(self, rules: Optional[Dict[PolicyKey, PolicyValue]] = None) -> None:
+        self.rules = rules if rules is not None else dict(DEFAULT_RULES)
+
+    def evaluate(self, role, purpose, consent: bool) -> PolicyValue:
+        role = coerce_role(role)
+        purpose = coerce_purpose(purpose)
+        consent = bool(consent)
+
+        hit = self.rules.get((role, purpose, consent))
+        if hit is not None:
+            return hit
+
+        consent_str = "even with patient consent" if consent else "without patient consent"
+        return (
+            _DN,
+            f"Access denied: {role.value.capitalize()}s are not authorized to access "
+            f"records for {purpose.value} purposes, {consent_str}.",
+        )

medguardx_core-1.0.0/src/medguardx/recognizers/__init__.py

@@ -0,0 +1,56 @@
+"""Model-independent pattern recognizers.
+
+These run the same way regardless of which spaCy model is loaded (sm / md / lg /
+trf), because structured identifiers -- Aadhaar, PAN, MRN, credit cards -- are
+matched by format, not by linguistic NER. This is what makes the "Indian PII"
+support actually work: it never depended on the model in the first place.
+"""
+from __future__ import annotations
+
+from typing import List
+
+from presidio_analyzer import Pattern, PatternRecognizer
+
+from .aadhaar import AadhaarRecognizer
+
+
+def build_custom_recognizers() -> List[PatternRecognizer]:
+    """Return the custom recognizers MedGuardX registers by default."""
+    return [
+        AadhaarRecognizer(),
+        _pan_recognizer(),
+        _mrn_recognizer(),
+    ]
+
+
+def _pan_recognizer() -> PatternRecognizer:
+    """Indian Permanent Account Number: 5 letters, 4 digits, 1 letter (e.g. ABCDE1234F)."""
+    return PatternRecognizer(
+        supported_entity="IN_PAN",
+        name="in_pan_recognizer",
+        patterns=[
+            Pattern(name="pan", regex=r"\b[A-Z]{5}[0-9]{4}[A-Z]\b", score=0.85),
+        ],
+        context=["pan", "permanent account", "income tax"],
+    )
+
+
+def _mrn_recognizer() -> PatternRecognizer:
+    """Medical Record Number.
+
+    MRNs have no universal format, so we anchor on the explicit ``MRN``/``medical
+    record`` context label followed by an alphanumeric code. Anchoring on the
+    label keeps this precise instead of masking every stray number.
+    """
+    return PatternRecognizer(
+        supported_entity="MEDICAL_RECORD_NUMBER",
+        name="mrn_recognizer",
+        patterns=[
+            Pattern(
+                name="mrn_labelled",
+                regex=r"\b(?:MRN|Medical\s*Record\s*(?:No\.?|Number|#)?)[:\s#-]*([A-Z0-9][A-Z0-9-]{2,14})\b",
+                score=0.8,
+            ),
+        ],
+        context=["mrn", "medical record", "patient id", "chart"],
+    )

medguardx_core-1.0.0/src/medguardx/recognizers/aadhaar.py

@@ -0,0 +1,93 @@
+"""Aadhaar recognizer with Verhoeff checksum validation.
+
+A 12-digit Aadhaar is easy to confuse with a phone number, an amount, or a date
+if you match on shape alone -- that is exactly why the old build mis-tagged
+Aadhaar as ``DATE_TIME``. Validating the Verhoeff checksum lets us assign a high
+confidence score and win overlap resolution against the generic recognizers,
+while keeping false positives low.
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Optional
+
+from presidio_analyzer import EntityRecognizer, RecognizerResult
+from presidio_analyzer.nlp_engine import NlpArtifacts
+
+# Verhoeff algorithm tables.
+_D = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
+    [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+    [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
+    [4, 0, 1, 2, 3, 9, 5, 6, 7, 8],
+    [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+    [6, 5, 9, 8, 7, 1, 0, 4, 3, 2],
+    [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
+    [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+    [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
+]
+_P = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
+    [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+    [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
+    [9, 4, 5, 3, 1, 2, 6, 8, 7, 0],
+    [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+    [2, 7, 9, 3, 8, 0, 6, 4, 1, 5],
+    [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
+]
+
+
+def _verhoeff_valid(number: str) -> bool:
+    c = 0
+    for i, digit in enumerate(reversed(number)):
+        c = _D[c][_P[i % 8][int(digit)]]
+    return c == 0
+
+
+# 12 digits, optionally grouped 4-4-4 by spaces or hyphens. First digit is 2-9.
+# The lookarounds ensure the 12-digit run is not part of a LONGER grouped number
+# (e.g. the first 12 digits of a 16-digit credit card) -- without them the
+# recognizer would shadow CREDIT_CARD and leak the trailing group.
+_AADHAAR_RE = re.compile(
+    r"(?<!\d)(?<![\d][\s-])"           # not preceded by a digit or a digit-group separator
+    r"[2-9][0-9]{3}[\s-]?[0-9]{4}[\s-]?[0-9]{4}"
+    r"(?![\s-]?[0-9])"                  # not followed by another digit group
+)
+
+
+class AadhaarRecognizer(EntityRecognizer):
+    """Detects Indian Aadhaar numbers, verified with the Verhoeff checksum."""
+
+    def __init__(self) -> None:
+        super().__init__(supported_entities=["IN_AADHAAR"], name="aadhaar_recognizer")
+
+    def load(self) -> None:  # required by the EntityRecognizer contract
+        return None
+
+    def analyze(
+        self, text: str, entities: List[str], nlp_artifacts: Optional[NlpArtifacts] = None
+    ) -> List[RecognizerResult]:
+        if "IN_AADHAAR" not in entities:
+            return []
+
+        results: List[RecognizerResult] = []
+        for match in _AADHAAR_RE.finditer(text):
+            digits = re.sub(r"[\s-]", "", match.group())
+            if len(digits) != 12:
+                continue
+            # A valid Verhoeff checksum -> high confidence. A well-shaped but
+            # unverified match still gets a moderate score so it is masked, just
+            # with lower priority in overlap resolution.
+            score = 0.9 if _verhoeff_valid(digits) else 0.5
+            results.append(
+                RecognizerResult(
+                    entity_type="IN_AADHAAR",
+                    start=match.start(),
+                    end=match.end(),
+                    score=score,
+                    analysis_explanation=None,
+                )
+            )
+        return results

medguardx_core-1.0.0/tests/test_aadhaar.py

@@ -0,0 +1,41 @@
+"""Aadhaar recognizer: Verhoeff-valid numbers score high; junk is rejected."""
+from medguardx.recognizers.aadhaar import AadhaarRecognizer, _verhoeff_valid
+
+
+def _run(text):
+    return AadhaarRecognizer().analyze(text, entities=["IN_AADHAAR"])
+
+
+def test_verhoeff_known_valid_and_invalid():
+    # 234123412346 has a valid Verhoeff check digit; flipping it invalidates.
+    assert _verhoeff_valid("234123412346")
+    assert not _verhoeff_valid("234123412340")
+
+
+def test_detects_spaced_aadhaar():
+    res = _run("Aadhaar 2341 2341 2346 on record")
+    assert len(res) == 1
+    assert res[0].entity_type == "IN_AADHAAR"
+    assert res[0].score >= 0.9  # valid checksum -> high confidence
+
+
+def test_detects_bare_twelve_digit_aadhaar():
+    # The exact case the old build missed entirely (returned nothing).
+    res = _run("ID 234123412346 filed")
+    assert len(res) == 1 and res[0].entity_type == "IN_AADHAAR"
+
+
+def test_shape_match_without_valid_checksum_still_flagged_lower():
+    res = _run("Number 234123412340 here")
+    assert len(res) == 1
+    assert 0.4 <= res[0].score < 0.9
+
+
+def test_ignores_non_aadhaar_numbers():
+    assert _run("Call 9305597756 today") == []  # 10 digits, not Aadhaar-shaped
+
+
+def test_does_not_match_inside_a_credit_card():
+    # 16-digit card must NOT be picked up as a 12-digit Aadhaar.
+    assert _run("card 4111 1111 1111 1111 on file") == []
+    assert _run("4111111111111111") == []

medguardx_core-1.0.0/tests/test_masking.py

@@ -0,0 +1,54 @@
+"""Masking must never leak the original substring (the old build's core bug)."""
+from medguardx.detection import PIIEntity
+from medguardx.enums import MaskingStrategy
+from medguardx.masking import mask_text
+
+
+def _ent(text, start, etype, score=0.9):
+    return PIIEntity(entity_type=etype, start=start, end=start + len(text), score=score, text=text)
+
+
+def test_full_access_returns_text_unchanged():
+    txt = "Card 4111 1111 1111 1111"
+    ents = [_ent("4111 1111 1111 1111", 5, "CREDIT_CARD")]
+    assert mask_text(txt, ents, MaskingStrategy.FULL_ACCESS) == txt
+
+
+def test_full_anonymize_removes_every_entity_substring():
+    txt = "IP 192.168.1.55 and IBAN DE89370400440532013000 here."
+    ents = [_ent("192.168.1.55", 3, "IP_ADDRESS"), _ent("DE89370400440532013000", 25, "IBAN_CODE")]
+    out = mask_text(txt, ents, MaskingStrategy.FULL_ANONYMIZE)
+    assert "192.168.1.55" not in out
+    assert "DE89370400440532013000" not in out
+    assert "[IP_REDACTED]" in out and "[IBAN_REDACTED]" in out
+
+
+def test_partial_card_reveals_only_last_four():
+    txt = "Card 4111111111111111 on file"
+    ents = [_ent("4111111111111111", 5, "CREDIT_CARD")]
+    out = mask_text(txt, ents, MaskingStrategy.PARTIAL_MASK)
+    assert "4111111111111111" not in out
+    assert "1111" in out  # last 4 kept for utility
+    assert out.count("1") == 4  # nothing else from the PAN survives
+
+
+def test_partial_ip_and_iban_are_fully_redacted_not_leaked():
+    # These have no partial operator -> must be fully redacted, unlike the old
+    # build which left "********1.55" and "********00440532013000".
+    txt = "IP 192.168.1.55, IBAN DE89370400440532013000"
+    ents = [_ent("192.168.1.55", 3, "IP_ADDRESS"), _ent("DE89370400440532013000", 22, "IBAN_CODE")]
+    out = mask_text(txt, ents, MaskingStrategy.PARTIAL_MASK)
+    assert "1.55" not in out
+    assert "440532013000" not in out
+
+
+def test_deny_returns_denied_placeholder_only():
+    out = mask_text("secret", [], MaskingStrategy.DENY)
+    assert "secret" not in out and "DENIED" in out.upper()
+
+
+def test_stale_span_is_skipped_not_crashing():
+    txt = "short"
+    ents = [_ent("this is longer than the text", 0, "PERSON")]
+    # end past len(text): span skipped rather than corrupting output
+    assert mask_text(txt, ents, MaskingStrategy.FULL_ANONYMIZE) == txt

medguardx_core-1.0.0/tests/test_overlap.py

@@ -0,0 +1,38 @@
+"""Overlap resolution: a specialized entity must beat a generic one deterministically."""
+from medguardx.detection import PIIEntity, resolve_overlaps
+
+
+def _ent(etype, start, end, score):
+    return PIIEntity(entity_type=etype, start=start, end=end, score=score, text="x")
+
+
+def test_phone_beats_datetime_even_at_lower_score():
+    # The exact failure from the old build: DATE_TIME(0.85) shadowed PHONE(0.75).
+    ents = [_ent("DATE_TIME", 0, 10, 0.85), _ent("PHONE_NUMBER", 0, 10, 0.75)]
+    out = resolve_overlaps(ents)
+    assert len(out) == 1
+    assert out[0].entity_type == "PHONE_NUMBER"
+
+
+def test_aadhaar_beats_datetime():
+    ents = [_ent("DATE_TIME", 5, 19, 0.85), _ent("IN_AADHAAR", 5, 19, 0.9)]
+    out = resolve_overlaps(ents)
+    assert len(out) == 1 and out[0].entity_type == "IN_AADHAAR"
+
+
+def test_email_beats_overlapping_url():
+    ents = [_ent("URL", 10, 21, 0.5), _ent("EMAIL_ADDRESS", 5, 21, 1.0)]
+    out = resolve_overlaps(ents)
+    assert len(out) == 1 and out[0].entity_type == "EMAIL_ADDRESS"
+
+
+def test_non_overlapping_entities_all_kept_and_sorted():
+    ents = [_ent("PERSON", 20, 30, 0.9), _ent("PHONE_NUMBER", 0, 10, 0.8)]
+    out = resolve_overlaps(ents)
+    assert [e.entity_type for e in out] == ["PHONE_NUMBER", "PERSON"]
+    assert out[0].start < out[1].start
+
+
+def test_deterministic_same_input_same_output():
+    ents = [_ent("DATE_TIME", 0, 10, 0.85), _ent("PHONE_NUMBER", 0, 10, 0.75)]
+    assert resolve_overlaps(list(ents)) == resolve_overlaps(list(reversed(ents)))

medguardx_core-1.0.0/tests/test_policy.py

@@ -0,0 +1,39 @@
+"""Policy engine: correct strategies and deny-by-default for unmapped combos."""
+from medguardx.enums import MaskingStrategy, Purpose, Role
+from medguardx.policy import PolicyEngine
+
+
+def setup_function():
+    global engine
+    engine = PolicyEngine()
+
+
+def test_doctor_treatment_consent_is_full_access():
+    strat, _ = engine.evaluate(Role.DOCTOR, Purpose.TREATMENT, True)
+    assert strat == MaskingStrategy.FULL_ACCESS
+
+
+def test_researcher_research_is_anonymized_regardless_of_consent():
+    for consent in (True, False):
+        strat, _ = engine.evaluate(Role.RESEARCHER, Purpose.RESEARCH, consent)
+        assert strat == MaskingStrategy.FULL_ANONYMIZE
+
+
+def test_unmapped_combination_is_denied():
+    strat, rule = engine.evaluate(Role.COMPANY, Purpose.TREATMENT, False)
+    assert strat == MaskingStrategy.DENY
+    assert "denied" in rule.lower()
+
+
+def test_accepts_plain_strings():
+    strat, _ = engine.evaluate("nurse", "treatment", False)
+    assert strat == MaskingStrategy.PARTIAL_MASK
+
+
+def test_custom_rules_override_defaults():
+    custom = {(Role.COMPANY, Purpose.TREATMENT, True): (MaskingStrategy.FULL_ACCESS, "custom")}
+    e = PolicyEngine(rules=custom)
+    strat, rule = e.evaluate(Role.COMPANY, Purpose.TREATMENT, True)
+    assert strat == MaskingStrategy.FULL_ACCESS and rule == "custom"
+    # anything else still deny-by-default
+    assert e.evaluate(Role.DOCTOR, Purpose.TREATMENT, True)[0] == MaskingStrategy.DENY