Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/uipath-platform/pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import json
import logging
import re
from typing import Any, Optional
Expand Down Expand Up @@ -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],
Expand Down Expand Up @@ -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:
Expand All @@ -190,79 +263,65 @@ 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:
source_headers[HEADER_GUARDRAILS_SOURCE] = execution_source
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", "")

Expand All @@ -272,15 +331,14 @@ 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,
)
result = GuardrailValidationResultType.VALIDATION_FAILED
else:
result = self._parse_result(result_str)

# Prepare model data
model_data: dict[str, Any] = {
"result": result.value,
"reason": reason,
Expand Down
82 changes: 82 additions & 0 deletions packages/uipath-platform/tests/services/test_guardrails_service.py
Original file line number Diff line number Diff line change
@@ -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,
Expand Down Expand Up @@ -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
2 changes: 1 addition & 1 deletion packages/uipath-platform/uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion packages/uipath/uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading