uipath-core 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

uipath/core/guardrails/__init__.py

@@ -0,0 +1,46 @@
+"""UiPath Guardrails Models.
+
+This module contains models related to UiPath Guardrails.
+"""
+
+from ._deterministic_guardrails_service import DeterministicGuardrailsService
+from .guardrails import (
+    AllFieldsSelector,
+    ApplyTo,
+    BaseGuardrail,
+    BooleanRule,
+    DeterministicGuardrail,
+    FieldReference,
+    FieldSelector,
+    FieldSource,
+    GuardrailScope,
+    GuardrailSelector,
+    GuardrailValidationResult,
+    NumberRule,
+    Rule,
+    SelectorType,
+    SpecificFieldsSelector,
+    UniversalRule,
+    WordRule,
+)
+
+__all__ = [
+    "DeterministicGuardrailsService",
+    "FieldSource",
+    "ApplyTo",
+    "FieldReference",
+    "SelectorType",
+    "AllFieldsSelector",
+    "SpecificFieldsSelector",
+    "FieldSelector",
+    "BaseGuardrail",
+    "DeterministicGuardrail",
+    "WordRule",
+    "NumberRule",
+    "BooleanRule",
+    "UniversalRule",
+    "Rule",
+    "GuardrailScope",
+    "GuardrailSelector",
+    "GuardrailValidationResult",
+]

uipath/core/guardrails/_deterministic_guardrails_service.py

@@ -0,0 +1,79 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+from ..tracing.decorators import traced
+from ._evaluators import (
+    evaluate_boolean_rule,
+    evaluate_number_rule,
+    evaluate_universal_rule,
+    evaluate_word_rule,
+)
+from .guardrails import (
+    BooleanRule,
+    DeterministicGuardrail,
+    GuardrailValidationResult,
+    NumberRule,
+    UniversalRule,
+    WordRule,
+)
+
+
+class DeterministicGuardrailsService(BaseModel):
+    @traced("evaluate_pre_deterministic_guardrail", run_type="uipath")
+    def evaluate_pre_deterministic_guardrail(
+        self,
+        input_data: dict[str, Any],
+        guardrail: DeterministicGuardrail,
+    ) -> GuardrailValidationResult:
+        """Evaluate deterministic guardrail rules against input data (pre-execution)."""
+        return self._evaluate_deterministic_guardrail(
+            input_data=input_data,
+            output_data={},
+            guardrail=guardrail,
+        )
+
+    @traced("evaluate_post_deterministic_guardrails", run_type="uipath")
+    def evaluate_post_deterministic_guardrail(
+        self,
+        input_data: dict[str, Any],
+        output_data: dict[str, Any],
+        guardrail: DeterministicGuardrail,
+    ) -> GuardrailValidationResult:
+        """Evaluate deterministic guardrail rules against input and output data."""
+        return self._evaluate_deterministic_guardrail(
+            input_data=input_data,
+            output_data=output_data,
+            guardrail=guardrail,
+        )
+
+    @staticmethod
+    def _evaluate_deterministic_guardrail(
+        input_data: dict[str, Any],
+        output_data: dict[str, Any],
+        guardrail: DeterministicGuardrail,
+    ) -> GuardrailValidationResult:
+        """Evaluate deterministic guardrail rules against input and output data."""
+        for rule in guardrail.rules:
+            if isinstance(rule, WordRule):
+                passed, reason = evaluate_word_rule(rule, input_data, output_data)
+            elif isinstance(rule, NumberRule):
+                passed, reason = evaluate_number_rule(rule, input_data, output_data)
+            elif isinstance(rule, BooleanRule):
+                passed, reason = evaluate_boolean_rule(rule, input_data, output_data)
+            elif isinstance(rule, UniversalRule):
+                passed, reason = evaluate_universal_rule(rule, output_data)
+            else:
+                return GuardrailValidationResult(
+                    validation_passed=False,
+                    reason=f"Unknown rule type: {type(rule)}",
+                )
+
+            if not passed:
+                return GuardrailValidationResult(
+                    validation_passed=False, reason=reason or "Rule validation failed"
+                )
+
+        return GuardrailValidationResult(
+            validation_passed=True, reason="All deterministic guardrail rules passed"
+        )

uipath/core/guardrails/_evaluators.py

@@ -0,0 +1,309 @@
+"""Guardrail rule evaluators.
+
+This module provides functions for evaluating different types of guardrail rules
+against input and output data.
+"""
+
+from enum import IntEnum
+from typing import Any
+
+from .guardrails import (
+    AllFieldsSelector,
+    ApplyTo,
+    BooleanRule,
+    FieldReference,
+    FieldSource,
+    NumberRule,
+    SpecificFieldsSelector,
+    UniversalRule,
+    WordRule,
+)
+
+
+class ArrayDepth(IntEnum):
+    """Array depth enumeration for path parsing."""
+
+    NONE = 0  # Not an array
+    SINGLE = 1  # Single array [*]
+    MATRIX = 2  # Matrix [*][*]
+
+
+def extract_field_value(path: str, data: dict[str, Any]) -> list[Any]:
+    """Extract field values from data using dot-notation path.
+
+    Supports array notation with [*] and [*][*] for arrays and matrices.
+    If an array is encountered at any point in the path, all elements are checked.
+    """
+    if not isinstance(data, dict):
+        return []
+
+    results: list[Any] = []
+
+    def _parse_path_segment(segment: str) -> tuple[str, ArrayDepth]:
+        """Parse a path segment to extract field name and array depth."""
+        if "[*][*]" in segment:
+            field_name = segment.replace("[*][*]", "")
+            return field_name, ArrayDepth.MATRIX
+        elif "[*]" in segment:
+            field_name = segment.replace("[*]", "")
+            return field_name, ArrayDepth.SINGLE
+        else:
+            return segment, ArrayDepth.NONE
+
+    def _traverse(current: Any, remaining_parts: list[str]) -> None:
+        """Recursively traverse the path, handling arrays and matrices."""
+        if not remaining_parts:
+            # End of path, add current value
+            if current is not None:
+                if isinstance(current, list):
+                    # If current is a list, add all elements
+                    results.extend(current)
+                else:
+                    results.append(current)
+            return
+
+        part = remaining_parts[0]
+        next_parts = remaining_parts[1:]
+        field_name, array_depth = _parse_path_segment(part)
+
+        if isinstance(current, dict):
+            if field_name not in current:
+                return
+            next_value = current.get(field_name)
+
+            if array_depth == ArrayDepth.MATRIX:
+                # Matrix [*][*] - expect 2D array
+                if isinstance(next_value, list):
+                    for row in next_value:
+                        if isinstance(row, list):
+                            for item in row:
+                                _traverse(item, next_parts)
+                        else:
+                            # Not a 2D array, treat as 1D
+                            _traverse(row, next_parts)
+            elif array_depth == ArrayDepth.SINGLE:
+                # Array [*] - expect 1D array
+                if isinstance(next_value, list):
+                    for item in next_value:
+                        _traverse(item, next_parts)
+                else:
+                    # Not an array, but path expects one - continue traversal
+                    _traverse(next_value, next_parts)
+            else:
+                # No array notation, continue traversal
+                if isinstance(next_value, list):
+                    # Array encountered without notation - check all elements
+                    for item in next_value:
+                        _traverse(item, next_parts)
+                else:
+                    _traverse(next_value, next_parts)
+        elif isinstance(current, list):
+            # Current is an array - check all elements
+            for item in current:
+                _traverse(item, remaining_parts)
+        else:
+            # Cannot traverse further
+            return
+
+    path_parts = path.split(".")
+    _traverse(data, path_parts)
+    return results
+
+
+def get_fields_from_selector(
+    field_selector: AllFieldsSelector | SpecificFieldsSelector,
+    input_data: dict[str, Any],
+    output_data: dict[str, Any],
+) -> list[tuple[Any, FieldReference]]:
+    """Get field values and their references based on the field selector."""
+    fields: list[tuple[Any, FieldReference]] = []
+
+    if isinstance(field_selector, AllFieldsSelector):
+        # For "all" selector, we need to collect all fields from both input and output
+        # This is a simplified implementation - in practice, you might want to
+        # recursively collect all nested fields
+        for key, value in input_data.items():
+            fields.append(
+                (
+                    value,
+                    FieldReference(path=key, source=FieldSource.INPUT),
+                )
+            )
+        for key, value in output_data.items():
+            fields.append(
+                (
+                    value,
+                    FieldReference(path=key, source=FieldSource.OUTPUT),
+                )
+            )
+    elif isinstance(field_selector, SpecificFieldsSelector):
+        # For specific fields, extract values based on field references
+        for field_ref in field_selector.fields:
+            # Use FieldSource to determine whether to use input_data or output_data
+            if field_ref.source == FieldSource.INPUT:
+                data = input_data
+            elif field_ref.source == FieldSource.OUTPUT:
+                data = output_data
+            else:
+                # Unknown source, skip this field
+                continue
+            # Extract values (may return multiple if arrays are in the path)
+            values = extract_field_value(field_ref.path, data)
+            # Add each value as a separate field reference
+            for value in values:
+                fields.append((value, field_ref))
+
+    return fields
+
+
+def format_guardrail_error_message(
+    field_ref: FieldReference,
+    operator: str,
+    expected_value: str | None = None,
+) -> str:
+    """Format a guardrail error message following the standard pattern."""
+    source = "Input" if field_ref.source == FieldSource.INPUT else "Output"
+    message = f"{source} data didn't match the guardrail condition: [{field_ref.path}] {operator}"
+    if expected_value and expected_value.strip():
+        message += f" [{expected_value.strip()}]"
+    return message
+
+
+def evaluate_word_rule(
+    rule: WordRule, input_data: dict[str, Any], output_data: dict[str, Any]
+) -> tuple[bool, str | None]:
+    """Evaluate a word rule against input and output data."""
+    fields = get_fields_from_selector(rule.field_selector, input_data, output_data)
+
+    for field_value, field_ref in fields:
+        if field_value is None:
+            continue
+
+        # Word rules should only be applied to string values
+        # Skip non-string values (numbers, booleans, objects, arrays, etc.)
+        if not isinstance(field_value, str):
+            continue
+
+        field_str = field_value
+
+        # Use the custom function to evaluate the rule
+        try:
+            passed = rule.func(field_str)
+        except Exception:
+            # If function raises an exception, treat as failure
+            passed = False
+
+        if not passed:
+            reason = format_guardrail_error_message(
+                field_ref, "comparing function", None
+            )
+            return False, reason
+
+    return True, "All word rule validations passed"
+
+
+def evaluate_number_rule(
+    rule: NumberRule, input_data: dict[str, Any], output_data: dict[str, Any]
+) -> tuple[bool, str | None]:
+    """Evaluate a number rule against input and output data."""
+    fields = get_fields_from_selector(rule.field_selector, input_data, output_data)
+
+    for field_value, field_ref in fields:
+        if field_value is None:
+            continue
+
+        # Number rules should only be applied to numeric values
+        # Skip non-numeric values (strings, booleans, objects, arrays, etc.)
+        # Note: bool is a subclass of int in Python, so we must check for bool first
+        if isinstance(field_value, bool) or not isinstance(field_value, (int, float)):
+            continue
+
+        field_num = float(field_value)
+
+        # Use the custom function to evaluate the rule
+        try:
+            passed = rule.func(field_num)
+        except Exception:
+            # If function raises an exception, treat as failure
+            passed = False
+
+        if not passed:
+            reason = format_guardrail_error_message(
+                field_ref, "comparing function", None
+            )
+            return False, reason
+
+    return True, "All number rule validations passed"
+
+
+def evaluate_boolean_rule(
+    rule: BooleanRule,
+    input_data: dict[str, Any],
+    output_data: dict[str, Any],
+) -> tuple[bool, str | None]:
+    """Evaluate a boolean rule against input and output data."""
+    fields = get_fields_from_selector(rule.field_selector, input_data, output_data)
+
+    for field_value, field_ref in fields:
+        if field_value is None:
+            continue
+
+        # Boolean rules should only be applied to boolean values
+        # Skip non-boolean values (strings, numbers, objects, arrays, etc.)
+        if not isinstance(field_value, bool):
+            continue
+
+        field_bool = field_value
+
+        # Use the custom function to evaluate the rule
+        try:
+            passed = rule.func(field_bool)
+        except Exception:
+            # If function raises an exception, treat as failure
+            passed = False
+
+        if not passed:
+            reason = format_guardrail_error_message(
+                field_ref, "comparing function", None
+            )
+            return False, reason
+
+    return True, "All boolean rule validations passed"
+
+
+def evaluate_universal_rule(
+    rule: UniversalRule,
+    output_data: dict[str, Any],
+) -> tuple[bool, str | None]:
+    """Evaluate a universal rule against input and output data.
+
+    Universal rules trigger based on the apply_to scope and execution phase:
+    - Pre-execution (empty output_data):
+      - INPUT: triggers (validation_passed = False)
+      - OUTPUT: does not trigger (validation_passed = True)
+      - INPUT_AND_OUTPUT: triggers (validation_passed = False)
+    - Post-execution (output_data has data):
+      - INPUT: does not trigger (validation_passed = True)
+      - OUTPUT: triggers (validation_passed = False)
+      - INPUT_AND_OUTPUT: triggers (validation_passed = False)
+    """
+    # Determine if this is pre-execution (no output data) or post-execution
+    is_pre_execution = not output_data or len(output_data) == 0
+
+    if rule.apply_to == ApplyTo.INPUT:
+        # INPUT: triggers in pre-execution, does not trigger in post-execution
+        if is_pre_execution:
+            return False, "Universal rule validation triggered (pre-execution, input)"
+        else:
+            return True, "Universal rule validation passed (post-execution, input)"
+    elif rule.apply_to == ApplyTo.OUTPUT:
+        # OUTPUT: does not trigger in pre-execution, triggers in post-execution
+        if is_pre_execution:
+            return True, "Universal rule validation passed (pre-execution, output)"
+        else:
+            return False, "Universal rule validation triggered (post-execution, output)"
+    elif rule.apply_to == ApplyTo.INPUT_AND_OUTPUT:
+        # INPUT_AND_OUTPUT: triggers in both phases
+        return False, "Universal rule validation triggered (input and output)"
+    else:
+        return False, f"Unknown apply_to value: {rule.apply_to}"

uipath/core/guardrails/guardrails.py

@@ -0,0 +1,170 @@
+"""Guardrails models for UiPath Platform."""
+
+from enum import Enum
+from typing import Annotated, Callable, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class GuardrailValidationResult(BaseModel):
+    """Result returned from validating input with a given guardrail.
+
+    Attributes:
+        validation_passed: Indicates whether the input data passed the guardrail validation.
+        reason: Textual explanation describing why the validation passed or failed.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    validation_passed: bool = Field(
+        alias="validation_passed", description="Whether the input passed validation."
+    )
+    reason: str = Field(
+        alias="reason", description="Explanation for the validation result."
+    )
+
+
+class FieldSource(str, Enum):
+    """Field source enumeration."""
+
+    INPUT = "input"
+    OUTPUT = "output"
+
+
+class ApplyTo(str, Enum):
+    """Apply to enumeration."""
+
+    INPUT = "input"
+    INPUT_AND_OUTPUT = "inputAndOutput"
+    OUTPUT = "output"
+
+
+class FieldReference(BaseModel):
+    """Field reference model."""
+
+    path: str
+    source: FieldSource
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class SelectorType(str, Enum):
+    """Selector type enumeration."""
+
+    ALL = "all"
+    SPECIFIC = "specific"
+
+
+class AllFieldsSelector(BaseModel):
+    """All fields selector."""
+
+    selector_type: Literal["all"] = Field(alias="$selectorType")
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class SpecificFieldsSelector(BaseModel):
+    """Specific fields selector."""
+
+    selector_type: Literal["specific"] = Field(alias="$selectorType")
+    fields: list[FieldReference]
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+FieldSelector = Annotated[
+    AllFieldsSelector | SpecificFieldsSelector,
+    Field(discriminator="selector_type"),
+]
+
+
+class RuleType(str, Enum):
+    """Rule type enumeration."""
+
+    BOOLEAN = "boolean"
+    NUMBER = "number"
+    UNIVERSAL = "always"
+    WORD = "word"
+
+
+class WordRule(BaseModel):
+    """Word rule model."""
+
+    rule_type: Literal["word"] = Field(alias="$ruleType")
+    field_selector: FieldSelector = Field(alias="fieldSelector")
+    func: Callable[[str], bool] = Field(exclude=True)
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class UniversalRule(BaseModel):
+    """Universal rule model."""
+
+    rule_type: Literal["always"] = Field(alias="$ruleType")
+    apply_to: ApplyTo = Field(alias="applyTo")
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class NumberRule(BaseModel):
+    """Number rule model."""
+
+    rule_type: Literal["number"] = Field(alias="$ruleType")
+    field_selector: FieldSelector = Field(alias="fieldSelector")
+    func: Callable[[float], bool] = Field(exclude=True)
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class BooleanRule(BaseModel):
+    """Boolean rule model."""
+
+    rule_type: Literal["boolean"] = Field(alias="$ruleType")
+    field_selector: FieldSelector = Field(alias="fieldSelector")
+    func: Callable[[bool], bool] = Field(exclude=True)
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+Rule = Annotated[
+    WordRule | NumberRule | BooleanRule | UniversalRule,
+    Field(discriminator="rule_type"),
+]
+
+
+class GuardrailScope(str, Enum):
+    """Guardrail scope enumeration."""
+
+    AGENT = "Agent"
+    LLM = "Llm"
+    TOOL = "Tool"
+
+
+class GuardrailSelector(BaseModel):
+    """Guardrail selector model."""
+
+    scopes: list[GuardrailScope] = Field(default=[GuardrailScope.TOOL])
+    match_names: list[str] | None = Field(None, alias="matchNames")
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class BaseGuardrail(BaseModel):
+    """Base guardrail model."""
+
+    id: str
+    name: str
+    description: str | None = None
+    enabled_for_evals: bool = Field(True, alias="enabledForEvals")
+    selector: GuardrailSelector
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class DeterministicGuardrail(BaseGuardrail):
+    """Deterministic guardrail model."""
+
+    guardrail_type: Literal["custom"] = Field(alias="custom")
+    rules: list[Rule]
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")

{uipath_core-0.1.1.dist-info → uipath_core-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uipath-core
-Version: 0.1.1
+Version: 0.1.3
 Summary: UiPath Core abstractions
 Project-URL: Homepage, https://uipath.com
 Project-URL: Repository, https://github.com/UiPath/uipath-core-python

{uipath_core-0.1.1.dist-info → uipath_core-0.1.3.dist-info}/RECORD

@@ -14,6 +14,10 @@ uipath/core/chat/meta.py,sha256=3t0eS9UHoAPHre97QTUeVbjDhnMX4zj4-qG6ju0B8wY,315
 uipath/core/chat/tool.py,sha256=6e5pyX3hOWM5fIzr_fdG49Mbzz6XzJD3nsmha-yGa2k,2308
 uipath/core/errors/__init__.py,sha256=gjxdLibZ0fjwgzPuLJY04P8dIX9rbSM2wQ97jP34ucE,278
 uipath/core/errors/errors.py,sha256=5LajjuTfNW82ju07wT5mD3tXk0S-Ju7OqJqQpPN0F6g,486
+uipath/core/guardrails/__init__.py,sha256=baH9Vj8f6spKOpxv3dUl5UKg-LWthaoZ0RidtlFjyEQ,956
+uipath/core/guardrails/_deterministic_guardrails_service.py,sha256=3WGcgpyUIvTXBvheEXjX-XguytxquWJkBevrVeM2tcc,2841
+uipath/core/guardrails/_evaluators.py,sha256=nIODDFu0IjrgVcf0pshmXV0BNAEU-16-liwJv50Lcy4,11343
+uipath/core/guardrails/guardrails.py,sha256=jM_In6kxttkuFoH5KiiE5iREcFAMY2wTxNQkg35ZQqw,4286
 uipath/core/tracing/__init__.py,sha256=1XNLYZ4J76XkRrizGO486mS6yxzVXUbrldpvxTyJe3E,483
 uipath/core/tracing/_utils.py,sha256=FiCFGOFa4czruhlSF87Q5Q4jX9KKPHZiw8k14K7W5v4,6636
 uipath/core/tracing/decorators.py,sha256=ag_MFwZ0TywrhbpLKqQwF1guvRA9sYiItxao5LN9_Iw,10942
@@ -21,7 +25,7 @@ uipath/core/tracing/exporters.py,sha256=FClouEEQfk3F8J7G_NFoarDJM3R0-gA5jUxA5xRH
 uipath/core/tracing/processors.py,sha256=R_652rtjPmfpUtaXoIcmfZrRZylVXFRNwjOmJUUxOQw,1408
 uipath/core/tracing/span_utils.py,sha256=WYBrd6ZbawAs7r1Js-Zvo9_8GzkD9LhHNOls00bK_xI,12235
 uipath/core/tracing/trace_manager.py,sha256=51rscJcepkTK4bWoCZdE-DFc9wt2F-aSuFBaSXmkHl0,3130
-uipath_core-0.1.1.dist-info/METADATA,sha256=y14_f9LW7iQRU0rXymBt8p17HiLxJcUBBREsHTaGbzI,938
-uipath_core-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-uipath_core-0.1.1.dist-info/licenses/LICENSE,sha256=-KBavWXepyDjimmzH5fVAsi-6jNVpIKFc2kZs0Ri4ng,1058
-uipath_core-0.1.1.dist-info/RECORD,,
+uipath_core-0.1.3.dist-info/METADATA,sha256=L3Hqe-B-OZ9pc2uIK73zSa_xLwBg4568I4RhJ9Fg47I,938
+uipath_core-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+uipath_core-0.1.3.dist-info/licenses/LICENSE,sha256=-KBavWXepyDjimmzH5fVAsi-6jNVpIKFc2kZs0Ri4ng,1058
+uipath_core-0.1.3.dist-info/RECORD,,