clinicsentry 0.3.0__py3-none-any.whl

clinicsentry/__init__.py

@@ -0,0 +1,32 @@
+"""ClinicSentry: framework-agnostic compliance middleware for clinical AI agents."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+from clinicsentry.guard import ClinicSentry
+from clinicsentry.phi.minimum_necessary import minimum_necessary
+from clinicsentry.types import (
+    AuditEvent,
+    AuditEventType,
+    ClinicalRiskTier,
+    EscalationDecision,
+    PHITag,
+    RegulatoryReport,
+)
+
+__all__ = [
+    "ClinicSentry",
+    "AuditEvent",
+    "AuditEventType",
+    "ClinicalRiskTier",
+    "EscalationDecision",
+    "PHITag",
+    "RegulatoryReport",
+    "minimum_necessary",
+]
+
+# Single-sourced from pyproject.toml via installed package metadata.
+try:
+    __version__ = _dist_version("clinicsentry")
+except PackageNotFoundError:  # pragma: no cover - source tree without install
+    __version__ = "0.0.0+unknown"

clinicsentry/adapters/__init__.py

@@ -0,0 +1,27 @@
+"""Framework adapters.
+
+All adapters subclass :class:`AgentFrameworkAdapter` and are functional even if
+the corresponding upstream SDK is not installed — only the ``wrap`` /
+``install`` methods raise :class:`ImportError` in that case.
+"""
+
+from clinicsentry.adapters.a2a import A2AInterceptor
+from clinicsentry.adapters.base import AgentFrameworkAdapter, GenericAdapter
+from clinicsentry.adapters.claude_sdk import ClaudeSDKAdapter
+from clinicsentry.adapters.crewai import CrewAIAdapter
+from clinicsentry.adapters.google_adk import GoogleADKAdapter
+from clinicsentry.adapters.langgraph import LangGraphAdapter
+from clinicsentry.adapters.mcp_proxy import MCPProxyAdapter
+from clinicsentry.adapters.openai_agents import OpenAIAgentsAdapter
+
+__all__ = [
+    "AgentFrameworkAdapter",
+    "GenericAdapter",
+    "A2AInterceptor",
+    "ClaudeSDKAdapter",
+    "CrewAIAdapter",
+    "GoogleADKAdapter",
+    "LangGraphAdapter",
+    "MCPProxyAdapter",
+    "OpenAIAgentsAdapter",
+]

clinicsentry/adapters/a2a.py

@@ -0,0 +1,60 @@
+"""Agent-to-Agent (A2A) interceptor.
+
+A2A is Google's open protocol for inter-agent communication. We intercept
+messages crossing an A2A boundary, scan their payloads, and update the
+propagation graph so cross-agent PHI flow is traceable in the audit report.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from clinicsentry.adapters.base import GenericAdapter
+from clinicsentry.types import AuditEvent, AuditEventType
+
+__all__ = ["A2AInterceptor"]
+
+
+class A2AInterceptor(GenericAdapter):
+    """Session-tagging layer for A2A protocol messages."""
+
+    framework_name = "a2a"
+
+    async def on_message(
+        self,
+        *,
+        from_agent: str,
+        to_agent: str,
+        message: dict[str, Any],
+        session_correlation_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Scan an A2A message, propagate PHI tags, audit, and return the redacted payload.
+
+        Args:
+            from_agent: agent id of the sender.
+            to_agent: agent id of the receiver.
+            message: the A2A message payload.
+            session_correlation_id: optional cross-session correlation token.
+
+        Returns:
+            The redacted message ready to forward.
+        """
+        scan = self.guard.firewall.scan(message, origin_agent=from_agent)
+        for tag in scan.tags:
+            self.guard.firewall.propagation.propagate(tag.tag_id, from_agent, to_agent)
+        self.guard.emit_event(
+            AuditEvent(
+                event_type=AuditEventType.A2A_MESSAGE,
+                session_id=self.guard.session_id,
+                sequence_number=0,
+                agent_framework=self.framework_name,
+                agent_id=from_agent,
+                redacted_output={
+                    "to": to_agent,
+                    "message": scan.redacted,
+                    "correlation_id": session_correlation_id,
+                },
+                phi_tags_detected=[t.tag_id for t in scan.tags],
+            )
+        )
+        return scan.redacted  # type: ignore[no-any-return]

clinicsentry/adapters/base.py

@@ -0,0 +1,158 @@
+"""Adapter ABC + a generic in-process adapter usable for testing.
+
+The README §10 abstract interface is preserved verbatim. The default
+``GenericAdapter`` implementation routes all interception points through the
+configured :class:`ClinicSentry` instance and is sufficient for
+framework-agnostic test coverage.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from clinicsentry.types import AuditEvent, AuditEventType
+
+__all__ = [
+    "AgentFrameworkAdapter",
+    "GenericAdapter",
+]
+
+if TYPE_CHECKING:
+    from clinicsentry.guard import ClinicSentry
+
+
+class AgentFrameworkAdapter(ABC):
+    """Adapter contract every framework integration must implement."""
+
+    framework_name: str = "generic"
+
+    def __init__(self, guard: ClinicSentry) -> None:
+        self.guard = guard
+
+    @abstractmethod
+    async def intercept_before_llm(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Sanitize messages before they reach the LLM."""
+
+    @abstractmethod
+    async def intercept_after_llm(self, response: dict[str, Any]) -> dict[str, Any]:
+        """Sanitize an LLM response before it returns to the agent."""
+
+    @abstractmethod
+    async def intercept_tool_call(
+        self, tool_name: str, arguments: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Sanitize tool arguments and apply minimum-necessary."""
+
+    @abstractmethod
+    async def intercept_tool_result(self, tool_name: str, result: dict[str, Any]) -> dict[str, Any]:
+        """Sanitize tool results before they enter the agent context."""
+
+    @abstractmethod
+    async def intercept_agent_message(
+        self, from_agent: str, to_agent: str, message: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Sanitize inter-agent messages."""
+
+
+def _hash(value: Any) -> str:
+    """Stable SHA-256 hash for arbitrary JSON-able value."""
+    return hashlib.sha256(json.dumps(value, sort_keys=True, default=str).encode()).hexdigest()
+
+
+class GenericAdapter(AgentFrameworkAdapter):
+    """Default adapter wiring all interception points to the firewall + audit."""
+
+    framework_name = "generic"
+
+    async def intercept_before_llm(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Scan and audit each message."""
+        scan = self.guard.firewall.scan(messages, origin_agent=self.framework_name)
+        self.guard.emit_event(
+            AuditEvent(
+                event_type=AuditEventType.AGENT_LLM_CALL,
+                session_id=self.guard.session_id,
+                sequence_number=0,
+                agent_framework=self.framework_name,
+                input_hash=_hash(messages),
+                redacted_input={"messages": scan.redacted},
+                phi_tags_detected=[t.tag_id for t in scan.tags],
+            )
+        )
+        return scan.redacted  # type: ignore[no-any-return]
+
+    async def intercept_after_llm(self, response: dict[str, Any]) -> dict[str, Any]:
+        """Scan and audit the LLM response."""
+        scan = self.guard.firewall.scan(response, origin_agent=self.framework_name)
+        self.guard.emit_event(
+            AuditEvent(
+                event_type=AuditEventType.AGENT_LLM_RESPONSE,
+                session_id=self.guard.session_id,
+                sequence_number=0,
+                agent_framework=self.framework_name,
+                output_hash=_hash(response),
+                redacted_output={"response": scan.redacted},
+                phi_tags_detected=[t.tag_id for t in scan.tags],
+            )
+        )
+        return scan.redacted  # type: ignore[no-any-return]
+
+    async def intercept_tool_call(
+        self, tool_name: str, arguments: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Scan tool args; minimum-necessary is applied at decoration time."""
+        self.guard.meddevice.assert_running()
+        scan = self.guard.firewall.scan(arguments, origin_agent=tool_name)
+        self.guard.emit_event(
+            AuditEvent(
+                event_type=AuditEventType.TOOL_CALL,
+                session_id=self.guard.session_id,
+                sequence_number=0,
+                agent_framework=self.framework_name,
+                agent_id=tool_name,
+                input_hash=_hash(arguments),
+                redacted_input={"tool_name": tool_name, "arguments": scan.redacted},
+                phi_tags_detected=[t.tag_id for t in scan.tags],
+            )
+        )
+        return scan.redacted  # type: ignore[no-any-return]
+
+    async def intercept_tool_result(self, tool_name: str, result: dict[str, Any]) -> dict[str, Any]:
+        """Scan tool result before it re-enters the agent."""
+        scan = self.guard.firewall.scan(result, origin_agent=tool_name)
+        self.guard.emit_event(
+            AuditEvent(
+                event_type=AuditEventType.TOOL_RESULT,
+                session_id=self.guard.session_id,
+                sequence_number=0,
+                agent_framework=self.framework_name,
+                agent_id=tool_name,
+                output_hash=_hash(result),
+                redacted_output={"tool_name": tool_name, "result": scan.redacted},
+                phi_tags_detected=[t.tag_id for t in scan.tags],
+            )
+        )
+        return scan.redacted  # type: ignore[no-any-return]
+
+    async def intercept_agent_message(
+        self, from_agent: str, to_agent: str, message: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Scan + propagate PHI tags across an agent-to-agent boundary."""
+        scan = self.guard.firewall.scan(message, origin_agent=from_agent)
+        for tag in scan.tags:
+            self.guard.firewall.propagation.propagate(tag.tag_id, from_agent, to_agent)
+        self.guard.emit_event(
+            AuditEvent(
+                event_type=AuditEventType.INTER_AGENT_MESSAGE,
+                session_id=self.guard.session_id,
+                sequence_number=0,
+                agent_framework=self.framework_name,
+                agent_id=from_agent,
+                output_hash=_hash(message),
+                redacted_output={"to": to_agent, "message": scan.redacted},
+                phi_tags_detected=[t.tag_id for t in scan.tags],
+            )
+        )
+        return scan.redacted  # type: ignore[no-any-return]

clinicsentry/adapters/claude_sdk.py

@@ -0,0 +1,71 @@
+"""Anthropic Claude (Agents) SDK adapter.
+
+The Claude API uses ``tool_use`` / ``tool_result`` content blocks. This adapter
+wraps :func:`Anthropic.messages.create` to scan blocks in both directions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from clinicsentry.adapters.base import GenericAdapter
+
+__all__ = ["ClaudeSDKAdapter"]
+
+
+class ClaudeSDKAdapter(GenericAdapter):
+    """Adapter for ``anthropic.Anthropic`` clients."""
+
+    framework_name = "claude_sdk"
+
+    def wrap(self, client: Any) -> Any:
+        """Patch the ``messages.create`` method on a Claude client.
+
+        Args:
+            client: an ``anthropic.Anthropic`` (or ``AsyncAnthropic``) instance.
+
+        Returns:
+            The same client with ``messages.create`` patched.
+
+        Raises:
+            ImportError: if the anthropic SDK is missing.
+        """
+        try:  # pragma: no cover
+            import anthropic  # noqa: F401
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError(
+                "anthropic is not installed. `pip install 'clinicsentry[claude]'`."
+            ) from exc
+
+        adapter = self
+        messages = client.messages
+        original_create = messages.create
+
+        def patched_create(**kwargs: Any) -> Any:
+            """Scan input messages / tool blocks; then scan the response."""
+            inbound = kwargs.get("messages") or []
+            scan_in = adapter.guard.firewall.scan(inbound, origin_agent=adapter.framework_name)
+            kwargs["messages"] = scan_in.redacted
+            response = original_create(**kwargs)
+            content = getattr(response, "content", None)
+            if content is not None:
+                scan_out = adapter.guard.firewall.scan(content, origin_agent=adapter.framework_name)
+                response.content = scan_out.redacted
+            return response
+
+        messages.create = patched_create
+        return client
+
+    def scan_tool_use(self, block: dict[str, Any]) -> dict[str, Any]:
+        """Synchronously scan a Claude ``tool_use`` content block."""
+        scan = self.guard.firewall.scan(
+            block.get("input", {}), origin_agent=block.get("name", "tool")
+        )
+        return {**block, "input": scan.redacted}
+
+    def scan_tool_result(self, block: dict[str, Any]) -> dict[str, Any]:
+        """Synchronously scan a Claude ``tool_result`` content block."""
+        scan = self.guard.firewall.scan(
+            block.get("content", ""), origin_agent=block.get("tool_use_id", "tool")
+        )
+        return {**block, "content": scan.redacted}

clinicsentry/adapters/crewai.py

@@ -0,0 +1,89 @@
+"""CrewAI adapter.
+
+CrewAI exposes ``before_kickoff`` / ``after_kickoff`` hooks on :class:`Crew` and
+``callback`` on individual :class:`Task` objects. We attach interception via
+these public extension points; agent-handoff PHI propagation is wired through
+the agent message hook.
+
+The adapter is functional without CrewAI installed: :class:`CrewAIAdapter`
+inherits :class:`GenericAdapter`'s interception methods, so the middleware can
+be invoked manually from custom CrewAI tools.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from clinicsentry.adapters.base import GenericAdapter
+
+__all__ = ["CrewAIAdapter"]
+
+
+class CrewAIAdapter(GenericAdapter):
+    """Adapter specialization for CrewAI Crew + Task workflows."""
+
+    framework_name = "crewai"
+
+    def wrap(self, crew: Any) -> Any:
+        """Attach ClinicSentry interception to a Crew.
+
+        Args:
+            crew: a ``crewai.Crew`` instance (duck-typed).
+
+        Returns:
+            The same ``crew`` for fluent chaining.
+
+        Raises:
+            ImportError: if CrewAI is not installed.
+        """
+        try:  # pragma: no cover - smoke check
+            import crewai  # noqa: F401
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError(
+                "CrewAI is not installed. `pip install 'clinicsentry[crewai]'`."
+            ) from exc
+
+        adapter = self
+        original_kickoff = getattr(crew, "kickoff", None)
+        if original_kickoff is None:  # pragma: no cover
+            return crew
+
+        def wrapped_kickoff(inputs: dict[str, Any] | None = None, **kwargs: Any) -> Any:
+            """Scan inputs, run the crew, scan outputs."""
+            scrubbed = inputs or {}
+            scan_in = adapter.guard.firewall.scan(scrubbed, origin_agent=adapter.framework_name)
+            result = original_kickoff(inputs=scan_in.redacted, **kwargs)
+            scan_out = adapter.guard.firewall.scan(result, origin_agent=adapter.framework_name)
+            return scan_out.redacted
+
+        crew.kickoff = wrapped_kickoff
+
+        # Wrap each task's callback so per-task outputs are scanned and audited.
+        for task in getattr(crew, "tasks", []) or []:
+            original_cb = getattr(task, "callback", None)
+
+            def task_callback(
+                output: Any,
+                _orig: Any = original_cb,
+                _task_name: str = getattr(task, "description", "task"),
+            ) -> Any:
+                """Scan the task output, then invoke the user's callback."""
+                scan = adapter.guard.firewall.scan(output, origin_agent=_task_name)
+                if _orig is not None:
+                    _orig(scan.redacted)
+                return scan.redacted
+
+            task.callback = task_callback
+
+        return crew
+
+    async def on_agent_handoff(
+        self, from_agent: str, to_agent: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Hook intended for CrewAI sequential / hierarchical handoffs."""
+        return await self.intercept_agent_message(from_agent, to_agent, payload)
+
+    def sync_intercept_tool_call(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        """Synchronous bridge for tools that cannot await."""
+        return asyncio.run(self.intercept_tool_call(tool_name, arguments))

clinicsentry/adapters/google_adk.py

@@ -0,0 +1,100 @@
+"""Google ADK (Agent Development Kit) adapter.
+
+Google ADK exposes ``before_model_callback`` / ``after_model_callback`` on each
+:class:`Agent` and tool-execution callbacks via the runner. We attach
+interception through these public extension points.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from clinicsentry.adapters.base import GenericAdapter
+
+__all__ = ["GoogleADKAdapter"]
+
+
+class GoogleADKAdapter(GenericAdapter):
+    """Adapter specialization for Google ADK agents."""
+
+    framework_name = "google_adk"
+
+    def wrap(self, agent: Any) -> Any:
+        """Attach callbacks to a ``google.adk.Agent`` instance.
+
+        Args:
+            agent: an ADK Agent instance (duck-typed).
+
+        Returns:
+            The same ``agent`` for fluent chaining.
+
+        Raises:
+            ImportError: if google-adk is not installed.
+        """
+        try:  # pragma: no cover
+            import google.adk  # noqa: F401
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError(
+                "Google ADK is not installed. `pip install 'clinicsentry[adk]'`."
+            ) from exc
+
+        adapter = self
+        agent.before_model_callback = self._make_before_model_cb(adapter)
+        agent.after_model_callback = self._make_after_model_cb(adapter)
+        agent.before_tool_callback = self._make_before_tool_cb(adapter)
+        agent.after_tool_callback = self._make_after_tool_cb(adapter)
+        return agent
+
+    @staticmethod
+    def _make_before_model_cb(adapter: GoogleADKAdapter) -> Callable[..., Any]:
+        """Build an ADK before-model callback closing over ``adapter``."""
+
+        def cb(*, callback_context: Any, llm_request: Any) -> None:
+            """Scan request contents in place."""
+            contents = getattr(llm_request, "contents", None)
+            if contents is None:
+                return
+            scan = adapter.guard.firewall.scan(contents, origin_agent=adapter.framework_name)
+            llm_request.contents = scan.redacted
+
+        return cb
+
+    @staticmethod
+    def _make_after_model_cb(adapter: GoogleADKAdapter) -> Callable[..., Any]:
+        """Build an ADK after-model callback."""
+
+        def cb(*, callback_context: Any, llm_response: Any) -> None:
+            """Scan the model response in place."""
+            content = getattr(llm_response, "content", None)
+            if content is None:
+                return
+            scan = adapter.guard.firewall.scan(content, origin_agent=adapter.framework_name)
+            llm_response.content = scan.redacted
+
+        return cb
+
+    @staticmethod
+    def _make_before_tool_cb(adapter: GoogleADKAdapter) -> Callable[..., Any]:
+        """Build an ADK before-tool callback."""
+
+        def cb(*, tool: Any, args: dict[str, Any], tool_context: Any) -> dict[str, Any]:
+            """Scan tool args; minimum-necessary applies at decoration time."""
+            adapter.guard.meddevice.assert_running()
+            scan = adapter.guard.firewall.scan(args, origin_agent=getattr(tool, "name", "tool"))
+            return scan.redacted  # type: ignore[no-any-return]
+
+        return cb
+
+    @staticmethod
+    def _make_after_tool_cb(adapter: GoogleADKAdapter) -> Callable[..., Any]:
+        """Build an ADK after-tool callback."""
+
+        def cb(*, tool: Any, args: dict[str, Any], tool_context: Any, tool_response: Any) -> Any:
+            """Scan tool result before it re-enters the agent context."""
+            scan = adapter.guard.firewall.scan(
+                tool_response, origin_agent=getattr(tool, "name", "tool")
+            )
+            return scan.redacted
+
+        return cb

clinicsentry/adapters/langgraph.py

@@ -0,0 +1,66 @@
+"""LangGraph adapter (best-effort).
+
+LangGraph is an optional dependency. The adapter exposes the same interface as
+:class:`GenericAdapter` and provides a ``wrap`` helper that, when LangGraph is
+present, registers ``before_node`` / ``after_node`` callbacks on a StateGraph.
+
+If LangGraph is not installed, ``wrap`` raises :class:`ImportError` while the
+adapter's interception methods remain functional for use as in-process
+middleware (e.g., callable from custom node implementations).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from clinicsentry.adapters.base import GenericAdapter
+
+__all__ = [
+    "LangGraphAdapter",
+]
+
+
+class LangGraphAdapter(GenericAdapter):
+    """Adapter specialization for LangGraph StateGraph workflows."""
+
+    framework_name = "langgraph"
+
+    def wrap(self, graph: Any) -> Any:  # pragma: no cover - thin LangGraph integration
+        """Attach ClinicSentry interception to a StateGraph instance.
+
+        We monkey-patch the graph's compiled ``ainvoke`` / ``invoke`` to scan I/O.
+        A future revision should switch to LangGraph's official callback handlers
+        once their public API stabilizes (target: ``langgraph >= 0.3``).
+        """
+        try:
+            from langgraph.graph import StateGraph  # noqa: F401
+        except Exception as exc:  # pragma: no cover
+            raise ImportError(
+                "LangGraph is not installed. `pip install clinicsentry[langgraph]`."
+            ) from exc
+
+        original_invoke = getattr(graph, "invoke", None)
+        original_ainvoke = getattr(graph, "ainvoke", None)
+        adapter = self
+
+        if original_invoke is not None:
+
+            def wrapped_invoke(state: dict[str, Any], *args: Any, **kwargs: Any) -> Any:
+                scanned = adapter.guard.firewall.scan(state, origin_agent=adapter.framework_name)
+                result = original_invoke(scanned.redacted, *args, **kwargs)
+                out_scan = adapter.guard.firewall.scan(result, origin_agent=adapter.framework_name)
+                return out_scan.redacted
+
+            graph.invoke = wrapped_invoke
+
+        if original_ainvoke is not None:
+
+            async def wrapped_ainvoke(state: dict[str, Any], *args: Any, **kwargs: Any) -> Any:
+                scanned = adapter.guard.firewall.scan(state, origin_agent=adapter.framework_name)
+                result = await original_ainvoke(scanned.redacted, *args, **kwargs)
+                out_scan = adapter.guard.firewall.scan(result, origin_agent=adapter.framework_name)
+                return out_scan.redacted
+
+            graph.ainvoke = wrapped_ainvoke
+
+        return graph