refactor(governance): migrate Pydantic AI adapter to factory-evaluator

Core PR #1761 removed BaseAdapter from uipath-core. Migrate to the
factory-evaluator pattern (matching #899):

- governance/adapter.py -> model.py: replace the BaseAdapter subclass
  (name/can_handle/attach/detach) with module-level install_governance();
  keep GovernanceModel + GovernanceCallbacks. File named for its seam
  (the model wrapper), like LangChain's callbacks.py.
- runtime/factory.py: new_runtime reads `evaluator` from kwargs and
  calls install_governance on the resolved agent.
- governance/__init__.py: drop register_governance_adapter + registry
  import; expose install_governance. No import-time side effects.
- pyproject.toml: remove the uipath.governance.adapters entry point.
- tests (test_adapter.py -> test_model.py): drop can_handle/attach/
  detach; cover install_governance + factory wiring.

ruff + mypy clean; 17 governance tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aditik0303

packages/uipath-pydantic-ai/pyproject.toml

@@ -28,9 +28,6 @@ register = "uipath_pydantic_ai.middlewares:register_middleware"
 [project.entry-points."uipath.runtime.factories"]
 pydantic-ai = "uipath_pydantic_ai.runtime:register_runtime_factory"
 
-[project.entry-points."uipath.governance.adapters"]
-pydantic-ai = "uipath_pydantic_ai.governance:register_governance_adapter"
-
 [project.urls]
 Homepage = "https://uipath.com"
 Repository = "https://github.com/UiPath/uipath-integrations-python"

packages/uipath-pydantic-ai/src/uipath_pydantic_ai/governance/__init__.py

@@ -1,52 +1,21 @@
 """Governance integration for ``uipath-pydantic-ai``.
 
-Registers :class:`PydanticAIAdapter` with the adapter registry in
-``uipath.core.adapters`` so the governance host can attach the
-Pydantic-AI-specific governance (BEFORE_MODEL, AFTER_MODEL, TOOL_CALL,
-AFTER_TOOL) when it sees a ``pydantic_ai.Agent``.
-
-Registration is **idempotent**: calling :func:`register_governance_adapter`
-twice is a no-op on the second call.
-
-Wiring: the package exposes :func:`register_governance_adapter` as an entry
-point under ``uipath.governance.adapters``. The governance adapter discovery
-path calls it to register the adapter. Importing this module does not, by
-itself, mutate the global registry.
+Exposes :func:`install_governance` — wraps a ``pydantic_ai.Agent``'s ``model``
+with a :class:`GovernanceModel` that brackets every model call with governance
+(BEFORE_MODEL, AFTER_MODEL, TOOL_CALL, AFTER_TOOL). Wired into a run by passing
+an ``evaluator`` to :class:`UiPathPydanticAIRuntimeFactory`; the factory calls
+:func:`install_governance` on the resolved agent.
+
+Importing this module has no side effects: no adapter is registered, no global
+state is mutated.
 """
 
 from __future__ import annotations
 
-import logging
-
-from uipath.core.adapters import get_adapter_registry
-
-from .adapter import GovernanceCallbacks, GovernanceModel, PydanticAIAdapter
-
-logger = logging.getLogger(__name__)
-
-_registered: bool = False
-
-
-def register_governance_adapter() -> None:
-    """Register :class:`PydanticAIAdapter` with the global registry.
-
-    Idempotent — safe to call multiple times.
-    """
-    global _registered
-    if _registered:
-        return
-    registry = get_adapter_registry()
-    if any(a.name == "PydanticAI" for a in registry.get_all()):
-        _registered = True
-        return
-    registry.register(PydanticAIAdapter())
-    _registered = True
-    logger.debug("Registered uipath-pydantic-ai governance adapter")
-
+from .model import GovernanceCallbacks, GovernanceModel, install_governance
 
 __all__ = [
     "GovernanceCallbacks",
     "GovernanceModel",
-    "PydanticAIAdapter",
-    "register_governance_adapter",
+    "install_governance",
 ]

…uipath_pydantic_ai/governance/adapter.py …c/uipath_pydantic_ai/governance/model.pypackages/uipath-pydantic-ai/src/uipath_pydantic_ai/governance/adapter.py renamed to packages/uipath-pydantic-ai/src/uipath_pydantic_ai/governance/model.py packages/uipath-pydantic-ai/src/uipath_pydantic_ai/governance/adapter.py renamed to packages/uipath-pydantic-ai/src/uipath_pydantic_ai/governance/model.py

@@ -1,4 +1,4 @@
-"""Pydantic AI adapter for UiPath governance.
+"""Pydantic AI governance model wrapper for UiPath.
 
 Pydantic AI has the thinnest hook surface of the supported frameworks — there
 is no per-agent callback or middleware system. But *everything* an agent does
@@ -17,15 +17,17 @@
 Both the non-streaming ``request`` and the streaming ``request_stream`` paths
 are covered (the runtime uses ``agent.run`` and ``agent.iter`` respectively).
 
-Because the wrap is installed on ``agent.model`` in place, :meth:`attach`
-returns the **original agent**; :meth:`detach` restores the original model.
+Because the wrap is installed on ``agent.model`` in place,
+:func:`install_governance` returns the **original agent**.
 
 Chain-level boundaries (BEFORE_AGENT / AFTER_AGENT) are owned by the
 governance host and are intentionally not fired here.
 
-Contracts and the evaluator protocol come from ``uipath-core``; this package
-contributes only the Pydantic-AI-specific implementation and registers it with
-the adapter registry via the ``uipath.governance.adapters`` entry point.
+The evaluator protocol comes from ``uipath-core``; this package contributes
+only the Pydantic-AI-specific wiring. Governance is installed by the runtime
+factory: passing an ``evaluator`` to ``new_runtime`` calls
+:func:`install_governance` on the resolved agent. No adapter registry, no
+entry point, no import-time side effects.
 
 Audit emission and enforcement (raising :class:`GovernanceBlockException` on
 DENY) are owned by the evaluator. The wrapper only extracts payloads and calls
@@ -41,6 +43,7 @@
 from typing import Any, AsyncIterator, Dict, List
 from uuid import uuid4
 
+from pydantic_ai import Agent
 from pydantic_ai.messages import (
     BuiltinToolCallPart,
     TextPart,
@@ -51,7 +54,7 @@
 from pydantic_ai.models import Model, ModelRequestParameters, StreamedResponse
 from pydantic_ai.models.wrapper import WrapperModel
 from pydantic_ai.settings import ModelSettings
-from uipath.core.adapters import BaseAdapter, EvaluatorProtocol
+from uipath.core.adapters import EvaluatorProtocol
 from uipath.core.governance.exceptions import GovernanceBlockException
 
 logger = logging.getLogger(__name__)
@@ -60,69 +63,39 @@
 # evaluation. Sized to match the runtime side and the other adapters.
 _BEFORE_MODEL_TEXT_CAP = 64000
 
-# Attribute used to stash the original (unwrapped) model so detach can restore it.
-_ORIGINAL_MODEL_ATTR = "_uipath_governance_original_model"
 
+def install_governance(
+    agent: Agent,
+    evaluator: EvaluatorProtocol,
+    *,
+    agent_name: str,
+    session_id: str,
+) -> Agent:
+    """Wrap ``agent.model`` with a :class:`GovernanceModel` (mutated in place).
 
-class PydanticAIAdapter(BaseAdapter):
-    """Adapter for the Pydantic AI framework.
+    Returns the original ``agent``. Idempotent: an already-wrapped model is
+    left untouched. If the agent has no concrete ``Model`` bound (the model is
+    supplied per-run), there is nothing to wrap and a warning is logged.
 
-    Detects ``pydantic_ai.Agent`` instances and wraps their ``model`` with a
-    :class:`GovernanceModel`.
+    Called by :class:`UiPathPydanticAIRuntimeFactory` when an ``evaluator``
+    is supplied to ``new_runtime``.
     """
-
-    @property
-    def name(self) -> str:
-        return "PydanticAI"
-
-    def can_handle(self, agent: Any) -> bool:
-        """Return True only for a ``pydantic_ai.Agent``."""
-        try:
-            from pydantic_ai import Agent
-        except ImportError:
-            return False
-        return isinstance(agent, Agent)
-
-    def attach(
-        self,
-        agent: Any,
-        agent_id: str,
-        session_id: str,
-        evaluator: EvaluatorProtocol,
-    ) -> Any:
-        """Wrap ``agent.model`` with governance (mutated in place).
-
-        Returns the original ``agent``. If the agent has no concrete ``Model``
-        bound (the model is supplied per-run), there is nothing to wrap and a
-        warning is logged.
-        """
-        model = getattr(agent, "model", None)
-        if isinstance(model, GovernanceModel):
-            return agent  # idempotent — already governed
-        if not isinstance(model, Model):
-            logger.warning(
-                "PydanticAIAdapter: agent has no bound Model to wrap (got %s); "
-                "model-layer governance will not fire",
-                type(model).__name__,
-            )
-            return agent
-        callbacks = GovernanceCallbacks(
-            evaluator=evaluator, agent_name=agent_id, session_id=session_id
+    model = getattr(agent, "model", None)
+    if isinstance(model, GovernanceModel):
+        return agent  # idempotent — already governed
+    if not isinstance(model, Model):
+        logger.warning(
+            "install_governance: agent has no bound Model to wrap (got %s); "
+            "model-layer governance will not fire",
+            type(model).__name__,
         )
-        setattr(agent, _ORIGINAL_MODEL_ATTR, model)
-        agent.model = GovernanceModel(model, callbacks)
-        logger.debug("Wrapped Pydantic AI agent model with governance")
         return agent
-
-    def detach(self, governed: Any) -> Any:
-        """Restore the agent's original (unwrapped) model and return it."""
-        if isinstance(getattr(governed, "model", None), GovernanceModel):
-            original = getattr(governed, _ORIGINAL_MODEL_ATTR, None)
-            if original is not None:
-                governed.model = original
-        if hasattr(governed, _ORIGINAL_MODEL_ATTR):
-            delattr(governed, _ORIGINAL_MODEL_ATTR)
-        return governed
+    callbacks = GovernanceCallbacks(
+        evaluator=evaluator, agent_name=agent_name, session_id=session_id
+    )
+    agent.model = GovernanceModel(model, callbacks)
+    logger.debug("Wrapped Pydantic AI agent model with governance")
+    return agent
 
 
 class GovernanceModel(WrapperModel):

packages/uipath-pydantic-ai/src/uipath_pydantic_ai/runtime/factory.py

@@ -4,6 +4,7 @@
 from typing import Any
 
 from pydantic_ai import Agent
+from uipath.core.adapters import EvaluatorProtocol
 from uipath.runtime import (
     UiPathRuntimeContext,
     UiPathRuntimeFactorySettings,
@@ -12,6 +13,7 @@
 )
 from uipath.runtime.errors import UiPathErrorCategory
 
+from uipath_pydantic_ai.governance import install_governance
 from uipath_pydantic_ai.runtime.config import PydanticAiConfig
 from uipath_pydantic_ai.runtime.errors import (
     UiPathPydanticAIErrorCode,
@@ -215,6 +217,7 @@ async def _create_runtime_instance(
         agent: Agent,
         runtime_id: str,
         entrypoint: str,
+        evaluator: EvaluatorProtocol | None = None,
     ) -> UiPathRuntimeProtocol:
         """
         Create a runtime instance from an agent.
@@ -223,10 +226,20 @@ async def _create_runtime_instance(
             agent: The PydanticAI Agent
             runtime_id: Unique identifier for the runtime instance
             entrypoint: Agent entrypoint name
+            evaluator: When supplied, governance is installed on the agent's
+                model in place via :func:`install_governance`.
 
         Returns:
             Configured runtime instance
         """
+        if evaluator is not None:
+            install_governance(
+                agent,
+                evaluator,
+                agent_name=entrypoint,
+                session_id=runtime_id,
+            )
+
         return UiPathPydanticAIRuntime(
             agent=agent,
             runtime_id=runtime_id,
@@ -242,7 +255,9 @@ async def new_runtime(
         Args:
             entrypoint: Agent name from pydantic_ai.json
             runtime_id: Unique identifier for the runtime instance
-            **kwargs: Additional keyword arguments (unused)
+            **kwargs: Forwarded factory kwargs. Recognized: ``evaluator``
+                (``EvaluatorProtocol``) — when present, governance is installed
+                on the agent's model via :func:`install_governance`.
 
         Returns:
             Configured runtime instance with agent
@@ -252,6 +267,7 @@ async def new_runtime(
         return await self._create_runtime_instance(
             agent=agent,
             runtime_id=runtime_id,
+            evaluator=kwargs.get("evaluator"),
             entrypoint=entrypoint,
         )