refactor(governance): migrate LlamaIndex adapter to factory-evaluator

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

- governance/adapter.py -> event_handler.py: replace the BaseAdapter
  subclass (name/can_handle/attach/detach) with module-level
  install_governance() that registers the GovernanceEventHandler on the
  root instrumentation dispatcher; keep the handler + callbacks. File
  named for its seam (the event handler), like LangChain's callbacks.py.
- runtime/factory.py: new_runtime reads `evaluator` from kwargs and
  calls install_governance.
- 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_event_handler.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-llamaindex/pyproject.toml

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

packages/uipath-llamaindex/src/uipath_llamaindex/governance/__init__.py

@@ -1,52 +1,20 @@
 """Governance integration for ``uipath-llamaindex``.
 
-Registers :class:`LlamaIndexAdapter` with the adapter registry in
-``uipath.core.adapters`` so the governance host can attach the
-LlamaIndex-specific governance (BEFORE_MODEL, AFTER_MODEL, TOOL_CALL) when it
-sees a LlamaIndex workflow/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` — registers a :class:`GovernanceEventHandler`
+on the LlamaIndex root instrumentation dispatcher, which governs LLM/tool events
+(BEFORE_MODEL, AFTER_MODEL, TOOL_CALL). Wired into a run by passing an
+``evaluator`` to :class:`UiPathLlamaIndexRuntimeFactory`; the factory calls
+:func:`install_governance`.
+
+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 GovernanceEventHandler, LlamaIndexAdapter
-
-logger = logging.getLogger(__name__)
-
-_registered: bool = False
-
-
-def register_governance_adapter() -> None:
-    """Register :class:`LlamaIndexAdapter` with the global registry.
-
-    Idempotent — safe to call multiple times.
-    """
-    global _registered
-    if _registered:
-        return
-    registry = get_adapter_registry()
-    if any(a.name == "LlamaIndex" for a in registry.get_all()):
-        _registered = True
-        return
-    registry.register(LlamaIndexAdapter())
-    _registered = True
-    logger.debug("Registered uipath-llamaindex governance adapter")
-
-
+from .event_handler import GovernanceEventHandler, install_governance
 
 __all__ = [
     "GovernanceEventHandler",
-    "LlamaIndexAdapter",
-    "register_governance_adapter",
+    "install_governance",
 ]

…/uipath_llamaindex/governance/adapter.py …h_llamaindex/governance/event_handler.pypackages/uipath-llamaindex/src/uipath_llamaindex/governance/adapter.py renamed to packages/uipath-llamaindex/src/uipath_llamaindex/governance/event_handler.py packages/uipath-llamaindex/src/uipath_llamaindex/governance/adapter.py renamed to packages/uipath-llamaindex/src/uipath_llamaindex/governance/event_handler.py

@@ -1,7 +1,7 @@
-"""LlamaIndex adapter for UiPath governance.
+"""LlamaIndex governance event handler for UiPath.
 
 Provides governance for LlamaIndex agents/workflows. Unlike the ADK / OpenAI /
-Agent-Framework adapters — which install per-agent callbacks or middleware —
+Agent-Framework integrations — which install per-agent callbacks or middleware —
 LlamaIndex routes everything (LLM calls, tool calls) through its global
 **instrumentation dispatcher** (the same mechanism the package already uses for
 OpenInference tracing). So this adapter governs by registering a
@@ -13,9 +13,9 @@
 - ``AgentToolCallEvent``  → TOOL_CALL     (tool name + arguments)
 
 The dispatcher is process-global, so registration is process-wide — which fits
-the coded-agent model (one workflow per process). :meth:`attach` therefore
-returns the ``agent`` unchanged (nothing is mutated on it); the wiring lives on
-the dispatcher. :meth:`detach` removes the handler.
+the coded-agent model (one workflow per process). :func:`install_governance`
+therefore returns the ``agent`` unchanged (nothing is mutated on it); the wiring
+lives on the dispatcher.
 
 LlamaIndex does **not** emit a tool-*end* instrumentation event, so AFTER_TOOL
 is not wired here; a tool's result is governed at the next ``LLMChatStartEvent``
@@ -25,9 +25,11 @@
 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 LlamaIndex-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 LlamaIndex-specific wiring. Governance is installed by the runtime
+factory: passing an ``evaluator`` to ``new_runtime`` calls
+:func:`install_governance`, which registers the handler on the dispatcher. 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 handler only extracts payloads and calls
@@ -54,7 +56,7 @@
     LLMChatStartEvent,
 )
 from pydantic import PrivateAttr
-from uipath.core.adapters import BaseAdapter, EvaluatorProtocol
+from uipath.core.adapters import EvaluatorProtocol
 from uipath.core.governance.exceptions import GovernanceBlockException
 
 logger = logging.getLogger(__name__)
@@ -64,57 +66,31 @@
 _BEFORE_MODEL_TEXT_CAP = 64000
 
 
-class LlamaIndexAdapter(BaseAdapter):
-    """Adapter for the LlamaIndex framework.
+def install_governance(
+    agent: Any,
+    evaluator: EvaluatorProtocol,
+    *,
+    agent_name: str,
+    session_id: str,
+) -> Any:
+    """Register the governance event handler on the root dispatcher.
 
-    Detects LlamaIndex workflows/agents and governs them by registering a
-    :class:`GovernanceEventHandler` on the root instrumentation dispatcher.
-    """
-
-    @property
-    def name(self) -> str:
-        return "LlamaIndex"
-
-    def can_handle(self, agent: Any) -> bool:
-        """Return True only for a LlamaIndex ``Workflow`` (incl. agent workflows)."""
-        try:
-            from workflows import Workflow
-        except ImportError:
-            return False
-        return isinstance(agent, Workflow)
+    Returns the ``agent`` unchanged — LlamaIndex governance is wired on the
+    process-global instrumentation dispatcher, not on the agent object.
+    Idempotent: a second call is a no-op while a handler is already registered.
 
-    def attach(
-        self,
-        agent: Any,
-        agent_id: str,
-        session_id: str,
-        evaluator: EvaluatorProtocol,
-    ) -> Any:
-        """Register the governance event handler on the root dispatcher.
-
-        Returns the ``agent`` unchanged — LlamaIndex governance is wired on the
-        process-global dispatcher, not on the agent object. Idempotent: a
-        second attach is a no-op while a handler is already registered.
-        """
-        dispatcher = get_dispatcher()
-        if any(isinstance(h, GovernanceEventHandler) for h in dispatcher.event_handlers):
-            return agent  # idempotent — already governed
-        callbacks = GovernanceCallbacks(
-            evaluator=evaluator, agent_name=agent_id, session_id=session_id
-        )
-        dispatcher.add_event_handler(GovernanceEventHandler(callbacks=callbacks))
-        logger.debug("Registered governance event handler on LlamaIndex dispatcher")
-        return agent
-
-    def detach(self, governed: Any) -> Any:
-        """Remove the governance event handler from the root dispatcher."""
-        dispatcher = get_dispatcher()
-        dispatcher.event_handlers = [
-            h
-            for h in dispatcher.event_handlers
-            if not isinstance(h, GovernanceEventHandler)
-        ]
-        return governed
+    Called by :class:`UiPathLlamaIndexRuntimeFactory` when an ``evaluator``
+    is supplied to ``new_runtime``.
+    """
+    dispatcher = get_dispatcher()
+    if any(isinstance(h, GovernanceEventHandler) for h in dispatcher.event_handlers):
+        return agent  # idempotent — already governed
+    callbacks = GovernanceCallbacks(
+        evaluator=evaluator, agent_name=agent_name, session_id=session_id
+    )
+    dispatcher.add_event_handler(GovernanceEventHandler(callbacks=callbacks))
+    logger.debug("Registered governance event handler on LlamaIndex dispatcher")
+    return agent
 
 
 class GovernanceEventHandler(BaseEventHandler):
@@ -279,5 +255,5 @@ def _coerce_args(arguments: Any) -> Dict[str, Any]:
 __all__: List[str] = [
     "GovernanceCallbacks",
     "GovernanceEventHandler",
-    "LlamaIndexAdapter",
+    "install_governance",
 ]

packages/uipath-llamaindex/src/uipath_llamaindex/runtime/factory.py

@@ -7,6 +7,7 @@
     LlamaIndexInstrumentor,
     get_current_span,
 )
+from uipath.core.adapters import EvaluatorProtocol
 from uipath.core.tracing import UiPathSpanUtils, UiPathTraceManager
 from uipath.platform.resume_triggers import UiPathResumeTriggerHandler
 from uipath.runtime import (
@@ -19,6 +20,7 @@
 from uipath.runtime.errors import UiPathErrorCategory
 from workflows import Workflow
 
+from uipath_llamaindex.governance import install_governance
 from uipath_llamaindex.runtime._telemetry import (
     ToolCallAttributeNormalizer,
 )
@@ -233,6 +235,7 @@ async def _create_runtime_instance(
         workflow: Workflow,
         runtime_id: str,
         entrypoint: str,
+        evaluator: EvaluatorProtocol | None = None,
     ) -> UiPathRuntimeProtocol:
         """
         Create a runtime instance from a workflow.
@@ -241,10 +244,19 @@ async def _create_runtime_instance(
             workflow: The workflow
             runtime_id: Unique identifier for the runtime instance
             entrypoint: Workflow entrypoint name
+            evaluator: When supplied, governance is installed on the
+                instrumentation dispatcher via :func:`install_governance`.
 
         Returns:
             Configured runtime instance
         """
+        if evaluator is not None:
+            install_governance(
+                workflow,
+                evaluator,
+                agent_name=entrypoint,
+                session_id=runtime_id,
+            )
 
         storage = await self._get_storage()
 
@@ -274,6 +286,9 @@ async def new_runtime(
         Args:
             entrypoint: Workflow name from llama_index.json
             runtime_id: Unique identifier for the runtime instance
+            **kwargs: Forwarded factory kwargs. Recognized: ``evaluator``
+                (``EvaluatorProtocol``) — when present, governance is installed
+                on the dispatcher via :func:`install_governance`.
 
         Returns:
             Configured runtime instance with workflow
@@ -284,6 +299,7 @@ async def new_runtime(
             workflow=workflow,
             runtime_id=runtime_id,
             entrypoint=entrypoint,
+            evaluator=kwargs.get("evaluator"),
         )
 
     async def dispose(self) -> None: