From a003aa0ad31b061853aa12740faf212a897766bc Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 10:40:17 +0200 Subject: [PATCH 01/11] feat(guardrails): group guardrail checks into stage containers Co-Authored-By: Claude Opus 5.5 --- pyproject.toml | 2 +- .../guardrails/middlewares/_base.py | 97 ++- .../guardrails/middlewares/_spans.py | 240 +++++++- .../guardrails/middlewares/deterministic.py | 22 +- src/uipath_langchain/runtime/factory.py | 9 +- .../middlewares/test_action_span.py | 2 + tests/guardrails/middlewares/test_grouping.py | 578 ++++++++++++++++++ uv.lock | 2 +- 8 files changed, 899 insertions(+), 53 deletions(-) create mode 100644 tests/guardrails/middlewares/test_grouping.py diff --git a/pyproject.toml b/pyproject.toml index e29eb473f..186b130b3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "uipath-langchain" -version = "0.20.7" +version = "0.20.8" description = "Python SDK that enables developers to build and deploy LangGraph agents to the UiPath Cloud Platform" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.11" diff --git a/src/uipath_langchain/guardrails/middlewares/_base.py b/src/uipath_langchain/guardrails/middlewares/_base.py index afadd2c84..b65c970fb 100644 --- a/src/uipath_langchain/guardrails/middlewares/_base.py +++ b/src/uipath_langchain/guardrails/middlewares/_base.py @@ -55,7 +55,12 @@ registry_references, tool_result_references, ) -from ._spans import guardrail_action_span +from ._spans import ( + guardrail_action_span, + guardrail_stage, + guardrails_in_use, + register_guardrail_node, +) from ._utils import ( convert_block_exception, create_modified_tool_request, @@ -416,16 +421,17 @@ async def _run_tool_guardrail( tool_args=input_data, ) try: - result = await asyncio.to_thread( - self._evaluate_guardrail, input_data, attachments - ) - modified_input = self._handle_validation_result( - result, - input_data, - scope=GuardrailScope.TOOL, - stage=GuardrailExecutionStage.PRE, - component=tool_name, - ) + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): + result = await asyncio.to_thread( + self._evaluate_guardrail, input_data, attachments + ) + modified_input = self._handle_validation_result( + result, + input_data, + scope=GuardrailScope.TOOL, + stage=GuardrailExecutionStage.PRE, + component=tool_name, + ) if modified_input is not None: request = create_modified_tool_request(request, modified_input) except GuardrailBlockException as exc: @@ -457,19 +463,22 @@ async def _run_tool_guardrail( tool_result=output_data, ) try: - result = await asyncio.to_thread( - self._evaluate_guardrail, output_data, attachments - ) - modified_output = self._handle_validation_result( - result, - output_data, - scope=GuardrailScope.TOOL, - stage=GuardrailExecutionStage.POST, - component=tool_name, - input_payload=json.dumps( - self._extract_tool_input_data(request) - ), - ) + with guardrail_stage( + GuardrailScope.TOOL, GuardrailExecutionStage.POST + ): + result = await asyncio.to_thread( + self._evaluate_guardrail, output_data, attachments + ) + modified_output = self._handle_validation_result( + result, + output_data, + scope=GuardrailScope.TOOL, + stage=GuardrailExecutionStage.POST, + component=tool_name, + input_payload=json.dumps( + self._extract_tool_input_data(request) + ), + ) if modified_output is not None: tool_result = create_modified_tool_result( tool_result, modified_output @@ -492,6 +501,7 @@ async def _run_tool_guardrail( def _create_tool_wrap_hook(self, guardrail_name: str) -> AgentMiddleware: """Create a wrap_tool_call hook that delegates to _run_tool_guardrail.""" + guardrails_in_use() middleware_instance = self async def _wrap_tool_call_func( @@ -547,6 +557,11 @@ async def _before_agent_func( ) _before_agent_func.__name__ = f"{guardrail_name}_before_agent" + register_guardrail_node( + f"{_before_agent_func.__name__}.before_agent", + GuardrailScope.AGENT, + GuardrailExecutionStage.PRE, + ) hooks.append(before_agent(_before_agent_func)) if include_post: @@ -575,6 +590,11 @@ async def _after_agent_func( ) _after_agent_func.__name__ = f"{guardrail_name}_after_agent" + register_guardrail_node( + f"{_after_agent_func.__name__}.after_agent", + GuardrailScope.AGENT, + GuardrailExecutionStage.POST, + ) hooks.append(after_agent(_after_agent_func)) elif scope == GuardrailScope.LLM: @@ -596,6 +616,11 @@ async def _before_model_func( ) _before_model_func.__name__ = f"{guardrail_name}_before_model" + register_guardrail_node( + f"{_before_model_func.__name__}.before_model", + GuardrailScope.LLM, + GuardrailExecutionStage.PRE, + ) hooks.append(before_model(_before_model_func)) if include_post: @@ -619,6 +644,11 @@ async def _after_model_func( ) _after_model_func.__name__ = f"{guardrail_name}_after_model" + register_guardrail_node( + f"{_after_model_func.__name__}.after_model", + GuardrailScope.LLM, + GuardrailExecutionStage.POST, + ) hooks.append(after_model(_after_model_func)) return hooks @@ -656,15 +686,16 @@ def _check_messages( payload = text or NO_TEXT_PLACEHOLDER try: - result = self._evaluate_guardrail(payload, attachments) - modified_text = self._handle_validation_result( - result, - payload, - scope=scope, - stage=stage, - component=component_label(scope), - input_payload=json.dumps(input_text) if input_text else None, - ) + with guardrail_stage(scope, stage): + result = self._evaluate_guardrail(payload, attachments) + modified_text = self._handle_validation_result( + result, + payload, + scope=scope, + stage=stage, + component=component_label(scope), + input_payload=json.dumps(input_text) if input_text else None, + ) if text: _apply_text_modification(messages, text, modified_text) except GuardrailBlockException as exc: diff --git a/src/uipath_langchain/guardrails/middlewares/_spans.py b/src/uipath_langchain/guardrails/middlewares/_spans.py index 36c8eba19..d5f8681aa 100644 --- a/src/uipath_langchain/guardrails/middlewares/_spans.py +++ b/src/uipath_langchain/guardrails/middlewares/_spans.py @@ -1,26 +1,42 @@ -"""Guardrail spans shaped like low-code agents'.""" +"""Guardrail spans shaped like low-code agents': actions, rule evaluations and +stage containers that group a stage's checks across separate middleware nodes.""" -from collections.abc import Generator +import threading +import time +import weakref +from collections.abc import Callable, Generator from contextlib import contextmanager +from contextvars import ContextVar from typing import Any from langgraph.errors import GraphBubbleUp +from opentelemetry import context as otel_context from opentelemetry import trace -from opentelemetry.trace import Span, StatusCode -from uipath.core.guardrails import GuardrailValidationResult +from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor +from opentelemetry.trace import NonRecordingSpan, Span, SpanContext, StatusCode +from uipath.core.guardrails import GuardrailScope, GuardrailValidationResult from uipath.core.tracing.span_utils import UiPathSpanUtils -from uipath.platform.guardrails.decorators import LoggingSeverityLevel +from uipath.platform.guardrails.decorators import ( + GuardrailExecutionStage, + LoggingSeverityLevel, +) from uipath.platform.guardrails.decorators._exceptions import GuardrailBlockException GUARDRAIL_ACTION = "guardrailAction" GUARDRAIL_EVALUATION = "guardrailEvaluation" +_CONTAINER_MARK = "uipath.guardrail_container" -def _new_span(name: str, span_type: str, **attributes: Any) -> Span: +def _new_span( + name: str, + span_type: str, + context: otel_context.Context | None = None, + **attributes: Any, +) -> Span: """Start a span under the deepest active span, as ``@traced`` does.""" return trace.get_tracer(__name__).start_span( name, - context=UiPathSpanUtils.get_parent_context(), + context=context or UiPathSpanUtils.get_parent_context(), attributes={ "type": span_type, "span_type": span_type, @@ -112,3 +128,213 @@ def set_validation_result(span: Span, result: GuardrailValidationResult) -> None span.set_attribute("validationResult", result.result.name) if result.reason: span.set_attribute("details", [result.reason]) + + +_PRE = GuardrailExecutionStage.PRE +_POST = GuardrailExecutionStage.POST + +# (scope, stage) -> (container name, span type), as in low-code agents. +_STAGES: dict[tuple[GuardrailScope, GuardrailExecutionStage], tuple[str, str]] = { + (GuardrailScope.AGENT, _PRE): ("Agent input guardrail check", "agentPreGuardrails"), + (GuardrailScope.AGENT, _POST): ( + "Agent output guardrail check", + "agentPostGuardrails", + ), + (GuardrailScope.LLM, _PRE): ("LLM input guardrail check", "llmPreGuardrails"), + (GuardrailScope.LLM, _POST): ("LLM output guardrail check", "llmPostGuardrails"), + (GuardrailScope.TOOL, _PRE): ("Tool input guardrail check", "toolPreGuardrails"), + (GuardrailScope.TOOL, _POST): ("Tool output guardrail check", "toolPostGuardrails"), +} + + +class _GroupingState: + """Process-wide state. Grouping stays off until a closer is registered.""" + + def __init__(self) -> None: + self.enabled = False + self.in_use = False # a guardrail middleware was built + self.trace_manager: Any = None # offered by the runtime factory + self.closers: weakref.WeakKeyDictionary[Any, GuardrailStageCloser] = ( + weakref.WeakKeyDictionary() + ) # trace manager -> its closer + self.guardrail_nodes: dict[str, str] = {} # node name -> stage span type + self.containers: dict[tuple[int, str], Span] = {} # (parent id, type) + self.last_check_end: dict[int, int] = {} # container span id -> ns + self.lock = threading.Lock() + + +_state = _GroupingState() + +_current_container: ContextVar[Span | None] = ContextVar( + "uipath_guardrail_container", default=None +) + + +def register_guardrail_node( + node_name: str, scope: GuardrailScope, stage: GuardrailExecutionStage +) -> None: + """Record which stage a guardrail hook's LangGraph node belongs to.""" + _state.guardrail_nodes[node_name] = _STAGES[(scope, stage)][1] + guardrails_in_use() + + +def guardrails_in_use() -> None: + """Called by guardrail middlewares when built; grouping needs one in use.""" + _state.in_use = True + _activate() + + +@contextmanager +def guardrail_stage( + scope: GuardrailScope | None, stage: GuardrailExecutionStage | None +) -> Generator[None]: + """Run one check inside its stage's shared container.""" + container = _shared_container(scope, stage) + if container is None: + yield + return + token = _current_container.set(container) + try: + yield + except GraphBubbleUp: + raise + except Exception as exc: + container.set_status(StatusCode.ERROR, _error_text(exc)) + raise + finally: + _current_container.reset(token) + with _state.lock: + _state.last_check_end[container.get_span_context().span_id] = time.time_ns() + + +def _shared_container( + scope: GuardrailScope | None, stage: GuardrailExecutionStage | None +) -> Span | None: + """Get or create the stage container: beside message nodes, inside ``tools``.""" + if not _state.enabled or (scope, stage) not in _STAGES: + return None + node = UiPathSpanUtils.get_external_current_span() + if node is None: + return None + if scope == GuardrailScope.TOOL: + parent: SpanContext | None = node.get_span_context() + else: + parent = getattr(node, "parent", None) + if parent is None or not parent.is_valid: + return None # nothing would ever close it + + name, span_type = _STAGES[(scope, stage)] # type: ignore[index] + key = (parent.span_id, span_type) + with _state.lock: + container = _state.containers.get(key) + if container is None: + container = _new_span( + name, + span_type, + context=trace.set_span_in_context(NonRecordingSpan(parent)), + **{ + _CONTAINER_MARK: True, + # Its parent is non-recording, so this isn't inherited. + "execution.id": (getattr(node, "attributes", None) or {}).get( + "execution.id" + ), + }, + ) + _state.containers[key] = container + return container + + +def guardrail_aware( + provider: Callable[[], Span | None], +) -> Callable[[], Span | None]: + """Report the running check's container as the current span.""" + + def current_span() -> Span | None: + return _current_container.get() or provider() + + return current_span + + +class GuardrailStageCloser(SpanProcessor): + """End a container when a non-guardrail sibling starts or its parent ends.""" + + def on_start( + self, span: Span, parent_context: otel_context.Context | None = None + ) -> None: + attributes = getattr(span, "attributes", None) or {} + parent = getattr(span, "parent", None) + if attributes.get(_CONTAINER_MARK) or parent is None: + return + same_stage = _state.guardrail_nodes.get(getattr(span, "name", "")) + self._close( + lambda key: key[0] == parent.span_id and key[1] != same_stage, + end_time=getattr(span, "start_time", None), + ) + + def on_end(self, span: ReadableSpan) -> None: + span_id = span.context.span_id if span.context else None + self._close(lambda key: key[0] == span_id, end_time=span.end_time) + + def shutdown(self) -> None: + """Called when its trace manager shuts down: unregister, end what's open.""" + with _state.lock: + owners = [m for m, closer in _state.closers.items() if closer is self] + for manager in owners: + del _state.closers[manager] + _state.enabled = bool(_state.closers) + if not _state.enabled: + self._close(lambda key: True, end_time=None) + + @staticmethod + def _close( + matches: Callable[[tuple[int, str]], bool], end_time: int | None + ) -> None: + with _state.lock: + done = [key for key in _state.containers if matches(key)] + spans = [_state.containers.pop(key) for key in done] + last_ends = [ + _state.last_check_end.pop(span.get_span_context().span_id, 0) + for span in spans + ] + for span, last_end in zip(spans, last_ends, strict=True): + status = getattr(span, "status", None) + if status is None or status.status_code is StatusCode.UNSET: + span.set_status(StatusCode.OK) + # Never before its last check: coarse clocks (Windows before Python + # 3.13) can stamp the next sibling's start a tick earlier. + span.end(end_time=max(end_time, last_end) if end_time else None) + + +def is_exported(span: ReadableSpan) -> bool: + """Span filter hiding guardrail node spans (by name: spans upload on start).""" + if not _state.enabled or span.name not in _state.guardrail_nodes: + return True + scope = getattr(span, "instrumentation_scope", None) + return "openinference" not in (getattr(scope, "name", "") or "") + + +def enable_guardrail_grouping( + trace_manager: Any, current_span_provider: Callable[[], Span | None] +) -> None: + """Register the span provider and offer the trace manager for grouping. + + Grouping turns on once a guardrail middleware is also in use. + """ + UiPathSpanUtils.register_current_span_provider( + guardrail_aware(current_span_provider) + ) + _state.trace_manager = trace_manager + _activate() + + +def _activate() -> None: + """Attach a closer to the offered trace manager if guardrails are in use.""" + with _state.lock: + manager = _state.trace_manager + if manager is None or not _state.in_use: + return + if manager not in _state.closers: + closer = GuardrailStageCloser() + manager.add_span_processor(closer) + _state.closers[manager] = closer + _state.enabled = True diff --git a/src/uipath_langchain/guardrails/middlewares/deterministic.py b/src/uipath_langchain/guardrails/middlewares/deterministic.py index 9a65af3d2..1b27996a5 100644 --- a/src/uipath_langchain/guardrails/middlewares/deterministic.py +++ b/src/uipath_langchain/guardrails/middlewares/deterministic.py @@ -12,6 +12,7 @@ from langgraph.prebuilt.tool_node import ToolCallRequest from langgraph.types import Command from uipath.core.guardrails import ( + GuardrailScope, GuardrailValidationResult, GuardrailValidationResultType, ) @@ -24,6 +25,8 @@ from ._spans import ( guardrail_action_span, guardrail_evaluation_span, + guardrail_stage, + guardrails_in_use, set_validation_result, span_guid, ) @@ -162,6 +165,7 @@ def __init__( def _create_middleware_instances(self) -> list[AgentMiddleware]: """Create middleware instances from decorated functions.""" + guardrails_in_use() instances = [] middleware_instance = self guardrail_name = self._name.replace(" ", "_") @@ -240,16 +244,16 @@ def _evaluate_and_apply_modifications( ToolCallRequest | None, dict[str, Any] | None, ToolMessage | Command[Any] | None ]: """Evaluate rules and apply modifications if validation fails.""" - with guardrail_evaluation_span(self._name, self._description) as span: - result = self._evaluate_rules(rules, stage, input_data, output_data) - set_validation_result(span, result) - if result.result != GuardrailValidationResultType.VALIDATION_FAILED: - return request, input_data, tool_result - try: - modified_data = self._handle_validation_result( - result, data_for_action, evaluation_span_id=span_guid(span) - ) + with guardrail_stage(GuardrailScope.TOOL, stage): + with guardrail_evaluation_span(self._name, self._description) as span: + result = self._evaluate_rules(rules, stage, input_data, output_data) + set_validation_result(span, result) + if result.result != GuardrailValidationResultType.VALIDATION_FAILED: + return request, input_data, tool_result + modified_data = self._handle_validation_result( + result, data_for_action, evaluation_span_id=span_guid(span) + ) except GuardrailBlockException as exc: raise convert_block_exception(exc) from exc except AgentRuntimeError: diff --git a/src/uipath_langchain/runtime/factory.py b/src/uipath_langchain/runtime/factory.py index d983cedae..755b4c5fb 100644 --- a/src/uipath_langchain/runtime/factory.py +++ b/src/uipath_langchain/runtime/factory.py @@ -11,7 +11,7 @@ get_current_span, ) from uipath.core.adapters import EvaluatorProtocol -from uipath.core.tracing import UiPathSpanUtils, UiPathTraceManager +from uipath.core.tracing import UiPathSpanUtils, UiPathTraceManager, UiPathTraceSettings from uipath.platform.resume_triggers import ( UiPathResumeTriggerHandler, ) @@ -28,6 +28,10 @@ from uipath_langchain._tracing import _instrument_traceable_attributes from uipath_langchain.chat.chat_model_factory import _TraceContextHeadersCallback from uipath_langchain.governance import GovernanceCallbackHandler +from uipath_langchain.guardrails.middlewares._spans import ( + enable_guardrail_grouping, + is_exported, +) from uipath_langchain.runtime.config import LangGraphConfig from uipath_langchain.runtime.errors import LangGraphErrorCode, LangGraphRuntimeError from uipath_langchain.runtime.graph import LangGraphLoader @@ -67,7 +71,7 @@ def _setup_instrumentation(self, trace_manager: UiPathTraceManager | None) -> No """Setup tracing and instrumentation.""" _instrument_traceable_attributes() LangChainInstrumentor().instrument() - UiPathSpanUtils.register_current_span_provider(get_current_span) + enable_guardrail_grouping(trace_manager, get_current_span) UiPathSpanUtils.register_current_span_ancestors_provider(get_ancestor_spans) def _get_connection_string(self) -> str: @@ -251,6 +255,7 @@ async def get_settings(self) -> UiPathRuntimeFactorySettings | None: return UiPathRuntimeFactorySettings( agent_type=_AGENT_TYPE_CODED, agent_framework=_AGENT_FRAMEWORK, + trace_settings=UiPathTraceSettings(span_filter=is_exported), ) async def get_storage(self) -> UiPathRuntimeStorageProtocol | None: diff --git a/tests/guardrails/middlewares/test_action_span.py b/tests/guardrails/middlewares/test_action_span.py index 7d68c8896..f44ea8ee8 100644 --- a/tests/guardrails/middlewares/test_action_span.py +++ b/tests/guardrails/middlewares/test_action_span.py @@ -32,6 +32,7 @@ from uipath_langchain.guardrails.middlewares import ( UiPathDeterministicGuardrailMiddleware, UiPathPIIDetectionMiddleware, + _spans, ) from uipath_langchain.guardrails.middlewares._spans import action_name from uipath_langchain.guardrails.models import PIIDetectionEntity @@ -49,6 +50,7 @@ @pytest.fixture def recorded_spans(monkeypatch: pytest.MonkeyPatch) -> Iterator[InMemorySpanExporter]: + monkeypatch.setattr(_spans, "_state", _spans._GroupingState()) provider = TracerProvider() exporter = InMemorySpanExporter() provider.add_span_processor(SimpleSpanProcessor(exporter)) diff --git a/tests/guardrails/middlewares/test_grouping.py b/tests/guardrails/middlewares/test_grouping.py new file mode 100644 index 000000000..a3591aad6 --- /dev/null +++ b/tests/guardrails/middlewares/test_grouping.py @@ -0,0 +1,578 @@ +"""Separate guardrail middlewares share one container span per stage.""" + +import asyncio +import time +from collections.abc import Iterator +from contextlib import contextmanager +from typing import Any +from unittest.mock import MagicMock, patch + +import pytest +from langchain.agents import create_agent +from langchain_core.language_models.fake_chat_models import GenericFakeChatModel +from langchain_core.messages import AIMessage, HumanMessage, ToolMessage +from langchain_core.tools import tool +from langgraph.prebuilt.tool_node import ToolCallRequest +from openinference.instrumentation.langchain import ( + LangChainInstrumentor, + get_ancestor_spans, + get_current_span, +) +from opentelemetry import trace +from opentelemetry.sdk.trace import ReadableSpan, TracerProvider +from opentelemetry.sdk.trace.export import SimpleSpanProcessor +from opentelemetry.sdk.trace.export.in_memory_span_exporter import ( + InMemorySpanExporter, +) +from opentelemetry.trace import Span, StatusCode +from uipath.core.guardrails import ( + GuardrailScope, + GuardrailValidationResult, + GuardrailValidationResultType, +) +from uipath.core.tracing.span_utils import UiPathSpanUtils +from uipath.platform.guardrails.decorators import BlockAction, LogAction + +from uipath_langchain.agent.exceptions import AgentRuntimeError +from uipath_langchain.guardrails import GuardrailExecutionStage +from uipath_langchain.guardrails.enums import PIIDetectionEntityType +from uipath_langchain.guardrails.middlewares import ( + UiPathDeterministicGuardrailMiddleware, + UiPathPIIDetectionMiddleware, + UiPathPromptInjectionMiddleware, + _base, + _spans, +) +from uipath_langchain.guardrails.middlewares._spans import ( + enable_guardrail_grouping, + guardrail_stage, + is_exported, +) +from uipath_langchain.guardrails.models import PIIDetectionEntity + +_FAILED = GuardrailValidationResult( + result=GuardrailValidationResultType.VALIDATION_FAILED, reason="found" +) +_STATE = {"messages": [HumanMessage(content="mail me at a@b.com")]} +_OPENINFERENCE = "openinference.instrumentation.langchain" + + +@pytest.fixture +def exporter(monkeypatch: pytest.MonkeyPatch) -> Iterator[InMemorySpanExporter]: + monkeypatch.setattr(_spans, "_state", _spans._GroupingState()) + provider = TracerProvider() + exporter = InMemorySpanExporter() + provider.add_span_processor(SimpleSpanProcessor(exporter)) + monkeypatch.setattr(trace, "get_tracer", provider.get_tracer) + exporter.provider = provider # type: ignore[attr-defined] + yield exporter + UiPathSpanUtils.register_current_span_provider(None) + UiPathSpanUtils.register_current_span_ancestors_provider(None) + provider.shutdown() + + +class _Graph: + """Plays LangGraph: a graph span and node spans started in order.""" + + def __init__(self, exporter: InMemorySpanExporter) -> None: + self.exporter = exporter + self._tracer = exporter.provider.get_tracer(_OPENINFERENCE) # type: ignore[attr-defined] + self.current: Span | None = None + self.span = self._tracer.start_span("LangGraph") + + @contextmanager + def node( + self, + name: str, + parent: Span | None = None, + attributes: dict[str, Any] | None = None, + start_time: int | None = None, + ) -> Iterator[Span]: + span = self._tracer.start_span( + name, + context=trace.set_span_in_context(parent or self.span), + attributes=attributes, + start_time=start_time, + ) + previous, self.current = self.current, span + try: + yield span + finally: + self.current = previous + span.end() + + def finish(self) -> list[ReadableSpan]: + self.span.end() + return list(self.exporter.get_finished_spans()) + + +@pytest.fixture +def graph(exporter: InMemorySpanExporter) -> _Graph: + fake = _Graph(exporter) + enable_guardrail_grouping(exporter.provider, lambda: fake.current) # type: ignore[attr-defined] + return fake + + +def _hook(middleware: Any, name: str) -> Any: + [hook] = [h for h in middleware if h.name.endswith(name)] + return hook + + +def _named(spans: list[ReadableSpan], name: str) -> list[ReadableSpan]: + return [s for s in spans if s.name == name] + + +def _children(spans: list[ReadableSpan], parent: ReadableSpan) -> list[str]: + return [ + s.name + for s in spans + if s.parent is not None and s.parent.span_id == parent.context.span_id + ] + + +def _pii(**kwargs: Any) -> UiPathPIIDetectionMiddleware: + return UiPathPIIDetectionMiddleware( + scopes=kwargs.pop("scopes", [GuardrailScope.LLM]), + action=kwargs.pop("action", LogAction()), + entities=[PIIDetectionEntity(PIIDetectionEntityType.EMAIL)], + **kwargs, + ) + + +def _rule(stage: GuardrailExecutionStage) -> UiPathDeterministicGuardrailMiddleware: + return UiPathDeterministicGuardrailMiddleware( + tools=["get_weather"], + rules=[lambda *args: True], + action=LogAction(), + stage=stage, + name="Rule", + ) + + +def _tool_request() -> ToolCallRequest: + return ToolCallRequest( + tool_call={"id": "tc1", "name": "get_weather", "args": {"city": "London"}}, + tool=MagicMock(), + state={}, + runtime=MagicMock(), + ) + + +class TestStages: + async def test_guardrail_nodes_of_one_stage_share_a_container( + self, graph: _Graph + ) -> None: + pii = _pii() + injection = UiPathPromptInjectionMiddleware(action=LogAction()) + pii_hook = _hook(pii, "_before_model") + injection_hook = _hook(injection, "_before_model") + + with ( + patch.object(pii, "_evaluate_guardrail", return_value=_FAILED), + patch.object(injection, "_evaluate_guardrail", return_value=_FAILED), + ): + with graph.node(f"{pii_hook.name}.before_model"): + await pii_hook.abefore_model(_STATE, MagicMock()) + with graph.node(f"{injection_hook.name}.before_model"): + await injection_hook.abefore_model(_STATE, MagicMock()) + with graph.node("model") as model: + model_start = model.start_time # type: ignore[attr-defined] + spans = graph.finish() + + [container] = _named(spans, "LLM input guardrail check") + assert (container.attributes or {})["span_type"] == "llmPreGuardrails" + assert container.parent is not None + assert container.parent.span_id == graph.span.get_span_context().span_id + assert _children(spans, container) == ["Log", "Log"] + assert container.end_time == model_start + assert container.status.status_code == StatusCode.OK + + async def test_a_container_never_ends_before_its_last_check( + self, graph: _Graph + ) -> None: + pii = _pii() + hook = _hook(pii, "_before_model") + + with ( + patch.object(pii, "_evaluate_guardrail", return_value=_FAILED), + graph.node(f"{hook.name}.before_model"), + ): + await hook.abefore_model(_STATE, MagicMock()) + # A coarse clock stamps the next node's start before the check ended. + with graph.node("model", start_time=time.time_ns() - 10_000_000): + pass + spans = graph.finish() + + [container] = _named(spans, "LLM input guardrail check") + [log] = _named(spans, "Log") + assert container.end_time is not None + assert log.end_time is not None + assert container.end_time >= log.end_time + + async def test_the_container_carries_the_execution_id(self, graph: _Graph) -> None: + pii = _pii() + hook = _hook(pii, "_before_model") + + with ( + patch.object(pii, "_evaluate_guardrail", return_value=_FAILED), + graph.node( + f"{hook.name}.before_model", attributes={"execution.id": "exec-1"} + ), + ): + await hook.abefore_model(_STATE, MagicMock()) + spans = graph.finish() + + [container] = _named(spans, "LLM input guardrail check") + assert (container.attributes or {})["execution.id"] == "exec-1" + + async def test_a_new_stage_gets_its_own_container(self, graph: _Graph) -> None: + pii = _pii(scopes=[GuardrailScope.AGENT, GuardrailScope.LLM]) + agent_hook = _hook(pii, "_before_agent") + model_hook = _hook(pii, "_before_model") + + with patch.object(pii, "_evaluate_guardrail", return_value=_FAILED): + with graph.node(f"{agent_hook.name}.before_agent"): + await agent_hook.abefore_agent(_STATE, MagicMock()) + with graph.node(f"{model_hook.name}.before_model"): + await model_hook.abefore_model(_STATE, MagicMock()) + spans = graph.finish() + + assert len(_named(spans, "Agent input guardrail check")) == 1 + assert len(_named(spans, "LLM input guardrail check")) == 1 + + async def test_another_node_between_guardrails_splits_the_stage( + self, graph: _Graph + ) -> None: + pii = _pii() + injection = UiPathPromptInjectionMiddleware(action=LogAction()) + pii_hook = _hook(pii, "_before_model") + injection_hook = _hook(injection, "_before_model") + + with ( + patch.object(pii, "_evaluate_guardrail", return_value=_FAILED), + patch.object(injection, "_evaluate_guardrail", return_value=_FAILED), + ): + with graph.node(f"{pii_hook.name}.before_model"): + await pii_hook.abefore_model(_STATE, MagicMock()) + with graph.node("SummarizationMiddleware.before_model"): + pass + with graph.node(f"{injection_hook.name}.before_model"): + await injection_hook.abefore_model(_STATE, MagicMock()) + spans = graph.finish() + + assert len(_named(spans, "LLM input guardrail check")) == 2 + + async def test_llm_output_checks_get_their_container(self, graph: _Graph) -> None: + pii = _pii() + hook = _hook(pii, "_after_model") + state = {"messages": [HumanMessage("hi"), AIMessage("mail a@b.com")]} + + with ( + patch.object(pii, "_evaluate_guardrail", return_value=_FAILED), + graph.node(f"{hook.name}.after_model"), + ): + await hook.aafter_model(state, MagicMock()) + spans = graph.finish() + + [container] = _named(spans, "LLM output guardrail check") + assert _children(spans, container) == ["Log"] + + async def test_a_block_marks_the_container_as_failed(self, graph: _Graph) -> None: + pii = _pii(action=BlockAction()) + hook = _hook(pii, "_before_model") + + with ( + patch.object(pii, "_evaluate_guardrail", return_value=_FAILED), + pytest.raises(AgentRuntimeError), + graph.node(f"{hook.name}.before_model"), + ): + await hook.abefore_model(_STATE, MagicMock()) + spans = graph.finish() + + [container] = _named(spans, "LLM input guardrail check") + assert container.status.status_code == StatusCode.ERROR + + async def test_a_stage_with_nothing_to_check_leaves_no_container( + self, graph: _Graph + ) -> None: + pii = _pii() + hook = _hook(pii, "_before_model") + + with ( + patch.object(pii, "_evaluate_guardrail") as evaluate, + graph.node(f"{hook.name}.before_model"), + ): + await hook.abefore_model({"messages": []}, MagicMock()) + spans = graph.finish() + + evaluate.assert_not_called() + assert not _named(spans, "LLM input guardrail check") + + +class TestTools: + async def _call_tool( + self, graph: _Graph, stage: GuardrailExecutionStage + ) -> list[ReadableSpan]: + [wrapper] = list(_rule(stage)) + with graph.node("tools") as tools: + + async def run_tool(request: ToolCallRequest) -> ToolMessage: + with graph.node("get_weather", parent=tools): + return ToolMessage(content="sunny", tool_call_id="tc1") + + await wrapper.awrap_tool_call(_tool_request(), run_tool) + return graph.finish() + + async def test_input_checks_close_when_the_tool_starts(self, graph: _Graph) -> None: + spans = await self._call_tool(graph, GuardrailExecutionStage.PRE) + + [container] = _named(spans, "Tool input guardrail check") + [tools] = _named(spans, "tools") + [tool_span] = _named(spans, "get_weather") + assert container.parent is not None + assert container.parent.span_id == tools.context.span_id + assert _children(spans, container) == ["Rule", "Log"] + assert container.end_time == tool_span.start_time + + async def test_output_checks_close_when_the_tools_node_ends( + self, graph: _Graph + ) -> None: + spans = await self._call_tool(graph, GuardrailExecutionStage.POST) + + [container] = _named(spans, "Tool output guardrail check") + [tools] = _named(spans, "tools") + [tool_span] = _named(spans, "get_weather") + assert container.start_time is not None + assert tool_span.end_time is not None + assert container.start_time >= tool_span.end_time + assert container.end_time == tools.end_time + + +class TestEnabling: + async def test_nothing_is_grouped_without_a_closer( + self, exporter: InMemorySpanExporter + ) -> None: + node = exporter.provider.get_tracer(_OPENINFERENCE).start_span("node") # type: ignore[attr-defined] + enable_guardrail_grouping(None, lambda: node) + + with guardrail_stage(GuardrailScope.LLM, GuardrailExecutionStage.PRE): + pass + node.end() + + assert _spans._state.containers == {} + assert not _spans._state.enabled + + async def test_nothing_is_grouped_under_an_invalid_node_span( + self, exporter: InMemorySpanExporter + ) -> None: + enable_guardrail_grouping(exporter.provider, lambda: trace.INVALID_SPAN) # type: ignore[attr-defined] + _pii() # a guardrail in use turns grouping on + + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): + pass + + assert _spans._state.enabled + assert _spans._state.containers == {} + + def test_the_closer_is_added_once_per_trace_manager( + self, exporter: InMemorySpanExporter + ) -> None: + manager = MagicMock() + enable_guardrail_grouping(manager, lambda: None) + _pii() + enable_guardrail_grouping(manager, lambda: None) + _pii() + + manager.add_span_processor.assert_called_once() + + def test_the_closer_comes_back_after_its_trace_manager_shuts_down( + self, exporter: InMemorySpanExporter + ) -> None: + manager = MagicMock() + enable_guardrail_grouping(manager, lambda: None) + _pii() + [closer] = [call.args[0] for call in manager.add_span_processor.call_args_list] + + closer.shutdown() # what UiPathTraceManager.shutdown() does + assert not _spans._state.enabled + enable_guardrail_grouping(manager, lambda: None) + + assert manager.add_span_processor.call_count == 2 + assert _spans._state.enabled + + def test_tool_only_guardrails_turn_grouping_on( + self, exporter: InMemorySpanExporter + ) -> None: + manager = MagicMock() + enable_guardrail_grouping(manager, lambda: None) + _rule(GuardrailExecutionStage.PRE) + + manager.add_span_processor.assert_called_once() + assert _spans._state.enabled + + def test_grouping_stays_off_without_guardrail_middlewares( + self, exporter: InMemorySpanExporter + ) -> None: + manager = MagicMock() + enable_guardrail_grouping(manager, lambda: None) + + manager.add_span_processor.assert_not_called() + assert not _spans._state.enabled + + async def test_only_guardrail_node_spans_are_hidden(self, graph: _Graph) -> None: + pii = _pii() + hook = _hook(pii, "_before_model") + node_name = f"{hook.name}.before_model" + user_span = trace.get_tracer("my_app").start_span(node_name) + user_span.end() + + with ( + patch.object(pii, "_evaluate_guardrail", return_value=_FAILED), + graph.node(node_name), + ): + await hook.abefore_model(_STATE, MagicMock()) + spans = graph.finish() + + hidden = [s for s in spans if not is_exported(s)] + assert [s.instrumentation_scope.name for s in hidden] == [_OPENINFERENCE] # type: ignore[union-attr] + assert is_exported(_named(spans, "LLM input guardrail check")[0]) + + +class _ToolCallingModel(GenericFakeChatModel): + def bind_tools(self, *args: Any, **kwargs: Any) -> "_ToolCallingModel": + return self + + +@tool +def get_weather(city: str) -> str: + """Weather for a city.""" + return "sunny" + + +class TestRealAgent: + """A real create_agent graph traced by OpenInference.""" + + @pytest.fixture + def instrumented(self, exporter: InMemorySpanExporter) -> Iterator[None]: + provider = exporter.provider # type: ignore[attr-defined] + instrumentor = LangChainInstrumentor() + # Instrumentation is global: re-instrument on this provider, then restore. + was_instrumented = instrumentor.is_instrumented_by_opentelemetry + if was_instrumented: + instrumentor.uninstrument() + instrumentor.instrument(tracer_provider=provider) + enable_guardrail_grouping(provider, get_current_span) + UiPathSpanUtils.register_current_span_ancestors_provider(get_ancestor_spans) + yield + instrumentor.uninstrument() + if was_instrumented: + instrumentor.instrument() + + def _agent(self, parallel_calls: int) -> Any: + calls = [ + {"id": f"t{i}", "name": "get_weather", "args": {"city": "London"}} + for i in range(parallel_calls) + ] + model = _ToolCallingModel( + messages=iter([AIMessage(content="", tool_calls=calls), AIMessage("ok")]) + ) + guardrails = [ + *_pii( + scopes=[GuardrailScope.LLM, GuardrailScope.TOOL], tools=[get_weather] + ), + *UiPathPromptInjectionMiddleware(action=LogAction()), + *_rule(GuardrailExecutionStage.PRE_AND_POST), + ] + return create_agent(model, tools=[get_weather], middleware=guardrails) + + @staticmethod + def _assert_well_formed(spans: list[ReadableSpan]) -> None: + by_id = {s.context.span_id: s for s in spans} + exported = [s for s in spans if is_exported(s)] + orphans = [ + s.name + for s in exported + if s.parent + and s.parent.span_id in by_id + and not is_exported(by_id[s.parent.span_id]) + ] + assert orphans == [] + assert _spans._state.containers == {} + + async def test_parallel_tool_calls_group_per_tools_span( + self, exporter: InMemorySpanExporter, instrumented: None + ) -> None: + with patch.object( + _base.BuiltInGuardrailMiddlewareMixin, + "_evaluate_guardrail", + return_value=_FAILED, + ): + await self._agent(parallel_calls=2).ainvoke( + {"messages": [HumanMessage("a@b.com weather")]} + ) + spans = list(exporter.get_finished_spans()) + + self._assert_well_formed(spans) + assert len(_named(spans, "LLM input guardrail check")) == 2 + assert len(_named(spans, "LLM output guardrail check")) == 1 + assert len(_named(spans, "Tool input guardrail check")) == 2 + assert len(_named(spans, "Tool output guardrail check")) == 2 + for container in _named(spans, "LLM input guardrail check"): + assert _children(spans, container) == ["Log", "Log"] + + async def test_overlapping_checks_on_parallel_tool_calls_stay_in_their_container( + self, exporter: InMemorySpanExporter, instrumented: None + ) -> None: + def slow_check(*args: Any, **kwargs: Any) -> GuardrailValidationResult: + time.sleep(0.05) # long enough for the calls' checks to overlap + return _FAILED + + with patch.object( + _base.BuiltInGuardrailMiddlewareMixin, "_evaluate_guardrail", slow_check + ): + await self._agent(parallel_calls=3).ainvoke( + {"messages": [HumanMessage("a@b.com weather")]} + ) + spans = list(exporter.get_finished_spans()) + + # Each tool call runs in its own tools span, so each has its own container, + # and every check ends inside it. + containers = _named(spans, "Tool input guardrail check") + assert len(containers) == 3 + assert len({c.parent.span_id for c in containers if c.parent}) == 3 + for container in containers: + children = [ + s + for s in spans + if s.parent and s.parent.span_id == container.context.span_id + ] + assert children + assert all( + c.end_time is not None + and container.end_time is not None + and c.end_time <= container.end_time + for c in children + ) + + async def test_concurrent_runs_keep_their_own_containers( + self, exporter: InMemorySpanExporter, instrumented: None + ) -> None: + with patch.object( + _base.BuiltInGuardrailMiddlewareMixin, + "_evaluate_guardrail", + return_value=_FAILED, + ): + await asyncio.gather( + self._agent(parallel_calls=1).ainvoke( + {"messages": [HumanMessage("a@b.com")]} + ), + self._agent(parallel_calls=1).ainvoke( + {"messages": [HumanMessage("a@b.com")]} + ), + ) + spans = list(exporter.get_finished_spans()) + + self._assert_well_formed(spans) + containers = _named(spans, "LLM input guardrail check") + assert len(containers) == 4 + assert all(_children(spans, c) for c in containers) diff --git a/uv.lock b/uv.lock index 4267b7d4e..960bd9fe6 100644 --- a/uv.lock +++ b/uv.lock @@ -5067,7 +5067,7 @@ wheels = [ [[package]] name = "uipath-langchain" -version = "0.20.7" +version = "0.20.8" source = { editable = "." } dependencies = [ { name = "a2a-sdk" }, From 77bfb06d50915ba183916c7125f837974dc9ce91 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 11:02:46 +0200 Subject: [PATCH 02/11] fix(guardrails): keep checks running and stages separate when grouping goes wrong - A failure to create a stage container now runs the check ungrouped. - Creating a stage's container closes the other stage's container under the same parent. - Shutting down a trace manager also forgets it, so it isn't reused. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_spans.py | 55 ++++++++++++++----- tests/guardrails/middlewares/test_grouping.py | 52 ++++++++++++++++++ 2 files changed, 93 insertions(+), 14 deletions(-) diff --git a/src/uipath_langchain/guardrails/middlewares/_spans.py b/src/uipath_langchain/guardrails/middlewares/_spans.py index d5f8681aa..73028d38b 100644 --- a/src/uipath_langchain/guardrails/middlewares/_spans.py +++ b/src/uipath_langchain/guardrails/middlewares/_spans.py @@ -1,6 +1,7 @@ """Guardrail spans shaped like low-code agents': actions, rule evaluations and stage containers that group a stage's checks across separate middleware nodes.""" +import logging import threading import time import weakref @@ -26,6 +27,8 @@ GUARDRAIL_EVALUATION = "guardrailEvaluation" _CONTAINER_MARK = "uipath.guardrail_container" +logger = logging.getLogger(__name__) + def _new_span( name: str, @@ -189,7 +192,11 @@ def guardrail_stage( scope: GuardrailScope | None, stage: GuardrailExecutionStage | None ) -> Generator[None]: """Run one check inside its stage's shared container.""" - container = _shared_container(scope, stage) + try: + container = _shared_container(scope, stage) + except Exception: + logger.warning("Could not group a guardrail check", exc_info=True) + container = None if container is None: yield return @@ -225,9 +232,15 @@ def _shared_container( name, span_type = _STAGES[(scope, stage)] # type: ignore[index] key = (parent.span_id, span_type) + previous: list[tuple[Span, int]] = [] with _state.lock: container = _state.containers.get(key) if container is None: + # No sibling may have started between the stages, e.g. when a + # middleware answers a tool call without running the tool. + previous = _pop_containers( + lambda k: k[0] == parent.span_id and k[1] != span_type + ) container = _new_span( name, span_type, @@ -241,6 +254,7 @@ def _shared_container( }, ) _state.containers[key] = container + _end_containers(previous, end_time=getattr(container, "start_time", None)) return container @@ -281,6 +295,8 @@ def shutdown(self) -> None: owners = [m for m, closer in _state.closers.items() if closer is self] for manager in owners: del _state.closers[manager] + if any(manager is _state.trace_manager for manager in owners): + _state.trace_manager = None _state.enabled = bool(_state.closers) if not _state.enabled: self._close(lambda key: True, end_time=None) @@ -290,19 +306,30 @@ def _close( matches: Callable[[tuple[int, str]], bool], end_time: int | None ) -> None: with _state.lock: - done = [key for key in _state.containers if matches(key)] - spans = [_state.containers.pop(key) for key in done] - last_ends = [ - _state.last_check_end.pop(span.get_span_context().span_id, 0) - for span in spans - ] - for span, last_end in zip(spans, last_ends, strict=True): - status = getattr(span, "status", None) - if status is None or status.status_code is StatusCode.UNSET: - span.set_status(StatusCode.OK) - # Never before its last check: coarse clocks (Windows before Python - # 3.13) can stamp the next sibling's start a tick earlier. - span.end(end_time=max(end_time, last_end) if end_time else None) + done = _pop_containers(matches) + _end_containers(done, end_time) + + +def _pop_containers( + matches: Callable[[tuple[int, str]], bool], +) -> list[tuple[Span, int]]: + """Remove matching containers, with their last check's end. Hold the lock.""" + keys = [key for key in _state.containers if matches(key)] + spans = [_state.containers.pop(key) for key in keys] + return [ + (span, _state.last_check_end.pop(span.get_span_context().span_id, 0)) + for span in spans + ] + + +def _end_containers(containers: list[tuple[Span, int]], end_time: int | None) -> None: + for span, last_end in containers: + status = getattr(span, "status", None) + if status is None or status.status_code is StatusCode.UNSET: + span.set_status(StatusCode.OK) + # Never before its last check: coarse clocks (Windows before Python + # 3.13) can stamp the next sibling's start a tick earlier. + span.end(end_time=max(end_time, last_end) if end_time else None) def is_exported(span: ReadableSpan) -> bool: diff --git a/tests/guardrails/middlewares/test_grouping.py b/tests/guardrails/middlewares/test_grouping.py index a3591aad6..e2136a437 100644 --- a/tests/guardrails/middlewares/test_grouping.py +++ b/tests/guardrails/middlewares/test_grouping.py @@ -292,6 +292,22 @@ async def test_a_block_marks_the_container_as_failed(self, graph: _Graph) -> Non [container] = _named(spans, "LLM input guardrail check") assert container.status.status_code == StatusCode.ERROR + async def test_a_grouping_failure_still_runs_the_check(self, graph: _Graph) -> None: + pii = _pii(action=BlockAction()) + hook = _hook(pii, "_before_model") + + with ( + patch.object(pii, "_evaluate_guardrail", return_value=_FAILED), + patch.object(_spans, "_shared_container", side_effect=RuntimeError), + pytest.raises(AgentRuntimeError), + graph.node(f"{hook.name}.before_model"), + ): + await hook.abefore_model(_STATE, MagicMock()) + spans = graph.finish() + + assert _named(spans, "LLM input guardrail check") == [] + assert len(_named(spans, "Block")) == 1 + async def test_a_stage_with_nothing_to_check_leaves_no_container( self, graph: _Graph ) -> None: @@ -347,6 +363,28 @@ async def test_output_checks_close_when_the_tools_node_ends( assert container.start_time >= tool_span.end_time assert container.end_time == tools.end_time + async def test_input_checks_close_when_the_output_stage_starts( + self, graph: _Graph + ) -> None: + [pre] = list(_rule(GuardrailExecutionStage.PRE)) + [post] = list(_rule(GuardrailExecutionStage.POST)) + with graph.node("tools"): + + async def answer_without_the_tool(request: ToolCallRequest) -> ToolMessage: + return ToolMessage(content="cached", tool_call_id="tc1") + + async def inner(request: ToolCallRequest) -> ToolMessage: + return await post.awrap_tool_call(request, answer_without_the_tool) + + await pre.awrap_tool_call(_tool_request(), inner) + spans = graph.finish() + + [pre_container] = _named(spans, "Tool input guardrail check") + [post_container] = _named(spans, "Tool output guardrail check") + assert pre_container.end_time is not None + assert post_container.start_time is not None + assert pre_container.end_time <= post_container.start_time + class TestEnabling: async def test_nothing_is_grouped_without_a_closer( @@ -400,6 +438,20 @@ def test_the_closer_comes_back_after_its_trace_manager_shuts_down( assert manager.add_span_processor.call_count == 2 assert _spans._state.enabled + def test_a_shut_down_trace_manager_is_not_reused( + self, exporter: InMemorySpanExporter + ) -> None: + manager = MagicMock() + enable_guardrail_grouping(manager, lambda: None) + _pii() + [closer] = [call.args[0] for call in manager.add_span_processor.call_args_list] + + closer.shutdown() + _pii() # a middleware built before the next runtime factory + + manager.add_span_processor.assert_called_once() + assert not _spans._state.enabled + def test_tool_only_guardrails_turn_grouping_on( self, exporter: InMemorySpanExporter ) -> None: From 1dcb472a6335fd57d217bc23b47099ff12ed6fe7 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 11:33:58 +0200 Subject: [PATCH 03/11] fix(guardrails): avoid a lock re-entry, sampled-out leaks and lost containers in grouping - The closer skips a starting container through a context flag, not only its attribute, so it never re-enters the lock. - Grouping is skipped under a non-recording (sampled-out) span. - A new stage's container is created before the previous one is removed. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_spans.py | 38 ++++++---- tests/guardrails/middlewares/test_grouping.py | 70 ++++++++++++++++++- 2 files changed, 92 insertions(+), 16 deletions(-) diff --git a/src/uipath_langchain/guardrails/middlewares/_spans.py b/src/uipath_langchain/guardrails/middlewares/_spans.py index 73028d38b..d882d4d98 100644 --- a/src/uipath_langchain/guardrails/middlewares/_spans.py +++ b/src/uipath_langchain/guardrails/middlewares/_spans.py @@ -171,6 +171,10 @@ def __init__(self) -> None: _current_container: ContextVar[Span | None] = ContextVar( "uipath_guardrail_container", default=None ) +# Set while a container starts, so the closer skips it without taking the lock. +_starting_container: ContextVar[bool] = ContextVar( + "uipath_guardrail_container_starting", default=False +) def register_guardrail_node( @@ -221,8 +225,8 @@ def _shared_container( if not _state.enabled or (scope, stage) not in _STAGES: return None node = UiPathSpanUtils.get_external_current_span() - if node is None: - return None + if node is None or not node.is_recording(): + return None # a sampled-out node never reports its end if scope == GuardrailScope.TOOL: parent: SpanContext | None = node.get_span_context() else: @@ -236,23 +240,27 @@ def _shared_container( with _state.lock: container = _state.containers.get(key) if container is None: + token = _starting_container.set(True) + try: + container = _new_span( + name, + span_type, + context=trace.set_span_in_context(NonRecordingSpan(parent)), + **{ + _CONTAINER_MARK: True, + # Its parent is non-recording, so this isn't inherited. + "execution.id": (getattr(node, "attributes", None) or {}).get( + "execution.id" + ), + }, + ) + finally: + _starting_container.reset(token) # No sibling may have started between the stages, e.g. when a # middleware answers a tool call without running the tool. previous = _pop_containers( lambda k: k[0] == parent.span_id and k[1] != span_type ) - container = _new_span( - name, - span_type, - context=trace.set_span_in_context(NonRecordingSpan(parent)), - **{ - _CONTAINER_MARK: True, - # Its parent is non-recording, so this isn't inherited. - "execution.id": (getattr(node, "attributes", None) or {}).get( - "execution.id" - ), - }, - ) _state.containers[key] = container _end_containers(previous, end_time=getattr(container, "start_time", None)) return container @@ -275,6 +283,8 @@ class GuardrailStageCloser(SpanProcessor): def on_start( self, span: Span, parent_context: otel_context.Context | None = None ) -> None: + if _starting_container.get(): + return attributes = getattr(span, "attributes", None) or {} parent = getattr(span, "parent", None) if attributes.get(_CONTAINER_MARK) or parent is None: diff --git a/tests/guardrails/middlewares/test_grouping.py b/tests/guardrails/middlewares/test_grouping.py index e2136a437..749937f71 100644 --- a/tests/guardrails/middlewares/test_grouping.py +++ b/tests/guardrails/middlewares/test_grouping.py @@ -1,6 +1,7 @@ """Separate guardrail middlewares share one container span per stage.""" import asyncio +import threading import time from collections.abc import Iterator from contextlib import contextmanager @@ -19,12 +20,18 @@ get_current_span, ) from opentelemetry import trace -from opentelemetry.sdk.trace import ReadableSpan, TracerProvider +from opentelemetry.sdk.trace import ReadableSpan, SpanLimits, TracerProvider from opentelemetry.sdk.trace.export import SimpleSpanProcessor from opentelemetry.sdk.trace.export.in_memory_span_exporter import ( InMemorySpanExporter, ) -from opentelemetry.trace import Span, StatusCode +from opentelemetry.trace import ( + NonRecordingSpan, + Span, + SpanContext, + StatusCode, + TraceFlags, +) from uipath.core.guardrails import ( GuardrailScope, GuardrailValidationResult, @@ -385,6 +392,25 @@ async def inner(request: ToolCallRequest) -> ToolMessage: assert post_container.start_time is not None assert pre_container.end_time <= post_container.start_time + async def test_a_failed_new_stage_keeps_the_previous_container_closable( + self, graph: _Graph + ) -> None: + _pii() # a guardrail in use turns grouping on + with graph.node("tools") as tools: + graph.current = tools + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): + pass + with ( + patch.object(_spans, "_new_span", side_effect=RuntimeError), + guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.POST), + ): + pass + spans = graph.finish() + + [container] = _named(spans, "Tool input guardrail check") + assert container.end_time == _named(spans, "tools")[0].end_time + assert _spans._state.containers == {} + class TestEnabling: async def test_nothing_is_grouped_without_a_closer( @@ -452,6 +478,46 @@ def test_a_shut_down_trace_manager_is_not_reused( manager.add_span_processor.assert_called_once() assert not _spans._state.enabled + async def test_nothing_is_grouped_under_a_sampled_out_node( + self, exporter: InMemorySpanExporter + ) -> None: + node = NonRecordingSpan( + SpanContext( + trace_id=1, span_id=2, is_remote=False, trace_flags=TraceFlags(0) + ) + ) + enable_guardrail_grouping(exporter.provider, lambda: node) # type: ignore[attr-defined] + _pii() + + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): + pass + + assert _spans._state.enabled + assert _spans._state.containers == {} + + def test_a_container_without_its_mark_does_not_deadlock( + self, exporter: InMemorySpanExporter, monkeypatch: pytest.MonkeyPatch + ) -> None: + # No attributes kept, so the container loses the mark the closer checks. + provider = TracerProvider(span_limits=SpanLimits(max_span_attributes=0)) + monkeypatch.setattr(trace, "get_tracer", provider.get_tracer) + node = provider.get_tracer(_OPENINFERENCE).start_span("tools") + enable_guardrail_grouping(provider, lambda: node) + _pii() + + def check() -> None: + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): + pass + + worker = threading.Thread(target=check, daemon=True) + worker.start() + worker.join(timeout=5) + + assert not worker.is_alive() + assert len(_spans._state.containers) == 1 + node.end() + provider.shutdown() + def test_tool_only_guardrails_turn_grouping_on( self, exporter: InMemorySpanExporter ) -> None: From 88628de65abcc7fd8d0835b05c890fd6fdc8f180 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 17:31:33 +0200 Subject: [PATCH 04/11] fix(guardrails): skip unsampled parents and stale end times in grouping Don't group under an unsampled parent, don't record a check's end on a container that already closed, and let the closer return without the lock while no container is open. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_spans.py | 11 ++-- tests/guardrails/middlewares/test_grouping.py | 50 +++++++++++++++++++ 2 files changed, 58 insertions(+), 3 deletions(-) diff --git a/src/uipath_langchain/guardrails/middlewares/_spans.py b/src/uipath_langchain/guardrails/middlewares/_spans.py index d882d4d98..81dd944aa 100644 --- a/src/uipath_langchain/guardrails/middlewares/_spans.py +++ b/src/uipath_langchain/guardrails/middlewares/_spans.py @@ -215,7 +215,10 @@ def guardrail_stage( finally: _current_container.reset(token) with _state.lock: - _state.last_check_end[container.get_span_context().span_id] = time.time_ns() + # A container closed meanwhile was already popped; don't re-add it. + if any(open_ is container for open_ in _state.containers.values()): + span_id = container.get_span_context().span_id + _state.last_check_end[span_id] = time.time_ns() def _shared_container( @@ -231,7 +234,7 @@ def _shared_container( parent: SpanContext | None = node.get_span_context() else: parent = getattr(node, "parent", None) - if parent is None or not parent.is_valid: + if parent is None or not parent.is_valid or not parent.trace_flags.sampled: return None # nothing would ever close it name, span_type = _STAGES[(scope, stage)] # type: ignore[index] @@ -283,7 +286,7 @@ class GuardrailStageCloser(SpanProcessor): def on_start( self, span: Span, parent_context: otel_context.Context | None = None ) -> None: - if _starting_container.get(): + if _starting_container.get() or not _state.containers: return attributes = getattr(span, "attributes", None) or {} parent = getattr(span, "parent", None) @@ -296,6 +299,8 @@ def on_start( ) def on_end(self, span: ReadableSpan) -> None: + if not _state.containers: + return span_id = span.context.span_id if span.context else None self._close(lambda key: key[0] == span_id, end_time=span.end_time) diff --git a/tests/guardrails/middlewares/test_grouping.py b/tests/guardrails/middlewares/test_grouping.py index 749937f71..d83a6d2c2 100644 --- a/tests/guardrails/middlewares/test_grouping.py +++ b/tests/guardrails/middlewares/test_grouping.py @@ -25,6 +25,7 @@ from opentelemetry.sdk.trace.export.in_memory_span_exporter import ( InMemorySpanExporter, ) +from opentelemetry.sdk.trace.sampling import ALWAYS_ON from opentelemetry.trace import ( NonRecordingSpan, Span, @@ -370,6 +371,18 @@ async def test_output_checks_close_when_the_tools_node_ends( assert container.start_time >= tool_span.end_time assert container.end_time == tools.end_time + def test_a_container_closed_during_a_check_keeps_no_end_time( + self, graph: _Graph + ) -> None: + _pii() + with graph.node("tools") as tools: + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): + with graph.node("get_weather", parent=tools): # closes it + pass + + assert _spans._state.containers == {} + assert _spans._state.last_check_end == {} + async def test_input_checks_close_when_the_output_stage_starts( self, graph: _Graph ) -> None: @@ -495,6 +508,43 @@ async def test_nothing_is_grouped_under_a_sampled_out_node( assert _spans._state.enabled assert _spans._state.containers == {} + def test_nothing_is_grouped_under_a_sampled_out_parent( + self, exporter: InMemorySpanExporter + ) -> None: + # A sampler that keeps the node although its parent was dropped. + provider = TracerProvider(sampler=ALWAYS_ON) + parent = NonRecordingSpan( + SpanContext( + trace_id=1, span_id=2, is_remote=False, trace_flags=TraceFlags(0) + ) + ) + node = provider.get_tracer(_OPENINFERENCE).start_span( + "pii_detection_before_model", context=trace.set_span_in_context(parent) + ) + enable_guardrail_grouping(exporter.provider, lambda: node) # type: ignore[attr-defined] + _pii() + + with guardrail_stage(GuardrailScope.LLM, GuardrailExecutionStage.PRE): + pass + + assert node.is_recording() + assert _spans._state.containers == {} + node.end() + provider.shutdown() + + def test_the_closer_skips_the_lock_with_nothing_open( + self, graph: _Graph, monkeypatch: pytest.MonkeyPatch + ) -> None: + lock = MagicMock() + monkeypatch.setattr(_spans._state, "lock", lock) + closer = _spans.GuardrailStageCloser() + + with graph.node("model") as span: + closer.on_start(span) + closer.on_end(span) # type: ignore[arg-type] + + lock.__enter__.assert_not_called() + def test_a_container_without_its_mark_does_not_deadlock( self, exporter: InMemorySpanExporter, monkeypatch: pytest.MonkeyPatch ) -> None: From aa71b6cfeede08392b5e3f02e4e87084c46aae8c Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 17:56:28 +0200 Subject: [PATCH 05/11] fix(guardrails): keep guardrail nodes visible when they can't be grouped Grouping and node hiding now share one parent check, so a node whose parent can't hold a container stays exported and its checks keep their parent. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_spans.py | 13 ++++++++--- tests/guardrails/middlewares/test_grouping.py | 22 +++++++++++++++++++ 2 files changed, 32 insertions(+), 3 deletions(-) diff --git a/src/uipath_langchain/guardrails/middlewares/_spans.py b/src/uipath_langchain/guardrails/middlewares/_spans.py index 81dd944aa..421f1d940 100644 --- a/src/uipath_langchain/guardrails/middlewares/_spans.py +++ b/src/uipath_langchain/guardrails/middlewares/_spans.py @@ -8,7 +8,7 @@ from collections.abc import Callable, Generator from contextlib import contextmanager from contextvars import ContextVar -from typing import Any +from typing import Any, TypeGuard from langgraph.errors import GraphBubbleUp from opentelemetry import context as otel_context @@ -234,8 +234,8 @@ def _shared_container( parent: SpanContext | None = node.get_span_context() else: parent = getattr(node, "parent", None) - if parent is None or not parent.is_valid or not parent.trace_flags.sampled: - return None # nothing would ever close it + if not _can_group_under(parent): + return None name, span_type = _STAGES[(scope, stage)] # type: ignore[index] key = (parent.span_id, span_type) @@ -269,6 +269,11 @@ def _shared_container( return container +def _can_group_under(parent: SpanContext | None) -> TypeGuard[SpanContext]: + """Whether a container under ``parent`` would ever be closed.""" + return parent is not None and parent.is_valid and parent.trace_flags.sampled + + def guardrail_aware( provider: Callable[[], Span | None], ) -> Callable[[], Span | None]: @@ -351,6 +356,8 @@ def is_exported(span: ReadableSpan) -> bool: """Span filter hiding guardrail node spans (by name: spans upload on start).""" if not _state.enabled or span.name not in _state.guardrail_nodes: return True + if not _can_group_under(span.parent): + return True # its checks stay under it, ungrouped scope = getattr(span, "instrumentation_scope", None) return "openinference" not in (getattr(scope, "name", "") or "") diff --git a/tests/guardrails/middlewares/test_grouping.py b/tests/guardrails/middlewares/test_grouping.py index d83a6d2c2..336aa29fc 100644 --- a/tests/guardrails/middlewares/test_grouping.py +++ b/tests/guardrails/middlewares/test_grouping.py @@ -605,6 +605,28 @@ async def test_only_guardrail_node_spans_are_hidden(self, graph: _Graph) -> None assert [s.instrumentation_scope.name for s in hidden] == [_OPENINFERENCE] # type: ignore[union-attr] assert is_exported(_named(spans, "LLM input guardrail check")[0]) + def test_a_node_that_cannot_be_grouped_stays_visible(self, graph: _Graph) -> None: + hook = _hook(_pii(), "_before_model") + node_name = f"{hook.name}.before_model" + # A sampler that keeps the nodes although one's parent was dropped. + provider = TracerProvider(sampler=ALWAYS_ON) + tracer = provider.get_tracer(_OPENINFERENCE) + unsampled = NonRecordingSpan( + SpanContext( + trace_id=1, span_id=2, is_remote=False, trace_flags=TraceFlags(0) + ) + ) + under_unsampled = tracer.start_span( + node_name, context=trace.set_span_in_context(unsampled) + ) + without_parent = tracer.start_span(node_name) + + assert is_exported(under_unsampled) # type: ignore[arg-type] + assert is_exported(without_parent) # type: ignore[arg-type] + under_unsampled.end() + without_parent.end() + provider.shutdown() + class _ToolCallingModel(GenericFakeChatModel): def bind_tools(self, *args: Any, **kwargs: Any) -> "_ToolCallingModel": From 1fa2fc39899e910e8db44a7c42da2760a6a78ffc Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 18:17:35 +0200 Subject: [PATCH 06/11] refactor(guardrails): keep guardrail span types and names in _span_name.py SpanType and SpanName replace the string literals in the stage table and the two span type constants, with the same member names as low-code. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_span_name.py | 27 +++++++++++++ .../guardrails/middlewares/_spans.py | 39 +++++++++++++------ 2 files changed, 54 insertions(+), 12 deletions(-) create mode 100644 src/uipath_langchain/guardrails/middlewares/_span_name.py diff --git a/src/uipath_langchain/guardrails/middlewares/_span_name.py b/src/uipath_langchain/guardrails/middlewares/_span_name.py new file mode 100644 index 000000000..b96c0fe3b --- /dev/null +++ b/src/uipath_langchain/guardrails/middlewares/_span_name.py @@ -0,0 +1,27 @@ +"""Guardrail span types and display names, the same as low-code agents use.""" + + +class SpanType: + """Span types of guardrail spans.""" + + GUARDRAIL_ACTION = "guardrailAction" + GUARDRAIL_EVALUATION = "guardrailEvaluation" + + # Stage containers + AGENT_PRE_GUARDRAILS = "agentPreGuardrails" + AGENT_POST_GUARDRAILS = "agentPostGuardrails" + LLM_PRE_GUARDRAILS = "llmPreGuardrails" + LLM_POST_GUARDRAILS = "llmPostGuardrails" + TOOL_PRE_GUARDRAILS = "toolPreGuardrails" + TOOL_POST_GUARDRAILS = "toolPostGuardrails" + + +class SpanName: + """Display names of the stage containers.""" + + AGENT_PRE_GUARDRAILS = "Agent input guardrail check" + AGENT_POST_GUARDRAILS = "Agent output guardrail check" + LLM_PRE_GUARDRAILS = "LLM input guardrail check" + LLM_POST_GUARDRAILS = "LLM output guardrail check" + TOOL_PRE_GUARDRAILS = "Tool input guardrail check" + TOOL_POST_GUARDRAILS = "Tool output guardrail check" diff --git a/src/uipath_langchain/guardrails/middlewares/_spans.py b/src/uipath_langchain/guardrails/middlewares/_spans.py index 421f1d940..e9fc1b929 100644 --- a/src/uipath_langchain/guardrails/middlewares/_spans.py +++ b/src/uipath_langchain/guardrails/middlewares/_spans.py @@ -23,8 +23,8 @@ ) from uipath.platform.guardrails.decorators._exceptions import GuardrailBlockException -GUARDRAIL_ACTION = "guardrailAction" -GUARDRAIL_EVALUATION = "guardrailEvaluation" +from ._span_name import SpanName, SpanType + _CONTAINER_MARK = "uipath.guardrail_container" logger = logging.getLogger(__name__) @@ -95,7 +95,7 @@ def guardrail_action_span( severity = getattr(action, "severity_level", None) span = _new_span( action_name(action), - GUARDRAIL_ACTION, + SpanType.GUARDRAIL_ACTION, guardrailName=guardrail_name, action=action_name(action), guardrailSpanId=evaluation_span_id or result.span_id, @@ -117,7 +117,7 @@ def guardrail_evaluation_span( """Record a rule check that runs in the agent.""" span = _new_span( guardrail_name, - GUARDRAIL_EVALUATION, + SpanType.GUARDRAIL_EVALUATION, guardrailName=guardrail_name, guardrailDescription=description, guardrailType="custom", @@ -136,17 +136,32 @@ def set_validation_result(span: Span, result: GuardrailValidationResult) -> None _PRE = GuardrailExecutionStage.PRE _POST = GuardrailExecutionStage.POST -# (scope, stage) -> (container name, span type), as in low-code agents. +# (scope, stage) -> (container name, span type) _STAGES: dict[tuple[GuardrailScope, GuardrailExecutionStage], tuple[str, str]] = { - (GuardrailScope.AGENT, _PRE): ("Agent input guardrail check", "agentPreGuardrails"), + (GuardrailScope.AGENT, _PRE): ( + SpanName.AGENT_PRE_GUARDRAILS, + SpanType.AGENT_PRE_GUARDRAILS, + ), (GuardrailScope.AGENT, _POST): ( - "Agent output guardrail check", - "agentPostGuardrails", + SpanName.AGENT_POST_GUARDRAILS, + SpanType.AGENT_POST_GUARDRAILS, + ), + (GuardrailScope.LLM, _PRE): ( + SpanName.LLM_PRE_GUARDRAILS, + SpanType.LLM_PRE_GUARDRAILS, + ), + (GuardrailScope.LLM, _POST): ( + SpanName.LLM_POST_GUARDRAILS, + SpanType.LLM_POST_GUARDRAILS, + ), + (GuardrailScope.TOOL, _PRE): ( + SpanName.TOOL_PRE_GUARDRAILS, + SpanType.TOOL_PRE_GUARDRAILS, + ), + (GuardrailScope.TOOL, _POST): ( + SpanName.TOOL_POST_GUARDRAILS, + SpanType.TOOL_POST_GUARDRAILS, ), - (GuardrailScope.LLM, _PRE): ("LLM input guardrail check", "llmPreGuardrails"), - (GuardrailScope.LLM, _POST): ("LLM output guardrail check", "llmPostGuardrails"), - (GuardrailScope.TOOL, _PRE): ("Tool input guardrail check", "toolPreGuardrails"), - (GuardrailScope.TOOL, _POST): ("Tool output guardrail check", "toolPostGuardrails"), } From c085ee1f445bfea32f538e62abc0143f912b5d54 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 18:26:35 +0200 Subject: [PATCH 07/11] refactor(guardrails): move stage grouping out of _spans.py into _grouping.py _spans.py keeps the spans of a single check. _grouping.py holds the stage containers, with named container keys and stages, one dict of open containers (each with its last check's end) instead of two, and sections for setup, running a check, closing and the export filter. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_base.py | 4 +- .../guardrails/middlewares/_grouping.py | 325 ++++++++++++++++++ .../guardrails/middlewares/_span_name.py | 2 +- .../guardrails/middlewares/_spans.py | 306 +---------------- .../guardrails/middlewares/deterministic.py | 3 +- src/uipath_langchain/runtime/factory.py | 2 +- .../middlewares/test_action_span.py | 4 +- tests/guardrails/middlewares/test_grouping.py | 53 +-- 8 files changed, 372 insertions(+), 327 deletions(-) create mode 100644 src/uipath_langchain/guardrails/middlewares/_grouping.py diff --git a/src/uipath_langchain/guardrails/middlewares/_base.py b/src/uipath_langchain/guardrails/middlewares/_base.py index b65c970fb..03579d6de 100644 --- a/src/uipath_langchain/guardrails/middlewares/_base.py +++ b/src/uipath_langchain/guardrails/middlewares/_base.py @@ -55,12 +55,12 @@ registry_references, tool_result_references, ) -from ._spans import ( - guardrail_action_span, +from ._grouping import ( guardrail_stage, guardrails_in_use, register_guardrail_node, ) +from ._spans import guardrail_action_span from ._utils import ( convert_block_exception, create_modified_tool_request, diff --git a/src/uipath_langchain/guardrails/middlewares/_grouping.py b/src/uipath_langchain/guardrails/middlewares/_grouping.py new file mode 100644 index 000000000..eee6b9469 --- /dev/null +++ b/src/uipath_langchain/guardrails/middlewares/_grouping.py @@ -0,0 +1,325 @@ +"""Group a stage's guardrail checks into one container span. + +Each guardrail hook runs as its own LangGraph node, so the checks of one stage +(e.g. LLM input) are spread over several nodes. The first check of a stage +starts a container next to those nodes (inside ``tools`` for tool checks); +later checks reuse it. ``GuardrailStageCloser`` ends it when something else +starts beside it or its parent ends, and ``is_exported`` hides the now-empty +guardrail node spans. +""" + +import logging +import threading +import time +import weakref +from collections.abc import Callable, Generator +from contextlib import contextmanager +from contextvars import ContextVar +from dataclasses import dataclass +from typing import Any, NamedTuple, TypeGuard + +from langgraph.errors import GraphBubbleUp +from opentelemetry import context as otel_context +from opentelemetry import trace +from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor +from opentelemetry.trace import NonRecordingSpan, Span, SpanContext, StatusCode +from uipath.core.guardrails import GuardrailScope +from uipath.core.tracing.span_utils import UiPathSpanUtils +from uipath.platform.guardrails.decorators import GuardrailExecutionStage + +from ._span_name import SpanName, SpanType +from ._spans import error_text, new_span + +logger = logging.getLogger(__name__) + +_CONTAINER_MARK = "uipath.guardrail_container" + + +class _Stage(NamedTuple): + name: str + span_type: str + + +_PRE = GuardrailExecutionStage.PRE +_POST = GuardrailExecutionStage.POST + +_STAGES: dict[tuple[GuardrailScope, GuardrailExecutionStage], _Stage] = { + (GuardrailScope.AGENT, _PRE): _Stage( + SpanName.AGENT_PRE_GUARDRAILS, SpanType.AGENT_PRE_GUARDRAILS + ), + (GuardrailScope.AGENT, _POST): _Stage( + SpanName.AGENT_POST_GUARDRAILS, SpanType.AGENT_POST_GUARDRAILS + ), + (GuardrailScope.LLM, _PRE): _Stage( + SpanName.LLM_PRE_GUARDRAILS, SpanType.LLM_PRE_GUARDRAILS + ), + (GuardrailScope.LLM, _POST): _Stage( + SpanName.LLM_POST_GUARDRAILS, SpanType.LLM_POST_GUARDRAILS + ), + (GuardrailScope.TOOL, _PRE): _Stage( + SpanName.TOOL_PRE_GUARDRAILS, SpanType.TOOL_PRE_GUARDRAILS + ), + (GuardrailScope.TOOL, _POST): _Stage( + SpanName.TOOL_POST_GUARDRAILS, SpanType.TOOL_POST_GUARDRAILS + ), +} + + +class _ContainerKey(NamedTuple): + parent_id: int + span_type: str + + +@dataclass +class _Container: + span: Span + last_check_end: int = 0 # ns; it never ends before its last check + + +class _GroupingState: + """Process-wide state. Grouping stays off until a closer is registered.""" + + def __init__(self) -> None: + self.enabled = False + self.in_use = False # a guardrail middleware was built + self.trace_manager: Any = None # offered by the runtime factory + self.closers: weakref.WeakKeyDictionary[Any, GuardrailStageCloser] = ( + weakref.WeakKeyDictionary() + ) # trace manager -> its closer + self.guardrail_nodes: dict[str, str] = {} # node name -> stage span type + self.containers: dict[_ContainerKey, _Container] = {} # the open ones + self.lock = threading.Lock() + + +_state = _GroupingState() + +_current_container: ContextVar[Span | None] = ContextVar( + "uipath_guardrail_container", default=None +) +# Set while a container starts, so the closer skips it without taking the lock. +_starting_container: ContextVar[bool] = ContextVar( + "uipath_guardrail_container_starting", default=False +) + + +# --- Setup ------------------------------------------------------------------- + + +def enable_guardrail_grouping( + trace_manager: Any, current_span_provider: Callable[[], Span | None] +) -> None: + """Register the span provider and offer the trace manager for grouping. + + Grouping turns on once a guardrail middleware is also in use. + """ + UiPathSpanUtils.register_current_span_provider( + guardrail_aware(current_span_provider) + ) + _state.trace_manager = trace_manager + _activate() + + +def guardrails_in_use() -> None: + """Called by guardrail middlewares when built; grouping needs one in use.""" + _state.in_use = True + _activate() + + +def register_guardrail_node( + node_name: str, scope: GuardrailScope, stage: GuardrailExecutionStage +) -> None: + """Record which stage a guardrail hook's LangGraph node belongs to.""" + _state.guardrail_nodes[node_name] = _STAGES[(scope, stage)].span_type + guardrails_in_use() + + +def _activate() -> None: + """Attach a closer to the offered trace manager if guardrails are in use.""" + with _state.lock: + manager = _state.trace_manager + if manager is None or not _state.in_use: + return + if manager not in _state.closers: + closer = GuardrailStageCloser() + manager.add_span_processor(closer) + _state.closers[manager] = closer + _state.enabled = True + + +# --- Running a check --------------------------------------------------------- + + +@contextmanager +def guardrail_stage( + scope: GuardrailScope | None, stage: GuardrailExecutionStage | None +) -> Generator[None]: + """Run one check inside its stage's shared container.""" + try: + container = _shared_container(scope, stage) + except Exception: + logger.warning("Could not group a guardrail check", exc_info=True) + container = None + if container is None: + yield + return + token = _current_container.set(container.span) + try: + yield + except GraphBubbleUp: + raise + except Exception as exc: + container.span.set_status(StatusCode.ERROR, error_text(exc)) + raise + finally: + _current_container.reset(token) + container.last_check_end = time.time_ns() + + +def guardrail_aware( + provider: Callable[[], Span | None], +) -> Callable[[], Span | None]: + """Report the running check's container as the current span.""" + + def current_span() -> Span | None: + return _current_container.get() or provider() + + return current_span + + +def _shared_container( + scope: GuardrailScope | None, stage: GuardrailExecutionStage | None +) -> _Container | None: + """Get the stage's open container, or start one.""" + if not _state.enabled or (scope, stage) not in _STAGES: + return None + node = UiPathSpanUtils.get_external_current_span() + if node is None or not node.is_recording(): + return None # a sampled-out node never reports its end + parent = _container_parent(node, scope) + if not _can_group_under(parent): + return None + + stage_spans = _STAGES[(scope, stage)] # type: ignore[index] + key = _ContainerKey(parent.span_id, stage_spans.span_type) + with _state.lock: + container = _state.containers.get(key) + if container is not None: + return container + container = _Container(_start_container(stage_spans, parent, node)) + # The other stage under this parent is over, even if no sibling + # started in between (a middleware that answers a tool call itself). + other_stage = _pop_containers( + lambda k: k.parent_id == key.parent_id and k.span_type != key.span_type + ) + _state.containers[key] = container + _end_containers(other_stage, end_time=getattr(container.span, "start_time", None)) + return container + + +def _container_parent(node: Span, scope: GuardrailScope | None) -> SpanContext | None: + """Tool checks go inside the ``tools`` node; others beside their own node.""" + if scope == GuardrailScope.TOOL: + return node.get_span_context() + return getattr(node, "parent", None) + + +def _can_group_under(parent: SpanContext | None) -> TypeGuard[SpanContext]: + """Whether a container under ``parent`` would ever be closed.""" + return parent is not None and parent.is_valid and parent.trace_flags.sampled + + +def _start_container(stage: _Stage, parent: SpanContext, node: Span) -> Span: + token = _starting_container.set(True) + try: + return new_span( + stage.name, + stage.span_type, + context=trace.set_span_in_context(NonRecordingSpan(parent)), + **{ + _CONTAINER_MARK: True, + # Its parent is non-recording, so this isn't inherited. + "execution.id": (getattr(node, "attributes", None) or {}).get( + "execution.id" + ), + }, + ) + finally: + _starting_container.reset(token) + + +# --- Closing containers ------------------------------------------------------ + + +class GuardrailStageCloser(SpanProcessor): + """End a container when a non-guardrail sibling starts or its parent ends.""" + + def on_start( + self, span: Span, parent_context: otel_context.Context | None = None + ) -> None: + if _starting_container.get() or not _state.containers: + return + attributes = getattr(span, "attributes", None) or {} + parent = getattr(span, "parent", None) + if attributes.get(_CONTAINER_MARK) or parent is None: + return + # A guardrail node of the same stage joins the container; anything + # else starting beside it ends the stage. + same_stage = _state.guardrail_nodes.get(getattr(span, "name", "")) + _close( + lambda key: key.parent_id == parent.span_id and key.span_type != same_stage, + end_time=getattr(span, "start_time", None), + ) + + def on_end(self, span: ReadableSpan) -> None: + if not _state.containers: + return + span_id = span.context.span_id if span.context else None + _close(lambda key: key.parent_id == span_id, end_time=span.end_time) + + def shutdown(self) -> None: + """Called when its trace manager shuts down: unregister, end what's open.""" + with _state.lock: + owners = [m for m, closer in _state.closers.items() if closer is self] + for manager in owners: + del _state.closers[manager] + if any(manager is _state.trace_manager for manager in owners): + _state.trace_manager = None + _state.enabled = bool(_state.closers) + if not _state.enabled: + _close(lambda key: True, end_time=None) + + +def _close(matches: Callable[[_ContainerKey], bool], end_time: int | None) -> None: + with _state.lock: + done = _pop_containers(matches) + _end_containers(done, end_time) + + +def _pop_containers(matches: Callable[[_ContainerKey], bool]) -> list[_Container]: + """Remove the matching open containers. Call with the lock held.""" + keys = [key for key in _state.containers if matches(key)] + return [_state.containers.pop(key) for key in keys] + + +def _end_containers(containers: list[_Container], end_time: int | None) -> None: + for container in containers: + span = container.span + status = getattr(span, "status", None) + if status is None or status.status_code is StatusCode.UNSET: + span.set_status(StatusCode.OK) + # Never before its last check: coarse clocks (Windows before Python + # 3.13) can stamp the next sibling's start a tick earlier. + span.end(end_time=max(end_time, container.last_check_end) if end_time else None) + + +# --- Export filter ----------------------------------------------------------- + + +def is_exported(span: ReadableSpan) -> bool: + """Span filter hiding guardrail node spans (by name: spans upload on start).""" + if not _state.enabled or span.name not in _state.guardrail_nodes: + return True + if not _can_group_under(span.parent): + return True # its checks stay under it, ungrouped + scope = getattr(span, "instrumentation_scope", None) + return "openinference" not in (getattr(scope, "name", "") or "") diff --git a/src/uipath_langchain/guardrails/middlewares/_span_name.py b/src/uipath_langchain/guardrails/middlewares/_span_name.py index b96c0fe3b..b8c1c0af4 100644 --- a/src/uipath_langchain/guardrails/middlewares/_span_name.py +++ b/src/uipath_langchain/guardrails/middlewares/_span_name.py @@ -1,4 +1,4 @@ -"""Guardrail span types and display names, the same as low-code agents use.""" +"""Guardrail span types and display names.""" class SpanType: diff --git a/src/uipath_langchain/guardrails/middlewares/_spans.py b/src/uipath_langchain/guardrails/middlewares/_spans.py index e9fc1b929..7cf0626f1 100644 --- a/src/uipath_langchain/guardrails/middlewares/_spans.py +++ b/src/uipath_langchain/guardrails/middlewares/_spans.py @@ -1,36 +1,25 @@ -"""Guardrail spans shaped like low-code agents': actions, rule evaluations and -stage containers that group a stage's checks across separate middleware nodes.""" +"""Spans for one guardrail check: the rule evaluation and the action taken on a +violation. ``_grouping`` puts them in their stage's container.""" -import logging -import threading -import time -import weakref -from collections.abc import Callable, Generator +from collections.abc import Generator from contextlib import contextmanager -from contextvars import ContextVar -from typing import Any, TypeGuard +from typing import Any from langgraph.errors import GraphBubbleUp from opentelemetry import context as otel_context from opentelemetry import trace -from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor -from opentelemetry.trace import NonRecordingSpan, Span, SpanContext, StatusCode -from uipath.core.guardrails import GuardrailScope, GuardrailValidationResult +from opentelemetry.trace import Span, StatusCode +from uipath.core.guardrails import GuardrailValidationResult from uipath.core.tracing.span_utils import UiPathSpanUtils from uipath.platform.guardrails.decorators import ( - GuardrailExecutionStage, LoggingSeverityLevel, ) from uipath.platform.guardrails.decorators._exceptions import GuardrailBlockException -from ._span_name import SpanName, SpanType +from ._span_name import SpanType -_CONTAINER_MARK = "uipath.guardrail_container" -logger = logging.getLogger(__name__) - - -def _new_span( +def new_span( name: str, span_type: str, context: otel_context.Context | None = None, @@ -61,12 +50,12 @@ def _active(span: Span) -> Generator[Span]: span.set_status(StatusCode.OK) raise except Exception as exc: - span.set_status(StatusCode.ERROR, _error_text(exc)) + span.set_status(StatusCode.ERROR, error_text(exc)) raise span.set_status(StatusCode.OK) -def _error_text(exc: BaseException) -> str: +def error_text(exc: BaseException) -> str: if isinstance(exc, GuardrailBlockException): return f"Guardrail violation: {exc.detail}" return str(exc) @@ -93,7 +82,7 @@ def guardrail_action_span( ) -> Generator[Span]: """Record the action taken on a failed ``result``.""" severity = getattr(action, "severity_level", None) - span = _new_span( + span = new_span( action_name(action), SpanType.GUARDRAIL_ACTION, guardrailName=guardrail_name, @@ -115,7 +104,7 @@ def guardrail_evaluation_span( guardrail_name: str, description: str | None = None ) -> Generator[Span]: """Record a rule check that runs in the agent.""" - span = _new_span( + span = new_span( guardrail_name, SpanType.GUARDRAIL_EVALUATION, guardrailName=guardrail_name, @@ -131,274 +120,3 @@ def set_validation_result(span: Span, result: GuardrailValidationResult) -> None span.set_attribute("validationResult", result.result.name) if result.reason: span.set_attribute("details", [result.reason]) - - -_PRE = GuardrailExecutionStage.PRE -_POST = GuardrailExecutionStage.POST - -# (scope, stage) -> (container name, span type) -_STAGES: dict[tuple[GuardrailScope, GuardrailExecutionStage], tuple[str, str]] = { - (GuardrailScope.AGENT, _PRE): ( - SpanName.AGENT_PRE_GUARDRAILS, - SpanType.AGENT_PRE_GUARDRAILS, - ), - (GuardrailScope.AGENT, _POST): ( - SpanName.AGENT_POST_GUARDRAILS, - SpanType.AGENT_POST_GUARDRAILS, - ), - (GuardrailScope.LLM, _PRE): ( - SpanName.LLM_PRE_GUARDRAILS, - SpanType.LLM_PRE_GUARDRAILS, - ), - (GuardrailScope.LLM, _POST): ( - SpanName.LLM_POST_GUARDRAILS, - SpanType.LLM_POST_GUARDRAILS, - ), - (GuardrailScope.TOOL, _PRE): ( - SpanName.TOOL_PRE_GUARDRAILS, - SpanType.TOOL_PRE_GUARDRAILS, - ), - (GuardrailScope.TOOL, _POST): ( - SpanName.TOOL_POST_GUARDRAILS, - SpanType.TOOL_POST_GUARDRAILS, - ), -} - - -class _GroupingState: - """Process-wide state. Grouping stays off until a closer is registered.""" - - def __init__(self) -> None: - self.enabled = False - self.in_use = False # a guardrail middleware was built - self.trace_manager: Any = None # offered by the runtime factory - self.closers: weakref.WeakKeyDictionary[Any, GuardrailStageCloser] = ( - weakref.WeakKeyDictionary() - ) # trace manager -> its closer - self.guardrail_nodes: dict[str, str] = {} # node name -> stage span type - self.containers: dict[tuple[int, str], Span] = {} # (parent id, type) - self.last_check_end: dict[int, int] = {} # container span id -> ns - self.lock = threading.Lock() - - -_state = _GroupingState() - -_current_container: ContextVar[Span | None] = ContextVar( - "uipath_guardrail_container", default=None -) -# Set while a container starts, so the closer skips it without taking the lock. -_starting_container: ContextVar[bool] = ContextVar( - "uipath_guardrail_container_starting", default=False -) - - -def register_guardrail_node( - node_name: str, scope: GuardrailScope, stage: GuardrailExecutionStage -) -> None: - """Record which stage a guardrail hook's LangGraph node belongs to.""" - _state.guardrail_nodes[node_name] = _STAGES[(scope, stage)][1] - guardrails_in_use() - - -def guardrails_in_use() -> None: - """Called by guardrail middlewares when built; grouping needs one in use.""" - _state.in_use = True - _activate() - - -@contextmanager -def guardrail_stage( - scope: GuardrailScope | None, stage: GuardrailExecutionStage | None -) -> Generator[None]: - """Run one check inside its stage's shared container.""" - try: - container = _shared_container(scope, stage) - except Exception: - logger.warning("Could not group a guardrail check", exc_info=True) - container = None - if container is None: - yield - return - token = _current_container.set(container) - try: - yield - except GraphBubbleUp: - raise - except Exception as exc: - container.set_status(StatusCode.ERROR, _error_text(exc)) - raise - finally: - _current_container.reset(token) - with _state.lock: - # A container closed meanwhile was already popped; don't re-add it. - if any(open_ is container for open_ in _state.containers.values()): - span_id = container.get_span_context().span_id - _state.last_check_end[span_id] = time.time_ns() - - -def _shared_container( - scope: GuardrailScope | None, stage: GuardrailExecutionStage | None -) -> Span | None: - """Get or create the stage container: beside message nodes, inside ``tools``.""" - if not _state.enabled or (scope, stage) not in _STAGES: - return None - node = UiPathSpanUtils.get_external_current_span() - if node is None or not node.is_recording(): - return None # a sampled-out node never reports its end - if scope == GuardrailScope.TOOL: - parent: SpanContext | None = node.get_span_context() - else: - parent = getattr(node, "parent", None) - if not _can_group_under(parent): - return None - - name, span_type = _STAGES[(scope, stage)] # type: ignore[index] - key = (parent.span_id, span_type) - previous: list[tuple[Span, int]] = [] - with _state.lock: - container = _state.containers.get(key) - if container is None: - token = _starting_container.set(True) - try: - container = _new_span( - name, - span_type, - context=trace.set_span_in_context(NonRecordingSpan(parent)), - **{ - _CONTAINER_MARK: True, - # Its parent is non-recording, so this isn't inherited. - "execution.id": (getattr(node, "attributes", None) or {}).get( - "execution.id" - ), - }, - ) - finally: - _starting_container.reset(token) - # No sibling may have started between the stages, e.g. when a - # middleware answers a tool call without running the tool. - previous = _pop_containers( - lambda k: k[0] == parent.span_id and k[1] != span_type - ) - _state.containers[key] = container - _end_containers(previous, end_time=getattr(container, "start_time", None)) - return container - - -def _can_group_under(parent: SpanContext | None) -> TypeGuard[SpanContext]: - """Whether a container under ``parent`` would ever be closed.""" - return parent is not None and parent.is_valid and parent.trace_flags.sampled - - -def guardrail_aware( - provider: Callable[[], Span | None], -) -> Callable[[], Span | None]: - """Report the running check's container as the current span.""" - - def current_span() -> Span | None: - return _current_container.get() or provider() - - return current_span - - -class GuardrailStageCloser(SpanProcessor): - """End a container when a non-guardrail sibling starts or its parent ends.""" - - def on_start( - self, span: Span, parent_context: otel_context.Context | None = None - ) -> None: - if _starting_container.get() or not _state.containers: - return - attributes = getattr(span, "attributes", None) or {} - parent = getattr(span, "parent", None) - if attributes.get(_CONTAINER_MARK) or parent is None: - return - same_stage = _state.guardrail_nodes.get(getattr(span, "name", "")) - self._close( - lambda key: key[0] == parent.span_id and key[1] != same_stage, - end_time=getattr(span, "start_time", None), - ) - - def on_end(self, span: ReadableSpan) -> None: - if not _state.containers: - return - span_id = span.context.span_id if span.context else None - self._close(lambda key: key[0] == span_id, end_time=span.end_time) - - def shutdown(self) -> None: - """Called when its trace manager shuts down: unregister, end what's open.""" - with _state.lock: - owners = [m for m, closer in _state.closers.items() if closer is self] - for manager in owners: - del _state.closers[manager] - if any(manager is _state.trace_manager for manager in owners): - _state.trace_manager = None - _state.enabled = bool(_state.closers) - if not _state.enabled: - self._close(lambda key: True, end_time=None) - - @staticmethod - def _close( - matches: Callable[[tuple[int, str]], bool], end_time: int | None - ) -> None: - with _state.lock: - done = _pop_containers(matches) - _end_containers(done, end_time) - - -def _pop_containers( - matches: Callable[[tuple[int, str]], bool], -) -> list[tuple[Span, int]]: - """Remove matching containers, with their last check's end. Hold the lock.""" - keys = [key for key in _state.containers if matches(key)] - spans = [_state.containers.pop(key) for key in keys] - return [ - (span, _state.last_check_end.pop(span.get_span_context().span_id, 0)) - for span in spans - ] - - -def _end_containers(containers: list[tuple[Span, int]], end_time: int | None) -> None: - for span, last_end in containers: - status = getattr(span, "status", None) - if status is None or status.status_code is StatusCode.UNSET: - span.set_status(StatusCode.OK) - # Never before its last check: coarse clocks (Windows before Python - # 3.13) can stamp the next sibling's start a tick earlier. - span.end(end_time=max(end_time, last_end) if end_time else None) - - -def is_exported(span: ReadableSpan) -> bool: - """Span filter hiding guardrail node spans (by name: spans upload on start).""" - if not _state.enabled or span.name not in _state.guardrail_nodes: - return True - if not _can_group_under(span.parent): - return True # its checks stay under it, ungrouped - scope = getattr(span, "instrumentation_scope", None) - return "openinference" not in (getattr(scope, "name", "") or "") - - -def enable_guardrail_grouping( - trace_manager: Any, current_span_provider: Callable[[], Span | None] -) -> None: - """Register the span provider and offer the trace manager for grouping. - - Grouping turns on once a guardrail middleware is also in use. - """ - UiPathSpanUtils.register_current_span_provider( - guardrail_aware(current_span_provider) - ) - _state.trace_manager = trace_manager - _activate() - - -def _activate() -> None: - """Attach a closer to the offered trace manager if guardrails are in use.""" - with _state.lock: - manager = _state.trace_manager - if manager is None or not _state.in_use: - return - if manager not in _state.closers: - closer = GuardrailStageCloser() - manager.add_span_processor(closer) - _state.closers[manager] = closer - _state.enabled = True diff --git a/src/uipath_langchain/guardrails/middlewares/deterministic.py b/src/uipath_langchain/guardrails/middlewares/deterministic.py index 1b27996a5..b578a483a 100644 --- a/src/uipath_langchain/guardrails/middlewares/deterministic.py +++ b/src/uipath_langchain/guardrails/middlewares/deterministic.py @@ -22,11 +22,10 @@ from ..enums import GuardrailExecutionStage from ..models import GuardrailAction +from ._grouping import guardrail_stage, guardrails_in_use from ._spans import ( guardrail_action_span, guardrail_evaluation_span, - guardrail_stage, - guardrails_in_use, set_validation_result, span_guid, ) diff --git a/src/uipath_langchain/runtime/factory.py b/src/uipath_langchain/runtime/factory.py index 755b4c5fb..864868700 100644 --- a/src/uipath_langchain/runtime/factory.py +++ b/src/uipath_langchain/runtime/factory.py @@ -28,7 +28,7 @@ from uipath_langchain._tracing import _instrument_traceable_attributes from uipath_langchain.chat.chat_model_factory import _TraceContextHeadersCallback from uipath_langchain.governance import GovernanceCallbackHandler -from uipath_langchain.guardrails.middlewares._spans import ( +from uipath_langchain.guardrails.middlewares._grouping import ( enable_guardrail_grouping, is_exported, ) diff --git a/tests/guardrails/middlewares/test_action_span.py b/tests/guardrails/middlewares/test_action_span.py index f44ea8ee8..a5d3c1875 100644 --- a/tests/guardrails/middlewares/test_action_span.py +++ b/tests/guardrails/middlewares/test_action_span.py @@ -32,7 +32,7 @@ from uipath_langchain.guardrails.middlewares import ( UiPathDeterministicGuardrailMiddleware, UiPathPIIDetectionMiddleware, - _spans, + _grouping, ) from uipath_langchain.guardrails.middlewares._spans import action_name from uipath_langchain.guardrails.models import PIIDetectionEntity @@ -50,7 +50,7 @@ @pytest.fixture def recorded_spans(monkeypatch: pytest.MonkeyPatch) -> Iterator[InMemorySpanExporter]: - monkeypatch.setattr(_spans, "_state", _spans._GroupingState()) + monkeypatch.setattr(_grouping, "_state", _grouping._GroupingState()) provider = TracerProvider() exporter = InMemorySpanExporter() provider.add_span_processor(SimpleSpanProcessor(exporter)) diff --git a/tests/guardrails/middlewares/test_grouping.py b/tests/guardrails/middlewares/test_grouping.py index 336aa29fc..59fc36d57 100644 --- a/tests/guardrails/middlewares/test_grouping.py +++ b/tests/guardrails/middlewares/test_grouping.py @@ -49,9 +49,9 @@ UiPathPIIDetectionMiddleware, UiPathPromptInjectionMiddleware, _base, - _spans, + _grouping, ) -from uipath_langchain.guardrails.middlewares._spans import ( +from uipath_langchain.guardrails.middlewares._grouping import ( enable_guardrail_grouping, guardrail_stage, is_exported, @@ -67,7 +67,7 @@ @pytest.fixture def exporter(monkeypatch: pytest.MonkeyPatch) -> Iterator[InMemorySpanExporter]: - monkeypatch.setattr(_spans, "_state", _spans._GroupingState()) + monkeypatch.setattr(_grouping, "_state", _grouping._GroupingState()) provider = TracerProvider() exporter = InMemorySpanExporter() provider.add_span_processor(SimpleSpanProcessor(exporter)) @@ -306,7 +306,7 @@ async def test_a_grouping_failure_still_runs_the_check(self, graph: _Graph) -> N with ( patch.object(pii, "_evaluate_guardrail", return_value=_FAILED), - patch.object(_spans, "_shared_container", side_effect=RuntimeError), + patch.object(_grouping, "_shared_container", side_effect=RuntimeError), pytest.raises(AgentRuntimeError), graph.node(f"{hook.name}.before_model"), ): @@ -371,7 +371,7 @@ async def test_output_checks_close_when_the_tools_node_ends( assert container.start_time >= tool_span.end_time assert container.end_time == tools.end_time - def test_a_container_closed_during_a_check_keeps_no_end_time( + def test_a_container_closed_during_a_check_stays_closed( self, graph: _Graph ) -> None: _pii() @@ -379,9 +379,12 @@ def test_a_container_closed_during_a_check_keeps_no_end_time( with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): with graph.node("get_weather", parent=tools): # closes it pass + spans = graph.finish() - assert _spans._state.containers == {} - assert _spans._state.last_check_end == {} + [container] = _named(spans, "Tool input guardrail check") + [tool_span] = _named(spans, "get_weather") + assert container.end_time == tool_span.start_time + assert _grouping._state.containers == {} async def test_input_checks_close_when_the_output_stage_starts( self, graph: _Graph @@ -414,7 +417,7 @@ async def test_a_failed_new_stage_keeps_the_previous_container_closable( with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): pass with ( - patch.object(_spans, "_new_span", side_effect=RuntimeError), + patch.object(_grouping, "new_span", side_effect=RuntimeError), guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.POST), ): pass @@ -422,7 +425,7 @@ async def test_a_failed_new_stage_keeps_the_previous_container_closable( [container] = _named(spans, "Tool input guardrail check") assert container.end_time == _named(spans, "tools")[0].end_time - assert _spans._state.containers == {} + assert _grouping._state.containers == {} class TestEnabling: @@ -436,8 +439,8 @@ async def test_nothing_is_grouped_without_a_closer( pass node.end() - assert _spans._state.containers == {} - assert not _spans._state.enabled + assert _grouping._state.containers == {} + assert not _grouping._state.enabled async def test_nothing_is_grouped_under_an_invalid_node_span( self, exporter: InMemorySpanExporter @@ -448,8 +451,8 @@ async def test_nothing_is_grouped_under_an_invalid_node_span( with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): pass - assert _spans._state.enabled - assert _spans._state.containers == {} + assert _grouping._state.enabled + assert _grouping._state.containers == {} def test_the_closer_is_added_once_per_trace_manager( self, exporter: InMemorySpanExporter @@ -471,11 +474,11 @@ def test_the_closer_comes_back_after_its_trace_manager_shuts_down( [closer] = [call.args[0] for call in manager.add_span_processor.call_args_list] closer.shutdown() # what UiPathTraceManager.shutdown() does - assert not _spans._state.enabled + assert not _grouping._state.enabled enable_guardrail_grouping(manager, lambda: None) assert manager.add_span_processor.call_count == 2 - assert _spans._state.enabled + assert _grouping._state.enabled def test_a_shut_down_trace_manager_is_not_reused( self, exporter: InMemorySpanExporter @@ -489,7 +492,7 @@ def test_a_shut_down_trace_manager_is_not_reused( _pii() # a middleware built before the next runtime factory manager.add_span_processor.assert_called_once() - assert not _spans._state.enabled + assert not _grouping._state.enabled async def test_nothing_is_grouped_under_a_sampled_out_node( self, exporter: InMemorySpanExporter @@ -505,8 +508,8 @@ async def test_nothing_is_grouped_under_a_sampled_out_node( with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): pass - assert _spans._state.enabled - assert _spans._state.containers == {} + assert _grouping._state.enabled + assert _grouping._state.containers == {} def test_nothing_is_grouped_under_a_sampled_out_parent( self, exporter: InMemorySpanExporter @@ -528,7 +531,7 @@ def test_nothing_is_grouped_under_a_sampled_out_parent( pass assert node.is_recording() - assert _spans._state.containers == {} + assert _grouping._state.containers == {} node.end() provider.shutdown() @@ -536,8 +539,8 @@ def test_the_closer_skips_the_lock_with_nothing_open( self, graph: _Graph, monkeypatch: pytest.MonkeyPatch ) -> None: lock = MagicMock() - monkeypatch.setattr(_spans._state, "lock", lock) - closer = _spans.GuardrailStageCloser() + monkeypatch.setattr(_grouping._state, "lock", lock) + closer = _grouping.GuardrailStageCloser() with graph.node("model") as span: closer.on_start(span) @@ -564,7 +567,7 @@ def check() -> None: worker.join(timeout=5) assert not worker.is_alive() - assert len(_spans._state.containers) == 1 + assert len(_grouping._state.containers) == 1 node.end() provider.shutdown() @@ -576,7 +579,7 @@ def test_tool_only_guardrails_turn_grouping_on( _rule(GuardrailExecutionStage.PRE) manager.add_span_processor.assert_called_once() - assert _spans._state.enabled + assert _grouping._state.enabled def test_grouping_stays_off_without_guardrail_middlewares( self, exporter: InMemorySpanExporter @@ -585,7 +588,7 @@ def test_grouping_stays_off_without_guardrail_middlewares( enable_guardrail_grouping(manager, lambda: None) manager.add_span_processor.assert_not_called() - assert not _spans._state.enabled + assert not _grouping._state.enabled async def test_only_guardrail_node_spans_are_hidden(self, graph: _Graph) -> None: pii = _pii() @@ -687,7 +690,7 @@ def _assert_well_formed(spans: list[ReadableSpan]) -> None: and not is_exported(by_id[s.parent.span_id]) ] assert orphans == [] - assert _spans._state.containers == {} + assert _grouping._state.containers == {} async def test_parallel_tool_calls_group_per_tools_span( self, exporter: InMemorySpanExporter, instrumented: None From c5788da3f66cdd380193438b20bfeb55d98430a7 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 18:29:55 +0200 Subject: [PATCH 08/11] chore(guardrails): trim grouping comments Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_grouping.py | 18 +++--------------- .../guardrails/middlewares/_span_name.py | 3 +-- 2 files changed, 4 insertions(+), 17 deletions(-) diff --git a/src/uipath_langchain/guardrails/middlewares/_grouping.py b/src/uipath_langchain/guardrails/middlewares/_grouping.py index eee6b9469..bfb58fb92 100644 --- a/src/uipath_langchain/guardrails/middlewares/_grouping.py +++ b/src/uipath_langchain/guardrails/middlewares/_grouping.py @@ -73,7 +73,7 @@ class _ContainerKey(NamedTuple): @dataclass class _Container: span: Span - last_check_end: int = 0 # ns; it never ends before its last check + last_check_end: int = 0 # ns; the container never ends before this class _GroupingState: @@ -87,7 +87,7 @@ def __init__(self) -> None: weakref.WeakKeyDictionary() ) # trace manager -> its closer self.guardrail_nodes: dict[str, str] = {} # node name -> stage span type - self.containers: dict[_ContainerKey, _Container] = {} # the open ones + self.containers: dict[_ContainerKey, _Container] = {} self.lock = threading.Lock() @@ -102,9 +102,6 @@ def __init__(self) -> None: ) -# --- Setup ------------------------------------------------------------------- - - def enable_guardrail_grouping( trace_manager: Any, current_span_provider: Callable[[], Span | None] ) -> None: @@ -146,9 +143,6 @@ def _activate() -> None: _state.enabled = True -# --- Running a check --------------------------------------------------------- - - @contextmanager def guardrail_stage( scope: GuardrailScope | None, stage: GuardrailExecutionStage | None @@ -247,9 +241,6 @@ def _start_container(stage: _Stage, parent: SpanContext, node: Span) -> Span: _starting_container.reset(token) -# --- Closing containers ------------------------------------------------------ - - class GuardrailStageCloser(SpanProcessor): """End a container when a non-guardrail sibling starts or its parent ends.""" @@ -312,11 +303,8 @@ def _end_containers(containers: list[_Container], end_time: int | None) -> None: span.end(end_time=max(end_time, container.last_check_end) if end_time else None) -# --- Export filter ----------------------------------------------------------- - - def is_exported(span: ReadableSpan) -> bool: - """Span filter hiding guardrail node spans (by name: spans upload on start).""" + """Hide guardrail node spans. Decided by name: a span uploads when it starts.""" if not _state.enabled or span.name not in _state.guardrail_nodes: return True if not _can_group_under(span.parent): diff --git a/src/uipath_langchain/guardrails/middlewares/_span_name.py b/src/uipath_langchain/guardrails/middlewares/_span_name.py index b8c1c0af4..9e91ba7b4 100644 --- a/src/uipath_langchain/guardrails/middlewares/_span_name.py +++ b/src/uipath_langchain/guardrails/middlewares/_span_name.py @@ -2,12 +2,11 @@ class SpanType: - """Span types of guardrail spans.""" + """Values of a guardrail span's ``span_type``.""" GUARDRAIL_ACTION = "guardrailAction" GUARDRAIL_EVALUATION = "guardrailEvaluation" - # Stage containers AGENT_PRE_GUARDRAILS = "agentPreGuardrails" AGENT_POST_GUARDRAILS = "agentPostGuardrails" LLM_PRE_GUARDRAILS = "llmPreGuardrails" From 6b63c1278026622f0ef01a3b50e792f42c1abbf9 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 18:44:44 +0200 Subject: [PATCH 09/11] refactor(guardrails): drop the container mark attribute The closer already skips a container while it starts, so the uipath.guardrail_container attribute was never needed. The deadlock test now opens a second container while the first is open, the case it guards. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_grouping.py | 6 +----- tests/guardrails/middlewares/test_grouping.py | 13 +++++++++---- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/src/uipath_langchain/guardrails/middlewares/_grouping.py b/src/uipath_langchain/guardrails/middlewares/_grouping.py index bfb58fb92..b67c4304f 100644 --- a/src/uipath_langchain/guardrails/middlewares/_grouping.py +++ b/src/uipath_langchain/guardrails/middlewares/_grouping.py @@ -32,8 +32,6 @@ logger = logging.getLogger(__name__) -_CONTAINER_MARK = "uipath.guardrail_container" - class _Stage(NamedTuple): name: str @@ -230,7 +228,6 @@ def _start_container(stage: _Stage, parent: SpanContext, node: Span) -> Span: stage.span_type, context=trace.set_span_in_context(NonRecordingSpan(parent)), **{ - _CONTAINER_MARK: True, # Its parent is non-recording, so this isn't inherited. "execution.id": (getattr(node, "attributes", None) or {}).get( "execution.id" @@ -249,9 +246,8 @@ def on_start( ) -> None: if _starting_container.get() or not _state.containers: return - attributes = getattr(span, "attributes", None) or {} parent = getattr(span, "parent", None) - if attributes.get(_CONTAINER_MARK) or parent is None: + if parent is None: return # A guardrail node of the same stage joins the container; anything # else starting beside it ends the stage. diff --git a/tests/guardrails/middlewares/test_grouping.py b/tests/guardrails/middlewares/test_grouping.py index 59fc36d57..5afaf24a1 100644 --- a/tests/guardrails/middlewares/test_grouping.py +++ b/tests/guardrails/middlewares/test_grouping.py @@ -20,7 +20,7 @@ get_current_span, ) from opentelemetry import trace -from opentelemetry.sdk.trace import ReadableSpan, SpanLimits, TracerProvider +from opentelemetry.sdk.trace import ReadableSpan, TracerProvider from opentelemetry.sdk.trace.export import SimpleSpanProcessor from opentelemetry.sdk.trace.export.in_memory_span_exporter import ( InMemorySpanExporter, @@ -548,19 +548,24 @@ def test_the_closer_skips_the_lock_with_nothing_open( lock.__enter__.assert_not_called() - def test_a_container_without_its_mark_does_not_deadlock( + def test_starting_a_container_does_not_deadlock( self, exporter: InMemorySpanExporter, monkeypatch: pytest.MonkeyPatch ) -> None: - # No attributes kept, so the container loses the mark the closer checks. - provider = TracerProvider(span_limits=SpanLimits(max_span_attributes=0)) + # A container starts under the lock that the closer's on_start takes. + # Its own provider, so a deadlock fails the test instead of hanging the + # fixture's shutdown. + provider = TracerProvider() monkeypatch.setattr(trace, "get_tracer", provider.get_tracer) node = provider.get_tracer(_OPENINFERENCE).start_span("tools") enable_guardrail_grouping(provider, lambda: node) _pii() def check() -> None: + # The second container starts while the first is open. with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): pass + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.POST): + pass worker = threading.Thread(target=check, daemon=True) worker.start() From cfd9b508643e66cf3752e70f20e48ccfe4450804 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 19:00:49 +0200 Subject: [PATCH 10/11] refactor(guardrails): simplify stage grouping state Containers are keyed by parent span id (a parent has at most one open container), so closing is a lookup instead of a scan. An RLock replaces the ContextVar guard, and one closer with its trace manager replaces the weak dict of closers. A new stage still ends the previous stage's container itself, outside the lock. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_grouping.py | 181 ++++++++---------- tests/guardrails/middlewares/test_grouping.py | 47 +++-- 2 files changed, 120 insertions(+), 108 deletions(-) diff --git a/src/uipath_langchain/guardrails/middlewares/_grouping.py b/src/uipath_langchain/guardrails/middlewares/_grouping.py index b67c4304f..60c61a82d 100644 --- a/src/uipath_langchain/guardrails/middlewares/_grouping.py +++ b/src/uipath_langchain/guardrails/middlewares/_grouping.py @@ -11,7 +11,6 @@ import logging import threading import time -import weakref from collections.abc import Callable, Generator from contextlib import contextmanager from contextvars import ContextVar @@ -63,30 +62,39 @@ class _Stage(NamedTuple): } -class _ContainerKey(NamedTuple): - parent_id: int - span_type: str - - @dataclass class _Container: span: Span - last_check_end: int = 0 # ns; the container never ends before this + span_type: str + last_check_end: int = 0 # ns + + def end(self, end_time: int | None) -> None: + status = getattr(self.span, "status", None) + if status is None or status.status_code is StatusCode.UNSET: + self.span.set_status(StatusCode.OK) + # Never before its last check: coarse clocks (Windows before Python + # 3.13) can stamp the next sibling's start a tick earlier. + self.span.end(end_time=max(end_time, self.last_check_end) if end_time else None) class _GroupingState: - """Process-wide state. Grouping stays off until a closer is registered.""" + """Process-wide state. Grouping is on while a closer is attached.""" def __init__(self) -> None: - self.enabled = False self.in_use = False # a guardrail middleware was built self.trace_manager: Any = None # offered by the runtime factory - self.closers: weakref.WeakKeyDictionary[Any, GuardrailStageCloser] = ( - weakref.WeakKeyDictionary() - ) # trace manager -> its closer + self.closer: GuardrailStageCloser | None = None self.guardrail_nodes: dict[str, str] = {} # node name -> stage span type - self.containers: dict[_ContainerKey, _Container] = {} - self.lock = threading.Lock() + # Parent span id -> its open container. One at a time: starting a + # stage's container ends the other stage's one under the same parent. + self.containers: dict[int, _Container] = {} + # Re-entrant: starting a container runs the closer's on_start, which + # takes it again on the same thread. + self.lock = threading.RLock() + + @property + def enabled(self) -> bool: + return self.closer is not None _state = _GroupingState() @@ -94,10 +102,6 @@ def __init__(self) -> None: _current_container: ContextVar[Span | None] = ContextVar( "uipath_guardrail_container", default=None ) -# Set while a container starts, so the closer skips it without taking the lock. -_starting_container: ContextVar[bool] = ContextVar( - "uipath_guardrail_container_starting", default=False -) def enable_guardrail_grouping( @@ -134,11 +138,9 @@ def _activate() -> None: manager = _state.trace_manager if manager is None or not _state.in_use: return - if manager not in _state.closers: - closer = GuardrailStageCloser() - manager.add_span_processor(closer) - _state.closers[manager] = closer - _state.enabled = True + if _state.closer is None or _state.closer.trace_manager is not manager: + _state.closer = GuardrailStageCloser(manager) + manager.add_span_processor(_state.closer) @contextmanager @@ -191,20 +193,25 @@ def _shared_container( if not _can_group_under(parent): return None - stage_spans = _STAGES[(scope, stage)] # type: ignore[index] - key = _ContainerKey(parent.span_id, stage_spans.span_type) + spans = _STAGES[(scope, stage)] # type: ignore[index] with _state.lock: - container = _state.containers.get(key) - if container is not None: - return container - container = _Container(_start_container(stage_spans, parent, node)) - # The other stage under this parent is over, even if no sibling - # started in between (a middleware that answers a tool call itself). - other_stage = _pop_containers( - lambda k: k.parent_id == key.parent_id and k.span_type != key.span_type - ) - _state.containers[key] = container - _end_containers(other_stage, end_time=getattr(container.span, "start_time", None)) + previous = _state.containers.get(parent.span_id) + if previous is not None and previous.span_type == spans.span_type: + return previous + # Taken out first, so the new container's start finds nothing to close. + _state.containers.pop(parent.span_id, None) + try: + span = _start_container(spans, parent, node) + except Exception: + if previous is not None: + _state.containers[parent.span_id] = previous + raise + container = _Container(span, spans.span_type) + _state.containers[parent.span_id] = container + # The other stage under this parent is over, even if no sibling started in + # between (a middleware that answers a tool call itself). + if previous is not None: + previous.end(getattr(span, "start_time", None)) return container @@ -221,82 +228,62 @@ def _can_group_under(parent: SpanContext | None) -> TypeGuard[SpanContext]: def _start_container(stage: _Stage, parent: SpanContext, node: Span) -> Span: - token = _starting_container.set(True) - try: - return new_span( - stage.name, - stage.span_type, - context=trace.set_span_in_context(NonRecordingSpan(parent)), - **{ - # Its parent is non-recording, so this isn't inherited. - "execution.id": (getattr(node, "attributes", None) or {}).get( - "execution.id" - ), - }, - ) - finally: - _starting_container.reset(token) + """Start ``stage``'s container under ``parent``.""" + return new_span( + stage.name, + stage.span_type, + context=trace.set_span_in_context(NonRecordingSpan(parent)), + **{ + # Its parent is non-recording, so this isn't inherited. + "execution.id": (getattr(node, "attributes", None) or {}).get( + "execution.id" + ), + }, + ) class GuardrailStageCloser(SpanProcessor): """End a container when a non-guardrail sibling starts or its parent ends.""" + def __init__(self, trace_manager: Any = None) -> None: + self.trace_manager = trace_manager + def on_start( - self, span: Span, parent_context: otel_context.Context | None = None + self, span: ReadableSpan, parent_context: otel_context.Context | None = None ) -> None: - if _starting_container.get() or not _state.containers: + if not _state.containers or span.parent is None: return - parent = getattr(span, "parent", None) - if parent is None: - return - # A guardrail node of the same stage joins the container; anything - # else starting beside it ends the stage. - same_stage = _state.guardrail_nodes.get(getattr(span, "name", "")) - _close( - lambda key: key.parent_id == parent.span_id and key.span_type != same_stage, - end_time=getattr(span, "start_time", None), - ) + with _state.lock: + container = _state.containers.get(span.parent.span_id) + # A guardrail node of the same stage joins the container; anything + # else starting beside it ends the stage. + if container is None or container.span_type == _state.guardrail_nodes.get( + span.name + ): + return + del _state.containers[span.parent.span_id] + container.end(span.start_time) def on_end(self, span: ReadableSpan) -> None: - if not _state.containers: + if not _state.containers or span.context is None: return - span_id = span.context.span_id if span.context else None - _close(lambda key: key.parent_id == span_id, end_time=span.end_time) + with _state.lock: + container = _state.containers.pop(span.context.span_id, None) + if container is not None: + container.end(span.end_time) def shutdown(self) -> None: - """Called when its trace manager shuts down: unregister, end what's open.""" + """Called when its trace manager shuts down: detach, end what's open.""" with _state.lock: - owners = [m for m, closer in _state.closers.items() if closer is self] - for manager in owners: - del _state.closers[manager] - if any(manager is _state.trace_manager for manager in owners): + if self is not _state.closer: + return + _state.closer = None + if _state.trace_manager is self.trace_manager: _state.trace_manager = None - _state.enabled = bool(_state.closers) - if not _state.enabled: - _close(lambda key: True, end_time=None) - - -def _close(matches: Callable[[_ContainerKey], bool], end_time: int | None) -> None: - with _state.lock: - done = _pop_containers(matches) - _end_containers(done, end_time) - - -def _pop_containers(matches: Callable[[_ContainerKey], bool]) -> list[_Container]: - """Remove the matching open containers. Call with the lock held.""" - keys = [key for key in _state.containers if matches(key)] - return [_state.containers.pop(key) for key in keys] - - -def _end_containers(containers: list[_Container], end_time: int | None) -> None: - for container in containers: - span = container.span - status = getattr(span, "status", None) - if status is None or status.status_code is StatusCode.UNSET: - span.set_status(StatusCode.OK) - # Never before its last check: coarse clocks (Windows before Python - # 3.13) can stamp the next sibling's start a tick earlier. - span.end(end_time=max(end_time, container.last_check_end) if end_time else None) + still_open = list(_state.containers.values()) + _state.containers.clear() + for container in still_open: + container.end(None) def is_exported(span: ReadableSpan) -> bool: diff --git a/tests/guardrails/middlewares/test_grouping.py b/tests/guardrails/middlewares/test_grouping.py index 5afaf24a1..c08bfc639 100644 --- a/tests/guardrails/middlewares/test_grouping.py +++ b/tests/guardrails/middlewares/test_grouping.py @@ -543,7 +543,7 @@ def test_the_closer_skips_the_lock_with_nothing_open( closer = _grouping.GuardrailStageCloser() with graph.node("model") as span: - closer.on_start(span) + closer.on_start(span) # type: ignore[arg-type] closer.on_end(span) # type: ignore[arg-type] lock.__enter__.assert_not_called() @@ -551,31 +551,56 @@ def test_the_closer_skips_the_lock_with_nothing_open( def test_starting_a_container_does_not_deadlock( self, exporter: InMemorySpanExporter, monkeypatch: pytest.MonkeyPatch ) -> None: - # A container starts under the lock that the closer's on_start takes. - # Its own provider, so a deadlock fails the test instead of hanging the - # fixture's shutdown. + # A container starts under the lock, and with another container open + # the closer's on_start takes it again. Its own provider, so a deadlock + # fails the test instead of hanging the fixture's shutdown. provider = TracerProvider() monkeypatch.setattr(trace, "get_tracer", provider.get_tracer) - node = provider.get_tracer(_OPENINFERENCE).start_span("tools") - enable_guardrail_grouping(provider, lambda: node) + tracer = provider.get_tracer(_OPENINFERENCE) + other_tools, tools = tracer.start_span("tools"), tracer.start_span("tools") + current = [other_tools] + enable_guardrail_grouping(provider, lambda: current[0]) _pii() + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): + pass # stays open under other_tools + current[0] = tools def check() -> None: - # The second container starts while the first is open. with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): pass - with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.POST): - pass worker = threading.Thread(target=check, daemon=True) worker.start() worker.join(timeout=5) assert not worker.is_alive() - assert len(_grouping._state.containers) == 1 - node.end() + assert len(_grouping._state.containers) == 2 + tools.end() + other_tools.end() provider.shutdown() + def test_a_new_stage_ends_the_previous_one_without_the_closer( + self, graph: _Graph, monkeypatch: pytest.MonkeyPatch + ) -> None: + # Containers from a provider the closer isn't attached to, so it never + # sees their start (as when another manager's shutdown detached it). + hidden = TracerProvider() + finished = InMemorySpanExporter() + hidden.add_span_processor(SimpleSpanProcessor(finished)) + monkeypatch.setattr(trace, "get_tracer", hidden.get_tracer) + _pii() + + with graph.node("tools"): + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.PRE): + pass + with guardrail_stage(GuardrailScope.TOOL, GuardrailExecutionStage.POST): + pass + + ended = [s.name for s in finished.get_finished_spans()] + assert ended == ["Tool input guardrail check"] + graph.finish() + hidden.shutdown() + def test_tool_only_guardrails_turn_grouping_on( self, exporter: InMemorySpanExporter ) -> None: From 55fdc8b1207158e62d56c75a1f6738287f343755 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Fri, 20 Nov 2026 19:06:17 +0200 Subject: [PATCH 11/11] refactor(guardrails): split _shared_container by job _container_place finds where a container goes and whether it would close; _open_container reuses or starts it. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/middlewares/_grouping.py | 55 ++++++++++++------- 1 file changed, 35 insertions(+), 20 deletions(-) diff --git a/src/uipath_langchain/guardrails/middlewares/_grouping.py b/src/uipath_langchain/guardrails/middlewares/_grouping.py index 60c61a82d..3236e4e27 100644 --- a/src/uipath_langchain/guardrails/middlewares/_grouping.py +++ b/src/uipath_langchain/guardrails/middlewares/_grouping.py @@ -183,53 +183,67 @@ def current_span() -> Span | None: def _shared_container( scope: GuardrailScope | None, stage: GuardrailExecutionStage | None ) -> _Container | None: - """Get the stage's open container, or start one.""" - if not _state.enabled or (scope, stage) not in _STAGES: + """Get the stage's open container, or start one. ``None`` if not grouped.""" + stage_spans = _STAGES.get((scope, stage)) # type: ignore[arg-type] + if not _state.enabled or stage_spans is None: return None + place = _container_place(scope) + if place is None: + return None + node, parent = place + return _open_container(stage_spans, parent, node) + + +def _container_place(scope: GuardrailScope | None) -> tuple[Span, SpanContext] | None: + """The check's node and the container's parent, if a container there would close. + + Tool checks go inside the ``tools`` node; others beside their own node. + """ node = UiPathSpanUtils.get_external_current_span() if node is None or not node.is_recording(): return None # a sampled-out node never reports its end - parent = _container_parent(node, scope) + if scope == GuardrailScope.TOOL: + parent: SpanContext | None = node.get_span_context() + else: + parent = getattr(node, "parent", None) if not _can_group_under(parent): return None + return node, parent - spans = _STAGES[(scope, stage)] # type: ignore[index] + +def _open_container(stage: _Stage, parent: SpanContext, node: Span) -> _Container: + """Reuse ``stage``'s open container under ``parent``, or start it there. + + Starting it ends the other stage's container under the same parent, even if + no sibling started in between (a middleware that answers a tool call itself). + """ with _state.lock: previous = _state.containers.get(parent.span_id) - if previous is not None and previous.span_type == spans.span_type: + if previous is not None and previous.span_type == stage.span_type: return previous - # Taken out first, so the new container's start finds nothing to close. + # Out while the new one starts, so the closer doesn't end it under the + # lock; back in if the start fails. _state.containers.pop(parent.span_id, None) try: - span = _start_container(spans, parent, node) + container = _start_container(stage, parent, node) except Exception: if previous is not None: _state.containers[parent.span_id] = previous raise - container = _Container(span, spans.span_type) _state.containers[parent.span_id] = container - # The other stage under this parent is over, even if no sibling started in - # between (a middleware that answers a tool call itself). if previous is not None: - previous.end(getattr(span, "start_time", None)) + previous.end(getattr(container.span, "start_time", None)) return container -def _container_parent(node: Span, scope: GuardrailScope | None) -> SpanContext | None: - """Tool checks go inside the ``tools`` node; others beside their own node.""" - if scope == GuardrailScope.TOOL: - return node.get_span_context() - return getattr(node, "parent", None) - - def _can_group_under(parent: SpanContext | None) -> TypeGuard[SpanContext]: """Whether a container under ``parent`` would ever be closed.""" return parent is not None and parent.is_valid and parent.trace_flags.sampled -def _start_container(stage: _Stage, parent: SpanContext, node: Span) -> Span: +def _start_container(stage: _Stage, parent: SpanContext, node: Span) -> _Container: """Start ``stage``'s container under ``parent``.""" - return new_span( + span = new_span( stage.name, stage.span_type, context=trace.set_span_in_context(NonRecordingSpan(parent)), @@ -240,6 +254,7 @@ def _start_container(stage: _Stage, parent: SpanContext, node: Span) -> Span: ), }, ) + return _Container(span, stage.span_type) class GuardrailStageCloser(SpanProcessor):