ClinicSentry

Framework-agnostic compliance middleware for clinical AI agents

ClinicSentry is an open-source Python library that wraps any AI agent framework (LangGraph, CrewAI, Google ADK, OpenAI Agents SDK, Claude SDK, MCP, A2A) and enforces clinical-domain guardrails — without requiring changes to your existing agent code.

⚠️ Important disclaimers

• ClinicSentry is not a medical device and is not FDA-cleared or CE-marked. Its controls align with HIPAA, FDA TPLC draft guidance, and IEC 62304 — alignment is not certification, and using this library does not make your system compliant by itself.
• The default detectors catch structured identifiers (SSN, MRN, phone, email, dates, …) deterministically. Person-name detection requires the optional NER extras (pip install 'clinicsentry[phi]'); its recall on real clinical text is not yet characterized on a public benchmark.
• Read RESPONSIBLE_USE.md before any deployment that touches real PHI or influences patient care.

Four Orthogonal Controls

Install

pip install clinicsentry            # core
pip install 'clinicsentry[all]'     # everything (Presidio, FHIR, OTEL, cloud KMS, …)

Extras: [postgres], [cloud-kms], [otel], [dashboard], [all]

Quick Example

from clinicsentry import ClinicSentry, ClinicalRiskTier

guard = ClinicSentry(framework="my-agent")

# 1. Scan input for PHI
scan = guard.firewall.scan(
    {"note": "Patient Jane Doe (MRN 12345678), SSN 123-45-6789"},
    origin_agent="intake",
)
print(scan.redacted)  # PHI replaced with [REDACTED:MRN], [REDACTED:SSN]

# 2. Register actions with risk tiers
@guard.register_action(
    tier=ClinicalRiskTier.ADVISORY,
    description="Summarize a clinical note",
    required_fields={"note"},
)
def summarize(payload: dict) -> str:
    return f"Summary ({len(payload['note'])} chars)"

# 3. Evaluate — router decides: proceed / escalate / block
decision = guard.evaluate_action(
    "summarize",
    output_text="Summary of visit note",
    reasoning_text="High confidence, structured input",
    provided_fields={"note"},
)
print(decision.action, decision.confidence)

# 4. End session → regulatory compliance report
report = guard.end_session(intended_use="clinical summarization")
print(report.compliance_attestation)

Or let the context manager guarantee the session boundary — SESSION_END is audited even if your pipeline raises:

with ClinicSentry(framework="my-agent") as guard:
    ...  # scans, evaluations, tool calls
# report available as guard.last_report

Risk Tiers

Unregistered actions escalate by default (fail closed) — see escalation.on_unregistered_action in the policy reference.

Fail-Safe by Default

• Adversarial PHI detection on the production scan path: homoglyphs, zero-width characters, full-width forms, percent-encoding, and base64-encoded payloads are normalized with exact offset mapping, then redacted in the original text (ADR-0016). Plain-ASCII inputs take a no-overhead fast path (~0.7 ms p95 on 3 KB notes, pure Python, no extra LLM calls).
• Whole-payload coverage: strings, dicts (keys included), lists, tuples, sets, UTF-8 bytes, FHIR/HL7/DICOM; nesting deeper than phi_firewall.max_depth is redacted wholesale rather than erroring.
• Tamper-evident auditing under concurrency: thread-safe gapless sequencing, plus tail-truncation detection on verify().
• Strict policy loading: typo'd keys and out-of-range values raise PolicyError at startup instead of silently disabling enforcement; CLINICSENTRY_* env overrides for containerized deployments.
• MedDevice guardrails: undeclared dose parameters and non-finite values fail validation; rate limits use a true rolling 1-hour window.

CLI

clinicsentry demo                                    # seeded demo session
clinicsentry scan "Patient SSN 123-45-6789"          # one-shot PHI scan
clinicsentry verify ./audit.sqlite --secret <hex>    # verify audit chain
clinicsentry report ./audit.sqlite --session <id>    # compliance report
clinicsentry policy-validate examples/policy.yaml    # validate policy file

Bundled Compliance Frameworks

All four are checked automatically by clinicsentry report.

Production Stack

# Postgres audit + S3 + OTEL + Grafana dashboard
docker compose -f deploy/compose/docker-compose.yml up

Open http://localhost:3000 (Grafana) or http://localhost:9001 (MinIO).

Documentation

• Quickstart — install and run in < 5 minutes
• Adapters — supported agent frameworks
• Regulatory Mapping — controls → regulation clauses
• Threat Model — STRIDE analysis
• API Reference

Status, Versioning, and Support

v0.3.0 — pre-1.0 software (per-module status). SemVer: breaking changes only in minor releases until 1.0, always flagged in the CHANGELOG with migration notes. Only the latest minor release receives security fixes (security policy — PHI-detection bypasses are treated as vulnerabilities, reported privately).

• Bugs and feature requests: GitHub issues (templates provided).
• Conduct: CODE_OF_CONDUCT.md.
• Contributing: CONTRIBUTING.md and CONVENTIONS.md.

How It Compares

Presidio is a complementary detector (we wrap it via [phi]); rails frameworks are complementary conversation shapers. ClinicSentry is the compliance enforcement and evidence layer between your agent and the world.

License

Apache-2.0. See LICENSE and NOTICE. Apache-2.0 permits commercial use, modification, and redistribution — including inside proprietary products.