diff --git a/packages/uipath-platform/pyproject.toml b/packages/uipath-platform/pyproject.toml index 78f8bc068..fdafe30cd 100644 --- a/packages/uipath-platform/pyproject.toml +++ b/packages/uipath-platform/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "uipath-platform" -version = "0.3.12" +version = "0.3.13" description = "HTTP client library for programmatic access to UiPath Platform" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.11" diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py b/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py index 3cf57f591..53b4b062c 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py @@ -1,3 +1,4 @@ +import json import logging import re from typing import Any, Optional @@ -133,7 +134,6 @@ def _parse_error_type(result_str: Any) -> Optional[GuardrailValidationErrorType] except ValueError: return None - @traced("evaluate_guardrail", run_type="uipath") def evaluate_guardrail( self, input_data: str | dict[str, Any], @@ -165,13 +165,86 @@ def evaluate_guardrail( Returns: GuardrailValidationResult: The outcome of the guardrail evaluation. """ - parameters = [ - param.model_dump(by_alias=True) for param in guardrail.validator_parameters - ] + # In a job, the Guardrails Service publishes its own span for this + # evaluation, so a client span would only duplicate it. Local runs don't + # get that span in their trace, so they keep the client one. + evaluate = ( + self._evaluate_guardrail + if UiPathConfig.job_key + else self._traced_evaluate_guardrail + ) + return evaluate( + input_data, + guardrail, + attachments=attachments, + termination_mode=termination_mode, + scope=scope, + execution_stage=execution_stage, + action_type=action_type, + ) + + @traced("evaluate_guardrail", run_type="uipath") + def _traced_evaluate_guardrail( + self, + input_data: str | dict[str, Any], + guardrail: BuiltInValidatorGuardrail, + **options: Any, + ) -> GuardrailValidationResult: + return self._evaluate_guardrail(input_data, guardrail, **options) + + def _evaluate_guardrail( + self, + input_data: str | dict[str, Any], + guardrail: BuiltInValidatorGuardrail, + *, + attachments: list[GuardrailAttachment] | None = None, + termination_mode: GuardrailTerminationMode | None = None, + scope: GuardrailScope | None = None, + execution_stage: str | None = None, + action_type: str | None = None, + ) -> GuardrailValidationResult: + spec = RequestSpec( + method="POST", + endpoint=Endpoint("/agentsruntime_/api/execution/guardrails/validate"), + json=self._build_validate_payload( + input_data, + guardrail, + attachments, + termination_mode, + scope=scope, + execution_stage=execution_stage, + action_type=action_type, + ), + ) + request_kwargs: dict[str, Any] = { + "json": spec.json, + "headers": self._build_validate_headers(spec, attachments), + } + if attachments: + request_kwargs["timeout"] = _ATTACHMENT_VALIDATE_TIMEOUT_SECONDS + + response_data, span_id = self._send_validate_request(spec, request_kwargs) + return self._to_validation_result(response_data, span_id, guardrail.name) + + @staticmethod + def _build_validate_payload( + input_data: str | dict[str, Any], + guardrail: BuiltInValidatorGuardrail, + attachments: list[GuardrailAttachment] | None, + termination_mode: GuardrailTerminationMode | None, + *, + scope: GuardrailScope | None = None, + execution_stage: str | None = None, + action_type: str | None = None, + ) -> dict[str, Any]: + """Build the body of a validate request.""" payload: dict[str, Any] = { "validator": guardrail.validator_type, "input": input_data if isinstance(input_data, str) else str(input_data), - "parameters": parameters, + "parameters": [ + param.model_dump(by_alias=True) + for param in guardrail.validator_parameters + ], "guardrailName": guardrail.name, } if guardrail.validator_type == BYO_VALIDATOR_TYPE: @@ -190,16 +263,20 @@ def evaluate_guardrail( payload["executionStage"] = execution_stage if action_type is not None: payload["actionType"] = action_type - spec = RequestSpec( - method="POST", - endpoint=Endpoint("/agentsruntime_/api/execution/guardrails/validate"), - json=payload, - ) - # Include trace context headers for server-side span correlation, plus - # the execution source (x-uipath-guardrails-source) and job key headers - # for licensing/metering correlation. The execution source is read from - # the execution context, propagated from the runtime context. - trace_headers = build_trace_context_headers(extra_baggage=["source=agents"]) + return payload + + def _build_validate_headers( + self, + spec: RequestSpec, + attachments: list[GuardrailAttachment] | None, + ) -> dict[str, str]: + """Build the headers of a validate request. + + Includes trace context headers for server-side span correlation, plus + the execution source (x-uipath-guardrails-source) and job key headers + for licensing/metering correlation. The execution source is read from + the execution context, propagated from the runtime context. + """ source_headers: dict[str, str] = {} execution_source = self._execution_context.execution_source if execution_source: @@ -207,62 +284,44 @@ def evaluate_guardrail( folder_headers: dict[str, str] = {} if attachments and UiPathConfig.folder_key: folder_headers[HEADER_FOLDER_KEY] = UiPathConfig.folder_key - request_headers = { + return { **(spec.headers or {}), - **trace_headers, + **build_trace_context_headers(extra_baggage=["source=agents"]), **source_headers, **header_job_key(), **folder_headers, } - request_kwargs: dict[str, Any] = { - "json": spec.json, - "headers": request_headers, - } - if attachments: - request_kwargs["timeout"] = _ATTACHMENT_VALIDATE_TIMEOUT_SECONDS - span_id = None + def _send_validate_request( + self, spec: RequestSpec, request_kwargs: dict[str, Any] + ) -> tuple[dict[str, Any], str | None]: + """Send a validate request; return the response body and the service span id.""" try: - response = self.request( - spec.method, - url=spec.endpoint, - **request_kwargs, - ) - span_id = self._extract_span_id_from_traceparent( - response.headers.get("x-uipath-traceparent-id") - ) - response_data = response.json() + response = self.request(spec.method, url=spec.endpoint, **request_kwargs) except EnrichedException as e: - # Handle 403 responses: API returns 403 with valid JSON body for - # ENTITLEMENTS_MISSING or FEATURE_DISABLED cases - if e.status_code == 403: - # Access the original HTTPStatusError to get the full response - original_error = e.__cause__ - if ( - isinstance(original_error, HTTPStatusError) - and original_error.response - ): - try: - span_id = self._extract_span_id_from_traceparent( - original_error.response.headers.get( - "x-uipath-traceparent-id" - ) - ) - response_data = original_error.response.json() - except Exception: - # If JSON parsing fails, re-raise the original exception - raise - else: - # Try to parse from response_content if available - try: - import json - - response_data = json.loads(e.response_content) - except Exception: - raise - else: + # The API returns 403 with a valid JSON body for ENTITLEMENTS_MISSING + # or FEATURE_DISABLED; any other error is raised. + if e.status_code != 403: raise + # Read the full response from the original HTTPStatusError when + # there is one, else parse the body kept on the exception. + original_error = e.__cause__ + if isinstance(original_error, HTTPStatusError) and original_error.response: + response = original_error.response + else: + return json.loads(e.response_content), None + span_id = self._extract_span_id_from_traceparent( + response.headers.get("x-uipath-traceparent-id") + ) + return response.json(), span_id + def _to_validation_result( + self, + response_data: dict[str, Any], + span_id: str | None, + guardrail_name: str, + ) -> GuardrailValidationResult: + """Map a validate response body to a GuardrailValidationResult.""" result_str = response_data.get("result", "") reason = response_data.get("details", "") @@ -272,7 +331,7 @@ def evaluate_guardrail( # guardrail action still fires, and report why on error_type. logger.warning( "Guardrail '%s' could not be evaluated (%s): %s", - guardrail.name, + guardrail_name, result_str, reason, ) @@ -280,7 +339,6 @@ def evaluate_guardrail( else: result = self._parse_result(result_str) - # Prepare model data model_data: dict[str, Any] = { "result": result.value, "reason": reason, diff --git a/packages/uipath-platform/tests/services/test_guardrails_service.py b/packages/uipath-platform/tests/services/test_guardrails_service.py index a74cf3051..6834615cd 100644 --- a/packages/uipath-platform/tests/services/test_guardrails_service.py +++ b/packages/uipath-platform/tests/services/test_guardrails_service.py @@ -1,8 +1,15 @@ import json import logging +from typing import Iterator import httpx import pytest +from opentelemetry import trace +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import SimpleSpanProcessor +from opentelemetry.sdk.trace.export.in_memory_span_exporter import ( + InMemorySpanExporter, +) from pytest_httpx import HTTPXMock from uipath.core.guardrails import ( GuardrailScope, @@ -1543,3 +1550,78 @@ def test_evaluated_results_have_no_error_type( assert result.error_type is None assert result.reason == "Evaluated" assert not [r for r in caplog.records if r.name == _SERVICE_LOGGER] + + +@pytest.fixture +def recorded_spans(monkeypatch: pytest.MonkeyPatch) -> Iterator[InMemorySpanExporter]: + """Record every span, including any @traced would open, in memory.""" + provider = TracerProvider() + exporter = InMemorySpanExporter() + provider.add_span_processor(SimpleSpanProcessor(exporter)) + monkeypatch.setattr(trace, "get_tracer", provider.get_tracer) + yield exporter + provider.shutdown() + + +class TestEvaluateGuardrailSpan: + """In a job the Guardrails Service's span is the only evaluation span (AL-712).""" + + def _evaluate_under_caller( + self, + httpx_mock: HTTPXMock, + service: GuardrailsService, + url: str, + ) -> int: + httpx_mock.add_response( + url=url, status_code=200, json={"result": "PASSED", "details": ""} + ) + with trace.get_tracer("test").start_as_current_span("caller") as caller: + service.evaluate_guardrail("some text", _judge_guardrail()) + return caller.get_span_context().span_id + + def test_job_run_opens_no_client_span( + self, + httpx_mock: HTTPXMock, + service: GuardrailsService, + base_url: str, + org: str, + tenant: str, + recorded_spans: InMemorySpanExporter, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.setenv("UIPATH_JOB_KEY", "job-123") + monkeypatch.setenv("UIPATH_TRACE_ID", "0af7651916cd43dd8448eb211c80319c") + + caller_span_id = self._evaluate_under_caller( + httpx_mock, service, f"{base_url}{org}{tenant}{_VALIDATE_PATH}" + ) + + assert [s.name for s in recorded_spans.get_finished_spans()] == ["caller"] + # The service's span is parented directly to the caller's span. + request = httpx_mock.get_request() + assert request is not None + assert request.headers["x-uipath-traceparent-id"].split("-")[2] == format( + caller_span_id, "016x" + ) + + def test_local_run_keeps_client_span( + self, + httpx_mock: HTTPXMock, + service: GuardrailsService, + base_url: str, + org: str, + tenant: str, + recorded_spans: InMemorySpanExporter, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.delenv("UIPATH_JOB_KEY", raising=False) + + caller_span_id = self._evaluate_under_caller( + httpx_mock, service, f"{base_url}{org}{tenant}{_VALIDATE_PATH}" + ) + + spans = {s.name: s for s in recorded_spans.get_finished_spans()} + assert set(spans) == {"caller", "evaluate_guardrail"} + parent = spans["evaluate_guardrail"].parent + assert parent is not None + assert parent.span_id == caller_span_id diff --git a/packages/uipath-platform/uv.lock b/packages/uipath-platform/uv.lock index 479b3bdca..17d0ca82d 100644 --- a/packages/uipath-platform/uv.lock +++ b/packages/uipath-platform/uv.lock @@ -1082,7 +1082,7 @@ dev = [ [[package]] name = "uipath-platform" -version = "0.3.12" +version = "0.3.13" source = { editable = "." } dependencies = [ { name = "anyio" }, diff --git a/packages/uipath/uv.lock b/packages/uipath/uv.lock index 42e39b292..85cca848a 100644 --- a/packages/uipath/uv.lock +++ b/packages/uipath/uv.lock @@ -2883,7 +2883,7 @@ wheels = [ [[package]] name = "uipath-platform" -version = "0.3.12" +version = "0.3.13" source = { editable = "../uipath-platform" } dependencies = [ { name = "anyio" },