From 0a3e28f9562feeac8014e4bbc4124d4311e2ebf1 Mon Sep 17 00:00:00 2001 From: Aditi Kumari Date: Fri, 12 Jun 2026 16:27:47 +0530 Subject: [PATCH] feat(governance): support governance enforcement-mode config, policy models, and dependencies Co-Authored-By: Claude Opus 4.8 --- pyproject.toml | 6 +- .../runtime/governance/_audit/__init__.py | 12 + src/uipath/runtime/governance/_audit/base.py | 639 +++++++++ .../runtime/governance/_audit/factory.py | 33 + .../runtime/governance/_audit/metadata.py | 69 + .../runtime/governance/_audit/traces.py | 287 ++++ .../runtime/governance/_audit/track_events.py | 329 +++++ .../runtime/governance/native/__init__.py | 40 + .../runtime/governance/native/evaluator.py | 1188 +++++++++++++++++ .../native/guardrail_compensation.py | 183 +++ .../runtime/governance/native/models.py | 162 +++ src/uipath/runtime/governance/runtime.py | 301 +++++ tests/conftest.py | 6 + tests/test_audit_factory.py | 50 + tests/test_audit_manager_lifecycle.py | 207 +++ .../test_audit_manager_track_event_wiring.py | 178 +++ tests/test_audit_register_sink.py | 108 ++ tests/test_commitment_concern.py | 200 +++ tests/test_evaluator.py | 407 ++++++ tests/test_evaluator_operators.py | 688 ++++++++++ tests/test_evaluator_telemetry.py | 289 ++++ tests/test_governance_metadata.py | 81 ++ tests/test_governance_runtime.py | 630 +++++++++ tests/test_guardrail_compensation.py | 298 +++++ tests/test_traces_severity.py | 472 +++++++ tests/test_track_events_sink.py | 416 ++++++ uv.lock | 178 ++- 27 files changed, 7450 insertions(+), 7 deletions(-) create mode 100644 src/uipath/runtime/governance/_audit/__init__.py create mode 100644 src/uipath/runtime/governance/_audit/base.py create mode 100644 src/uipath/runtime/governance/_audit/factory.py create mode 100644 src/uipath/runtime/governance/_audit/metadata.py create mode 100644 src/uipath/runtime/governance/_audit/traces.py create mode 100644 src/uipath/runtime/governance/_audit/track_events.py create mode 100644 src/uipath/runtime/governance/native/__init__.py create mode 100644 src/uipath/runtime/governance/native/evaluator.py create mode 100644 src/uipath/runtime/governance/native/guardrail_compensation.py create mode 100644 src/uipath/runtime/governance/native/models.py create mode 100644 src/uipath/runtime/governance/runtime.py create mode 100644 tests/test_audit_factory.py create mode 100644 tests/test_audit_manager_lifecycle.py create mode 100644 tests/test_audit_manager_track_event_wiring.py create mode 100644 tests/test_audit_register_sink.py create mode 100644 tests/test_commitment_concern.py create mode 100644 tests/test_evaluator.py create mode 100644 tests/test_evaluator_operators.py create mode 100644 tests/test_evaluator_telemetry.py create mode 100644 tests/test_governance_metadata.py create mode 100644 tests/test_governance_runtime.py create mode 100644 tests/test_guardrail_compensation.py create mode 100644 tests/test_traces_severity.py create mode 100644 tests/test_track_events_sink.py diff --git a/pyproject.toml b/pyproject.toml index 2bf085c..5f35dec 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,11 +1,13 @@ [project] name = "uipath-runtime" -version = "0.11.5" +version = "0.11.6" description = "Runtime abstractions and interfaces for building agents and automation scripts in the UiPath ecosystem" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.11" dependencies = [ - "uipath-core>=0.5.26,<0.6.0", + "uipath-core>=0.5.28, <0.6.0", + "vaderSentiment>=3.3.2, <4.0", + "chardet>=5.2.0, <8.0", ] classifiers = [ "Intended Audience :: Developers", diff --git a/src/uipath/runtime/governance/_audit/__init__.py b/src/uipath/runtime/governance/_audit/__init__.py new file mode 100644 index 0000000..ce109ef --- /dev/null +++ b/src/uipath/runtime/governance/_audit/__init__.py @@ -0,0 +1,12 @@ +"""Audit sink framework for governance events. + +Internal module. Provides a pluggable audit system that emits +governance events to one or more sinks. The built-in +:class:`TracesAuditSink` emits OpenTelemetry spans and is always +registered by every :class:`AuditManager` — it carries the governance +audit trail and cannot be disabled by application code. + +Callers import from the submodules directly (``_audit.base``, +``_audit.traces``, ``_audit.factory``). This package exposes no +aggregated symbols. +""" diff --git a/src/uipath/runtime/governance/_audit/base.py b/src/uipath/runtime/governance/_audit/base.py new file mode 100644 index 0000000..7f00271 --- /dev/null +++ b/src/uipath/runtime/governance/_audit/base.py @@ -0,0 +1,639 @@ +"""Base classes and models for the audit sink framework. + +This module provides the core abstractions for the governance audit system: +- AuditEvent: The data model for audit events +- EventType: Constants for common event types +- AuditSink: Abstract base class for sink implementations +- AuditManager: Central hub for routing events to sinks + +Sink dispatch is synchronous on the caller's thread. Sinks that need +async export (HTTP, batched I/O) own that concern internally — the +OTel traces sink rides on opentelemetry-sdk's BatchSpanProcessor, +which handles export off the caller's thread. +""" + +from __future__ import annotations + +import json +import logging +import threading +from abc import ABC, abstractmethod +from dataclasses import asdict, dataclass, field +from datetime import datetime, timezone +from typing import Any, Callable + +from uipath.core.governance import EnforcementMode + +from .metadata import GovernanceRuntimeMetadata + +logger = logging.getLogger(__name__) + + +# ============================================================================= +# Audit Event Model +# ============================================================================= + + +@dataclass +class AuditEvent: + """Generic audit event that can be sent to any sink. + + Trace correlation is intentionally absent from this dataclass. + Sinks that need a trace id resolve one at their own boundary: + OTel-backed sinks read the live span from the caller's + ``contextvars`` directly (sink dispatch runs synchronously on the + caller's thread, so ``trace.get_current_span()`` resolves to the + agent's live span), and HTTP sinks defer to their injected + provider, which resolves at HTTP-call time. + + Attributes: + event_type: Type of event (e.g., "rule_evaluation", "hook_summary") + timestamp: When the event occurred (auto-set if not provided) + agent_name: Name of the agent being governed + hook: Lifecycle hook where event occurred (optional) + data: Event-specific data dictionary + metadata: Additional metadata for filtering/routing + """ + + event_type: str + agent_name: str = "unknown" + hook: str = "" + data: dict[str, Any] = field(default_factory=dict) + metadata: dict[str, Any] = field(default_factory=dict) + timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc)) + + def to_dict(self) -> dict[str, Any]: + """Convert to dictionary for serialization.""" + result = asdict(self) + result["timestamp"] = self.timestamp.isoformat() + return result + + def to_json(self) -> str: + """Convert to JSON string.""" + return json.dumps(self.to_dict()) + + +class EventType: + """Constants for common event types.""" + + RULE_EVALUATION = "rule_evaluation" + HOOK_START = "hook_start" + HOOK_END = "hook_end" + SESSION_START = "session_start" + SESSION_END = "session_end" + POLICY_VIOLATION = "policy_violation" + POLICY_ALLOW = "policy_allow" + PACKS_LOADED = "packs_loaded" + + +# ============================================================================= +# Audit Sink Base Class +# ============================================================================= + + +class AuditSink(ABC): + """Abstract base class for audit output destinations. + + Subclass this to create custom audit sinks. Each sink receives + all audit events and decides how to handle them. + + Sinks that perform network I/O should batch internally — :meth:`emit` + runs on the caller's thread (typically an agent hook), so a slow + synchronous sink blocks the agent. The standard pattern is the one + opentelemetry-sdk uses for its trace exporter: enqueue in-process, + drain on a sink-owned background thread. + + Example: + A Slack sink that posts on rule denials. ``emit`` enqueues onto + an in-process queue; a daemon thread the sink owns drains the + queue and runs the HTTP POST off the caller's thread. + + class SlackAuditSink(AuditSink): + def __init__(self, webhook_url: str): + self.webhook_url = webhook_url + self._name = "slack" + self._queue: queue.Queue[AuditEvent | None] = queue.Queue() + self._worker = threading.Thread( + target=self._drain, name="slack-audit", daemon=True + ) + self._worker.start() + + @property + def name(self) -> str: + return self._name + + def accepts(self, event: AuditEvent) -> bool: + # Only ship denials — drops irrelevant events at the + # boundary instead of forwarding them to the queue. + return ( + event.data.get("matched") + and event.data.get("action") == "deny" + ) + + def emit(self, event: AuditEvent) -> None: + # Non-blocking — runs on the caller's hook thread. + self._queue.put_nowait(event) + + def _drain(self) -> None: + while True: + event = self._queue.get() + if event is None: + return # close() sentinel + try: + requests.post(self.webhook_url, json=event.to_dict()) + except Exception: + pass # log/retry per sink's own policy + finally: + self._queue.task_done() + + def flush(self) -> None: + self._queue.join() + + def close(self) -> None: + self._queue.put_nowait(None) + self._worker.join(timeout=2.0) + """ + + @property + @abstractmethod + def name(self) -> str: + """Unique name for this sink.""" + pass + + @abstractmethod + def emit(self, event: AuditEvent) -> None: + """Emit an audit event to this sink. + + Args: + event: The audit event to emit + + Note: + Implementations should handle errors gracefully and not + raise exceptions that would disrupt governance evaluation. + """ + pass + + def flush(self) -> None: # noqa: B027 — optional hook; subclasses override + """Flush any buffered events. + + Override if sink buffers events before writing. + """ + + def close(self) -> None: # noqa: B027 — optional hook; subclasses override + """Clean up resources. + + Override if sink holds resources that need cleanup. + """ + + def accepts(self, event: AuditEvent) -> bool: + """Check if this sink should receive the event. + + Override to filter events. Default accepts all events. + + Args: + event: The audit event to check + + Returns: + True if sink should receive event, False to skip + """ + return True + + +# ============================================================================= +# Audit Manager +# ============================================================================= + + +class AuditManager: + """Manages multiple audit sinks and routes events to them. + + Instance-scoped: each :class:`GovernanceRuntime` owns its own + manager. Parallel runtimes (``uipath eval``) don't share sinks or + per-sink failure state. + + Constructor automatically registers the always-on ``traces`` sink, + which carries the governance audit trail and cannot be disabled by + application code. Additional sinks can be added via + :meth:`register_sink`. + + Thread Safety: + :meth:`emit` dispatches synchronously on the caller's thread. + Sinks that need to avoid blocking the caller (HTTP exporters) + own their own batching — the OTel traces sink, for example, + rides on opentelemetry-sdk's BatchSpanProcessor. + """ + + # Trip a sink after this many consecutive emit failures (circuit-breaker). + _SINK_FAILURE_THRESHOLD = 10 + + def __init__( + self, + register_default_sinks: bool = True, + *, + track_event: Callable[..., None] | None = None, + runtime_metadata: GovernanceRuntimeMetadata | None = None, + ) -> None: + """Initialize the audit manager. + + Args: + register_default_sinks: If True (default), register the + always-on ``traces`` and platform-mandated + ``track_events`` sinks. Tests that want a bare manager + can pass ``False`` and register sinks explicitly. + track_event: Platform-supplied telemetry callable wired by + the host. When ``None`` (or any sink-construction + error), the ``track_events`` sink is skipped and a + warning is logged — the runtime continues so a wiring + bug never breaks the agent run. + runtime_metadata: Constants stamped on every telemetry + event (execution engine, agent type, agent framework, + runtime version). Defaults to + :class:`GovernanceRuntimeMetadata` () — auto-resolved + version + ``unknown`` agent type / framework. The host + overrides with concrete values. + """ + self._sinks: list[AuditSink] = [] + # Guards _sinks, _sink_failures, _tripped_sinks — all read + + # mutated by emit() across threads when concurrent agent hooks + # share one manager. + self._sinks_lock = threading.Lock() + # Per-sink consecutive-failure counter, keyed by sink name. + self._sink_failures: dict[str, int] = {} + self._tripped_sinks: set[str] = set() + + if register_default_sinks: + self._register_traces_sink() + self._register_track_event_sink(track_event, runtime_metadata) + + def _register_traces_sink(self) -> None: + """Register the always-on ``traces`` sink. + + Registered for every manager and cannot be disabled by + application code — it carries the governance audit trail. The + factory import is deferred to avoid a module-load cycle + (``factory`` imports back into this module). + """ + from .factory import create_sink + + sink = create_sink("traces") + if sink is not None: + self.register_sink(sink) + logger.info("Governance audit sink registered: traces") + + def _register_track_event_sink( + self, + track_event: Callable[..., None] | None, + runtime_metadata: GovernanceRuntimeMetadata | None, + ) -> None: + """Register the platform-mandated ``track_events`` sink. + + Mirrors :meth:`_register_traces_sink`: deferred import, + construct, register, log. The sink is expected to be wired by + the host's platform layer. + + Wrapped in a broad ``except`` so a misconfigured wiring layer + (missing callable, sink construction error) never crashes the + agent — the runtime logs and proceeds without the sink. The + sink-level circuit breaker handles per-emit failures + separately. + """ + try: + from .track_events import TrackEventAuditSink + + if track_event is None: + raise ValueError( + "Platform-mandated track_event callable was not supplied; " + "the host wiring layer must pass it to AuditManager(...)." + ) + meta = ( + runtime_metadata + if runtime_metadata is not None + else GovernanceRuntimeMetadata() + ) + sink = TrackEventAuditSink(track_event, meta) + self.register_sink(sink) + logger.info("Governance audit sink registered: track_events") + except Exception as exc: # noqa: BLE001 - registration must not crash the agent + # ``str(exc)`` instead of passing ``exc`` directly: the + # logging LogRecord retains its ``args`` tuple until the + # handler formats the record, and a raw exception there + # carries its ``__traceback__`` → frame chain → ``self``, + # which would keep the AuditManager alive in any + # log-capturing test. Stringifying breaks that ref. + logger.warning("Failed to register track_events sink: %s", str(exc)) + + def register_sink(self, sink: AuditSink) -> None: + """Register an audit sink. + + Args: + sink: The sink to register + + Note: + Duplicate sinks (same name) are ignored. + The circuit-breaker failure counter is cleared so a freshly + registered sink doesn't inherit a previous instance's tripped + state. ``unregister_sink`` already clears these, but the + defensive reset here guards against external manipulation + of the internal counters (tests, future callers). + """ + with self._sinks_lock: + if any(s.name == sink.name for s in self._sinks): + logger.debug("Sink '%s' already registered, skipping", sink.name) + return + self._sinks.append(sink) + self._sink_failures.pop(sink.name, None) + self._tripped_sinks.discard(sink.name) + logger.info("Registered audit sink: %s", sink.name) + + def unregister_sink(self, name: str) -> bool: + """Unregister an audit sink by name. + + Args: + name: Name of the sink to remove + + Returns: + True if sink was removed, False if not found + """ + sink_to_close: AuditSink | None = None + with self._sinks_lock: + for i, sink in enumerate(self._sinks): + if sink.name == name: + sink_to_close = sink + del self._sinks[i] + self._sink_failures.pop(name, None) + self._tripped_sinks.discard(name) + break + if sink_to_close is not None: + try: + sink_to_close.close() + except Exception as e: + logger.warning("Audit sink '%s' failed to close: %s", name, e) + logger.info("Unregistered audit sink: %s", name) + return True + return False + + def get_sink(self, name: str) -> AuditSink | None: + """Get a registered sink by name.""" + with self._sinks_lock: + for sink in self._sinks: + if sink.name == name: + return sink + return None + + def list_sinks(self) -> list[str]: + """Get names of all registered sinks.""" + with self._sinks_lock: + return [s.name for s in self._sinks] + + def emit(self, event: AuditEvent) -> None: + """Dispatch ``event`` synchronously to every live sink. + + Per-sink errors are caught and folded into the circuit breaker + — a sink that fails too many times in a row is skipped for the + rest of the manager's lifetime. The caller never sees a sink + exception. + + Args: + event: The audit event to emit + """ + with self._sinks_lock: + sinks = list(self._sinks) + tripped = set(self._tripped_sinks) + for sink in sinks: + if sink.name in tripped: + continue + try: + if sink.accepts(event): + sink.emit(event) + # Success — reset failure counter for this sink. + with self._sinks_lock: + if self._sink_failures.get(sink.name): + self._sink_failures[sink.name] = 0 + except Exception as exc: # noqa: BLE001 — swallow to guard the agent + self._record_sink_failure(sink.name, exc) + + def _record_sink_failure(self, sink_name: str, exc: Exception) -> None: + """Bump the circuit-breaker counter for ``sink_name`` and log. + + Extracted from :meth:`emit` to keep that method's cognitive + complexity below the linter's threshold. The lock-guarded + counter mutation and the branch between "still under threshold" + vs "just tripped" logging live here as a single responsibility. + """ + with self._sinks_lock: + fails = self._sink_failures.get(sink_name, 0) + 1 + self._sink_failures[sink_name] = fails + tripped_now = fails >= self._SINK_FAILURE_THRESHOLD + if tripped_now: + self._tripped_sinks.add(sink_name) + if tripped_now: + # ``logger.exception`` captures the traceback via + # ``exc_info`` — no need to interpolate ``exc`` into + # the message (Sonar S8572). + logger.exception( + "Audit sink '%s' tripped after %d consecutive failures; " + "will be skipped for the rest of this process.", + sink_name, + fails, + ) + else: + logger.warning( + "Audit sink '%s' failed to emit event (%d/%d): %s", + sink_name, + fails, + self._SINK_FAILURE_THRESHOLD, + exc, + ) + + def emit_rule_evaluation( + self, + policy_id: str, + rule_name: str, + pack_name: str, + hook: str, + matched: bool, + action: str, + enforcement_mode: EnforcementMode, + detail: str = "", + agent_name: str = "agent", + description: str = "", + duration_ms: float = 0.0, + mapped_to_uipath: bool = False, + ) -> None: + """Convenience method to emit a rule evaluation event. + + ``enforcement_mode`` travels on the event so sinks don't have to + read a process-global. Each emitter (instance-scoped) supplies + its own mode — parallel runtimes can run in different modes + simultaneously, and a process-global wouldn't be authoritative + for any of them. + + ``duration_ms`` and ``mapped_to_uipath`` are stamped on the + event's data dict for telemetry sinks (e.g. + :class:`TrackEventAuditSink`); the OTel traces sink ignores them. + """ + self.emit( + AuditEvent( + event_type=EventType.RULE_EVALUATION, + agent_name=agent_name, + hook=hook, + data={ + "policy_id": policy_id, + "rule_name": rule_name, + "pack_name": pack_name, + "matched": matched, + "action": action, + "enforcement_mode": enforcement_mode, + "detail": detail, + "description": description, + "status": "MATCHED" if matched else "PASS", + "duration_ms": duration_ms, + "mapped_to_uipath": mapped_to_uipath, + }, + ) + ) + + def emit_hook_summary( + self, + hook: str, + agent_name: str, + total_rules: int, + matched_rules: int, + final_action: str, + enforcement_mode: EnforcementMode, + duration_ms: float = 0.0, + skipped_policy_names: list[str] | None = None, + guardrail_dispatched_count: int = 0, + denied_count: int | None = None, + ) -> None: + """Convenience method to emit a hook summary event. + + ``matched_rules`` keeps its historical meaning — any rule whose + checks matched, regardless of the configured action — for + backward compatibility with existing sinks. The newer + ``denied_count`` captures only the rules the evaluator actually + wanted to act on (matched **and** configured action ≠ + ``allow``). A matched rule whose action is ``allow`` is a + positive informational match and is folded into + ``passed_count``, not ``denied_count``. + + Args: + duration_ms: Total wall time spent evaluating this hook. + skipped_policy_names: Rules in the pack that were not + evaluated (currently disabled). The summary carries + their ids so operators can spot which policies a tenant + turned off. + guardrail_dispatched_count: How many UiPath-mapped + guardrail-fallback rules fired for this hook and were + handed to the compensating path. Lets dashboards + compute the native-vs-dispatched ratio. + denied_count: Rules that matched **and** would have acted + (action ∈ {``deny``, ``escalate``, ``audit``}). When + ``None`` (legacy callers), falls back to + ``matched_rules`` so the old "matched == denial" + semantic is preserved. + """ + skipped = list(skipped_policy_names or []) + actual_denied = denied_count if denied_count is not None else matched_rules + passed_count = max(total_rules - actual_denied, 0) + self.emit( + AuditEvent( + event_type=EventType.HOOK_END, + agent_name=agent_name, + hook=hook, + data={ + "total_rules": total_rules, + "matched_rules": matched_rules, + "final_action": final_action, + "enforcement_mode": enforcement_mode, + "duration_ms": duration_ms, + "passed_count": passed_count, + "denied_count": actual_denied, + "skipped_count": len(skipped), + "skipped_policy_names": skipped, + "guardrail_dispatched_count": guardrail_dispatched_count, + }, + ) + ) + + def emit_session_start( + self, + session_id: str, + agent_name: str, + packs: list[str], + enforcement_mode: EnforcementMode, + ) -> None: + """Convenience method to emit a session start event. + + Same ``enforcement_mode: EnforcementMode`` contract as + :meth:`emit_rule_evaluation` and :meth:`emit_hook_summary` + — every governance event carries the emitter's per-instance + mode so sinks don't depend on a process-global. + """ + self.emit( + AuditEvent( + event_type=EventType.SESSION_START, + agent_name=agent_name, + data={ + "session_id": session_id, + "packs": packs, + "enforcement_mode": enforcement_mode, + }, + ) + ) + + def emit_session_end( + self, + session_id: str, + agent_name: str, + total_evaluations: int, + rules_matched: int, + rules_denied: int, + enforcement_mode: EnforcementMode, + ) -> None: + """Convenience method to emit a session end event.""" + self.emit( + AuditEvent( + event_type=EventType.SESSION_END, + agent_name=agent_name, + data={ + "session_id": session_id, + "total_evaluations": total_evaluations, + "rules_matched": rules_matched, + "rules_denied": rules_denied, + "enforcement_mode": enforcement_mode, + }, + ) + ) + + def flush(self) -> None: + """Flush every registered sink. + + Per-sink — a sink that maintains its own buffer (OTel batched + export, HTTP batcher, etc.) gets a chance to drain. The + manager itself holds no queue. + """ + with self._sinks_lock: + sinks = list(self._sinks) + for sink in sinks: + try: + sink.flush() + except Exception as e: + logger.warning("Audit sink '%s' failed to flush: %s", sink.name, e) + + def close(self) -> None: + """Close all sinks and release resources. + + Idempotent — a manager that has already been closed has an + empty sink list, so a repeat call is a no-op. + """ + with self._sinks_lock: + sinks = list(self._sinks) + self._sinks.clear() + self._sink_failures.clear() + self._tripped_sinks.clear() + for sink in sinks: + try: + sink.close() + except Exception as e: + logger.warning("Audit sink '%s' failed to close: %s", sink.name, e) diff --git a/src/uipath/runtime/governance/_audit/factory.py b/src/uipath/runtime/governance/_audit/factory.py new file mode 100644 index 0000000..334f867 --- /dev/null +++ b/src/uipath/runtime/governance/_audit/factory.py @@ -0,0 +1,33 @@ +"""Factory function for creating audit sinks by name. + +Used by :class:`AuditManager` to construct the always-on ``traces`` +sink at initialization. +""" + +from __future__ import annotations + +import logging + +from .base import AuditSink + +logger = logging.getLogger(__name__) + + +def create_sink(name: str) -> AuditSink | None: + """Create an audit sink by name. + + Args: + name: Name of the sink to create (currently only ``traces``). + + Returns: + The created sink, or ``None`` if the name is unknown. + """ + name = name.lower() + + if name == "traces": + from .traces import TracesAuditSink + + return TracesAuditSink() + + logger.warning("Unknown audit sink: %s", name) + return None diff --git a/src/uipath/runtime/governance/_audit/metadata.py b/src/uipath/runtime/governance/_audit/metadata.py new file mode 100644 index 0000000..068a8a6 --- /dev/null +++ b/src/uipath/runtime/governance/_audit/metadata.py @@ -0,0 +1,69 @@ +"""Per-runtime metadata stamped on every governance telemetry event. + +The host constructs a :class:`GovernanceRuntimeMetadata` once per +agent run and passes it to the telemetry sink. Every event produced +by :class:`TrackEventAuditSink` carries these fields so downstream +consumers can pivot on engine / agent type / framework / runtime +version. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from importlib.metadata import PackageNotFoundError, version + +NATIVE_EXECUTION_ENGINE = "uipath_native_governance_checker" + + +def _resolve_runtime_version() -> str: + """Read the ``uipath-runtime`` package version, or ``"unknown"``. + + ``importlib.metadata.version`` fails when the package is imported + from a source checkout that was never installed (CI fixtures, + editable installs with stripped metadata). Telemetry must keep + flowing in those cases, so the fallback is a sentinel rather than + a raise. + """ + try: + return version("uipath-runtime") + except PackageNotFoundError: + return "unknown" + + +@dataclass(frozen=True) +class GovernanceRuntimeMetadata: + """Constants stamped on every governance telemetry event. + + Attributes: + execution_engine: Implementation behind the evaluator. Default + ``"uipath_native_governance_checker"``. When a future engine + (e.g. AGT) replaces the native checker, the host supplies + its own identifier here so the emitted event records which + engine produced the verdict. + agent_type: Category of agent under governance — e.g. + ``"uipath_coded"``, ``"uipath_lowcode"``, ``"servicenow"``, + or any other identifier the host wants to attach. External + agents (ServiceNow, etc.) join this taxonomy when they + land. ``"unknown"`` keeps telemetry flowing if the host + forgets to set it. + agent_framework: Framework that drives the agent — e.g. + ``"langchain"``, ``"openai_agents"``, ``"llamaindex"``, + ``"google_adk"``, ``"agent_framework"``, ``"mcp"``. + runtime_version: ``uipath-runtime`` package version. Resolved + from installed package metadata at construction; falls + back to ``"unknown"`` for source checkouts. + """ + + execution_engine: str = NATIVE_EXECUTION_ENGINE + agent_type: str = "unknown" + agent_framework: str = "unknown" + runtime_version: str = field(default_factory=_resolve_runtime_version) + + def as_payload(self) -> dict[str, str]: + """Return the metadata as a dict ready to merge into an event payload.""" + return { + "execution_engine": self.execution_engine, + "agent_type": self.agent_type, + "agent_framework": self.agent_framework, + "runtime_version": self.runtime_version, + } diff --git a/src/uipath/runtime/governance/_audit/traces.py b/src/uipath/runtime/governance/_audit/traces.py new file mode 100644 index 0000000..1c76e43 --- /dev/null +++ b/src/uipath/runtime/governance/_audit/traces.py @@ -0,0 +1,287 @@ +"""OpenTelemetry traces audit sink for governance events. + +Emits an OpenTelemetry span per rule evaluation and per hook summary. +This sink emits spans only — it does not resolve or stamp +job-execution metadata (organization, tenant, folder, job, trace id) +onto them. That resolution is owned by the platform-side OTel +exporter that ships spans downstream, so the runtime governance +contract stays scoped to span emission. +""" + +from __future__ import annotations + +import importlib.metadata +import logging +from typing import Any + +from uipath.core.governance import EnforcementMode + +from .base import AuditEvent, AuditSink, EventType + +logger = logging.getLogger(__name__) + + +def _package_version() -> str: + """Return the installed ``uipath-runtime`` version (``unknown`` if absent).""" + try: + return importlib.metadata.version("uipath-runtime") + except importlib.metadata.PackageNotFoundError: + return "unknown" + + +# Stamped on every governance span as ``uipath_governance.version`` so +# consumers can correlate the trace payload shape with the runtime +# release that produced it. Resolved once at import time — the installed +# package version doesn't change for the life of the process. +SCHEMA_VERSION = _package_version() + +# Value of the ``type`` / ``span_type`` span attributes on every +# governance span. Local to the runtime trace contract — kept as a +# string literal (not a cross-package import) so the runtime stays +# self-contained. +SPAN_TYPE_AGENT_RUN = "agentRun" + +# Set as the ``source`` attribute on every governance span. Lets +# consumers identify which producer emitted a given span when more +# than one governance producer feeds the same trace backend. +GOVERNANCE_SOURCE = "governance-checker-python" + +# Shared attribute namespace for every governance span attribute. +# Concatenated into each ``span.set_attribute`` call so the prefix +# appears in one place and a future rename is a one-line change. +NS = "uipath_governance" + +# Governance verdict / action vocabulary (UPPER_SNAKE). +EVALUATOR_ALLOW = "ALLOW" +EVALUATOR_DENY = "DENY" +EVALUATOR_HITL = "HITL" + +ACTION_ALLOW = "ALLOW" +ACTION_DENY = "DENY" +ACTION_HITL = "HITL" +ACTION_AUDIT = "AUDIT" +ACTION_NONE = "NONE" + + +def _resolve_mode(event: AuditEvent) -> EnforcementMode: + """Read the enforcement mode the evaluator stamped on the event. + + Mode travels with the event (set by the emitter when it calls + :meth:`AuditManager.emit_rule_evaluation` / + :meth:`emit_hook_summary` and passes its own per-instance mode) so + the sink doesn't read a process-global that wouldn't be + authoritative in a parallel-runtime setup. + + Falls back to ``AUDIT`` only when the field is missing — that's a + contract violation by the emitter (every governance event must carry + the mode), but defaulting to the safe option avoids a sink crash. + """ + mode = event.data.get("enforcement_mode") + if isinstance(mode, EnforcementMode): + return mode + if isinstance(mode, str): + try: + return EnforcementMode(mode.lower()) + except ValueError: + pass + return EnforcementMode.AUDIT + + +def _derive_results( + matched: bool, configured_action: str, mode: EnforcementMode +) -> tuple[str, str]: + """Return ``(evaluator_result, action_applied)`` in spec vocabulary. + + ``evaluator_result`` is mode-independent — what the rule decided. The + rule's configured ``audit`` action collapses into a DENY decision + here; whether that DENY is actually applied is reflected in + ``action_applied``. + + ``action_applied`` is mode-driven. Currently only AUDIT mode is wired + in the runtime, so every non-allow result lands on ``AUDIT``; the + ENFORCE branch is kept so the contract is already correct when + ENFORCE arrives in a later phase. + + The configured ``audit`` rule-level action acts as a per-rule audit + override: even when global mode is ENFORCE, such a rule only ever + produces ``action_applied = AUDIT``. This preserves today's "audit + never blocks" behavior. + """ + action = configured_action.lower() + + if not matched or action == "allow": + return EVALUATOR_ALLOW, ACTION_NONE + + if action == "escalate": + evaluator = EVALUATOR_HITL + else: + evaluator = EVALUATOR_DENY + + # Per-rule audit override: emit AUDIT regardless of global mode. + if action == "audit": + return evaluator, ACTION_AUDIT + + if mode == EnforcementMode.ENFORCE: + return evaluator, ACTION_DENY if evaluator == EVALUATOR_DENY else ACTION_HITL + return evaluator, ACTION_AUDIT + + +class TracesAuditSink(AuditSink): + """Audit sink that emits an OpenTelemetry span per governance event.""" + + def __init__(self) -> None: + """Initialize the sink with a deferred tracer and zero span count.""" + self._tracer: Any = None # Can be None, Tracer, or False + self._spans_created = 0 + + @property + def name(self) -> str: + """Constant sink identifier.""" + return "traces" + + def _get_tracer(self) -> Any: + """Get or create the OpenTelemetry tracer.""" + if self._tracer is None: + try: + from opentelemetry import trace + + self._tracer = trace.get_tracer("uipath.governance") + logger.info("OpenTelemetry tracer initialized for governance traces") + except ImportError: + logger.warning( + "OpenTelemetry not available — governance traces disabled." + ) + self._tracer = False + return self._tracer if self._tracer else None + + def emit(self, event: AuditEvent) -> None: + """Create a span for RULE_EVALUATION or HOOK_END events; drop others.""" + if event.event_type == EventType.RULE_EVALUATION: + self._emit_rule_span(event) + elif event.event_type == EventType.HOOK_END: + self._emit_hook_span(event) + + def _emit_hook_span(self, event: AuditEvent) -> None: + """Create a span for a hook summary (always emitted for each governance check).""" + tracer = self._get_tracer() + if tracer is None: + return + + try: + data = event.data + hook = event.hook or "unknown" + span_name = f"governance.{hook.lower()}" + + # Sink dispatch runs on the caller's thread (see + # :meth:`AuditManager.emit`), so the current OTel context + # is the agent's live span — the governance span attaches + # as its child without any cross-thread plumbing. + with tracer.start_as_current_span(span_name) as span: + span.set_attribute("type", SPAN_TYPE_AGENT_RUN) + span.set_attribute("span_type", SPAN_TYPE_AGENT_RUN) + span.set_attribute("uipath.custom_instrumentation", True) + span.set_attribute(f"{NS}.source", GOVERNANCE_SOURCE) + + # Mode travels on the event so parallel runtimes running + # different per-instance modes don't cross-contaminate. + mode = _resolve_mode(event) + final_action = data.get("final_action", "allow") + _, action_applied = _derive_results( + matched=final_action.lower() != "allow", + configured_action=final_action, + mode=mode, + ) + span.set_attribute(f"{NS}.hook", hook) + span.set_attribute(f"{NS}.action_applied", action_applied) + span.set_attribute(f"{NS}.mode", mode.value.upper()) + + # Hook spans are summary containers — severity lives on + # the per-rule spans. Marking the hook ERROR would paint + # the whole lifecycle phase as failed when only one rule + # fired beneath it. + + self._spans_created += 1 + + except Exception as e: + logger.warning("Failed to create governance hook span: %s", e) + + def _emit_rule_span(self, event: AuditEvent) -> None: + """Create a span for a rule evaluation.""" + tracer = self._get_tracer() + if tracer is None: + return + + try: + data = event.data + policy_id = data.get("policy_id", "unknown") + span_name = f"{NS}.rule.{policy_id}" + + # See _emit_hook_span: sync dispatch on the caller's + # thread means the current OTel context is the agent's + # live span, so this rule span attaches as its child. + with tracer.start_as_current_span(span_name) as span: + span.set_attribute("type", SPAN_TYPE_AGENT_RUN) + span.set_attribute("span_type", SPAN_TYPE_AGENT_RUN) + span.set_attribute("uipath.custom_instrumentation", True) + span.set_attribute(f"{NS}.source", GOVERNANCE_SOURCE) + + # Single source of truth for the emitted attributes + # below AND the verbosityLevel / Status decision further + # down. Mode comes from the event (per-instance) so + # parallel runtimes don't cross-contaminate. + mode = _resolve_mode(event) + configured_action = data.get("action", "allow") + matched = bool(data.get("matched", False)) + evaluator_result, action_applied = _derive_results( + matched=matched, + configured_action=configured_action, + mode=mode, + ) + + span.set_attribute(f"{NS}.policy_id", policy_id) + span.set_attribute(f"{NS}.rule_name", data.get("rule_name", "")) + span.set_attribute(f"{NS}.pack_name", data.get("pack_name", "")) + span.set_attribute(f"{NS}.hook", event.hook) + span.set_attribute(f"{NS}.evaluator_result", evaluator_result) + span.set_attribute(f"{NS}.action_applied", action_applied) + span.set_attribute(f"{NS}.mode", mode.value.upper()) + span.set_attribute(f"{NS}.version", SCHEMA_VERSION) + + detail = data.get("detail", "") + if detail: + span.set_attribute(f"{NS}.evidence", detail[:500]) + + # Severity is driven off the derived ``action_applied``: + # - DENY — runtime blocked → verbosityLevel=4 + + # Status.ERROR (agent span genuinely failed). + # - AUDIT / HITL — advisory, runtime did not block → + # verbosityLevel=3, Status stays UNSET. Marking the + # agent span failed for an advisory rule would mislead. + # - ALLOW / NONE — no verbosityLevel attribute set. + if action_applied == ACTION_DENY: + span.set_attribute("verbosityLevel", 4) + try: + from opentelemetry.trace import Status, StatusCode + + span.set_status( + Status( + StatusCode.ERROR, + f"Policy violation: " + f"{data.get('rule_name', policy_id)} " + f"(action={configured_action.lower()})", + ) + ) + except ImportError: + pass + elif action_applied in (ACTION_AUDIT, ACTION_HITL): + span.set_attribute("verbosityLevel", 3) + + self._spans_created += 1 + + except Exception as e: + logger.warning("Failed to create governance span: %s", e) + + @property + def spans_created(self) -> int: + """Number of spans created.""" + return self._spans_created diff --git a/src/uipath/runtime/governance/_audit/track_events.py b/src/uipath/runtime/governance/_audit/track_events.py new file mode 100644 index 0000000..8a2b745 --- /dev/null +++ b/src/uipath/runtime/governance/_audit/track_events.py @@ -0,0 +1,329 @@ +"""Telemetry sink for governance evaluation events. + +Submits custom telemetry events through a caller-supplied **non-blocking** +``track_event`` callable. The runtime layer does not own dispatch — the +host is responsible for supplying a callable that returns immediately +(typically a thread-pool-backed adapter around the real telemetry +client). Tests pass a mock that captures payloads. + +Event-rate policy (volume control): + +- DENIED rules (``matched=True``) → one ``governance.rule.denied`` event + per matched rule. +- PASSED + SKIPPED rules → one ``governance.hook.summary`` event per + hook with counts + the names of skipped rules + the count of + UiPath-mapped guardrails dispatched through the compensating path. + +Why: a 50-rule pack evaluated on every hook of every agent step would +multiply per-step telemetry calls by 50. Bundling the "nothing +happened" cases into a single hook summary cuts that to 1. +""" + +from __future__ import annotations + +import logging +from typing import Any, Callable + +from uipath.core.governance import EnforcementMode + +from .base import AuditEvent, AuditSink, EventType +from .metadata import GovernanceRuntimeMetadata + +logger = logging.getLogger(__name__) + + +TrackEventCallable = Callable[..., None] +"""Host-supplied telemetry callable. + +Expected kwargs: ``event_name: str``, ``data: dict | None``, +``operation_id: str | None``. The sink calls this synchronously from +the caller's hook thread, so the callable **MUST** be non-blocking — +the agent run shares that thread, and any wait propagates straight +into latency the agent observes. Hosts that need to do network I/O +are expected to wrap the underlying call in a thread-pool-backed +adapter that submits the work and returns immediately. +""" + + +EVENT_RULE_DENIED = "governance.rule.denied" +EVENT_HOOK_SUMMARY = "governance.hook.summary" + + +def _resolve_operation_id() -> str | None: + """Read the current OTel span's trace id for downstream correlation. + + Sink dispatch runs on the caller's thread (see + :meth:`AuditManager.emit`), so the live agent span is visible via + ``trace.get_current_span()`` directly. Rendered as a 32-char + lowercase hex string for use as a correlation id by the consumer. + + Returns ``None`` when: + + - OpenTelemetry isn't installed (sink no-ops gracefully). + - No span is recording (no trace context to correlate against). + + The live span is the single source of truth for trace correlation; + the sink does not consult environment variables. + """ + try: + from opentelemetry import trace + except ImportError: + return None + + span = trace.get_current_span() + span_ctx = span.get_span_context() + if not span_ctx.is_valid: + return None + return f"{span_ctx.trace_id:032x}" + + +def _mode_str(mode: Any) -> str: + """Coerce an enforcement-mode field to its canonical uppercase string.""" + if isinstance(mode, EnforcementMode): + return mode.value.upper() + if isinstance(mode, str): + return mode.upper() + return "AUDIT" + + +def _evaluator_result(action: str) -> str: + """Map a rule's configured action to the spec-vocabulary verdict. + + Mirrors :func:`uipath.runtime.governance._audit.traces._derive_results` + so both sinks agree on the (matched, action) → verdict mapping. + """ + action_lc = action.lower() + if action_lc == "deny": + return "DENY" + if action_lc == "escalate": + return "HITL" + if action_lc == "audit": + # The rule wanted to deny but was tagged audit-only at the + # check level — the evaluator's intent is still "deny". + return "DENY" + return "ALLOW" + + +def _action_applied(evaluator_result: str, configured_action: str, mode: str) -> str: + """Mode-adjusted action: AUDIT mode collapses DENY/HITL into AUDIT.""" + if mode == "AUDIT": + if evaluator_result in ("DENY", "HITL"): + return "AUDIT" + return "NONE" + # ENFORCE mode: per-rule ``audit`` override stays AUDIT. + if configured_action.lower() == "audit": + return "AUDIT" + return evaluator_result if evaluator_result != "ALLOW" else "NONE" + + +class TrackEventAuditSink(AuditSink): + """Sink that emits governance telemetry via the injected ``track_event``. + + Volume-controlled per the module docstring: individual events only + for denials, one aggregated event per hook for passed / skipped / + dispatched. Other event types are dropped at :meth:`accepts`. + + The ``track_event`` callable is invoked synchronously on the + caller's hook thread, so the callable must be non-blocking — see + the :class:`TrackEventCallable` type alias for the contract the + host is expected to satisfy. + """ + + SINK_NAME = "track_events" + + def __init__( + self, + track_event: TrackEventCallable, + runtime_metadata: GovernanceRuntimeMetadata, + *, + name: str = SINK_NAME, + ) -> None: + """Initialize the sink. + + Args: + track_event: Host-supplied **non-blocking** telemetry + callable. Receives ``event_name``, ``data``, + ``operation_id`` kwargs. The sink invokes it + synchronously from the agent's hook thread, so any + network or otherwise blocking work in the underlying + implementation must be offloaded by the host (e.g., + via a thread-pool-backed adapter). Tests pass a + capture callable. **Required** — ``None`` is a wiring + bug and is rejected here so the manager's registration + try/except surfaces it as a clear warning rather than + letting a ``TypeError`` fire on the first event. + runtime_metadata: Per-run constants stamped on every event + (execution engine, agent type, agent framework, runtime + version). + name: Sink name used for circuit-breaker accounting in the + manager. Override only if more than one telemetry sink + of this kind is registered against the same manager. + """ + if track_event is None: + raise ValueError( + "TrackEventAuditSink requires a non-None track_event callable. " + "The host is expected to supply a non-blocking adapter — " + "wiring a blocking client (e.g., raw HTTP) on the agent's " + "hook thread will block the agent on every governance event." + ) + self._track_event = track_event + self._meta = runtime_metadata + self._name = name + + @property + def name(self) -> str: + return self._name + + def accepts(self, event: AuditEvent) -> bool: + """Filter the audit stream down to denials + non-empty hook summaries. + + Drops: + + - **Any event whose mode is** :attr:`EnforcementMode.DISABLED` + — governance is off; emit nothing. The evaluator short-circuits + before ``_emit_audit`` in this case, so in practice the sink + shouldn't see these, but the guard here is belt-and-suspenders + against any future emitter that bypasses the short-circuit. + - Rules that didn't match (``matched=False``) — rolled into the + hook summary's ``passed_count``. + - Rules that matched but whose configured ``action`` is + ``allow`` — a positive informational match isn't a denial; + rolled into the hook summary too. + - **Empty hook summaries** — ``total_rules=0`` AND + ``skipped_count=0`` means nothing was evaluated and nothing + was deliberately skipped. Zero operator value; suppressed. + (A summary with ``skipped_count>0`` still fires because the + ``skipped_policy_names`` payload is operator-relevant — it + shows which policies a tenant turned off.) + - Other event types (``hook_start``, ``session_*``, generic + violations) — out of scope for this sink's telemetry surface. + + The result is bounded volume: at most one ``rule.denied`` event + per matched-and-restrictive rule + at most one + ``hook.summary`` per hook end (and only when it carries data). + """ + if _mode_str(event.data.get("enforcement_mode")) == "DISABLED": + return False + + if event.event_type == EventType.RULE_EVALUATION: + if not event.data.get("matched"): + return False + action = str(event.data.get("action") or "allow").lower() + return action != "allow" + if event.event_type == EventType.HOOK_END: + data = event.data + total = int(data.get("total_rules") or 0) + skipped = int(data.get("skipped_count") or 0) + return not (total == 0 and skipped == 0) + return False + + def emit(self, event: AuditEvent) -> None: + """Render the event and dispatch via the injected callable. + + Re-checks ``matched`` for rule evaluations as a defense-in-depth + guard. :meth:`accepts` already drops passed rules at the + :class:`AuditManager` dispatch boundary, but a direct + ``sink.emit(event)`` call (tests, future alternate dispatch + paths) must not route a passed rule into the + ``governance.rule.denied`` telemetry stream. + + Errors from ``track_event`` propagate to the audit manager, + which has its own circuit breaker (10 consecutive failures → + sink tripped for the rest of the process). The sink itself + doesn't catch — letting the manager track failure rate is the + whole point of the sink-failure protocol. + """ + # DISABLED governance = no telemetry, full stop. Same + # defense-in-depth rationale as the matched/allow check below: + # ``accepts`` drops these at the manager boundary, but a + # direct ``sink.emit`` call must not leak a DISABLED-mode + # event downstream either. + if _mode_str(event.data.get("enforcement_mode")) == "DISABLED": + return + + if event.event_type == EventType.RULE_EVALUATION: + if not event.data.get("matched"): + return + action = str(event.data.get("action") or "allow").lower() + if action == "allow": + # Positive informational match — not a denial. Same + # defense-in-depth rationale as the ``matched`` check + # above: ``accepts`` drops these at the manager + # boundary, but a direct ``sink.emit`` call must not + # leak them into the ``rule.denied`` stream. + return + self._emit_rule_denied(event) + elif event.event_type == EventType.HOOK_END: + data = event.data + total = int(data.get("total_rules") or 0) + skipped = int(data.get("skipped_count") or 0) + if total == 0 and skipped == 0: + # Empty hook — same defense-in-depth as the disabled + # mode and matched-allow filters. + return + self._emit_hook_summary(event) + # Other event types are filtered out at accepts(); reaching + # here for anything else would be a contract violation by the + # manager, not the sink. + + def _common_payload(self, event: AuditEvent) -> dict[str, Any]: + """Per-runtime constants + event identifiers stamped on every payload.""" + payload: dict[str, Any] = dict(self._meta.as_payload()) + payload["agent_name"] = event.agent_name + payload["hook"] = event.hook + payload["timestamp"] = event.timestamp.isoformat() + return payload + + def _emit_rule_denied(self, event: AuditEvent) -> None: + """Emit one ``governance.rule.denied`` per matched rule.""" + data = event.data + mode = _mode_str(data.get("enforcement_mode")) + configured_action = str(data.get("action") or "allow") + evaluator_result = _evaluator_result(configured_action) + action_applied = _action_applied(evaluator_result, configured_action, mode) + + payload = self._common_payload(event) + payload.update( + { + "pack": str(data.get("pack_name") or ""), + "clause": str(data.get("policy_id") or ""), + "rule_name": str(data.get("rule_name") or ""), + "mode": mode, + "evaluator_result": evaluator_result, + "action_applied": action_applied, + "duration_ms": float(data.get("duration_ms") or 0.0), + "mapped_to_uipath": bool(data.get("mapped_to_uipath", False)), + "detail": str(data.get("detail") or ""), + } + ) + self._track_event( + event_name=EVENT_RULE_DENIED, + data=payload, + operation_id=_resolve_operation_id(), + ) + + def _emit_hook_summary(self, event: AuditEvent) -> None: + """Emit one ``governance.hook.summary`` per hook end.""" + data = event.data + mode = _mode_str(data.get("enforcement_mode")) + + payload = self._common_payload(event) + payload.update( + { + "mode": mode, + "passed_count": int(data.get("passed_count") or 0), + "skipped_count": int(data.get("skipped_count") or 0), + "skipped_policy_names": list(data.get("skipped_policy_names") or []), + "denied_count": int(data.get("denied_count") or 0), + "guardrail_dispatched_count": int( + data.get("guardrail_dispatched_count") or 0 + ), + "duration_ms": float(data.get("duration_ms") or 0.0), + "final_action": str(data.get("final_action") or "allow").upper(), + } + ) + self._track_event( + event_name=EVENT_HOOK_SUMMARY, + data=payload, + operation_id=_resolve_operation_id(), + ) diff --git a/src/uipath/runtime/governance/native/__init__.py b/src/uipath/runtime/governance/native/__init__.py new file mode 100644 index 0000000..e3bca07 --- /dev/null +++ b/src/uipath/runtime/governance/native/__init__.py @@ -0,0 +1,40 @@ +"""Native UiPath governance policy evaluator. + +Rules evaluated in-process at each agent lifecycle hook. The caller +fetches the policy pack and compiles it into a :class:`PolicyIndex` +outside this package — the runtime never sees the wire format. Any +provider, any code path, any format is fair game; this package only +consumes the compiled index. + +This subpackage owns: + +- :class:`GovernanceEvaluator` – the evaluator implementation. +- The native policy model: :class:`Rule`, :class:`Check`, + :class:`Condition`, :class:`PolicyIndex`, :class:`PolicyPack`. + +Shared output types (``Action``, ``AuditRecord``, …) live in +:mod:`uipath.core.governance`. +""" + +from .evaluator import GovernanceEvaluator +from .models import ( + Check, + CheckContext, + Condition, + PolicyIndex, + PolicyPack, + Rule, + Severity, +) + +__all__ = [ + "GovernanceEvaluator", + # Native policy model + "Check", + "CheckContext", + "Condition", + "PolicyIndex", + "PolicyPack", + "Rule", + "Severity", +] diff --git a/src/uipath/runtime/governance/native/evaluator.py b/src/uipath/runtime/governance/native/evaluator.py new file mode 100644 index 0000000..a9c60a6 --- /dev/null +++ b/src/uipath/runtime/governance/native/evaluator.py @@ -0,0 +1,1188 @@ +"""Governance rule evaluator. + +Instance-scoped — every :class:`GovernanceRuntime` constructs its own +evaluator with explicit dependencies (audit manager, compensator, +enforcement mode). The evaluator does not reach across the runtime +layer through process-globals; the wiring layer composes the runtime +graph and the evaluator consumes what it's given. +""" + +from __future__ import annotations + +import logging +import math +import re +import time +from collections import Counter +from datetime import datetime, timezone +from functools import cache, lru_cache +from typing import Any + +from uipath.core.governance import EnforcementMode +from uipath.core.governance.exceptions import GovernanceBlockException +from uipath.core.governance.models import ( + Action, + AuditRecord, + LifecycleHook, + RuleEvaluation, +) + +from uipath.runtime.governance._audit.base import AuditManager +from uipath.runtime.governance.native.guardrail_compensation import ( + GuardrailCompensator, + disabled_guardrails, +) +from uipath.runtime.governance.native.models import ( + Check, + CheckContext, + Condition, + PolicyIndex, + Rule, +) + +logger = logging.getLogger(__name__) + + +def _compensation_data_for_hook(context: CheckContext) -> dict[str, Any]: + """Build the ``data`` payload for the compensating-governance call. + + Forwards whichever :class:`CheckContext` field is populated for the + active hook so the compensating call evaluates the same content + the evaluator was looking at. Fields not relevant to the hook are + omitted to keep the payload tight. + """ + if context.hook in (LifecycleHook.BEFORE_AGENT,): + return {"content": context.agent_input} + if context.hook in (LifecycleHook.AFTER_AGENT,): + return {"content": context.agent_output} + if context.hook in (LifecycleHook.BEFORE_MODEL,): + payload: dict[str, Any] = {"content": context.model_input} + if context.messages: + payload["messages"] = context.messages + return payload + if context.hook in (LifecycleHook.AFTER_MODEL,): + return {"content": context.model_output} + if context.hook in (LifecycleHook.TOOL_CALL,): + return {"tool_name": context.tool_name, "tool_args": context.tool_args} + if context.hook in (LifecycleHook.AFTER_TOOL,): + return {"tool_name": context.tool_name, "tool_result": context.tool_result} + # Memory-write and unknown hooks: pass an empty content so the + # server still receives a structurally-valid payload. + return {"content": ""} + + +@lru_cache(maxsize=256) +def _compile_regex(pattern: str) -> re.Pattern[str] | None: + """Compile and cache a regex pattern. + + Args: + pattern: The regex pattern string + + Returns: + Compiled pattern or None if invalid + """ + try: + return re.compile(pattern) + except re.error as e: + logger.warning("Invalid regex pattern '%s': %s", pattern, e) + return None + + +# --- vaderSentiment: lazy-imported singleton --- +# Hard dependency, but lazy-loaded to keep import-time cost off the +# critical path. The except branch is defence against a corrupted +# install (file present in METADATA but module unimportable) — the +# operator no-ops rather than crashing the agent. +@cache +def _get_vader_analyzer() -> Any: + """Return a cached SentimentIntensityAnalyzer, or None if unavailable.""" + try: + from vaderSentiment.vaderSentiment import ( # type: ignore[import-untyped] + SentimentIntensityAnalyzer, + ) + + return SentimentIntensityAnalyzer() + except ImportError: + logger.error( + "vaderSentiment failed to import despite being a hard dependency; " + "sentiment_concern checks will not fire." + ) + return None + + +# --- chardet: lazy-imported module for encoding integrity (A.7.4) --- +# Hard dependency, lazy-loaded for symmetry with the other library +# wrappers. The except branch covers corrupted installs only. +@cache +def _get_chardet() -> Any: + """Return the chardet module, or None if unavailable.""" + try: + import chardet + + return chardet + except ImportError: + logger.error( + "chardet failed to import despite being a hard dependency; " + "encoding_concern confidence check will not fire (stdlib " + "signals still apply)." + ) + return None + + +# --- Static patterns for encoding_concern (A.7.4) --- +# Latin-1-as-UTF-8 mojibake bigrams — the visible artefacts when +# UTF-8-encoded text is re-decoded as Latin-1 / Windows-1252. +_MOJIBAKE_BIGRAMS: tuple[str, ...] = ( + "é", + "è", + "â", + "à ", + "ù", + "î", + "ô", + "ç", # accented vowels + "Ä", + "Ö", + "Ãœ", + "ß", # German umlauts / eszett + "’", + "“", + "â€\x9d", + "–", + "—", + "•", # smart quotes / dashes + "£", + "°", + "§", + "¶", + "©", + "®", # NBSP-leading symbols + "ï¿", + "¿½", # mojibake'd U+FFFD (0xEF 0xBF 0xBD as Latin-1) + "ï»", + "»¿", # mojibake'd BOM (0xEF 0xBB 0xBF as Latin-1) +) + +# Literal hex escape sequences ("\x80" as 4 source chars) indicate raw +# bytes leaked through a string layer rather than being decoded. +_HEX_ESCAPE_PATTERN = re.compile(r"\\x[0-9a-fA-F]{2}") + + +# --- Static patterns for incident_concern (A.8.4) --- +# Stdlib-only categorical taxonomy. Mirrors sentry-sdk's incident shape +# (categorical types over stack/status), but for string payloads from +# model output / tool result rather than exception objects. +_INCIDENT_PATTERNS: dict[str, list[re.Pattern[str]]] = { + "safety_refusal": [ + re.compile( + r"(?i)\b(i\s+(?:cannot|can'?t|am\s+unable\s+to|won'?t\s+be\s+able\s+to)" + r"\s+(?:help|assist|provide|answer|do\s+that))\b" + ), + re.compile(r"(?i)\b(i'?m\s+sorry,?\s+but\s+i\s+(?:cannot|can'?t))\b"), + re.compile(r"(?i)\b(against\s+my\s+(?:guidelines|policies|programming))\b"), + ], + "tool_failure": [ + re.compile( + r"\b(5\d{2})\b\s*(?:internal\s+server\s+error|service\s+unavailable)" + ), + re.compile(r"(?i)\b(ERR_[A-Z_]+|connection\s+refused|ECONNREFUSED)\b"), + re.compile(r"(?i)\b(timed?\s*out)\b"), + ], + "auth_failure": [ + re.compile(r"\b(401|403)\b\s*(?:unauthori[sz]ed|forbidden)"), + re.compile( + r"(?i)\b(authentication\s+failed|invalid\s+(?:token|credentials))\b" + ), + ], + "quota_exceeded": [ + re.compile(r"\b(429)\b"), + re.compile( + r"(?i)\b(rate\s+limit\s+exceeded|quota\s+exceeded|too\s+many\s+requests)\b" + ), + ], + "hallucination": [ + re.compile(r"(?i)\b(i\s+(?:made\s+(?:that|this)\s+up|am\s+just\s+guessing))\b"), + re.compile(r"(?i)\b(i\s+don'?t\s+actually\s+know|i\s+fabricat(?:ed|ing))\b"), + ], +} + +# --- Static patterns for commitment_concern (A.10.4) --- +# Commitment-language signals. The verb pattern covers both first-person +# promise verbs ("we will refund") and formal-business commitment markers +# common in proposal / SOW outputs ("Cost: $X", "fixed scope", +# "Deliverables", "Timeline: N days", "I propose"). Verb, amount, and +# deadline signals combine via OR semantics — see +# :meth:`_check_commitment_concern`. +_COMMITMENT_VERB_PATTERN = re.compile( + r"(?i)(" + # First-person promise / liability verbs + r"\brefund\b|\breimburse\b|" + r"\bwarranty\b|\bwarrant(?:y|ed|ies)\b|\bguarante[ed]+\b|" + r"\bsla\b|" + r"\bwaive[d]?\b|" + r"\b(?:we|i)\s+(?:will|shall|promise|commit|guarantee)\b|" + r"\b(?:we|i|i'?ll)\s+(?:deliver|provide|complete|finish|" + r"handover|hand\s+over|ship)\b|" + # Proposal / SOW commitment markers + r"\bfixed\s+(?:price|cost|fee|scope|bid|rate)\b|" + r"\bcost\s*:\s*\$?\d|" + r"\bquote\s*:\s*\$?\d|" + r"\bdeliverables?\b|" + r"\btimeline\s*:\s*\d+\s*(?:second|minute|hour|day|week|month|year)s?\b|" + r"\bI\s+propose\b" + r")" +) +# Currency-anchored amount detection. Requires a currency marker adjacent +# to the number so URL fragments (e.g. ``/667851``) don't false-positive. +# Covers symbol-then-number ($780) and number-then-code (780 USD). +# +# Bare percentages (``75%``, ``99.9%``) are deliberately NOT matched +# here — they fire on benign status / progress text ("75% complete", +# "99.9% uptime") under OR semantics. Real percentage-bearing +# commitments ("we'll give you a 20% discount", "refund 100%") still +# fire via the verb pattern. +_COMMITMENT_AMOUNT_FALLBACK = re.compile( + r"(?:\$|€|£|¥|₹|USD|EUR|GBP|JPY|INR)\s*\d[\d,]*(?:\.\d+)?" + r"|\b\d[\d,]*(?:\.\d+)?\s*(?:USD|EUR|GBP|JPY|INR|" + r"dollars?|euros?|pounds?|yen|rupees?)\b" +) +_COMMITMENT_DEADLINE_PATTERN = re.compile( + r"(?i)\bwithin\s+\d+\s*(?:second|minute|hour|day|week|month|year)s?\b" + r"|\bby\s+(?:tomorrow|next\s+\w+|\d+/\d+(?:/\d+)?)\b" +) + + +class GovernanceEvaluator: + """Evaluates governance rules against check contexts. + + Supports two enforcement modes: + + - ``AUDIT``: log all violations but never block (DENY collapses to + AUDIT in the final action). + - ``ENFORCE``: actually block on DENY rules — raises + :class:`GovernanceBlockException` and the agent stops. + + All dependencies (mode, audit manager, compensator) are injected + via the constructor. The evaluator does not consult any + process-global state — parallel runtimes (``uipath eval``) get + their own evaluator with their own audit + compensation pipelines. + """ + + def __init__( + self, + policy_index: PolicyIndex, + *, + enforcement_mode: EnforcementMode = EnforcementMode.AUDIT, + audit_manager: AuditManager | None = None, + compensator: GuardrailCompensator | None = None, + ) -> None: + """Initialize with a compiled policy index and runtime-scoped deps. + + Args: + policy_index: The compiled :class:`PolicyIndex` to evaluate. + Typically read from :attr:`GovernanceRuntime.policy_index` + — built by the caller from whatever policy source they + own; the evaluator only consumes the compiled index. + enforcement_mode: Mode the evaluator applies. Defaults to + ``AUDIT`` — the safe default for callers that don't + explicitly opt in to ENFORCE. The wiring layer should + pass ``runtime.enforcement_mode`` here so the evaluator + and the wrapping :class:`GovernanceRuntime` agree on a + single source of truth. + audit_manager: Per-runtime :class:`AuditManager`. When + ``None`` the evaluator runs silently (no audit events + emitted). Tests that don't care about emission can + leave this out. + compensator: Per-runtime :class:`GuardrailCompensator` + used to dispatch compensating-governance calls for + guardrail-fallback rules. When ``None`` such dispatch + is skipped — the evaluator still records the matched + rules in the :class:`AuditRecord`. + """ + self._policy_index = policy_index + self._enforcement_mode = enforcement_mode + self._audit_manager = audit_manager + self._compensator = compensator + + @property + def policy_index(self) -> PolicyIndex: + """Return the compiled policy index this evaluator runs against.""" + return self._policy_index + + @property + def mode(self) -> EnforcementMode: + """The enforcement mode this evaluator applies.""" + return self._enforcement_mode + + def is_audit_mode(self) -> bool: + """Check if running in audit-only mode.""" + return self._enforcement_mode == EnforcementMode.AUDIT + + def evaluate(self, context: CheckContext) -> AuditRecord: + """Evaluate rules registered for ``context.hook`` against the context. + + Only rules whose ``hook`` field matches the current lifecycle hook + are evaluated — a ``tool_call`` rule does not fire on + ``before_model``, and vice versa. This avoids running checks + against fields the context cannot provide and keeps the audit + stream scoped to the active phase. + + The final action depends on the enforcement mode: + - DISABLED mode: Short-circuit; no rules evaluated, no audit emitted. + - AUDIT mode: Even DENY rules result in AUDIT action (log only, don't block) + - ENFORCE mode: DENY rules result in DENY action AND a + :class:`GovernanceBlockException` is raised. + + Audit events (per-rule + hook summary) are emitted via the + :class:`AuditManager` injected at construction (skipped when + none was supplied). + + Args: + context: The check context with hook and content + + Returns: + AuditRecord with all evaluations and final action. + + Raises: + GovernanceBlockException: In ENFORCE mode when a DENY rule matches. + """ + mode = self._enforcement_mode + if mode == EnforcementMode.DISABLED: + return AuditRecord( + timestamp=datetime.now(timezone.utc), + agent_name=context.agent_name, + runtime_id=context.runtime_id, + hook=context.hook, + evaluations=[], + final_action=Action.ALLOW, + metadata={**context.metadata, "enforcement_mode": mode.value}, + ) + + rules = self._policy_index.get_rules_for_hook(context.hook) + + evaluations: list[RuleEvaluation] = [] + # Per-rule wall time (ms), keyed by rule_id. Forwarded to the + # telemetry sink via emit_rule_evaluation(duration_ms=...) so + # operators can see which rules are slow. + rule_durations: dict[str, float] = {} + # Disabled rules — never evaluated, surfaced in the hook + # summary's skipped_policy_names so dashboards can spot which + # policies a tenant turned off. + skipped_policy_ids: list[str] = [] + raw_action = Action.ALLOW # The action before mode adjustment + deny_would_fire = False # Track if DENY would have fired + + hook_start = time.monotonic() + + for rule in rules: + if not rule.enabled: + skipped_policy_ids.append(rule.rule_id) + continue + + rule_start = time.monotonic() + evaluation = self._evaluate_rule(rule, context) + rule_durations[rule.rule_id] = (time.monotonic() - rule_start) * 1000.0 + evaluations.append(evaluation) + + if evaluation.matched: + # Take the most restrictive action. Use evaluation.action + # (which already folds in per-check overrides), not + # rule.action, so check-level overrides are honored here too. + eval_action = evaluation.action + if eval_action == Action.DENY: + raw_action = Action.DENY + deny_would_fire = True + elif eval_action == Action.ESCALATE and raw_action != Action.DENY: + raw_action = Action.ESCALATE + elif eval_action == Action.AUDIT and raw_action == Action.ALLOW: + raw_action = Action.AUDIT + + hook_duration_ms = (time.monotonic() - hook_start) * 1000.0 + + # Apply enforcement mode + final_action = self._apply_enforcement_mode(raw_action) + + # Build metadata with mode info + record_metadata = dict(context.metadata) + record_metadata["enforcement_mode"] = mode.value + if deny_would_fire and self.is_audit_mode(): + record_metadata["audit_mode_would_deny"] = True + + audit = AuditRecord( + timestamp=datetime.now(timezone.utc), + agent_name=context.agent_name, + runtime_id=context.runtime_id, + hook=context.hook, + evaluations=evaluations, + final_action=final_action, + metadata=record_metadata, + ) + + self._emit_audit( + audit, + mode, + rule_durations=rule_durations, + skipped_policy_ids=skipped_policy_ids, + hook_duration_ms=hook_duration_ms, + ) + + # For any guardrail mapped to UiPath but currently disabled, + # dispatch a compensating-governance call via the injected + # compensator. The compensating call (provider-owned) runs the + # real guardrail check and writes its own audit trace — the + # evaluator does NOT emit a Python-side trace for these rules, + # to avoid double-writing. The provider is expected to be + # non-blocking (batched / async / fire-and-forget internally); + # the runtime layer no longer owns that scheduling. + self._dispatch_compensation(audit, context) + + if final_action == Action.DENY: + raise GovernanceBlockException.from_audit_record(audit) + + return audit + + def _dispatch_compensation(self, audit: AuditRecord, context: CheckContext) -> None: + """Dispatch compensating governance for any matched fallback rules. + + Delegates to the injected :class:`GuardrailCompensator`, which + builds the wire payload and hands it to the provider. This + method picks the fallback rules out of the audit, logs the + summary, and submits. + + No-op when no compensator was supplied at construction (e.g. + unit tests that don't care about the dispatch path). + """ + if self._compensator is None: + return + + try: + disabled = disabled_guardrails(audit, self._policy_index) + if not disabled: + return + + # Distinct validator names for the operator-facing log line. + validators = [rule.validator for rule in disabled] + + # Surface the disabled-guardrail fire-up: how many rules + # triggered the compensating call, and which validators + # they map to (e.g. pii_detection / prompt_injection / + # harmful_content). One line per dispatch so an operator + # can see the volume + breakdown at a glance. + logger.info( + "Compensating governance triggered: hook=%s, count=%d, validators=[%s]", + audit.hook.value, + len(disabled), + ", ".join(validators), + ) + + self._compensator.submit( + rules=disabled, + data=_compensation_data_for_hook(context), + hook=audit.hook.value, + src_timestamp=audit.timestamp.isoformat(), + agent_name=audit.agent_name, + runtime_id=audit.runtime_id, + ) + except Exception as exc: # noqa: BLE001 - fail-open + logger.warning("Failed to dispatch compensating governance call: %s", exc) + + def _emit_audit( + self, + audit: AuditRecord, + mode: EnforcementMode, + *, + rule_durations: dict[str, float] | None = None, + skipped_policy_ids: list[str] | None = None, + hook_duration_ms: float = 0.0, + ) -> None: + """Emit per-rule and hook-summary events to the injected audit manager. + + No-op when no audit manager was supplied at construction. The + per-runtime :class:`AuditManager` handles sink-level circuit + breaking; emission errors stay there and never break evaluation. + + Args: + audit: Resolved :class:`AuditRecord` produced by + :meth:`evaluate`. + mode: Active :class:`EnforcementMode`. + rule_durations: Per-rule wall time in ms, keyed by + ``rule_id``. Looked up when emitting individual + rule-evaluation events; unknown ids default to 0. + skipped_policy_ids: Ids of rules that were disabled and + therefore not evaluated. Folded into the hook + summary's ``skipped_policy_names``. + hook_duration_ms: Total wall time spent evaluating this + hook. Folded into the hook summary's ``duration_ms``. + """ + manager = self._audit_manager + if manager is None: + return + + hook_name = audit.hook.name + durations = rule_durations or {} + + # ``guardrail_fallback`` rules are traced by the compensating + # path (see :meth:`_dispatch_compensation`), which carries the + # actual validator verdict. Emitting a Python-side + # ``rule_evaluation`` event here would produce a duplicate + # trace carrying no verdict, so filter these rules out of every + # per-rule event the evaluator emits AND out of the hook + # summary's passed/denied counts. The summary keeps a separate + # ``guardrail_dispatched_count`` so the mapped-vs-unmapped + # dimension is still queryable. + emittable = [ + ev + for ev in audit.evaluations + if not self._is_guardrail_fallback_rule(ev.rule_id) + ] + guardrail_dispatched_count = sum( + 1 + for ev in audit.evaluations + if ev.matched and self._is_guardrail_fallback_rule(ev.rule_id) + ) + + # No emittable rules means every match this hook was a + # guardrail-fallback already traced by the compensation path. + # Skip the hook summary entirely — emitting it with + # total_rules=0 + the audit's overall final_action would + # double-count the compensation-owned verdict. + if not emittable: + return + + for evaluation in emittable: + manager.emit_rule_evaluation( + policy_id=evaluation.rule_id, + rule_name=evaluation.rule_name, + pack_name=evaluation.pack_name, + hook=hook_name, + matched=evaluation.matched, + action=evaluation.action.value if evaluation.matched else "allow", + enforcement_mode=mode, + detail=evaluation.detail, + agent_name=audit.agent_name, + description=evaluation.description, + duration_ms=durations.get(evaluation.rule_id, 0.0), + # Per-rule events the evaluator emits are never for + # UiPath-mapped guardrails (those are filtered out of + # ``emittable`` above and traced by the compensating + # path). Stamping ``False`` keeps the schema stable + # for sinks. + mapped_to_uipath=False, + ) + + # All summary metrics derive from ``emittable`` only — + # ``audit.final_action`` folded in fallback rules whose + # verdict travels on the compensation path, so using it here + # would mix the two trace paths' verdicts. + # + # ``matched_rules`` keeps the historical "any check matched" + # semantic (used by the legacy traces sink). ``denied_count`` + # is the precise spec verdict — only rules whose configured + # action would actually act (not ``allow``). A matched rule + # configured as ``allow`` is an explicit positive match and + # rolls into ``passed_count`` via the manager's arithmetic. + matched_rules = sum(1 for ev in emittable if ev.matched) + denied_count = sum( + 1 for ev in emittable if ev.matched and ev.action != Action.ALLOW + ) + summary_final_action = self._apply_enforcement_mode( + self._most_restrictive_matched_action(emittable) + ) + + manager.emit_hook_summary( + hook=hook_name, + agent_name=audit.agent_name, + total_rules=len(emittable), + matched_rules=matched_rules, + final_action=summary_final_action.value, + enforcement_mode=mode, + duration_ms=hook_duration_ms, + skipped_policy_names=list(skipped_policy_ids or []), + guardrail_dispatched_count=guardrail_dispatched_count, + denied_count=denied_count, + ) + + @staticmethod + def _most_restrictive_matched_action( + evals: list[RuleEvaluation], + ) -> Action: + """Return the most-restrictive matched action across ``evals``. + + Mirrors the cross-rule aggregation in :meth:`evaluate`: + DENY > ESCALATE > AUDIT > ALLOW. Unmatched rules contribute + nothing. + """ + result = Action.ALLOW + for ev in evals: + if not ev.matched: + continue + a = ev.action + if a == Action.DENY: + return Action.DENY + if a == Action.ESCALATE and result != Action.DENY: + result = Action.ESCALATE + elif a == Action.AUDIT and result == Action.ALLOW: + result = Action.AUDIT + return result + + def _is_guardrail_fallback_rule(self, rule_id: str) -> bool: + """Return True if the rule carries a ``guardrail_fallback`` condition. + + Such rules are traced by the compensating path, so the + evaluator must not emit a duplicate Python-side trace for them. + """ + rule = self._policy_index.get_rule(rule_id) + if rule is None: + return False + for check in rule.checks: + for cond in check.conditions: + if cond.operator == "guardrail_fallback": + return True + return False + + def _apply_enforcement_mode(self, raw_action: Action) -> Action: + """Apply enforcement mode to the raw action. + + In AUDIT mode: + - DENY becomes AUDIT (log but don't block) + - ESCALATE becomes AUDIT (log but don't escalate) + - AUDIT stays AUDIT + - ALLOW stays ALLOW + + In ENFORCE mode: + - All actions pass through unchanged + """ + if self._enforcement_mode == EnforcementMode.AUDIT: + if raw_action in (Action.DENY, Action.ESCALATE): + return Action.AUDIT + return raw_action + + def evaluate_before_agent( + self, + agent_input: str, + agent_name: str, + runtime_id: str, + model_name: str = "", + **kwargs: Any, + ) -> AuditRecord: + """Evaluate BEFORE_AGENT rules.""" + context = CheckContext( + hook=LifecycleHook.BEFORE_AGENT, + agent_name=agent_name, + runtime_id=runtime_id, + agent_input=agent_input, + model_name=model_name, + metadata=kwargs.get("metadata", {}), + ) + return self.evaluate(context) + + def evaluate_after_agent( + self, + agent_output: str, + agent_name: str, + runtime_id: str, + **kwargs: Any, + ) -> AuditRecord: + """Evaluate AFTER_AGENT rules.""" + context = CheckContext( + hook=LifecycleHook.AFTER_AGENT, + agent_name=agent_name, + runtime_id=runtime_id, + agent_output=agent_output, + metadata=kwargs.get("metadata", {}), + ) + return self.evaluate(context) + + def evaluate_before_model( + self, + model_input: str, + agent_name: str, + runtime_id: str, + messages: list[dict[str, Any]] | None = None, + model_name: str = "", + **kwargs: Any, + ) -> AuditRecord: + """Evaluate BEFORE_MODEL rules.""" + context = CheckContext( + hook=LifecycleHook.BEFORE_MODEL, + agent_name=agent_name, + runtime_id=runtime_id, + model_input=model_input, + model_name=model_name, + messages=messages or [], + metadata=kwargs.get("metadata", {}), + ) + return self.evaluate(context) + + def evaluate_after_model( + self, + model_output: str, + agent_name: str, + runtime_id: str, + **kwargs: Any, + ) -> AuditRecord: + """Evaluate AFTER_MODEL rules.""" + context = CheckContext( + hook=LifecycleHook.AFTER_MODEL, + agent_name=agent_name, + runtime_id=runtime_id, + model_output=model_output, + metadata=kwargs.get("metadata", {}), + ) + return self.evaluate(context) + + def evaluate_tool_call( + self, + tool_name: str, + tool_args: dict[str, Any], + agent_name: str, + runtime_id: str, + session_state: dict[str, Any] | None = None, + **kwargs: Any, + ) -> AuditRecord: + """Evaluate TOOL_CALL rules.""" + context = CheckContext( + hook=LifecycleHook.TOOL_CALL, + agent_name=agent_name, + runtime_id=runtime_id, + tool_name=tool_name, + tool_args=tool_args, + session_state=session_state or {}, + metadata=kwargs.get("metadata", {}), + ) + return self.evaluate(context) + + def evaluate_after_tool( + self, + tool_name: str, + tool_result: str, + agent_name: str, + runtime_id: str, + **kwargs: Any, + ) -> AuditRecord: + """Evaluate AFTER_TOOL rules.""" + context = CheckContext( + hook=LifecycleHook.AFTER_TOOL, + agent_name=agent_name, + runtime_id=runtime_id, + tool_name=tool_name, + tool_result=tool_result, + metadata=kwargs.get("metadata", {}), + ) + return self.evaluate(context) + + def _evaluate_rule(self, rule: Rule, context: CheckContext) -> RuleEvaluation: + """Evaluate a single rule against the context.""" + if not rule.checks: + # No checks = always matches (for audit-only rules) + return RuleEvaluation( + rule_id=rule.rule_id, + rule_name=rule.name, + matched=True, + detail="Rule has no conditions (always matches)", + pack_name=rule.pack_name, + action=rule.action, + description=rule.description, + ) + + check_results: list[dict[str, Any]] = [] + any_check_matched = False + # Resolve the rule's action from the MATCHED checks so per-check + # `action` overrides take effect. ``Check.action`` defaults to the + # rule's action (see _yaml_to_index), so for rules without an + # override this equals ``rule.action`` exactly. Take the most + # restrictive matched action (DENY > ESCALATE > AUDIT > ALLOW), + # mirroring evaluate()'s cross-rule aggregation. + matched_action = Action.ALLOW + + for check in rule.checks: + matched, detail = self._evaluate_check(check, context) + check_results.append( + { + "matched": matched, + "detail": detail, + "action": check.action.value, + } + ) + if matched: + any_check_matched = True + if check.action == Action.DENY: + matched_action = Action.DENY + elif check.action == Action.ESCALATE and matched_action != Action.DENY: + matched_action = Action.ESCALATE + elif check.action == Action.AUDIT and matched_action == Action.ALLOW: + matched_action = Action.AUDIT + + # Surface the FIRST matched check's message; falls back to the + # first check's detail (empty string when none matched) for + # backward compatibility with rules that have a single check. + first_matched_detail = next( + (cr["detail"] for cr in check_results if cr["matched"]), + check_results[0]["detail"] if check_results else "", + ) + + return RuleEvaluation( + rule_id=rule.rule_id, + rule_name=rule.name, + matched=any_check_matched, + detail=first_matched_detail, + pack_name=rule.pack_name, + action=matched_action if any_check_matched else Action.ALLOW, + description=rule.description, + check_results=check_results, + ) + + def _evaluate_check(self, check: Check, context: CheckContext) -> tuple[bool, str]: + """Evaluate a single check against the context.""" + if not check.conditions: + return True, "No conditions (always matches)" + + results = [] + for condition in check.conditions: + matched = self._evaluate_condition(condition, context) + results.append(matched) + + if check.logic == "any": + final_match = any(results) + else: # "all" is default + final_match = all(results) + + detail = check.message if final_match else "" + return final_match, detail + + def _evaluate_condition(self, condition: Condition, context: CheckContext) -> bool: + """Evaluate a single condition against the context.""" + field_value = self._get_field_value(condition.field, context) + result = self._apply_operator(condition.operator, field_value, condition.value) + + if condition.negate: + result = not result + + return result + + def _get_field_value(self, field: str, context: CheckContext) -> Any: + """Get a field value from the context.""" + parts = field.split(".") + + # Start with context + value: Any = context + + for part in parts: + if hasattr(value, part): + value = getattr(value, part) + elif isinstance(value, dict) and part in value: + value = value[part] + else: + return None + + return value + + def _apply_operator( + self, operator: str, field_value: Any, check_value: Any + ) -> bool: + """Apply an operator to compare field value against check value.""" + # Handle existence checks before the None check + if operator == "exists": + return field_value is not None + if operator == "not_exists": + return field_value is None + + # guardrail_fallback fires only when the guardrail is mapped to + # UiPath but its policy is disabled. Config travels in + # ``check_value``; the rule's ``field`` is unused (so + # ``field_value`` is ``None`` here, which is expected — we must + # special-case this before the generic ``None`` short-circuit + # below). + if operator == "guardrail_fallback": + cfg = check_value if isinstance(check_value, dict) else {} + return bool(cfg.get("mapped_to_uipath", False)) and not bool( + cfg.get("policy_enabled", True) + ) + + if field_value is None: + return False + + # Numeric operators don't need stringification — short-circuit + # before `str(field_value)` (expensive for dict / large payloads). + if operator in ("gt", "gte", "lt", "lte"): + try: + lhs = float(field_value) + rhs = float(check_value) + except (ValueError, TypeError): + return False + if operator == "gt": + return lhs > rhs + if operator == "gte": + return lhs >= rhs + if operator == "lt": + return lhs < rhs + return lhs <= rhs + + field_str = str(field_value) + + match operator: + case "equals" | "eq": + return field_str == str(check_value) + + case "not_equals" | "ne": + return field_str != str(check_value) + + case "contains": + return str(check_value).lower() in field_str.lower() + + case "not_contains": + return str(check_value).lower() not in field_str.lower() + + case "regex" | "matches": + compiled = _compile_regex(str(check_value)) + if compiled is None: + return False + return bool(compiled.search(field_str)) + + case "in_list": + if isinstance(check_value, list): + return field_str in check_value + return False + + case "not_in_list": + if isinstance(check_value, list): + return field_str not in check_value + return True + + case "vader_concern": + # VADER compound score <= threshold. + # check_value: dict like {"threshold": -0.3} (default -0.3) + return self._check_vader_concern(field_str, check_value) + + case "encoding_concern": + # chardet-backed encoding integrity check (A.7.4). + # check_value: dict with optional `min_confidence` (default 0.5) + # and `max_replacement_ratio` (default 0.05). + return self._check_encoding_concern(field_str, check_value) + + case "entropy_concern": + # Shannon entropy outside expected range (A.7.4). + # check_value: dict with optional `min` (default 1.5) and + # `max` (default 7.5) bits/byte. Stdlib only. + return self._check_entropy_concern(field_str, check_value) + + case "incident_concern": + # Categorical incident detection (A.8.4). + # check_value: dict with optional `categories` list + # (subset of safety_refusal/tool_failure/auth_failure/ + # quota_exceeded/hallucination). Default: all categories. + return self._check_incident_concern(field_str, check_value) + + case "commitment_concern": + # Customer commitment language detection (A.10.4). + # check_value: dict with optional `require_amount` (default + # True) and `require_deadline` (default False). Fires when + # a commitment verb co-occurs with the configured signals. + return self._check_commitment_concern(field_str, check_value) + + case _: + logger.debug("Unknown operator: %s", operator) + return False + + @staticmethod + def _check_vader_concern(text: str, params: Any) -> bool: + """Return True if VADER compound score on `text` is <= threshold. + + Args: + text: Text to analyse. + params: Either a dict with `threshold` key, or a numeric threshold + directly. Default threshold is -0.3 (clearly-negative). + + Returns: + True iff vaderSentiment is available AND compound score <= threshold. + Returns False on empty input or if the library is not installed — + sentiment checks no-op rather than crash. + """ + if not text or not text.strip(): + return False + + analyzer = _get_vader_analyzer() + if analyzer is None: + return False + + if isinstance(params, dict): + threshold = float(params.get("threshold", -0.3)) + else: + try: + threshold = float(params) + except (TypeError, ValueError): + threshold = -0.3 + + try: + compound = float(analyzer.polarity_scores(text)["compound"]) + except Exception as exc: # pragma: no cover - defensive + logger.debug("VADER analysis failed: %s", exc) + return False + + return compound <= threshold + + @staticmethod + def _check_encoding_concern(text: str, params: Any) -> bool: + r"""Return True if `text` shows encoding integrity issues. + + Sums multiple deterministic corruption signals against text length: + - U+FFFD replacement characters (already-decoded lossy text) + - Literal ``�`` escape sequences carried through a JSON + / repr layer rather than being decoded + - Literal ``\xHH`` hex escapes (raw bytes leaked into a string) + - Latin-1-as-UTF-8 mojibake bigrams (e.g. ``é``, ``’``) + If the corruption ratio exceeds ``max_replacement_ratio`` the + check fires. chardet (when installed) is consulted as a + secondary low-confidence signal. + """ + if not text or not text.strip(): + return False + + if not isinstance(params, dict): + params = {} + min_confidence = float(params.get("min_confidence", 0.5)) + max_replacement_ratio = float(params.get("max_replacement_ratio", 0.05)) + min_corruption_events = int(params.get("min_corruption_events", 2)) + + length = max(len(text), 1) + + replacement_chars = text.count("�") + literal_ufffd_escapes = text.count("\\ufffd") + hex_escapes = len(_HEX_ESCAPE_PATTERN.findall(text)) + mojibake_bigrams = sum(text.count(bigram) for bigram in _MOJIBAKE_BIGRAMS) + + # Absolute count of distinct corruption *events* (one per + # U+FFFD, one per literal escape sequence, one per mojibake + # bigram). Even diluted by a lot of clean text, a few of these + # in production output is a strong signal. + corruption_events = ( + replacement_chars + literal_ufffd_escapes + hex_escapes + mojibake_bigrams + ) + if corruption_events >= min_corruption_events: + return True + + # Ratio-based fallback for cases below the absolute floor: still + # catches very short payloads where a single corruption char is + # disproportionate. + # Weight each event by its source-char span so denser corruption + # in shorter text trips the ratio sooner: + # U+FFFD = 1 char, "�" = 6 chars, "\xHH" = 4 chars, + # mojibake bigram = 2 chars. + corruption_chars = ( + replacement_chars + + 6 * literal_ufffd_escapes + + 4 * hex_escapes + + 2 * mojibake_bigrams + ) + if corruption_chars / length > max_replacement_ratio: + return True + + # Secondary: chardet on the encoded bytes. For pure str input + # this almost always reports high UTF-8/ASCII confidence (the + # branch is intentionally permissive), but it does catch bytes + # routed through `repr()` or `__str__` of a `bytes` object that + # chardet recognises as a non-UTF8 encoding with low confidence. + chardet = _get_chardet() + if chardet is None: + return False + try: + detection = chardet.detect(text.encode("utf-8", errors="replace")) + confidence = float(detection.get("confidence") or 0.0) + except Exception as exc: # pragma: no cover - defensive + logger.debug("chardet detection failed: %s", exc) + return False + + return confidence < min_confidence + + @staticmethod + def _check_entropy_concern(text: str, params: Any) -> bool: + """Return True if Shannon entropy of `text` is outside an expected range. + + Stdlib-only. Entropy is computed in bits per symbol over byte + frequencies. English prose typically lands ~3.5–4.5 bits/byte; + binary noise approaches 8 bits/byte; constant/repetitive text + approaches 0. + """ + if not text or not text.strip(): + return False + + if not isinstance(params, dict): + params = {} + lo = float(params.get("min", 1.5)) + hi = float(params.get("max", 7.5)) + + data = text.encode("utf-8", errors="replace") + total = len(data) + if total == 0: + return False + + counts = Counter(data) + entropy = 0.0 + for c in counts.values(): + p = c / total + entropy -= p * math.log2(p) + + return entropy < lo or entropy > hi + + @staticmethod + def _check_incident_concern(text: str, params: Any) -> bool: + """Return True if `text` matches any configured incident pattern (A.8.4). + + Categories: safety_refusal, tool_failure, auth_failure, + quota_exceeded, hallucination. Pass ``{"categories": [...]}`` to + restrict; default scans all categories. + """ + if not text or not text.strip(): + return False + + if isinstance(params, dict): + requested = params.get("categories") + else: + requested = None + + if not requested: + categories = list(_INCIDENT_PATTERNS.keys()) + else: + categories = [c for c in requested if c in _INCIDENT_PATTERNS] + + for category in categories: + for pattern in _INCIDENT_PATTERNS[category]: + if pattern.search(text): + return True + return False + + @staticmethod + def _check_commitment_concern(text: str, params: Any) -> bool: + """Return True if `text` carries customer-commitment language (A.10.4). + + OR semantics: a commitment-verb match always fires; when + ``require_amount`` is true, a currency-anchored amount alone also + fires; when ``require_deadline`` is true, a deadline phrase alone + also fires. With both flags false the rule matches on verb only + (verb-only mode). + + The verb pattern covers first-person promise verbs *and* proposal + / SOW commitment markers ("Cost: $X", "fixed scope", + "Deliverables", "Timeline: N days", "I propose"). The amount + pattern requires a currency marker adjacent to the number so URL + fragments don't false-positive. + """ + if not text or not text.strip(): + return False + + if not isinstance(params, dict): + params = {} + require_amount = bool(params.get("require_amount", True)) + require_deadline = bool(params.get("require_deadline", False)) + + verb_match = bool(_COMMITMENT_VERB_PATTERN.search(text)) + + # Verb-only mode: neither supporting signal is enabled. + if not require_amount and not require_deadline: + return verb_match + + amount_match = require_amount and bool(_COMMITMENT_AMOUNT_FALLBACK.search(text)) + deadline_match = require_deadline and bool( + _COMMITMENT_DEADLINE_PATTERN.search(text) + ) + return verb_match or amount_match or deadline_match diff --git a/src/uipath/runtime/governance/native/guardrail_compensation.py b/src/uipath/runtime/governance/native/guardrail_compensation.py new file mode 100644 index 0000000..53fd688 --- /dev/null +++ b/src/uipath/runtime/governance/native/guardrail_compensation.py @@ -0,0 +1,183 @@ +"""Compensating governance for disabled centralized guardrails. + +When a ``guardrail_fallback`` rule fires, this module builds the +:class:`GovernRequest` wire payload and calls the injected +:class:`uipath.core.governance.GovernanceCompensationProvider`. The +provider runs the actual guardrail check and writes its own audit +trace; the runtime layer here only assembles the request. + +Synchronous dispatch on the caller's thread. The provider owns +non-blocking semantics (internal batching, async fire-and-forget, or +whatever scheduling the host wires) — the runtime layer no longer +holds a worker pool, semaphore, or process-exit cleanup for this +path. Same architectural shape as :class:`AuditManager`: runtime is +synchronous and pure; async export is the sink/provider's concern. +""" + +from __future__ import annotations + +import logging +from typing import Any + +from uipath.core.governance import ( + FiredRule, + GovernanceCompensationProvider, + GovernRequest, +) + +from .._audit.metadata import GovernanceRuntimeMetadata + +logger = logging.getLogger(__name__) + + +# ---------------------------------------------------------------------------- +# Stateless helpers +# ---------------------------------------------------------------------------- + + +def disabled_guardrails(audit: Any, policy_index: Any) -> list[FiredRule]: + """Return per-rule metadata for each fired guardrail-fallback rule. + + A guardrail rule fires only when it is mapped to UiPath + (``mapped_to_uipath`` true) but disabled (``policy_enabled`` false) — + see the ``guardrail_fallback`` operator. The validator name (e.g. + ``pii_detection``) is read from the rule's ``guardrail_fallback`` + check config and used as the validator on the compensating call. + + One :class:`FiredRule` entry is emitted per matching + ``guardrail_fallback`` condition. Rules in this codebase declare a + single fallback condition each, so the returned list has one entry + per fired rule in practice; multi-condition rules would emit more + than one entry sharing the same ``rule_id``. + """ + out: list[FiredRule] = [] + for ev in audit.evaluations: + if not ev.matched: + continue + rule = policy_index.get_rule(ev.rule_id) + if rule is None: + continue + for check in rule.checks: + for cond in check.conditions: + if cond.operator != "guardrail_fallback": + continue + if not isinstance(cond.value, dict): + continue + # The ``guardrail_fallback`` operator at evaluation time + # only matches when ``mapped_to_uipath=True`` AND + # ``policy_enabled=False``. We re-check here defensively + # so a future code path that bypasses the evaluator (or + # a multi-condition rule that fired on a sibling check) + # can't trigger a compensation call for a guardrail + # that isn't actually disabled. + if not bool(cond.value.get("mapped_to_uipath", False)): + continue + if bool(cond.value.get("policy_enabled", True)): + continue + validator = str(cond.value.get("validator", "")) + if validator: + out.append( + FiredRule( + rule_id=ev.rule_id, + rule_name=ev.rule_name, + pack_name=getattr(rule, "pack_name", "") or "", + validator=validator, + ) + ) + return out + + +def _validators(rules: list[FiredRule]) -> list[str]: + """Distinct validator names from the fired rules, preserving order.""" + return list(dict.fromkeys(r.validator for r in rules if r.validator)) + + +# ---------------------------------------------------------------------------- +# GuardrailCompensator +# ---------------------------------------------------------------------------- + + +class GuardrailCompensator: + """Synchronous dispatcher for compensating-governance calls. + + Builds the :class:`GovernRequest` payload and invokes the injected + provider's ``compensate`` method on the caller's thread. The + provider is expected to be non-blocking (batched internally, async + fire-and-forget, or otherwise scheduled off the agent's hook + thread) — the runtime layer owns no worker pool, semaphore, or + process-exit cleanup for this path. + + Per-call exceptions are caught and logged so a provider failure + never breaks the agent hook. + """ + + def __init__( + self, + provider: GovernanceCompensationProvider, + *, + runtime_metadata: GovernanceRuntimeMetadata | None = None, + ) -> None: + """Construct a compensator bound to one provider. + + Args: + provider: Host-supplied + :class:`GovernanceCompensationProvider`. ``compensate`` + is invoked synchronously on the agent's hook thread. + runtime_metadata: Per-run identity (agent framework / type / + runtime version) stamped onto the ``/runtime/govern`` call + so the server can attach it to the rule-denied telemetry it + emits. ``None`` leaves the fields unset (server defaults + them to ``unknown``). + """ + self._provider = provider + self._runtime_metadata = runtime_metadata + + def submit( + self, + rules: list[FiredRule], + data: dict[str, Any], + hook: str, + src_timestamp: str, + agent_name: str, + runtime_id: str, + ) -> None: + """Build the wire payload and hand it to the provider. + + Short-circuits on empty rules / empty validators. Per-call + provider exceptions are caught and logged. + """ + if not rules: + return + validators = _validators(rules) + if not validators: + return + + meta = self._runtime_metadata + request = GovernRequest( + validators=validators, + rules=rules, + data=data, + hook=hook, + src_timestamp=src_timestamp, + agent_name=agent_name, + runtime_id=runtime_id, + agent_framework=meta.agent_framework if meta else None, + agent_type=meta.agent_type if meta else None, + runtime_version=meta.runtime_version if meta else None, + ) + + try: + self._provider.compensate(request) + except Exception as exc: # noqa: BLE001 - fail-open by contract + logger.warning( + "Compensation provider call failed (validators=[%s]): %s", + ", ".join(validators), + exc, + ) + + def close(self) -> None: + """No-op — the compensator holds no resources. + + Kept on the API so callers that wire ``close()`` (e.g. shared + teardown patterns) don't need a branch for this class. + """ diff --git a/src/uipath/runtime/governance/native/models.py b/src/uipath/runtime/governance/native/models.py new file mode 100644 index 0000000..eb874a7 --- /dev/null +++ b/src/uipath/runtime/governance/native/models.py @@ -0,0 +1,162 @@ +"""Native policy model. + +Rules, checks, conditions and pack indexes consumed by the native +governance evaluator. + +These are the inputs of the native evaluator. The evaluator-agnostic +*output* types (``Action``, ``AuditRecord``, …) live in +:mod:`uipath.core.governance.models`. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from enum import Enum +from typing import Any + +from uipath.core.governance.models import Action, LifecycleHook + + +class Severity(Enum): + """Rule severity levels.""" + + LOW = "low" + MEDIUM = "medium" + HIGH = "high" + CRITICAL = "critical" + + +class Logic(str, Enum): + """How a check combines its conditions.""" + + ALL = "all" # AND — every condition must hold. + ANY = "any" # OR — any matching condition is a hit. + + +@dataclass +class Condition: + """A single condition within a rule check.""" + + operator: str + field: str + value: Any + negate: bool = False + + +@dataclass +class Check: + """A check within a rule - contains conditions and action.""" + + conditions: list[Condition] + action: Action = Action.DENY + message: str = "" + logic: Logic = Logic.ALL + + +@dataclass +class Rule: + """A compliance rule with checks evaluated at a specific lifecycle hook.""" + + rule_id: str + name: str + clause: str + hook: LifecycleHook + action: Action + severity: Severity = Severity.HIGH + checks: list[Check] = field(default_factory=list) + enabled: bool = True + description: str = "" + pack_name: str = "" + + # Approval configuration (for ESCALATE action) + approval_config: dict[str, Any] = field(default_factory=dict) + + +@dataclass +class CheckContext: + """Context passed to rule evaluation. + + Scoped to evaluator input data only. Trace correlation is + intentionally not carried here — that concern is owned by the + provider / platform layer, not by the evaluator input model. + """ + + hook: LifecycleHook + agent_name: str + runtime_id: str + + # Content fields (populated based on hook) + agent_input: str = "" + agent_output: str = "" + model_input: str = "" + model_output: str = "" + model_name: str = "" + tool_name: str = "" + tool_args: dict[str, Any] = field(default_factory=dict) + tool_result: str = "" + messages: list[dict[str, Any]] = field(default_factory=list) + + # Session state + session_state: dict[str, Any] = field(default_factory=dict) + metadata: dict[str, Any] = field(default_factory=dict) + + # Ring level (privilege level: 0=system, 1=admin, 2=user, 3=untrusted) + ring: int = 2 + + +@dataclass +class PolicyPack: + """A collection of rules for a compliance standard.""" + + name: str + version: str + description: str + rules: list[Rule] + enabled: bool = True + + +@dataclass +class PolicyIndex: + """Index of all loaded policy packs and rules.""" + + packs: dict[str, PolicyPack] = field(default_factory=dict) + _rules_by_id: dict[str, Rule] = field(default_factory=dict) + _rules_by_hook: dict[LifecycleHook, list[Rule]] = field(default_factory=dict) + + def add_pack(self, pack: PolicyPack) -> None: + """Add a policy pack to the index.""" + self.packs[pack.name] = pack + for rule in pack.rules: + rule.pack_name = pack.name + self._rules_by_id[rule.rule_id] = rule + if rule.hook not in self._rules_by_hook: + self._rules_by_hook[rule.hook] = [] + self._rules_by_hook[rule.hook].append(rule) + + def get_rule(self, rule_id: str) -> Rule | None: + """Get a rule by ID.""" + return self._rules_by_id.get(rule_id) + + def get_rules_for_hook(self, hook: LifecycleHook) -> list[Rule]: + """Get all rules for a lifecycle hook.""" + return self._rules_by_hook.get(hook, []) + + def get_rules_for_pack(self, pack_name: str) -> list[Rule]: + """Get all rules for a pack.""" + pack = self.packs.get(pack_name) + return pack.rules if pack else [] + + @property + def pack_names(self) -> list[str]: + """Get all pack names.""" + return list(self.packs.keys()) + + @property + def total_rules(self) -> int: + """Get total number of rules.""" + return len(self._rules_by_id) + + @property + def all_rules(self) -> list[Rule]: + """Get all rules.""" + return list(self._rules_by_id.values()) diff --git a/src/uipath/runtime/governance/runtime.py b/src/uipath/runtime/governance/runtime.py new file mode 100644 index 0000000..c9cf699 --- /dev/null +++ b/src/uipath/runtime/governance/runtime.py @@ -0,0 +1,301 @@ +"""Governance runtime wrapper. + +Wraps a :class:`UiPathRuntimeProtocol` delegate and carries a resolved +policy snapshot — a :class:`PolicyIndex` and :class:`EnforcementMode` +supplied by the caller. The wrapper performs no I/O at construction, +holds no background thread, retains no policy provider, and reads no +host environment variables. + +The caller is expected to: + +- resolve a policy pack for the current run — any provider, any code + path, any wire format, +- produce a :class:`~uipath.runtime.governance.native.PolicyIndex` + from that policy; the runtime is format-agnostic and only accepts a + compiled index, +- skip wrapping entirely when the resolved enforcement mode is + :attr:`EnforcementMode.DISABLED`, +- pass the resolved ``PolicyIndex`` and ``EnforcementMode`` into the + constructor. + +The wrapper owns the BEFORE_AGENT / AFTER_AGENT lifecycle boundary +when an evaluator is supplied at construction. Framework adapters +intentionally skip chain-level events so nested chain runs don't fire +duplicate boundary evaluations; the runtime layer is the unambiguous +"one invocation = one boundary" point, so it owns those hooks. Per-step +hooks (BEFORE_MODEL, AFTER_MODEL, TOOL_CALL, AFTER_TOOL) are fired by +adapters that observe per-step events. + +Trace correlation: :meth:`UiPathGovernedRuntime.execute` and +:meth:`UiPathGovernedRuntime.stream` open a single OTel span that +wraps BEFORE_AGENT, the delegate's run (including any framework +adapter spans), and AFTER_AGENT. The span inherits the host's +ambient context when one is set, or opens a new root trace +otherwise. Every governance event emitted under that span shares +its ``trace_id``, so runtime-layer telemetry and framework-layer +OTel spans correlate end-to-end. Downstream consumers map that +``trace_id`` to whatever correlation field they use. + +The governance compensator dispatches synchronously on the caller's +thread; the injected compensation provider resolves the canonical +trace id at call time. The runtime layer remains env-free for that +path. +""" + +from __future__ import annotations + +import json +import logging +from contextlib import contextmanager +from typing import Any, AsyncGenerator, Iterator + +from uipath.core.governance import EnforcementMode +from uipath.core.governance.exceptions import GovernanceBlockException +from uipath.core.serialization import serialize_object + +from uipath.runtime.base import ( + UiPathExecuteOptions, + UiPathRuntimeProtocol, + UiPathStreamOptions, +) +from uipath.runtime.events import UiPathRuntimeEvent +from uipath.runtime.governance.native.evaluator import GovernanceEvaluator +from uipath.runtime.governance.native.models import PolicyIndex +from uipath.runtime.result import UiPathRuntimeResult +from uipath.runtime.schema import UiPathRuntimeSchema + +logger = logging.getLogger(__name__) + + +@contextmanager +def _governance_root_span(agent_name: str, runtime_id: str) -> Iterator[None]: + """Open the governance run's root OTel span if OTel is available. + + Every governance event and every framework OTel span emitted + inside this block inherits the span's ``trace_id``. The result + is one trace per agent run that correlates BEFORE_AGENT, + BEFORE_MODEL / AFTER_MODEL, AFTER_AGENT, and any per-rule + governance events. + + Behavior matrix: + + - **OTel installed + host opened a parent span**: this becomes a + child of the host's span and inherits its ``trace_id`` — the + host's outer correlation context is preserved end-to-end. + - **OTel installed + no parent span**: this becomes the root + span of a fresh trace; everything below it shares the new + ``trace_id``. + - **OTel not installed**: no-op context manager — the wrapper + degrades gracefully (no spans, no correlation, but the + runtime still functions). + + Lazy import mirrors + :func:`uipath.runtime.governance._audit.track_events._resolve_operation_id`: + OTel is a transitive runtime dependency, but the wrapper must + not crash if a downstream host strips it. + """ + try: + from opentelemetry import trace + except ImportError: + yield + return + + tracer = trace.get_tracer("uipath.runtime.governance") + # No explicit ``context=`` → OTel picks up the ambient context. + # If the host wrapped this call in its own span, we become its + # child (same trace_id). Otherwise we open a root span (new + # trace_id). + with tracer.start_as_current_span("uipath.governance.run") as span: + # Span attributes for downstream consumers. ``agent_name`` + # and ``runtime_id`` are the primary keys an operator + # filters on; ``source`` identifies which producer emitted + # the span (mirrors the constant used by + # :class:`TracesAuditSink` so consumers stay consistent). + if agent_name: + span.set_attribute("uipath_governance.agent_name", agent_name) + if runtime_id: + span.set_attribute("uipath_governance.runtime_id", runtime_id) + span.set_attribute("uipath_governance.source", "governance-runtime-python") + yield + + +def _serialize_payload(payload: Any) -> str: + """Serialize an agent input / output to a string for evaluator checks. + + The native evaluator's BEFORE_AGENT / AFTER_AGENT checks scan a + flat string. ``None`` becomes ``""``, ``str`` passes through (so + regex / sentiment checks don't see JSON quotes around the bare + text), and everything else is normalized via + :func:`uipath.core.serialization.serialize_object` (handles + Pydantic / dataclass / datetime / nested structures) and then + JSON-encoded. + """ + if payload is None: + return "" + if isinstance(payload, str): + return payload + try: + return json.dumps(serialize_object(payload)) + except Exception: # noqa: BLE001 — last-resort string fallback + return str(payload) + + +class UiPathGovernedRuntime: + """Governance wrapper over a :class:`UiPathRuntimeProtocol` delegate. + + Holds a caller-resolved :class:`PolicyIndex` and + :class:`EnforcementMode` for the lifetime of the instance. + ``execute`` / ``stream`` / ``get_schema`` forward to the delegate. + ``dispose`` is a no-op — the caller owns the delegate (and every + other host-managed resource) and is responsible for tearing them + down. The method is kept only to satisfy + :class:`UiPathDisposableProtocol` so the wrapper stays + structurally substitutable for any :class:`UiPathRuntimeProtocol`. + + When ``evaluator`` is supplied, :meth:`execute` and :meth:`stream` + fire ``BEFORE_AGENT`` before delegating and ``AFTER_AGENT`` after a + successful return. Without an evaluator the wrapper is a pure + pass-through. + """ + + def __init__( + self, + delegate: UiPathRuntimeProtocol, + policy_index: PolicyIndex, + enforcement_mode: EnforcementMode, + *, + evaluator: GovernanceEvaluator | None = None, + agent_name: str = "", + runtime_id: str = "", + ): + """Initialize the governance runtime with a resolved policy snapshot. + + Args: + delegate: The wrapped runtime to forward execution to. + policy_index: Resolved :class:`PolicyIndex` built from the + provider's :class:`PolicyResponse`. Pass an empty + ``PolicyIndex()`` to attach the wrapper without any + rules (useful when the wrapper exists for audit + emission only). + enforcement_mode: Resolved :class:`EnforcementMode` from + the provider's :class:`PolicyResponse`. The caller is + expected to skip wrapping entirely when the response + mode is :attr:`EnforcementMode.DISABLED`; this + constructor does not check. + evaluator: Optional :class:`GovernanceEvaluator` that + drives BEFORE_AGENT / AFTER_AGENT inside + :meth:`execute` / :meth:`stream`. When ``None`` the + wrapper is a pure passthrough — the caller is expected + to fire those evaluations itself. + agent_name: Name of the agent (the runtime's entrypoint). + Passed through to the evaluator's hook methods. + runtime_id: Runtime-instance id (conversation id, job id, + or a synthetic per-run id). Passed through so + per-runtime state routes cleanly. + """ + self._delegate = delegate + self._policy_index = policy_index + self._enforcement_mode = enforcement_mode + self._evaluator = evaluator + self._agent_name = agent_name + self._runtime_id = runtime_id + + def _fire_before_agent(self, input: Any) -> None: + """Fire BEFORE_AGENT when an evaluator is wired; otherwise no-op. + + ``GovernanceBlockException`` propagates — that's how + ENFORCE-mode DENY rules halt a run. Anything else is logged + and swallowed so a governance bug never breaks the agent. + """ + if self._evaluator is None: + return + try: + self._evaluator.evaluate_before_agent( + agent_input=_serialize_payload(input), + agent_name=self._agent_name, + runtime_id=self._runtime_id, + ) + except GovernanceBlockException: + raise + except Exception as exc: # noqa: BLE001 — never break a run on audit failure + logger.warning("BEFORE_AGENT governance evaluation failed: %s", exc) + + def _fire_after_agent(self, result: UiPathRuntimeResult) -> None: + """Fire AFTER_AGENT against ``result.output``. + + Same exception policy as :meth:`_fire_before_agent`. + """ + if self._evaluator is None: + return + try: + self._evaluator.evaluate_after_agent( + agent_output=_serialize_payload(result.output), + agent_name=self._agent_name, + runtime_id=self._runtime_id, + ) + except GovernanceBlockException: + raise + except Exception as exc: # noqa: BLE001 + logger.warning("AFTER_AGENT governance evaluation failed: %s", exc) + + async def execute( + self, + input: dict[str, Any] | None = None, + options: UiPathExecuteOptions | None = None, + ) -> UiPathRuntimeResult: + """Execute the delegate, firing BEFORE_AGENT / AFTER_AGENT around it. + + Wraps the entire invocation — BEFORE_AGENT, delegate execution + (which may itself open framework spans), and AFTER_AGENT — in + a single OTel span. The shared ``trace_id`` unifies the + runtime-side governance events with any framework-side OTel + spans the delegate emits. + + AFTER_AGENT fires only on successful return — if the delegate + raises, there's no output to evaluate. + """ + with _governance_root_span(self._agent_name, self._runtime_id): + self._fire_before_agent(input) + result = await self._delegate.execute(input, options=options) + self._fire_after_agent(result) + return result + + async def stream( + self, + input: dict[str, Any] | None = None, + options: UiPathStreamOptions | None = None, + ) -> AsyncGenerator[UiPathRuntimeEvent, None]: + """Stream events from the delegate, firing BEFORE_AGENT first. + + Same root-span wrap as :meth:`execute`. Holding the span + across ``async for`` is safe — Python asyncio propagates + contextvars (including the OTel current-span pointer) across + ``await`` suspensions. + + AFTER_AGENT fires once a :class:`UiPathRuntimeResult` event is + observed in the stream — that's the runtime's contract for + signalling a completed invocation. Intermediate state events + pass through untouched. + """ + with _governance_root_span(self._agent_name, self._runtime_id): + self._fire_before_agent(input) + async for event in self._delegate.stream(input, options=options): + if isinstance(event, UiPathRuntimeResult): + self._fire_after_agent(event) + yield event + + async def get_schema(self) -> UiPathRuntimeSchema: + """Forward schema lookup to the delegate.""" + return await self._delegate.get_schema() + + async def dispose(self) -> None: + """No-op — the caller owns delegate + host-resource lifecycle. + + The wrapper deliberately does not forward to + ``self._delegate.dispose()`` (the caller instantiated the + delegate and is responsible for disposing it) and does not + invoke any host-supplied cleanup hook (the host runs its own + teardown on the same code path). Kept as a method purely to + satisfy :class:`UiPathDisposableProtocol` — the wrapper stays + structurally substitutable for any ``UiPathRuntimeProtocol``. + """ diff --git a/tests/conftest.py b/tests/conftest.py index 2556e75..a6c5cd5 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -17,3 +17,9 @@ def temp_dir() -> Generator[str, None, None]: """Provide a temporary directory for test files.""" with tempfile.TemporaryDirectory() as tmp_dir: yield tmp_dir + + +# Governance state is held inline on the :class:`UiPathGovernedRuntime` +# instance — the host passes a resolved :class:`PolicyIndex` + +# :class:`EnforcementMode` into the constructor, no module-level +# state, no cross-test reset needed. diff --git a/tests/test_audit_factory.py b/tests/test_audit_factory.py new file mode 100644 index 0000000..3dc44e1 --- /dev/null +++ b/tests/test_audit_factory.py @@ -0,0 +1,50 @@ +"""Tests for :func:`uipath.runtime.governance._audit.factory.create_sink`. + +The factory is the entry point :class:`AuditManager` uses to construct +its always-on ``traces`` sink at init. It's tiny (one name → one sink) +but the unknown-name path deserves a regression guard so a future +refactor can't silently drop a sink registration. +""" + +from __future__ import annotations + +import logging + +import pytest + +from uipath.runtime.governance._audit.factory import create_sink +from uipath.runtime.governance._audit.traces import TracesAuditSink + + +def test_create_sink_traces_returns_traces_audit_sink() -> None: + """The single supported name resolves to a real ``TracesAuditSink``.""" + sink = create_sink("traces") + assert isinstance(sink, TracesAuditSink) + + +def test_create_sink_is_name_case_insensitive() -> None: + """Callers can pass any casing — the factory normalizes internally. + + Regression guard: dropping the ``.lower()`` would silently break + every consumer that hand-typed a name with different casing. + """ + assert isinstance(create_sink("TRACES"), TracesAuditSink) + assert isinstance(create_sink("Traces"), TracesAuditSink) + + +def test_create_sink_unknown_name_returns_none_and_warns( + caplog: pytest.LogCaptureFixture, +) -> None: + """An unknown name returns ``None`` (no crash) and logs a warning. + + Contract: registration failures must not raise — the audit manager's + ``_register_traces_sink`` handles ``None`` by skipping the sink, + which is safer than crashing at construction on a bad config. + """ + with caplog.at_level( + logging.WARNING, logger="uipath.runtime.governance._audit.factory" + ): + result = create_sink("unknown-sink") + + assert result is None + assert any("Unknown audit sink" in r.message for r in caplog.records) diff --git a/tests/test_audit_manager_lifecycle.py b/tests/test_audit_manager_lifecycle.py new file mode 100644 index 0000000..25094f9 --- /dev/null +++ b/tests/test_audit_manager_lifecycle.py @@ -0,0 +1,207 @@ +"""Lifecycle tests for :class:`AuditManager`. + +Pins the production-readiness invariants of the audit manager: + +- Construction is side-effect-free: no background thread, no atexit + registration, no global state mutation. +- :meth:`close` is idempotent. +- :meth:`emit` dispatches on the caller's thread, so an OTel-backed + sink sees the caller's live span without any cross-thread plumbing. +""" + +from __future__ import annotations + +import threading +from typing import Any + +from uipath.runtime.governance._audit.base import ( + AuditEvent, + AuditManager, + AuditSink, + EventType, +) + +# --------------------------------------------------------------------------- +# Construction is side-effect-free +# --------------------------------------------------------------------------- + + +def test_construction_starts_no_background_thread() -> None: + """``AuditManager()`` must not spawn a worker thread. + + Regression guard for the design pivot: the audit pipeline used to + construct a daemon worker thread eagerly. Construction now only + builds in-memory state; any async export lives inside the sink. + """ + before = {t.name for t in threading.enumerate()} + m = AuditManager(register_default_sinks=False) + after = {t.name for t in threading.enumerate()} + try: + assert after == before, ( + f"AuditManager() spawned a thread; new threads: {after - before}" + ) + finally: + m.close() + + +def test_default_sink_registered_on_construction() -> None: + """With defaults, the traces sink is auto-registered.""" + m = AuditManager() + try: + assert "traces" in m.list_sinks() + finally: + m.close() + + +def test_bare_construction_skips_default_sink() -> None: + """``register_default_sinks=False`` produces an empty manager.""" + m = AuditManager(register_default_sinks=False) + try: + assert m.list_sinks() == [] + finally: + m.close() + + +# --------------------------------------------------------------------------- +# close() is idempotent and clears sinks +# --------------------------------------------------------------------------- + + +def test_close_clears_sinks_and_failure_state() -> None: + """``close()`` empties sinks, failure counters, and tripped set.""" + + class _Sink(AuditSink): + def __init__(self, name: str) -> None: + self._name = name + self.closed = False + + @property + def name(self) -> str: + return self._name + + def emit(self, event: AuditEvent) -> None: + pass + + def close(self) -> None: + self.closed = True + + m = AuditManager(register_default_sinks=False) + s = _Sink("test") + m.register_sink(s) + m._sink_failures["test"] = 3 + m._tripped_sinks.add("test") + + m.close() + + assert m.list_sinks() == [] + assert m._sink_failures == {} + assert m._tripped_sinks == set() + assert s.closed + + +def test_close_is_idempotent() -> None: + """Calling ``close()`` twice must not raise.""" + m = AuditManager(register_default_sinks=False) + m.close() + m.close() # must not raise + + +# --------------------------------------------------------------------------- +# flush() delegates to every sink +# --------------------------------------------------------------------------- + + +def test_flush_calls_flush_on_each_sink() -> None: + """The manager holds no buffer; ``flush()`` is a fan-out to sinks.""" + + class _Sink(AuditSink): + def __init__(self, name: str) -> None: + self._name = name + self.flush_count = 0 + + @property + def name(self) -> str: + return self._name + + def emit(self, event: AuditEvent) -> None: + pass + + def flush(self) -> None: + self.flush_count += 1 + + m = AuditManager(register_default_sinks=False) + a, b = _Sink("a"), _Sink("b") + m.register_sink(a) + m.register_sink(b) + try: + m.flush() + assert a.flush_count == 1 + assert b.flush_count == 1 + finally: + m.close() + + +# --------------------------------------------------------------------------- +# emit() runs on the caller's thread — OTel context visible directly +# --------------------------------------------------------------------------- + + +def test_emit_runs_on_caller_thread() -> None: + """``emit()`` invokes sinks synchronously on the calling thread. + + Asserts the design contract that lets OTel-backed sinks see the + agent's live span via ``trace.get_current_span()`` without any + cross-thread context propagation. + """ + captured: dict[str, Any] = {} + + class _Probe(AuditSink): + @property + def name(self) -> str: + return "probe" + + def emit(self, event: AuditEvent) -> None: + captured["thread"] = threading.current_thread() + + m = AuditManager(register_default_sinks=False) + m.register_sink(_Probe()) + try: + m.emit(AuditEvent(event_type=EventType.RULE_EVALUATION)) + assert captured["thread"] is threading.current_thread() + finally: + m.close() + + +def test_emit_propagates_otel_span_via_current_context() -> None: + """An OTel-backed sink sees the caller's live span directly. + + With sync dispatch there's no contextvars snapshot/restore — the + sink just calls ``trace.get_current_span()`` on the same thread the + caller is on, and that's the span the caller has active. + """ + from opentelemetry import trace + from opentelemetry.sdk.trace import TracerProvider + + captured: dict[str, Any] = {} + + class _Probe(AuditSink): + @property + def name(self) -> str: + return "probe" + + def emit(self, event: AuditEvent) -> None: + sc = trace.get_current_span().get_span_context() + captured["trace_id"] = sc.trace_id if sc.is_valid else None + captured["span_id"] = sc.span_id if sc.is_valid else None + + tracer = TracerProvider().get_tracer("test") + m = AuditManager(register_default_sinks=False) + m.register_sink(_Probe()) + try: + with tracer.start_as_current_span("agent-run") as span: + expected = span.get_span_context() + m.emit(AuditEvent(event_type=EventType.RULE_EVALUATION)) + assert captured["trace_id"] == expected.trace_id + assert captured["span_id"] == expected.span_id + finally: + m.close() diff --git a/tests/test_audit_manager_track_event_wiring.py b/tests/test_audit_manager_track_event_wiring.py new file mode 100644 index 0000000..31c62e9 --- /dev/null +++ b/tests/test_audit_manager_track_event_wiring.py @@ -0,0 +1,178 @@ +"""Tests for ``AuditManager`` auto-registration of the ``track_events`` sink. + +The sink is platform-mandated, like ``traces``. The host wires the +``track_event`` callable + ``GovernanceRuntimeMetadata`` at +construction. ``_register_track_event_sink`` mirrors the simple shape +of ``_register_traces_sink`` — deferred import, construct, register, +log — wrapped in a broad ``except`` so a misconfigured wiring layer +(missing callable, sink-construction error) is surfaced as a warning +instead of crashing the agent. +""" + +from __future__ import annotations + +import logging +from typing import Any + +import pytest + +from uipath.runtime.governance._audit.base import AuditManager +from uipath.runtime.governance._audit.metadata import GovernanceRuntimeMetadata +from uipath.runtime.governance._audit.track_events import TrackEventAuditSink + + +class _Capture: + """Stand-in for ``provider.track_event`` — records calls.""" + + def __init__(self) -> None: + self.calls: list[dict[str, Any]] = [] + + def __call__(self, **kwargs: Any) -> None: + self.calls.append(kwargs) + + +# --------------------------------------------------------------------------- +# Happy path — host wires the callable +# --------------------------------------------------------------------------- + + +def test_track_event_sink_registered_when_callable_supplied() -> None: + mgr = AuditManager( + track_event=_Capture(), + runtime_metadata=GovernanceRuntimeMetadata(agent_type="uipath_coded"), + ) + try: + sinks = mgr.list_sinks() + assert TrackEventAuditSink.SINK_NAME in sinks + sink = mgr.get_sink(TrackEventAuditSink.SINK_NAME) + assert isinstance(sink, TrackEventAuditSink) + finally: + mgr.close() + + +def test_traces_sink_is_still_registered_alongside() -> None: + """track_events doesn't replace traces — both are mandatory.""" + mgr = AuditManager( + track_event=_Capture(), + runtime_metadata=GovernanceRuntimeMetadata(), + ) + try: + sinks = mgr.list_sinks() + assert "traces" in sinks + assert TrackEventAuditSink.SINK_NAME in sinks + finally: + mgr.close() + + +def test_supplied_runtime_metadata_reaches_sink() -> None: + mgr = AuditManager( + track_event=_Capture(), + runtime_metadata=GovernanceRuntimeMetadata( + agent_type="uipath_coded", agent_framework="langchain" + ), + ) + try: + sink = mgr.get_sink(TrackEventAuditSink.SINK_NAME) + assert isinstance(sink, TrackEventAuditSink) + # Internal: confirm the sink carries the host-supplied metadata. + assert sink._meta.agent_type == "uipath_coded" + assert sink._meta.agent_framework == "langchain" + finally: + mgr.close() + + +def test_metadata_defaults_when_not_supplied() -> None: + """Helper falls back to ``GovernanceRuntimeMetadata()`` defaults.""" + mgr = AuditManager(track_event=_Capture()) + try: + sink = mgr.get_sink(TrackEventAuditSink.SINK_NAME) + assert isinstance(sink, TrackEventAuditSink) + assert sink._meta.agent_type == "unknown" + assert sink._meta.agent_framework == "unknown" + finally: + mgr.close() + + +# --------------------------------------------------------------------------- +# Missing-callable path — caught by the helper's try/except, logged +# --------------------------------------------------------------------------- + + +def test_missing_callable_logs_warning_and_skips_sink( + caplog: pytest.LogCaptureFixture, +) -> None: + """``track_event=None`` → sink __init__ raises → helper catches + warns.""" + caplog.set_level(logging.WARNING, logger="uipath.runtime.governance._audit.base") + mgr = AuditManager() # no track_event supplied + try: + # Traces sink still wired; track_events skipped because sink + # construction raised ValueError caught by the helper. + assert "traces" in mgr.list_sinks() + assert TrackEventAuditSink.SINK_NAME not in mgr.list_sinks() + + warnings = [r.message for r in caplog.records if r.levelno == logging.WARNING] + assert any("Failed to register track_events sink" in m for m in warnings), ( + f"expected registration-failure warning, got: {warnings}" + ) + finally: + mgr.close() + + +def test_sink_construction_error_does_not_crash_manager( + caplog: pytest.LogCaptureFixture, monkeypatch: pytest.MonkeyPatch +) -> None: + """An exception inside ``TrackEventAuditSink.__init__`` is swallowed. + + Forces a non-``ValueError`` exception (a raise inside ``__init__`` + triggered via the runtime_metadata path) to confirm the helper's + ``except Exception`` covers the broad case the user asked for, not + just the validation error. + """ + caplog.set_level(logging.WARNING, logger="uipath.runtime.governance._audit.base") + + def _boom(*args: Any, **kwargs: Any) -> Any: + raise RuntimeError("synthetic registration failure") + + from uipath.runtime.governance._audit import track_events as te + + monkeypatch.setattr(te, "TrackEventAuditSink", _boom) + + mgr = AuditManager(track_event=_Capture()) + try: + # Helper swallowed the RuntimeError; manager kept the traces sink + # and reached a constructed state without crashing. + assert "traces" in mgr.list_sinks() + assert TrackEventAuditSink.SINK_NAME not in mgr.list_sinks() + warnings = [r.message for r in caplog.records if r.levelno == logging.WARNING] + assert any( + "Failed to register track_events sink" in m + and "synthetic registration failure" in m + for m in warnings + ), f"expected wrapped registration failure, got: {warnings}" + finally: + mgr.close() + + +# --------------------------------------------------------------------------- +# Opt-out path — register_default_sinks=False +# --------------------------------------------------------------------------- + + +def test_opt_out_skips_both_sinks() -> None: + """register_default_sinks=False keeps the audit pipeline empty for tests.""" + mgr = AuditManager(register_default_sinks=False) + try: + assert mgr.list_sinks() == [] + finally: + mgr.close() + + +def test_opt_out_does_not_warn(caplog: pytest.LogCaptureFixture) -> None: + """Opting out is an explicit signal — no missing-callable warning.""" + caplog.set_level(logging.WARNING, logger="uipath.runtime.governance._audit.base") + mgr = AuditManager(register_default_sinks=False) + try: + warnings = [r.message for r in caplog.records if r.levelno == logging.WARNING] + assert not any("track_events" in m for m in warnings) + finally: + mgr.close() diff --git a/tests/test_audit_register_sink.py b/tests/test_audit_register_sink.py new file mode 100644 index 0000000..d0e3590 --- /dev/null +++ b/tests/test_audit_register_sink.py @@ -0,0 +1,108 @@ +"""Tests for ``AuditManager.register_sink`` failure-counter semantics. + +A re-registered same-name sink must NOT inherit the previous instance's +tripped circuit-breaker state. ``unregister_sink`` already clears these +counters, but ``register_sink`` also clears them on a successful add as +defense-in-depth (covers tests / external callers that touch the +internal counter dicts directly). +""" + +from __future__ import annotations + +from typing import Any + +import pytest + +from uipath.runtime.governance._audit.base import ( + AuditEvent, + AuditManager, + AuditSink, + EventType, +) + + +class _NoopSink(AuditSink): + """Sink that records emit calls and never raises.""" + + def __init__(self, name: str = "test-sink") -> None: + self._name = name + self.events: list[AuditEvent] = [] + + @property + def name(self) -> str: + return self._name + + def emit(self, event: AuditEvent) -> None: + self.events.append(event) + + +def _event() -> AuditEvent: + return AuditEvent(event_type=EventType.RULE_EVALUATION, agent_name="a") + + +@pytest.fixture +def manager() -> Any: + """Build a fresh AuditManager with no default sinks. + + ``register_default_sinks=False`` keeps the traces sink out of the + test, so assertions about registered sinks see only what the test + puts there. + """ + return AuditManager(register_default_sinks=False) + + +def test_register_clears_stale_failure_counter(manager: AuditManager) -> None: + """A new sink with a name that previously tripped starts fresh.""" + # Simulate prior instance having tripped the circuit-breaker without + # going through unregister (e.g. test code or external code that + # mutated the counters directly). + manager._sink_failures["test-sink"] = manager._SINK_FAILURE_THRESHOLD + manager._tripped_sinks.add("test-sink") + + new_sink = _NoopSink(name="test-sink") + manager.register_sink(new_sink) + + # Counter and tripped-set must be cleared. + assert manager._sink_failures.get("test-sink", 0) == 0 + assert "test-sink" not in manager._tripped_sinks + + # And the new sink actually receives events (would be skipped if + # still considered tripped). + manager.emit(_event()) + assert len(new_sink.events) == 1 + + +def test_register_does_not_clear_for_duplicate(manager: AuditManager) -> None: + """Re-registering an already-present sink is a no-op (no counter reset).""" + sink = _NoopSink(name="test-sink") + manager.register_sink(sink) + + # Simulate the existing sink having accumulated some failures. + manager._sink_failures["test-sink"] = 3 + + # A second register call with the same name should NOT clear those + # failures — the duplicate-check fires before the reset. + duplicate = _NoopSink(name="test-sink") + manager.register_sink(duplicate) + + assert manager._sink_failures["test-sink"] == 3 + + +def test_unregister_then_register_starts_fresh(manager: AuditManager) -> None: + """The full lifecycle: register → trip → unregister → register again.""" + sink = _NoopSink(name="test-sink") + manager.register_sink(sink) + manager._sink_failures["test-sink"] = manager._SINK_FAILURE_THRESHOLD + manager._tripped_sinks.add("test-sink") + + manager.unregister_sink("test-sink") + # Unregister already clears. + assert "test-sink" not in manager._tripped_sinks + + new_sink = _NoopSink(name="test-sink") + manager.register_sink(new_sink) + assert manager._sink_failures.get("test-sink", 0) == 0 + assert "test-sink" not in manager._tripped_sinks + + manager.emit(_event()) + assert len(new_sink.events) == 1 diff --git a/tests/test_commitment_concern.py b/tests/test_commitment_concern.py new file mode 100644 index 0000000..378bb60 --- /dev/null +++ b/tests/test_commitment_concern.py @@ -0,0 +1,200 @@ +"""Tests for the commitment_concern check (A.10.4). + +The check now uses OR semantics: a verb match, an amount match, or a +deadline match is each sufficient when its enabling flag is on. With +both flags false the rule matches verb-only. + +The verb pattern also covers proposal / SOW style commitment markers +("Cost: $X", "fixed scope", "Deliverables", "Timeline", "I propose") +so formal-business commitments without first-person verbs still fire. + +Amount detection requires a currency marker adjacent to the number to +prevent URL fragments (forum-post IDs, image dimensions, etc.) from +false-positiving. +""" + +from __future__ import annotations + +import pytest + +from uipath.runtime.governance.native.evaluator import GovernanceEvaluator + +# --------------------------------------------------------------------------- +# The proposal-style sample that originally slipped through the rule. +# Contains: "Cost: $780 (fixed for the above scope)", "Deliverables", +# "Timeline: 4 days total", "I propose", a forum URL with a 6-digit ID. +# Triple-quoted so we keep the line breaks the model produced. +# --------------------------------------------------------------------------- +SAMPLE_PROPOSAL = """To address your concerns, I reviewed the official UiPath site you referenced and relevant resources on uipath.com to inform a fast stabilization plan. Notable findings include: a community CI/CD sample for UiPath projects (https://forum.uipath.com/t/announcement-ci-cd-pipeline-sample-implementation-s-for-uipath-projects-alpha/667851). + +Here's how I propose we turn your software around quickly: + +Plan +- Triage (logs + reproduce) +- Quick stabilization + +Deliverables +- Defect triage report + +Timeline: 4 days total +- Day 1: Triage + reproduction + +Cost: $780 (fixed for the above scope) +""" + + +@pytest.mark.parametrize( + "text", + [ + "Cost: $780 (fixed for the above scope)", + "Deliverables: a, b, c", + "Timeline: 4 days total for the whole engagement", + "I propose we turn this around in a week", + "We will refund the difference", + "I'll deliver the report by Friday", + "the warranty covers parts only", + "fixed price of one hundred dollars", + ], +) +def test_verb_match_alone_fires(text: str) -> None: + """Each verb-style commitment marker fires on its own (verb-only mode).""" + assert ( + GovernanceEvaluator._check_commitment_concern( + text, {"require_amount": False, "require_deadline": False} + ) + is True + ) + + +def test_full_proposal_sample_fires() -> None: + """The originally-missed proposal output now fires.""" + assert ( + GovernanceEvaluator._check_commitment_concern( + SAMPLE_PROPOSAL, + {"require_amount": False, "require_deadline": False}, + ) + is True + ) + + +@pytest.mark.parametrize( + "text", + [ + "$780", + "We charge USD 1,200 per seat", + "The fee is 500 EUR", + ], +) +def test_amount_alone_fires_when_require_amount_true(text: str) -> None: + """Currency-anchored amount alone fires under OR semantics.""" + assert ( + GovernanceEvaluator._check_commitment_concern( + text, {"require_amount": True, "require_deadline": False} + ) + is True + ) + + +@pytest.mark.parametrize( + "text", + [ + "Task is 75% complete.", + "We maintain 99.9% uptime.", + "Battery at 50%.", + "Score: 12%.", + ], +) +def test_bare_percentage_does_not_fire(text: str) -> None: + """Status-only percentages must not trigger commitment_concern. + + Regression for the prior ``\\d{1,3}\\s*%`` branch in the amount + regex, which fired on benign status / progress text. Real + percentage-bearing commitments ("we'll give a 20% discount") + still fire via the verb pattern. + """ + assert ( + GovernanceEvaluator._check_commitment_concern( + text, {"require_amount": True, "require_deadline": False} + ) + is False + ) + + +def test_percentage_with_verb_still_fires() -> None: + """A commitment verb co-occurring with a percentage still fires.""" + assert ( + GovernanceEvaluator._check_commitment_concern( + "We will refund 100% of the purchase price.", + {"require_amount": True, "require_deadline": False}, + ) + is True + ) + + +def test_amount_alone_does_not_fire_when_require_amount_false() -> None: + """Amount-only text is silent when require_amount=False and no verb.""" + assert ( + GovernanceEvaluator._check_commitment_concern( + "The list price is $780.", + {"require_amount": False, "require_deadline": False}, + ) + is False + ) + + +def test_deadline_alone_fires_when_require_deadline_true() -> None: + """Deadline phrase alone fires under OR semantics.""" + assert ( + GovernanceEvaluator._check_commitment_concern( + "Will be done within 5 days.", + {"require_amount": False, "require_deadline": True}, + ) + is True + ) + + +def test_url_fragment_digits_do_not_false_positive() -> None: + """A long URL with embedded digits is not a 'commitment'. + + Catches the prior price-parser misbehaviour where Price.fromstring() + picked up forum-post IDs (e.g. ``667851``) and conflated them with + unrelated currency symbols elsewhere in the text. + """ + text = ( + "See https://forum.example.com/t/topic/667851 for details — " + "no commitment language here." + ) + assert ( + GovernanceEvaluator._check_commitment_concern( + text, {"require_amount": True, "require_deadline": True} + ) + is False + ) + + +@pytest.mark.parametrize( + "text", + [ + "", + " ", + "Just chatting about the weather today.", + "The product is durable and well-made.", + ], +) +def test_no_signal_does_not_fire(text: str) -> None: + """Text without any commitment signal stays silent regardless of flags.""" + assert ( + GovernanceEvaluator._check_commitment_concern( + text, {"require_amount": True, "require_deadline": True} + ) + is False + ) + + +def test_non_dict_params_treated_as_defaults() -> None: + """``params`` of the wrong type degrades to defaults rather than crashing.""" + assert GovernanceEvaluator._check_commitment_concern("we will refund", None) is True + assert ( + GovernanceEvaluator._check_commitment_concern("no verbs here", "garbage") + is False + ) diff --git a/tests/test_evaluator.py b/tests/test_evaluator.py new file mode 100644 index 0000000..96750a2 --- /dev/null +++ b/tests/test_evaluator.py @@ -0,0 +1,407 @@ +"""Tests for the audit + enforcement behavior of GovernanceEvaluator. + +The evaluator's three load-bearing responsibilities: + +1. DISABLED enforcement mode short-circuits — no rules evaluated, no + audit events emitted, no exceptions raised. +2. AUDIT mode evaluates rules and emits audit events, but transforms + matched DENY actions into AUDIT so execution continues. +3. ENFORCE mode evaluates, emits audit, and raises + :class:`GovernanceBlockException` when a DENY rule matches. + +Plus a fail-safe contract: a misbehaving audit sink must not stop +evaluation from completing or propagate as an exception. The +evaluator is constructed with explicit dependencies (audit manager, +enforcement mode); no process-globals are involved. +""" + +from __future__ import annotations + +from typing import Any + +import pytest +from uipath.core.governance import EnforcementMode +from uipath.core.governance.exceptions import GovernanceBlockException +from uipath.core.governance.models import Action, LifecycleHook + +from uipath.runtime.governance._audit.base import ( + AuditEvent, + AuditManager, + AuditSink, + EventType, +) +from uipath.runtime.governance.native.evaluator import GovernanceEvaluator +from uipath.runtime.governance.native.models import ( + Check, + CheckContext, + Condition, + PolicyIndex, + PolicyPack, + Rule, +) + +# --------------------------------------------------------------------------- +# Test helpers +# --------------------------------------------------------------------------- + + +class _CapturingSink(AuditSink): + """Audit sink that records every event for assertions.""" + + def __init__(self) -> None: + self.events: list[AuditEvent] = [] + + @property + def name(self) -> str: + return "capturing" + + def emit(self, event: AuditEvent) -> None: + self.events.append(event) + + +def _deny_rule_on_input_contains(needle: str) -> Rule: + """Build a rule that DENIES when agent_input contains ``needle``.""" + return Rule( + rule_id="TEST-01", + name="Test deny on input", + clause="A.1.1", + hook=LifecycleHook.BEFORE_AGENT, + action=Action.DENY, + checks=[ + Check( + conditions=[ + Condition( + operator="contains", + field="agent_input", + value=needle, + ) + ], + action=Action.DENY, + message=f"Input must not contain {needle!r}", + ) + ], + ) + + +def _build_index_with(rule: Rule) -> PolicyIndex: + """Wrap a single rule in a one-pack PolicyIndex.""" + idx = PolicyIndex() + idx.add_pack( + PolicyPack( + name="test_pack", + version="1.0", + description="test", + rules=[rule], + ) + ) + return idx + + +def _ctx(agent_input: str) -> CheckContext: + return CheckContext( + hook=LifecycleHook.BEFORE_AGENT, + agent_name="test-agent", + runtime_id="run-1", + agent_input=agent_input, + ) + + +def _build_evaluator( + rule: Rule, + mode: EnforcementMode, + audit_manager: AuditManager | None = None, +) -> GovernanceEvaluator: + """Construct an evaluator with explicit deps — no process-globals involved.""" + return GovernanceEvaluator( + _build_index_with(rule), + enforcement_mode=mode, + audit_manager=audit_manager, + ) + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + + +@pytest.fixture +def audit_setup() -> Any: + """Per-test :class:`AuditManager` + capturing sink — no default sinks. + + Returns ``(manager, sink)`` so a test can build evaluators with the + manager and inspect emitted events through the sink. + """ + manager = AuditManager(register_default_sinks=False) + sink = _CapturingSink() + manager.register_sink(sink) + yield manager, sink + manager.close() + + +# --------------------------------------------------------------------------- +# DISABLED mode +# --------------------------------------------------------------------------- + + +def test_disabled_mode_short_circuits_with_empty_record(audit_setup: Any) -> None: + """DISABLED returns an empty AuditRecord and emits nothing.""" + manager, sink = audit_setup + evaluator = _build_evaluator( + _deny_rule_on_input_contains("secret"), + EnforcementMode.DISABLED, + audit_manager=manager, + ) + + audit = evaluator.evaluate(_ctx("definitely contains secret")) + + assert audit.evaluations == [] + assert audit.final_action == Action.ALLOW + assert audit.metadata["enforcement_mode"] == "disabled" + assert sink.events == [] + + +def test_disabled_mode_does_not_raise_on_deny_match(audit_setup: Any) -> None: + """Even when a DENY rule WOULD match, DISABLED never raises.""" + manager, _ = audit_setup + evaluator = _build_evaluator( + _deny_rule_on_input_contains("blocked"), + EnforcementMode.DISABLED, + audit_manager=manager, + ) + + # Must not raise. + evaluator.evaluate(_ctx("this is blocked")) + + +# --------------------------------------------------------------------------- +# AUDIT mode +# --------------------------------------------------------------------------- + + +def test_audit_mode_transforms_deny_to_audit(audit_setup: Any) -> None: + """AUDIT mode evaluates rules but never returns a DENY final_action.""" + manager, _ = audit_setup + evaluator = _build_evaluator( + _deny_rule_on_input_contains("secret"), + EnforcementMode.AUDIT, + audit_manager=manager, + ) + + audit = evaluator.evaluate(_ctx("contains secret data")) + + assert len(audit.evaluations) == 1 + assert audit.evaluations[0].matched is True + assert audit.evaluations[0].action == Action.DENY # raw rule action preserved + assert audit.final_action == Action.AUDIT # mode-adjusted + assert audit.metadata["audit_mode_would_deny"] is True + + +def test_audit_mode_does_not_raise_on_deny_match(audit_setup: Any) -> None: + """AUDIT mode never raises GovernanceBlockException, even on a DENY hit.""" + manager, _ = audit_setup + evaluator = _build_evaluator( + _deny_rule_on_input_contains("blocked"), + EnforcementMode.AUDIT, + audit_manager=manager, + ) + + evaluator.evaluate(_ctx("this is blocked")) # must not raise + + +def test_audit_mode_emits_per_rule_and_summary_events(audit_setup: Any) -> None: + """One rule_evaluation event per rule + one hook_summary per evaluate().""" + manager, sink = audit_setup + evaluator = _build_evaluator( + _deny_rule_on_input_contains("secret"), + EnforcementMode.AUDIT, + audit_manager=manager, + ) + + evaluator.evaluate(_ctx("contains secret")) + + rule_events = [e for e in sink.events if e.event_type == EventType.RULE_EVALUATION] + summary_events = [e for e in sink.events if e.event_type == EventType.HOOK_END] + assert len(rule_events) == 1 + assert rule_events[0].hook == "BEFORE_AGENT" + assert rule_events[0].data["policy_id"] == "TEST-01" + assert rule_events[0].data["matched"] is True + assert rule_events[0].data["action"] == "deny" + # Mode travels on every event (PR #122 contract). + assert rule_events[0].data["enforcement_mode"] == EnforcementMode.AUDIT + + assert len(summary_events) == 1 + assert summary_events[0].data["matched_rules"] == 1 + assert summary_events[0].data["final_action"] == "audit" + assert summary_events[0].data["enforcement_mode"] == EnforcementMode.AUDIT + + +def test_audit_mode_unmatched_rule_logged_as_allow(audit_setup: Any) -> None: + """Unmatched rules still emit a rule_evaluation event with action='allow'.""" + manager, sink = audit_setup + evaluator = _build_evaluator( + _deny_rule_on_input_contains("secret"), + EnforcementMode.AUDIT, + audit_manager=manager, + ) + + evaluator.evaluate(_ctx("benign user query")) + + rule_events = [e for e in sink.events if e.event_type == EventType.RULE_EVALUATION] + assert len(rule_events) == 1 + assert rule_events[0].data["matched"] is False + assert rule_events[0].data["action"] == "allow" + + +# --------------------------------------------------------------------------- +# ENFORCE mode +# --------------------------------------------------------------------------- + + +def test_enforce_mode_raises_on_deny_match(audit_setup: Any) -> None: + """ENFORCE mode raises GovernanceBlockException when a DENY rule matches.""" + manager, _ = audit_setup + evaluator = _build_evaluator( + _deny_rule_on_input_contains("blocked"), + EnforcementMode.ENFORCE, + audit_manager=manager, + ) + + with pytest.raises(GovernanceBlockException) as exc_info: + evaluator.evaluate(_ctx("input is blocked")) + + exc = exc_info.value + assert exc.rule_id == "TEST-01" + assert exc.rule_name == "Test deny on input" + assert exc.audit_record is not None + assert exc.audit_record.final_action == Action.DENY + + +def test_enforce_mode_emits_audit_before_raising(audit_setup: Any) -> None: + """The audit trail must be emitted even when the call raises.""" + manager, sink = audit_setup + evaluator = _build_evaluator( + _deny_rule_on_input_contains("blocked"), + EnforcementMode.ENFORCE, + audit_manager=manager, + ) + + with pytest.raises(GovernanceBlockException): + evaluator.evaluate(_ctx("contains blocked")) + + rule_events = [e for e in sink.events if e.event_type == EventType.RULE_EVALUATION] + summary_events = [e for e in sink.events if e.event_type == EventType.HOOK_END] + assert len(rule_events) == 1 + assert summary_events[0].data["final_action"] == "deny" + assert summary_events[0].data["enforcement_mode"] == EnforcementMode.ENFORCE + + +def test_enforce_mode_returns_record_when_no_rule_matches(audit_setup: Any) -> None: + """No DENY hit → no raise; the AuditRecord is returned normally.""" + manager, _ = audit_setup + evaluator = _build_evaluator( + _deny_rule_on_input_contains("blocked"), + EnforcementMode.ENFORCE, + audit_manager=manager, + ) + + audit = evaluator.evaluate(_ctx("benign query")) + + assert audit.final_action == Action.ALLOW + assert audit.evaluations[0].matched is False + + +# --------------------------------------------------------------------------- +# Sink-failure isolation + no-audit-manager case +# --------------------------------------------------------------------------- + + +def test_sink_failure_does_not_propagate_or_block_evaluation( + audit_setup: Any, +) -> None: + """A broken sink must not make evaluate() raise or lose its return value. + + Contract: AuditManager wraps each sink's emit() in try/except with a + per-sink failure counter (circuit-breaker), so a sink exception + never propagates back to the evaluator. + """ + manager, capturing_sink = audit_setup + + class _BrokenSink(AuditSink): + @property + def name(self) -> str: + return "broken" + + def emit(self, event: AuditEvent) -> None: + raise RuntimeError("sink broke") + + manager.register_sink(_BrokenSink()) + + evaluator = _build_evaluator( + _deny_rule_on_input_contains("secret"), + EnforcementMode.AUDIT, + audit_manager=manager, + ) + + # Must complete without raising even with a broken sink registered. + audit = evaluator.evaluate(_ctx("contains secret")) + + assert audit.final_action == Action.AUDIT + # The non-broken capturing sink still got its events. + assert any(e.event_type == EventType.RULE_EVALUATION for e in capturing_sink.events) + + +def test_no_audit_manager_short_circuits_emission() -> None: + """``audit_manager=None`` is a no-op — evaluation still completes. + + Replaces the previous test that mocked ``get_audit_manager`` to + raise. With explicit injection, the equivalent "no manager + available" state is simply ``audit_manager=None`` at construction. + """ + evaluator = _build_evaluator( + _deny_rule_on_input_contains("secret"), + EnforcementMode.AUDIT, + audit_manager=None, + ) + + # Must complete, return record, and not raise. + audit = evaluator.evaluate(_ctx("contains secret")) + + assert audit.final_action == Action.AUDIT + assert audit.evaluations[0].matched is True + + +# --------------------------------------------------------------------------- +# Protocol conformance smoke test +# --------------------------------------------------------------------------- + + +def test_governance_evaluator_satisfies_evaluator_protocol() -> None: + """GovernanceEvaluator must be usable wherever EvaluatorProtocol is expected. + + Mirrors the pattern from test_detached_bridge_satisfies_debug_protocol — + an explicit assignment to the protocol-typed variable documents the + structural contract. + """ + from uipath.core.adapters import EvaluatorProtocol + + evaluator: EvaluatorProtocol = GovernanceEvaluator(PolicyIndex()) + assert isinstance(evaluator, EvaluatorProtocol) + + +def test_evaluator_protocol_methods_resolvable_on_concrete() -> None: + """Every method the protocol declares must be callable on the concrete impl.""" + from uipath.core.adapters import EvaluatorProtocol + + evaluator: Any = GovernanceEvaluator(PolicyIndex()) + for method_name in ( + "evaluate_before_agent", + "evaluate_after_agent", + "evaluate_before_model", + "evaluate_after_model", + "evaluate_tool_call", + "evaluate_after_tool", + ): + assert callable(getattr(evaluator, method_name)) + # The variable annotation also asserts type compatibility at runtime + # because EvaluatorProtocol is @runtime_checkable. + assert isinstance(evaluator, EvaluatorProtocol) diff --git a/tests/test_evaluator_operators.py b/tests/test_evaluator_operators.py new file mode 100644 index 0000000..9f05055 --- /dev/null +++ b/tests/test_evaluator_operators.py @@ -0,0 +1,688 @@ +"""Tests for ``GovernanceEvaluator`` operators and field resolution. + +Covers each operator implemented in :meth:`_apply_operator` plus the +``_check_*`` helper functions (vader, encoding, entropy, incident, +commitment) and the ``evaluate_*`` dispatchers. +""" + +from __future__ import annotations + +from typing import Any + +import pytest +from uipath.core.governance import EnforcementMode +from uipath.core.governance.models import Action, LifecycleHook + +from uipath.runtime.governance.native.evaluator import ( + _INCIDENT_PATTERNS, + GovernanceEvaluator, +) +from uipath.runtime.governance.native.models import ( + Check, + CheckContext, + Condition, + Logic, + PolicyIndex, + PolicyPack, + Rule, +) + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _evaluator() -> GovernanceEvaluator: + """Build a GovernanceEvaluator with an empty PolicyIndex (operators only). + + AUDIT is the default mode; operator tests don't care about + enforcement and we don't need an audit manager for purely + operator-level assertions. + """ + return GovernanceEvaluator(policy_index=PolicyIndex()) + + +def _ctx(**fields: Any) -> CheckContext: + """Construct a CheckContext with sensible defaults plus overrides.""" + defaults: dict[str, Any] = dict( + hook=LifecycleHook.AFTER_MODEL, + agent_name="agent", + runtime_id="rt-1", + ) + defaults.update(fields) + return CheckContext(**defaults) + + +def _rule_with_condition( + operator: str, field: str, value, *, negate: bool = False +) -> Rule: + return Rule( + rule_id="r1", + name="r1", + clause="", + hook=LifecycleHook.AFTER_MODEL, + action=Action.AUDIT, + checks=[ + Check( + conditions=[ + Condition( + operator=operator, field=field, value=value, negate=negate + ) + ], + ) + ], + ) + + +# Mode is per-instance now — tests construct evaluators with the mode +# they need via the ``enforcement_mode`` kwarg. No process-globals to +# reset. + + +# --------------------------------------------------------------------------- +# Field resolution — _get_field_value +# --------------------------------------------------------------------------- + + +def test_get_field_value_top_level_attr() -> None: + ev = _evaluator() + ctx = _ctx(model_output="hello") + assert ev._get_field_value("model_output", ctx) == "hello" + + +def test_get_field_value_dotted_path_into_dict() -> None: + ev = _evaluator() + ctx = _ctx(session_state={"tool_calls": 7}) + assert ev._get_field_value("session_state.tool_calls", ctx) == 7 + + +def test_get_field_value_missing_segment_returns_none() -> None: + ev = _evaluator() + ctx = _ctx() + assert ev._get_field_value("nonexistent", ctx) is None + assert ev._get_field_value("session_state.absent", ctx) is None + + +# --------------------------------------------------------------------------- +# Existence / guardrail_fallback (special-cased before the None check) +# --------------------------------------------------------------------------- + + +def test_exists_true_when_value_present() -> None: + ev = _evaluator() + ctx = _ctx(model_output="x") + assert ( + ev._apply_operator("exists", ev._get_field_value("model_output", ctx), None) + is True + ) + + +def test_exists_false_when_missing() -> None: + ev = _evaluator() + assert ev._apply_operator("exists", None, None) is False + + +def test_not_exists_inverse() -> None: + ev = _evaluator() + assert ev._apply_operator("not_exists", None, None) is True + assert ev._apply_operator("not_exists", "x", None) is False + + +def test_guardrail_fallback_mapped_and_disabled_fires() -> None: + ev = _evaluator() + result = ev._apply_operator( + "guardrail_fallback", + None, + {"mapped_to_uipath": True, "policy_enabled": False, "validator": "pii"}, + ) + assert result is True + + +@pytest.mark.parametrize( + "cfg", + [ + {"mapped_to_uipath": False, "policy_enabled": False}, + {"mapped_to_uipath": True, "policy_enabled": True}, + {"mapped_to_uipath": False, "policy_enabled": True}, + ], +) +def test_guardrail_fallback_silent_when_not_mapped_or_enabled( + cfg: dict[str, Any], +) -> None: + ev = _evaluator() + assert ev._apply_operator("guardrail_fallback", None, cfg) is False + + +def test_guardrail_fallback_non_dict_value_silent() -> None: + ev = _evaluator() + assert ev._apply_operator("guardrail_fallback", None, "string") is False + + +# --------------------------------------------------------------------------- +# None-field short-circuit (everything except exists / guardrail_fallback) +# --------------------------------------------------------------------------- + + +def test_other_operators_short_circuit_when_field_is_none() -> None: + ev = _evaluator() + for op in ("contains", "regex", "in_list", "gt"): + assert ev._apply_operator(op, None, "anything") is False, op + + +# --------------------------------------------------------------------------- +# Numeric operators +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "op,lhs,rhs,expected", + [ + ("gt", 5, 3, True), + ("gt", 3, 5, False), + ("gt", 3, 3, False), + ("gte", 3, 3, True), + ("gte", 2, 3, False), + ("lt", 1, 3, True), + ("lt", 3, 3, False), + ("lte", 3, 3, True), + ("lte", 4, 3, False), + ], +) +def test_numeric_operators(op: str, lhs: float, rhs: float, expected: bool) -> None: + assert _evaluator()._apply_operator(op, lhs, rhs) is expected + + +def test_numeric_operators_handle_string_coercion() -> None: + ev = _evaluator() + assert ev._apply_operator("gt", "5", "3") is True + + +def test_numeric_operators_return_false_on_uncoercible() -> None: + ev = _evaluator() + assert ev._apply_operator("gt", "not-a-number", 3) is False + assert ev._apply_operator("gt", 3, "not-a-number") is False + + +# --------------------------------------------------------------------------- +# String operators +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "op,lhs,rhs,expected", + [ + ("equals", "abc", "abc", True), + ("equals", "abc", "ABC", False), # equals is case-sensitive + ("eq", "x", "x", True), + ("not_equals", "abc", "xyz", True), + ("ne", "x", "x", False), + ("contains", "Hello World", "world", True), # case-insensitive + ("contains", "Hello", "xyz", False), + ("not_contains", "Hello", "xyz", True), + ("not_contains", "Hello", "hello", False), + ], +) +def test_string_operators(op: str, lhs: str, rhs: str, expected: bool) -> None: + assert _evaluator()._apply_operator(op, lhs, rhs) is expected + + +def test_regex_matches_pattern() -> None: + ev = _evaluator() + assert ev._apply_operator("regex", "Cost: $1,200", r"\$\d+") is True + + +def test_regex_matches_alias() -> None: + """``matches`` is documented as a synonym for ``regex``.""" + ev = _evaluator() + assert ev._apply_operator("matches", "abc-123", r"\d+") is True + + +def test_regex_invalid_pattern_returns_false() -> None: + """Malformed regex is logged and silently returns False.""" + ev = _evaluator() + assert ev._apply_operator("regex", "anything", "(unclosed") is False + + +# --------------------------------------------------------------------------- +# List operators +# --------------------------------------------------------------------------- + + +def test_in_list_membership() -> None: + ev = _evaluator() + assert ( + ev._apply_operator("in_list", "delete_file", ["shell", "delete_file"]) is True + ) + assert ev._apply_operator("in_list", "ls", ["shell", "delete_file"]) is False + + +def test_in_list_non_list_value_returns_false() -> None: + ev = _evaluator() + assert ev._apply_operator("in_list", "x", "not a list") is False + + +def test_not_in_list_inverse() -> None: + ev = _evaluator() + assert ev._apply_operator("not_in_list", "ls", ["shell"]) is True + assert ev._apply_operator("not_in_list", "shell", ["shell"]) is False + + +def test_not_in_list_non_list_value_returns_true() -> None: + """``not_in_list`` against a non-list value safely returns True + (nothing is in a non-list).""" + ev = _evaluator() + assert ev._apply_operator("not_in_list", "x", "not a list") is True + + +# --------------------------------------------------------------------------- +# Unknown operator +# --------------------------------------------------------------------------- + + +def test_unknown_operator_returns_false() -> None: + """Unknown operator strings log a debug message and return False.""" + ev = _evaluator() + assert ev._apply_operator("never_heard_of_this", "x", "y") is False + + +# --------------------------------------------------------------------------- +# Negate flag — flips the result +# --------------------------------------------------------------------------- + + +def test_condition_negate_flips_result() -> None: + ev = _evaluator() + ctx = _ctx(model_output="hello") + # contains "hello" → matches; negate inverts to False. + cond = Condition( + operator="contains", + field="model_output", + value="hello", + negate=True, + ) + assert ev._evaluate_condition(cond, ctx) is False + cond2 = Condition( + operator="contains", + field="model_output", + value="world", + negate=True, + ) + assert ev._evaluate_condition(cond2, ctx) is True + + +# --------------------------------------------------------------------------- +# Check-level logic: "all" (AND) vs "any" (OR), and empty-conditions +# --------------------------------------------------------------------------- + + +def test_empty_check_conditions_always_match() -> None: + """A check with no conditions trivially matches — surfaces rule shape bugs.""" + ev = _evaluator() + check = Check(conditions=[], logic=Logic.ALL) + matched, _ = ev._evaluate_check(check, _ctx()) + assert matched is True + + +def test_check_logic_all_requires_every_condition() -> None: + ev = _evaluator() + check = Check( + conditions=[ + Condition(operator="contains", field="model_output", value="a"), + Condition(operator="contains", field="model_output", value="missing"), + ], + logic=Logic.ALL, + ) + matched, _ = ev._evaluate_check(check, _ctx(model_output="a only")) + assert matched is False + + +def test_check_logic_any_requires_one_condition() -> None: + ev = _evaluator() + check = Check( + conditions=[ + Condition(operator="contains", field="model_output", value="present"), + Condition(operator="contains", field="model_output", value="absent"), + ], + logic=Logic.ANY, + ) + matched, detail = ev._evaluate_check(check, _ctx(model_output="present text")) + assert matched is True + # detail is the check's message on match; empty by default in our builder. + assert detail == "" + + +# --------------------------------------------------------------------------- +# VADER sentiment +# --------------------------------------------------------------------------- + + +def test_vader_concern_negative_text_fires() -> None: + """A clearly-negative sentence trips the default threshold of -0.3.""" + assert ( + GovernanceEvaluator._check_vader_concern( + "I absolutely hate this terrible, awful product.", {"threshold": -0.3} + ) + is True + ) + + +def test_vader_concern_positive_text_does_not_fire() -> None: + assert ( + GovernanceEvaluator._check_vader_concern( + "This is wonderful and I love it!", {"threshold": -0.3} + ) + is False + ) + + +def test_vader_concern_empty_text_silent() -> None: + assert GovernanceEvaluator._check_vader_concern("", {}) is False + assert GovernanceEvaluator._check_vader_concern(" ", {}) is False + + +def test_vader_concern_threshold_as_scalar() -> None: + """``params`` may be a bare number; the operator coerces.""" + assert GovernanceEvaluator._check_vader_concern("I hate everything", -0.3) is True + + +def test_vader_concern_invalid_threshold_falls_back() -> None: + """Non-numeric scalar params fall back to the documented default.""" + # "garbage" -> default -0.3 → should still classify clear negative + assert ( + GovernanceEvaluator._check_vader_concern( + "I hate this awful, terrible thing", "garbage" + ) + is True + ) + + +# --------------------------------------------------------------------------- +# Encoding integrity +# --------------------------------------------------------------------------- + + +def test_encoding_concern_clean_text_silent() -> None: + assert ( + GovernanceEvaluator._check_encoding_concern( + "Just a normal English sentence with no corruption.", {} + ) + is False + ) + + +def test_encoding_concern_empty_silent() -> None: + assert GovernanceEvaluator._check_encoding_concern("", {}) is False + + +def test_encoding_concern_replacement_chars_fire() -> None: + """U+FFFD replacement chars are a strong corruption signal.""" + text = "Hello � � world" + assert ( + GovernanceEvaluator._check_encoding_concern(text, {"min_corruption_events": 2}) + is True + ) + + +def test_encoding_concern_mojibake_bigrams_fire() -> None: + """Latin-1-as-UTF-8 mojibake patterns are a known corruption shape.""" + text = "é é hello é" + assert ( + GovernanceEvaluator._check_encoding_concern(text, {"min_corruption_events": 2}) + is True + ) + + +def test_encoding_concern_hex_escape_literals_fire() -> None: + """Literal ``\\xHH`` sequences mean raw bytes leaked into a string.""" + text = r"Hello \x80 \x81 \x82 world" + assert ( + GovernanceEvaluator._check_encoding_concern(text, {"min_corruption_events": 2}) + is True + ) + + +# --------------------------------------------------------------------------- +# Entropy (stdlib only — deterministic) +# --------------------------------------------------------------------------- + + +def test_entropy_concern_normal_english_does_not_fire() -> None: + """English prose entropy lands ~3.5–4.5 bits/byte — inside default range.""" + text = "The quick brown fox jumps over the lazy dog." * 5 + assert ( + GovernanceEvaluator._check_entropy_concern(text, {"min": 1.5, "max": 7.5}) + is False + ) + + +def test_entropy_concern_low_entropy_fires() -> None: + """Highly repetitive text approaches 0 bits/byte.""" + text = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + assert ( + GovernanceEvaluator._check_entropy_concern(text, {"min": 1.5, "max": 7.5}) + is True + ) + + +def test_entropy_concern_high_entropy_fires() -> None: + """Random-ish bytes approach 8 bits/byte.""" + # Build text with many distinct chars to push entropy high. + text = "".join(chr(c) for c in range(32, 127)) * 5 + assert ( + GovernanceEvaluator._check_entropy_concern(text, {"min": 1.5, "max": 6.0}) + is True + ) + + +def test_entropy_concern_empty_silent() -> None: + assert GovernanceEvaluator._check_entropy_concern("", {}) is False + + +def test_entropy_concern_non_dict_params_uses_defaults() -> None: + """Non-dict params don't crash; defaults apply.""" + # Normal English prose still won't trip the default min=1.5, max=7.5 range. + text = "The quick brown fox jumps over the lazy dog." + assert GovernanceEvaluator._check_entropy_concern(text, "garbage") is False + + +# --------------------------------------------------------------------------- +# Incident taxonomy (regex-based, deterministic) +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "text,expected_category", + [ + ("I cannot help with that.", "safety_refusal"), + ("I'm sorry, but I cannot answer.", "safety_refusal"), + ("500 internal server error", "tool_failure"), + ("Connection refused", "tool_failure"), + ("timed out", "tool_failure"), + ("401 unauthorized", "auth_failure"), + ("authentication failed", "auth_failure"), + ("429", "quota_exceeded"), + ("rate limit exceeded", "quota_exceeded"), + ("I made that up", "hallucination"), + ("I don't actually know", "hallucination"), + ], +) +def test_incident_concern_categorical_matches( + text: str, expected_category: str +) -> None: + """Each category in ``_INCIDENT_PATTERNS`` has at least one matching exemplar.""" + assert expected_category in _INCIDENT_PATTERNS + assert GovernanceEvaluator._check_incident_concern(text, {}) is True + + +def test_incident_concern_unmatched_silent() -> None: + assert ( + GovernanceEvaluator._check_incident_concern( + "All systems operating normally.", {} + ) + is False + ) + + +def test_incident_concern_empty_silent() -> None: + assert GovernanceEvaluator._check_incident_concern("", {}) is False + + +def test_incident_concern_category_filter() -> None: + """Limit scanning to a subset of categories via ``categories`` param.""" + # "401 unauthorized" hits auth_failure; with only quota_exceeded enabled, + # the scanner should miss it. + assert ( + GovernanceEvaluator._check_incident_concern( + "401 unauthorized", {"categories": ["quota_exceeded"]} + ) + is False + ) + # With auth_failure enabled, it fires. + assert ( + GovernanceEvaluator._check_incident_concern( + "401 unauthorized", {"categories": ["auth_failure"]} + ) + is True + ) + + +def test_incident_concern_unknown_category_silently_dropped() -> None: + """Categories the system doesn't know about are silently ignored.""" + # Only the unknown category is requested — falls back to no categories, + # so even matching text doesn't fire. + result = GovernanceEvaluator._check_incident_concern( + "401 unauthorized", {"categories": ["unknown_cat_xyz"]} + ) + assert result is False + + +# --------------------------------------------------------------------------- +# evaluate_* dispatchers — verify they build the right CheckContext +# --------------------------------------------------------------------------- + + +def _record_context_evaluator() -> tuple[GovernanceEvaluator, dict[str, Any]]: + """Patch evaluate() to capture the context it receives instead of running rules.""" + captured: dict[str, Any] = {} + ev = _evaluator() + + def _fake_evaluate(ctx: CheckContext) -> Any: + captured["ctx"] = ctx + from datetime import datetime, timezone + + from uipath.core.governance.models import AuditRecord + + return AuditRecord( + timestamp=datetime.now(timezone.utc), + agent_name=ctx.agent_name, + runtime_id=ctx.runtime_id, + hook=ctx.hook, + evaluations=[], + final_action=Action.ALLOW, + ) + + ev.evaluate = _fake_evaluate # type: ignore[assignment] + return ev, captured + + +def test_evaluate_before_agent_builds_context() -> None: + ev, captured = _record_context_evaluator() + ev.evaluate_before_agent( + agent_input="user-text", + agent_name="a", + runtime_id="r", + model_name="gpt-5", + ) + ctx = captured["ctx"] + assert ctx.hook == LifecycleHook.BEFORE_AGENT + assert ctx.agent_input == "user-text" + assert ctx.model_name == "gpt-5" + + +def test_evaluate_after_agent_builds_context() -> None: + ev, captured = _record_context_evaluator() + ev.evaluate_after_agent( + agent_output="reply", + agent_name="a", + runtime_id="r", + ) + ctx = captured["ctx"] + assert ctx.hook == LifecycleHook.AFTER_AGENT + assert ctx.agent_output == "reply" + + +def test_evaluate_before_model_carries_messages() -> None: + ev, captured = _record_context_evaluator() + ev.evaluate_before_model( + model_input="prompt", + agent_name="a", + runtime_id="r", + messages=[{"role": "user", "content": "hi"}], + model_name="gpt-5", + ) + ctx = captured["ctx"] + assert ctx.hook == LifecycleHook.BEFORE_MODEL + assert ctx.model_input == "prompt" + assert ctx.messages == [{"role": "user", "content": "hi"}] + + +def test_evaluate_after_model_builds_context() -> None: + ev, captured = _record_context_evaluator() + ev.evaluate_after_model( + model_output="resp", + agent_name="a", + runtime_id="r", + ) + ctx = captured["ctx"] + assert ctx.hook == LifecycleHook.AFTER_MODEL + assert ctx.model_output == "resp" + + +def test_evaluate_tool_call_carries_args() -> None: + ev, captured = _record_context_evaluator() + ev.evaluate_tool_call( + tool_name="search", + tool_args={"q": "x"}, + agent_name="a", + runtime_id="r", + session_state={"tool_calls": 1}, + ) + ctx = captured["ctx"] + assert ctx.hook == LifecycleHook.TOOL_CALL + assert ctx.tool_name == "search" + assert ctx.tool_args == {"q": "x"} + assert ctx.session_state == {"tool_calls": 1} + + +def test_evaluate_after_tool_carries_result() -> None: + ev, captured = _record_context_evaluator() + ev.evaluate_after_tool( + tool_name="search", + tool_result="some-data", + agent_name="a", + runtime_id="r", + ) + ctx = captured["ctx"] + assert ctx.hook == LifecycleHook.AFTER_TOOL + assert ctx.tool_name == "search" + assert ctx.tool_result == "some-data" + + +# --------------------------------------------------------------------------- +# DISABLED mode — evaluate() short-circuits without emitting audit +# --------------------------------------------------------------------------- + + +def test_disabled_mode_returns_empty_audit_record() -> None: + """DISABLED mode short-circuits the rule loop and audit emission.""" + rule = _rule_with_condition("contains", "model_output", "anything") + pack = PolicyPack(name="p", version="1", description="", rules=[rule]) + idx = PolicyIndex() + idx.add_pack(pack) + ev = GovernanceEvaluator( + policy_index=idx, enforcement_mode=EnforcementMode.DISABLED + ) + + audit = ev.evaluate(_ctx(model_output="contains anything")) + assert audit.final_action == Action.ALLOW + assert audit.evaluations == [] diff --git a/tests/test_evaluator_telemetry.py b/tests/test_evaluator_telemetry.py new file mode 100644 index 0000000..55b61cd --- /dev/null +++ b/tests/test_evaluator_telemetry.py @@ -0,0 +1,289 @@ +"""Tests that the evaluator passes the new telemetry fields downstream. + +The evaluator must: + +- Measure per-rule and per-hook wall-clock duration. +- Collect disabled rule ids into ``skipped_policy_names``. +- Count matched UiPath-mapped guardrails (``guardrail_dispatched_count``). +- Hand all of the above to ``AuditManager.emit_rule_evaluation`` and + ``emit_hook_summary`` so the ``TrackEventAuditSink`` payload carries + them. + +We capture events via a manager registered with no default sinks + +one ``_CapturingSink`` so the assertions see exactly the per-rule and +hook-summary events the evaluator emits. +""" + +from __future__ import annotations + +import pytest +from uipath.core.governance import EnforcementMode +from uipath.core.governance.models import Action, LifecycleHook + +from uipath.runtime.governance._audit.base import ( + AuditEvent, + AuditManager, + AuditSink, + EventType, +) +from uipath.runtime.governance.native.evaluator import GovernanceEvaluator +from uipath.runtime.governance.native.models import ( + Check, + CheckContext, + Condition, + PolicyIndex, + PolicyPack, + Rule, +) + + +class _CapturingSink(AuditSink): + def __init__(self) -> None: + self.events: list[AuditEvent] = [] + + @property + def name(self) -> str: + return "capturing" + + def emit(self, event: AuditEvent) -> None: + self.events.append(event) + + +def _rule( + rule_id: str, + *, + enabled: bool = True, + matches: bool = True, + action: Action = Action.DENY, +) -> Rule: + """A rule whose ``contains`` check always (or never) matches the input.""" + return Rule( + rule_id=rule_id, + name=f"rule-{rule_id}", + clause=rule_id, + hook=LifecycleHook.BEFORE_AGENT, + action=action, + enabled=enabled, + checks=[ + Check( + conditions=[ + Condition( + operator="contains", + field="agent_input", + value="needle" if matches else "absent-needle", + ) + ], + action=action, + message=f"matched {rule_id}", + ) + ], + ) + + +def _pack(*rules: Rule) -> PolicyIndex: + idx = PolicyIndex() + idx.add_pack( + PolicyPack(name="test_pack", version="1.0", description="t", rules=list(rules)) + ) + return idx + + +def _ctx() -> CheckContext: + return CheckContext( + hook=LifecycleHook.BEFORE_AGENT, + agent_name="agent-x", + runtime_id="run-1", + agent_input="needle", + ) + + +@pytest.fixture +def sink_and_manager() -> tuple[_CapturingSink, AuditManager]: + """Sink-capturing manager with no default sinks (no traces, no track_events).""" + sink = _CapturingSink() + mgr = AuditManager(register_default_sinks=False) + mgr.register_sink(sink) + return sink, mgr + + +def _rule_events(sink: _CapturingSink) -> list[AuditEvent]: + return [e for e in sink.events if e.event_type == EventType.RULE_EVALUATION] + + +def _hook_summary(sink: _CapturingSink) -> AuditEvent: + summaries = [e for e in sink.events if e.event_type == EventType.HOOK_END] + assert len(summaries) == 1, f"expected 1 hook summary, got {len(summaries)}" + return summaries[0] + + +# --------------------------------------------------------------------------- +# Per-rule timing +# --------------------------------------------------------------------------- + + +def test_rule_evaluation_carries_duration_ms( + sink_and_manager: tuple[_CapturingSink, AuditManager], +) -> None: + sink, mgr = sink_and_manager + try: + evaluator = GovernanceEvaluator( + _pack(_rule("A.1.1")), + enforcement_mode=EnforcementMode.AUDIT, + audit_manager=mgr, + ) + evaluator.evaluate(_ctx()) + finally: + mgr.close() + + rule_evs = _rule_events(sink) + assert len(rule_evs) == 1 + duration = rule_evs[0].data["duration_ms"] + assert isinstance(duration, float) + assert duration >= 0.0 + + +def test_rule_evaluation_mapped_to_uipath_is_false_for_native( + sink_and_manager: tuple[_CapturingSink, AuditManager], +) -> None: + """Native rules (no guardrail_fallback) always emit ``mapped_to_uipath=False``.""" + sink, mgr = sink_and_manager + try: + evaluator = GovernanceEvaluator( + _pack(_rule("A.1.1")), + enforcement_mode=EnforcementMode.AUDIT, + audit_manager=mgr, + ) + evaluator.evaluate(_ctx()) + finally: + mgr.close() + + rule_evs = _rule_events(sink) + assert rule_evs[0].data["mapped_to_uipath"] is False + + +# --------------------------------------------------------------------------- +# Hook-summary aggregates +# --------------------------------------------------------------------------- + + +def test_hook_summary_carries_total_duration( + sink_and_manager: tuple[_CapturingSink, AuditManager], +) -> None: + sink, mgr = sink_and_manager + try: + evaluator = GovernanceEvaluator( + _pack(_rule("A.1.1"), _rule("A.1.2", matches=False)), + enforcement_mode=EnforcementMode.AUDIT, + audit_manager=mgr, + ) + evaluator.evaluate(_ctx()) + finally: + mgr.close() + + summary = _hook_summary(sink) + duration = summary.data["duration_ms"] + assert isinstance(duration, float) + assert duration >= 0.0 + + +def test_hook_summary_tracks_skipped_disabled_rules( + sink_and_manager: tuple[_CapturingSink, AuditManager], +) -> None: + """Disabled rules appear in ``skipped_policy_names`` (and skipped_count).""" + sink, mgr = sink_and_manager + try: + evaluator = GovernanceEvaluator( + _pack( + _rule("A.1.1"), # enabled, matches + _rule("A.1.2", enabled=False), # DISABLED + _rule("A.1.3", enabled=False), # DISABLED + ), + enforcement_mode=EnforcementMode.AUDIT, + audit_manager=mgr, + ) + evaluator.evaluate(_ctx()) + finally: + mgr.close() + + summary = _hook_summary(sink) + assert summary.data["skipped_count"] == 2 + assert set(summary.data["skipped_policy_names"]) == {"A.1.2", "A.1.3"} + + +def test_hook_summary_passed_and_denied_counts( + sink_and_manager: tuple[_CapturingSink, AuditManager], +) -> None: + """One match + two non-matches → denied=1, passed=2, matched_rules=1.""" + sink, mgr = sink_and_manager + try: + evaluator = GovernanceEvaluator( + _pack( + _rule("A.1.1"), # matches (DENY) + _rule("A.1.2", matches=False), # passes + _rule("A.1.3", matches=False), # passes + ), + enforcement_mode=EnforcementMode.AUDIT, + audit_manager=mgr, + ) + evaluator.evaluate(_ctx()) + finally: + mgr.close() + + summary = _hook_summary(sink) + assert summary.data["denied_count"] == 1 + assert summary.data["passed_count"] == 2 + # ``matched_rules`` keeps its historical "any check matched" sense. + assert summary.data["matched_rules"] == 1 + + +def test_hook_summary_matched_allow_rule_counts_as_passed( + sink_and_manager: tuple[_CapturingSink, AuditManager], +) -> None: + """A matched rule with action=ALLOW is a positive informational match. + + It should NOT contribute to ``denied_count`` — it rolls into + ``passed_count`` instead. ``matched_rules`` (raw count) still + includes it for backward compatibility with the legacy traces sink. + """ + sink, mgr = sink_and_manager + try: + evaluator = GovernanceEvaluator( + _pack( + _rule("A.1.1"), # matches (DENY) + _rule("A.1.2", action=Action.ALLOW), # matches (ALLOW) — positive + _rule("A.1.3", matches=False), # passes (unmatched) + ), + enforcement_mode=EnforcementMode.AUDIT, + audit_manager=mgr, + ) + evaluator.evaluate(_ctx()) + finally: + mgr.close() + + summary = _hook_summary(sink) + # 3 total rules; only the explicit DENY counts as a denial. + assert summary.data["denied_count"] == 1 + # ``passed_count`` includes the unmatched rule AND the matched-allow rule. + assert summary.data["passed_count"] == 2 + # Raw ``matched_rules`` still reflects "any check matched" — both + # the DENY and the ALLOW match contribute. + assert summary.data["matched_rules"] == 2 + + +def test_hook_summary_guardrail_dispatched_count_for_native_rules_is_zero( + sink_and_manager: tuple[_CapturingSink, AuditManager], +) -> None: + """Without guardrail_fallback conditions, dispatched count is 0.""" + sink, mgr = sink_and_manager + try: + evaluator = GovernanceEvaluator( + _pack(_rule("A.1.1")), + enforcement_mode=EnforcementMode.AUDIT, + audit_manager=mgr, + ) + evaluator.evaluate(_ctx()) + finally: + mgr.close() + + summary = _hook_summary(sink) + assert summary.data["guardrail_dispatched_count"] == 0 diff --git a/tests/test_governance_metadata.py b/tests/test_governance_metadata.py new file mode 100644 index 0000000..0feb264 --- /dev/null +++ b/tests/test_governance_metadata.py @@ -0,0 +1,81 @@ +"""Tests for :class:`GovernanceRuntimeMetadata`. + +The dataclass carries the per-runtime constants every governance +telemetry event stamps. Defaults must keep telemetry flowing when the +host hasn't populated agent type / framework yet, and the runtime +version must resolve from installed package metadata when available. +""" + +from __future__ import annotations + +from unittest.mock import patch + +from uipath.runtime.governance._audit.metadata import ( + NATIVE_EXECUTION_ENGINE, + GovernanceRuntimeMetadata, + _resolve_runtime_version, +) + + +def test_defaults() -> None: + """Default-constructed metadata uses native engine + ``unknown`` slots.""" + meta = GovernanceRuntimeMetadata() + assert meta.execution_engine == NATIVE_EXECUTION_ENGINE + assert meta.agent_type == "unknown" + assert meta.agent_framework == "unknown" + # runtime_version is resolved at construction; either real or "unknown" + assert isinstance(meta.runtime_version, str) + assert meta.runtime_version != "" + + +def test_explicit_overrides_persist() -> None: + """Host-supplied values override the defaults verbatim.""" + meta = GovernanceRuntimeMetadata( + execution_engine="agt", + agent_type="uipath_coded", + agent_framework="langchain", + runtime_version="1.2.3", + ) + assert meta.execution_engine == "agt" + assert meta.agent_type == "uipath_coded" + assert meta.agent_framework == "langchain" + assert meta.runtime_version == "1.2.3" + + +def test_frozen() -> None: + """Dataclass is frozen — host can't mutate per-run constants mid-run.""" + meta = GovernanceRuntimeMetadata() + try: + meta.agent_type = "other" # type: ignore[misc] + except Exception as exc: + assert "frozen" in str(exc).lower() or "cannot assign" in str(exc).lower() + else: + raise AssertionError("frozen dataclass must reject attribute writes") + + +def test_as_payload_contains_all_four_fields() -> None: + """``as_payload`` is the canonical merge-into-event-data dict shape.""" + meta = GovernanceRuntimeMetadata( + execution_engine="agt", + agent_type="uipath_coded", + agent_framework="langchain", + runtime_version="1.2.3", + ) + payload = meta.as_payload() + assert payload == { + "execution_engine": "agt", + "agent_type": "uipath_coded", + "agent_framework": "langchain", + "runtime_version": "1.2.3", + } + + +def test_runtime_version_fallback_on_missing_package() -> None: + """A source checkout with no installed metadata falls back to ``unknown``.""" + from importlib.metadata import PackageNotFoundError + + with patch( + "uipath.runtime.governance._audit.metadata.version", + side_effect=PackageNotFoundError("uipath-runtime"), + ): + assert _resolve_runtime_version() == "unknown" diff --git a/tests/test_governance_runtime.py b/tests/test_governance_runtime.py new file mode 100644 index 0000000..b2ca3e3 --- /dev/null +++ b/tests/test_governance_runtime.py @@ -0,0 +1,630 @@ +"""Tests for :class:`UiPathGovernedRuntime` — pure resolved-policy wrapper. + +The runtime takes an already-resolved :class:`PolicyIndex` + +:class:`EnforcementMode` at construction. The caller resolves and +compiles the policy on its own side; the runtime is format-agnostic +and never sees a wire representation. Tests here confirm the wrapper +holds the snapshot and passes execution straight through to the +delegate. +""" + +from __future__ import annotations + +from typing import Any + +import pytest +from uipath.core.governance import EnforcementMode + +from uipath.runtime.governance.native.models import PolicyIndex +from uipath.runtime.governance.runtime import UiPathGovernedRuntime + +# --------------------------------------------------------------------------- +# UiPathGovernedRuntime — passthroughs +# --------------------------------------------------------------------------- + + +class _StubDelegate: + """Captures delegate calls so the passthroughs can be asserted.""" + + def __init__(self) -> None: + self.execute_calls: list[tuple[Any, Any]] = [] + self.stream_calls: list[tuple[Any, Any]] = [] + self.disposed = False + self.schema_called = False + + async def execute(self, input: Any = None, options: Any = None) -> Any: + self.execute_calls.append((input, options)) + return "result" + + async def stream(self, input: Any = None, options: Any = None) -> Any: + self.stream_calls.append((input, options)) + for event in ("a", "b"): + yield event + + async def get_schema(self) -> Any: + self.schema_called = True + return "schema" + + async def dispose(self) -> None: + self.disposed = True + + +def _make_runtime( + delegate: _StubDelegate | None = None, + *, + policy_index: PolicyIndex | None = None, + enforcement_mode: EnforcementMode = EnforcementMode.AUDIT, +) -> UiPathGovernedRuntime: + """Build a runtime with sensible test defaults.""" + return UiPathGovernedRuntime( + delegate or _StubDelegate(), + policy_index if policy_index is not None else PolicyIndex(), + enforcement_mode, + ) + + +# --------------------------------------------------------------------------- +# Snapshot stored internally — not exposed as a public property +# --------------------------------------------------------------------------- + + +def test_resolved_policy_index_is_held_for_evaluator_use() -> None: + """The wrapper stores the resolved snapshot; the evaluator reads it. + + The wrapper is oblivious to how the index was built (any wire + format, any compilation path, or a hand-constructed test fixture) + — it just holds the instance. A plain ``PolicyIndex()`` suffices + to prove the reference is preserved. + """ + index = PolicyIndex() + runtime = _make_runtime(policy_index=index) + # Internal attribute — verify the wrapper kept the exact instance. + assert runtime._policy_index is index + + +def test_enforcement_mode_is_held_for_evaluator_use() -> None: + """The wrapper stores the mode supplied at construction.""" + runtime = _make_runtime(enforcement_mode=EnforcementMode.ENFORCE) + assert runtime._enforcement_mode is EnforcementMode.ENFORCE + + +def test_empty_policy_index_is_a_valid_construction() -> None: + """``PolicyIndex()`` with no packs is acceptable — wrapper attaches without rules.""" + runtime = _make_runtime(policy_index=PolicyIndex()) + assert runtime._policy_index.total_rules == 0 + + +# --------------------------------------------------------------------------- +# Passthrough behavior +# --------------------------------------------------------------------------- + + +async def test_governance_runtime_execute_delegates() -> None: + delegate = _StubDelegate() + runtime = _make_runtime(delegate) + + result = await runtime.execute({"x": 1}) + + assert result == "result" + assert delegate.execute_calls == [({"x": 1}, None)] + + +async def test_governance_runtime_stream_delegates() -> None: + delegate = _StubDelegate() + runtime = _make_runtime(delegate) + + events = [e async for e in runtime.stream({"x": 1})] + + assert events == ["a", "b"] + assert delegate.stream_calls == [({"x": 1}, None)] + + +async def test_governance_runtime_schema_delegates() -> None: + """``get_schema`` still forwards — only ``dispose`` was cut to a no-op.""" + delegate = _StubDelegate() + runtime = _make_runtime(delegate) + + assert await runtime.get_schema() == "schema" + assert delegate.schema_called + + +# --------------------------------------------------------------------------- +# dispose — no-op by contract; caller owns delegate + host cleanup +# --------------------------------------------------------------------------- + + +async def test_dispose_does_not_touch_the_delegate() -> None: + """The wrapper deliberately does not forward ``dispose`` to the delegate. + + Caller-owned lifecycle: whichever code built the delegate is + responsible for disposing it, along with any adjacent resources + the caller wired up (telemetry dispatchers, session pools, etc.). + The wrapper's ``dispose`` exists only to satisfy + :class:`UiPathDisposableProtocol` so the wrapper stays structurally + substitutable for any runtime. + """ + delegate = _StubDelegate() + runtime = _make_runtime(delegate) + + await runtime.dispose() + + # The delegate was never touched — caller must dispose it themselves. + assert delegate.disposed is False + + +async def test_dispose_does_not_raise_when_delegate_would_have_raised() -> None: + """Because the wrapper's ``dispose`` never invokes the delegate, + a delegate whose ``dispose`` raises has no path to surface through + the wrapper. + """ + + class _RaisingDelegate(_StubDelegate): + async def dispose(self) -> None: + raise RuntimeError("delegate would boom — but wrapper never calls this") + + runtime = _make_runtime(_RaisingDelegate()) + + # Must not raise — the wrapper's dispose is a plain no-op. + await runtime.dispose() + + +async def test_dispose_is_idempotent() -> None: + """Two calls in a row must not raise — teardown paths sometimes wire + ``close``/``dispose`` from multiple layers. + """ + runtime = _make_runtime() + + await runtime.dispose() + await runtime.dispose() # second call: no crash, no state to corrupt + + +# --------------------------------------------------------------------------- +# Root-span trace correlation — one trace_id per agent run +# --------------------------------------------------------------------------- + + +async def test_execute_opens_a_root_span_that_covers_the_whole_invocation() -> None: + """A single OTel span wraps BEFORE_AGENT, delegate, and AFTER_AGENT. + + Verifies the unified-trace contract: every code path under + ``execute`` — including any framework adapter span the delegate + opens — sees the same ``trace_id`` and the same current span. The + ``track_events`` sink reads ``trace.get_current_span()`` at emit + time, so this guarantee is what makes its ``operation_id`` + correlate across BEFORE_AGENT, BEFORE_MODEL, AFTER_MODEL, and + AFTER_AGENT events. + """ + from opentelemetry import trace + from opentelemetry.sdk.trace import TracerProvider + + # Replace the global tracer provider for this test so our span + # actually records (the default NoOp provider returns invalid + # contexts). + trace.set_tracer_provider(TracerProvider()) + + seen_trace_ids: list[int] = [] + + class _SpanProbeDelegate: + async def execute(self, input: Any = None, options: Any = None) -> Any: + seen_trace_ids.append(trace.get_current_span().get_span_context().trace_id) + return "result" + + async def stream(self, input: Any = None, options: Any = None) -> Any: + if False: + yield # pragma: no cover + + async def get_schema(self) -> Any: + return "schema" + + async def dispose(self) -> None: + return None + + runtime = UiPathGovernedRuntime( + _SpanProbeDelegate(), + PolicyIndex(), + EnforcementMode.AUDIT, + agent_name="agent-x", + runtime_id="run-1", + ) + + # Outside execute(): no governance span is active. + pre_call_ctx = trace.get_current_span().get_span_context() + assert not pre_call_ctx.is_valid, ( + "no span should be active before execute() opens the wrapper" + ) + + await runtime.execute({"x": 1}) + + # Inside the delegate: a valid span context was current. + assert len(seen_trace_ids) == 1 + assert seen_trace_ids[0] != 0, ( + "delegate must see a valid OTel trace_id from the wrapping span" + ) + + # After execute(): the span has closed. + post_call_ctx = trace.get_current_span().get_span_context() + assert not post_call_ctx.is_valid, "wrapper span must close on return" + + +async def test_execute_span_inherits_host_trace_id_when_one_is_active() -> None: + """When the host opens a span first, our wrapper becomes a child. + + Same ``trace_id`` flows through everything — governance events + emitted by runtime hooks correlate with the host's outer + operation. The host's OTel context is preserved end-to-end. + """ + from opentelemetry import trace + from opentelemetry.sdk.trace import TracerProvider + + trace.set_tracer_provider(TracerProvider()) + tracer = trace.get_tracer("test-host") + + inner_trace_id: list[int] = [] + + class _ProbeDelegate: + async def execute(self, input: Any = None, options: Any = None) -> Any: + inner_trace_id.append(trace.get_current_span().get_span_context().trace_id) + return "result" + + async def stream(self, input: Any = None, options: Any = None) -> Any: + if False: + yield # pragma: no cover + + async def get_schema(self) -> Any: + return "schema" + + async def dispose(self) -> None: + return None + + runtime = UiPathGovernedRuntime( + _ProbeDelegate(), PolicyIndex(), EnforcementMode.AUDIT + ) + + with tracer.start_as_current_span("host-outer") as host_span: + host_trace_id = host_span.get_span_context().trace_id + await runtime.execute({"x": 1}) + + # The trace_id seen inside the delegate equals the host's + # trace_id — the wrapper became a child of the host's span. + assert inner_trace_id == [host_trace_id] + + +async def test_stream_opens_a_root_span_that_covers_iteration() -> None: + """``stream``'s span stays open across the entire ``async for``. + + Holding the span over ``await`` boundaries is safe — Python's + asyncio propagates contextvars (including OTel's current-span + pointer) across suspensions. The delegate (which yields events) + must see the same wrapper span on every iteration. + """ + from opentelemetry import trace + from opentelemetry.sdk.trace import TracerProvider + + trace.set_tracer_provider(TracerProvider()) + + per_event_trace_ids: list[int] = [] + + class _StreamProbeDelegate: + async def execute(self, input: Any = None, options: Any = None) -> Any: + return "result" + + async def stream(self, input: Any = None, options: Any = None) -> Any: + for label in ("a", "b", "c"): + per_event_trace_ids.append( + trace.get_current_span().get_span_context().trace_id + ) + yield label + + async def get_schema(self) -> Any: + return "schema" + + async def dispose(self) -> None: + return None + + runtime = UiPathGovernedRuntime( + _StreamProbeDelegate(), PolicyIndex(), EnforcementMode.AUDIT + ) + + events = [e async for e in runtime.stream({"x": 1})] + + assert events == ["a", "b", "c"] + # Same valid trace_id on every yield — one span covers the whole + # stream. + assert len(set(per_event_trace_ids)) == 1 + assert per_event_trace_ids[0] != 0 + + +# --------------------------------------------------------------------------- +# _serialize_payload — evaluator input/output flattening +# --------------------------------------------------------------------------- + + +def test_serialize_payload_none_returns_empty_string() -> None: + """``None`` becomes ``""`` — the evaluator's regex/sentiment checks + scan a string and would break on a raw ``None``. + """ + from uipath.runtime.governance.runtime import _serialize_payload + + assert _serialize_payload(None) == "" + + +def test_serialize_payload_string_passes_through_unchanged() -> None: + """A bare string must not be JSON-quoted — regex/sentiment expect the + text as-is, without surrounding double quotes. + """ + from uipath.runtime.governance.runtime import _serialize_payload + + assert _serialize_payload("hello world") == "hello world" + + +def test_serialize_payload_dict_is_json_encoded() -> None: + """Structured payloads route through ``serialize_object`` then + ``json.dumps`` — the evaluator sees a flat JSON string it can scan. + """ + from uipath.runtime.governance.runtime import _serialize_payload + + result = _serialize_payload({"a": 1, "b": ["x", "y"]}) + # Order-agnostic content check — json.dumps default ordering can vary + # by dict insertion order across Python versions. + assert '"a": 1' in result + assert '"b": ["x", "y"]' in result + + +def test_serialize_payload_unserializable_object_falls_back_to_str() -> None: + """When ``serialize_object`` + ``json.dumps`` can't handle the value + (e.g., raw file handles, sockets, generators), the wrapper falls back + to ``str(payload)`` so the evaluator still gets *something* rather + than crashing the agent hook. + """ + from uipath.runtime.governance.runtime import _serialize_payload + + class _Unpicklable: + def __repr__(self) -> str: + return "" + + # A recursive dict that can't JSON-encode without hitting cycles or + # non-serializable values. + obj = _Unpicklable() + result = _serialize_payload(obj) + assert result == "" + + +# --------------------------------------------------------------------------- +# _fire_before_agent / _fire_after_agent — evaluator-wired paths +# --------------------------------------------------------------------------- + + +class _CapturingEvaluator: + """Minimal stub for :class:`GovernanceEvaluator` — records calls. + + The runtime only invokes ``evaluate_before_agent`` / + ``evaluate_after_agent`` on the evaluator, so those two are the only + methods this stub needs to expose. + """ + + def __init__(self) -> None: + self.before_calls: list[dict[str, Any]] = [] + self.after_calls: list[dict[str, Any]] = [] + self.before_raises: Exception | None = None + self.after_raises: Exception | None = None + + def evaluate_before_agent(self, **kwargs: Any) -> None: + self.before_calls.append(kwargs) + if self.before_raises is not None: + raise self.before_raises + + def evaluate_after_agent(self, **kwargs: Any) -> None: + self.after_calls.append(kwargs) + if self.after_raises is not None: + raise self.after_raises + + +class _ResultDelegate: + """Delegate that returns a real ``UiPathRuntimeResult`` so + :meth:`_fire_after_agent` can read ``result.output`` without + tripping over the ``_StubDelegate``'s bare-string return. + """ + + def __init__(self) -> None: + self.execute_calls: list[tuple[Any, Any]] = [] + + async def execute(self, input: Any = None, options: Any = None) -> Any: + from uipath.runtime.result import UiPathRuntimeResult, UiPathRuntimeStatus + + self.execute_calls.append((input, options)) + return UiPathRuntimeResult( + output="agent-output", status=UiPathRuntimeStatus.SUCCESSFUL + ) + + async def stream(self, input: Any = None, options: Any = None) -> Any: + if False: + yield # pragma: no cover + + async def get_schema(self) -> Any: + return "schema" + + async def dispose(self) -> None: + return None + + +async def test_execute_fires_before_and_after_agent_when_evaluator_wired() -> None: + """The evaluator's hooks fire on happy-path execute — this is the + core reason ``UiPathGovernedRuntime`` exists. + + Regression guard: without wiring the evaluator's calls, the wrapper + silently degrades to a pure passthrough (the ``self._evaluator is + None`` early-returns in ``_fire_*`` would kick in), and no + governance would run. + """ + delegate = _ResultDelegate() + evaluator = _CapturingEvaluator() + runtime = UiPathGovernedRuntime( + delegate, + PolicyIndex(), + EnforcementMode.AUDIT, + evaluator=evaluator, # type: ignore[arg-type] + agent_name="agent-x", + runtime_id="run-1", + ) + + result = await runtime.execute({"prompt": "leak?"}) + + assert result.output == "agent-output" + assert len(evaluator.before_calls) == 1 + assert len(evaluator.after_calls) == 1 + # ``_serialize_payload`` turned the dict input into a JSON string. + assert "leak" in evaluator.before_calls[0]["agent_input"] + assert evaluator.before_calls[0]["agent_name"] == "agent-x" + assert evaluator.before_calls[0]["runtime_id"] == "run-1" + # And AFTER_AGENT saw the delegate's output. + assert evaluator.after_calls[0]["agent_output"] == "agent-output" + + +async def test_execute_propagates_governance_block_exception() -> None: + """A DENY in ``ENFORCE`` mode must halt the run — the evaluator + raises :class:`GovernanceBlockException` and the wrapper propagates + it rather than swallowing. + """ + from uipath.core.governance.exceptions import GovernanceBlockException + + evaluator = _CapturingEvaluator() + evaluator.before_raises = GovernanceBlockException("policy denied") + + runtime = UiPathGovernedRuntime( + _StubDelegate(), + PolicyIndex(), + EnforcementMode.ENFORCE, + evaluator=evaluator, # type: ignore[arg-type] + ) + + with pytest.raises(GovernanceBlockException): + await runtime.execute({"x": 1}) + + +async def test_after_agent_block_exception_also_propagates() -> None: + """The re-raise contract holds for AFTER_AGENT too, not just + BEFORE_AGENT. + + Even though DENY on output is a rarer configuration (most policies + fire pre-model / on tool call), the wrapper must treat both hooks + symmetrically — a governance block from either boundary halts the + run, not just the input side. + """ + from uipath.core.governance.exceptions import GovernanceBlockException + + evaluator = _CapturingEvaluator() + evaluator.after_raises = GovernanceBlockException("output policy denied") + + runtime = UiPathGovernedRuntime( + _ResultDelegate(), + PolicyIndex(), + EnforcementMode.ENFORCE, + evaluator=evaluator, # type: ignore[arg-type] + ) + + with pytest.raises(GovernanceBlockException): + await runtime.execute({"x": 1}) + + +async def test_execute_swallows_unexpected_evaluator_errors() -> None: + """A generic ``Exception`` from the evaluator must NOT break the + agent run — governance bugs are logged and the delegate still runs. + """ + delegate = _StubDelegate() + evaluator = _CapturingEvaluator() + evaluator.before_raises = RuntimeError("evaluator internal error") + + runtime = UiPathGovernedRuntime( + delegate, + PolicyIndex(), + EnforcementMode.AUDIT, + evaluator=evaluator, # type: ignore[arg-type] + ) + + # Must not raise — the wrapper swallows non-block exceptions so a + # governance bug never breaks the agent. + result = await runtime.execute({"x": 1}) + assert result == "result" + # The delegate still ran (the evaluator failure didn't short-circuit). + assert delegate.execute_calls == [({"x": 1}, None)] + + +async def test_stream_fires_after_agent_only_on_result_event() -> None: + """AFTER_AGENT fires when a :class:`UiPathRuntimeResult` event is + yielded — intermediate events pass through untouched. + + Uses a delegate that yields a mix of plain events + a + ``UiPathRuntimeResult`` sentinel so the branch is exercised. + """ + from uipath.runtime.result import UiPathRuntimeResult, UiPathRuntimeStatus + + class _MixedStreamDelegate: + async def execute(self, input: Any = None, options: Any = None) -> Any: + return None + + async def stream(self, input: Any = None, options: Any = None) -> Any: + yield "intermediate-1" + yield UiPathRuntimeResult( + output="final-output", status=UiPathRuntimeStatus.SUCCESSFUL + ) + yield "intermediate-2" + + async def get_schema(self) -> Any: + return "schema" + + async def dispose(self) -> None: + return None + + evaluator = _CapturingEvaluator() + runtime = UiPathGovernedRuntime( + _MixedStreamDelegate(), + PolicyIndex(), + EnforcementMode.AUDIT, + evaluator=evaluator, # type: ignore[arg-type] + ) + + events = [e async for e in runtime.stream({"x": 1})] + + # All three events came through in order. + assert len(events) == 3 + assert isinstance(events[1], UiPathRuntimeResult) + # AFTER_AGENT fires exactly once — on the UiPathRuntimeResult. + assert len(evaluator.after_calls) == 1 + # BEFORE_AGENT fires once at stream start. + assert len(evaluator.before_calls) == 1 + + +# --------------------------------------------------------------------------- +# OTel-not-installed fallback for _governance_root_span +# --------------------------------------------------------------------------- + + +async def test_execute_still_runs_when_opentelemetry_is_unavailable( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """The runtime must not depend on OTel being importable. + + Simulate a stripped host by making ``from opentelemetry import trace`` + inside ``_governance_root_span`` raise ``ImportError``. The wrapper + should yield without opening a span and the agent still runs. + """ + import builtins + + real_import = builtins.__import__ + + def _blocked_import(name: str, *args: Any, **kwargs: Any) -> Any: + if name == "opentelemetry" or name.startswith("opentelemetry."): + raise ImportError(f"simulated missing: {name}") + return real_import(name, *args, **kwargs) + + monkeypatch.setattr(builtins, "__import__", _blocked_import) + + delegate = _StubDelegate() + runtime = UiPathGovernedRuntime(delegate, PolicyIndex(), EnforcementMode.AUDIT) + + # Must not raise. The context manager takes the ImportError branch, + # yields with no span, and execute completes normally. + result = await runtime.execute({"x": 1}) + + assert result == "result" + assert delegate.execute_calls == [({"x": 1}, None)] diff --git a/tests/test_guardrail_compensation.py b/tests/test_guardrail_compensation.py new file mode 100644 index 0000000..22b238e --- /dev/null +++ b/tests/test_guardrail_compensation.py @@ -0,0 +1,298 @@ +"""Tests for the synchronous GuardrailCompensator. + +The runtime layer builds the wire payload and hands it to the +injected provider. The provider owns batching / async / fire-and- +forget. HTTP/auth/URL/header concerns — including ``trace_id`` +resolution — live behind the +:class:`uipath.core.governance.GovernanceCompensationProvider` +protocol and are exercised in the concrete provider's own tests. + +These tests cover: + +- ``disabled_guardrails`` — distilling fired ``guardrail_fallback`` rules + into per-rule wire metadata. +- ``GuardrailCompensator.submit`` — short-circuits on empty input, + wire-model assembly, provider invocation, and fail-open behavior + when the provider raises. +- ``close`` is a no-op (kept for API symmetry). +""" + +from __future__ import annotations + +from types import SimpleNamespace +from unittest.mock import MagicMock + +from uipath.core.governance import ( + FiredRule, + GovernanceCompensationProvider, + GovernRequest, +) + +from uipath.runtime.governance.native.guardrail_compensation import ( + GuardrailCompensator, + disabled_guardrails, +) + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _provider() -> MagicMock: + """Mock satisfying the GovernanceCompensationProvider protocol.""" + return MagicMock(spec=GovernanceCompensationProvider) + + +def _rules( + *validators: str, + rule_id: str = "R1", + rule_name: str = "n", + pack: str = "p", +) -> list[FiredRule]: + """Build a list of FiredRule wire models — one per validator.""" + return [ + FiredRule( + rule_id=rule_id, + rule_name=rule_name, + pack_name=pack, + validator=v, + ) + for v in validators + ] + + +# --------------------------------------------------------------------------- +# disabled_guardrails +# --------------------------------------------------------------------------- + + +def test_disabled_guardrails_returns_fired_rule_for_matched_disabled_guardrail() -> ( + None +): + cond = SimpleNamespace( + operator="guardrail_fallback", + value={ + "validator": "pii_detection", + "mapped_to_uipath": True, + "policy_enabled": False, + }, + ) + rule = SimpleNamespace(checks=[SimpleNamespace(conditions=[cond])], pack_name="") + audit = SimpleNamespace( + evaluations=[ + SimpleNamespace(matched=True, rule_id="R1", rule_name="PII guardrail") + ] + ) + policy_index = SimpleNamespace(get_rule=lambda rid: rule if rid == "R1" else None) + + out = disabled_guardrails(audit, policy_index) + + assert len(out) == 1 + fr = out[0] + assert isinstance(fr, FiredRule) + assert fr.rule_id == "R1" + assert fr.rule_name == "PII guardrail" + assert fr.pack_name == "" + assert fr.validator == "pii_detection" + + +def test_disabled_guardrails_skips_unmatched_evaluations() -> None: + audit = SimpleNamespace( + evaluations=[SimpleNamespace(matched=False, rule_id="R1", rule_name="x")] + ) + policy_index = SimpleNamespace(get_rule=lambda rid: None) + assert disabled_guardrails(audit, policy_index) == [] + + +def test_disabled_guardrails_skips_non_guardrail_conditions() -> None: + cond = SimpleNamespace(operator="regex", value="some-pattern") + rule = SimpleNamespace(checks=[SimpleNamespace(conditions=[cond])]) + audit = SimpleNamespace( + evaluations=[SimpleNamespace(matched=True, rule_id="R1", rule_name="x")] + ) + policy_index = SimpleNamespace(get_rule=lambda rid: rule) + assert disabled_guardrails(audit, policy_index) == [] + + +def test_disabled_guardrails_skips_enabled_guardrails() -> None: + """Mapped to UiPath AND enabled → no compensation needed.""" + cond = SimpleNamespace( + operator="guardrail_fallback", + value={ + "validator": "pii_detection", + "mapped_to_uipath": True, + "policy_enabled": True, + }, + ) + rule = SimpleNamespace(checks=[SimpleNamespace(conditions=[cond])], pack_name="") + audit = SimpleNamespace( + evaluations=[SimpleNamespace(matched=True, rule_id="R1", rule_name="x")] + ) + policy_index = SimpleNamespace(get_rule=lambda rid: rule) + assert disabled_guardrails(audit, policy_index) == [] + + +def test_disabled_guardrails_skips_unmapped_guardrails() -> None: + """Not mapped to UiPath → server can't fall back; skip.""" + cond = SimpleNamespace( + operator="guardrail_fallback", + value={ + "validator": "pii_detection", + "mapped_to_uipath": False, + "policy_enabled": False, + }, + ) + rule = SimpleNamespace(checks=[SimpleNamespace(conditions=[cond])], pack_name="") + audit = SimpleNamespace( + evaluations=[SimpleNamespace(matched=True, rule_id="R1", rule_name="x")] + ) + policy_index = SimpleNamespace(get_rule=lambda rid: rule) + assert disabled_guardrails(audit, policy_index) == [] + + +# --------------------------------------------------------------------------- +# GuardrailCompensator.submit — short-circuits +# --------------------------------------------------------------------------- + + +def test_submit_empty_rules_short_circuits() -> None: + """No rules → no provider call.""" + provider = _provider() + compensator = GuardrailCompensator(provider) + compensator.submit([], {}, "before_model", "ts", "a", "r") + provider.compensate.assert_not_called() + + +def test_submit_no_validators_short_circuits() -> None: + """Rules with empty validator strings → no call (nothing to dispatch).""" + provider = _provider() + compensator = GuardrailCompensator(provider) + rules = [FiredRule(rule_id="R", rule_name="n", pack_name="p", validator="")] + compensator.submit(rules, {}, "before_model", "ts", "a", "r") + provider.compensate.assert_not_called() + + +# --------------------------------------------------------------------------- +# GuardrailCompensator.submit — wire-model assembly + provider invocation +# --------------------------------------------------------------------------- + + +def test_submit_invokes_provider_with_govern_request() -> None: + """The provider receives a GovernRequest carrying every wire field. + + ``trace_id`` is left empty on the wire — the injected provider + resolves it at HTTP-call time. + """ + provider = _provider() + compensator = GuardrailCompensator(provider) + rules = _rules("pii_detection", "harmful_content") + + compensator.submit( + rules, + {"content": "x"}, + "before_model", + "2026-06-06T00:00:00Z", + "langchain", + "patch-langchain", + ) + + provider.compensate.assert_called_once() + (request,) = provider.compensate.call_args.args + assert isinstance(request, GovernRequest) + # distinct validators drive the guardrail API call + assert request.validators == ["pii_detection", "harmful_content"] + assert request.rules == rules + assert request.data == {"content": "x"} + assert request.hook == "before_model" + # ``trace_id`` is not carried on the wire — the provider resolves at HTTP time. + assert request.trace_id in (None, "") + assert request.src_timestamp == "2026-06-06T00:00:00Z" + assert request.agent_name == "langchain" + assert request.runtime_id == "patch-langchain" + # Job-context fields are left for the provider to auto-fill from env. + assert request.folder_key is None + assert request.job_key is None + assert request.process_key is None + assert request.reference_id is None + assert request.agent_version is None + # Runtime-identity fields are unset without metadata (server defaults them). + assert request.agent_framework is None + assert request.agent_type is None + assert request.runtime_version is None + + +def test_submit_stamps_runtime_metadata() -> None: + """When runtime_metadata is supplied, its identity fields ride the request.""" + from uipath.runtime.governance._audit.metadata import GovernanceRuntimeMetadata + + meta = GovernanceRuntimeMetadata( + agent_type="uipath_coded", + agent_framework="langchain", + runtime_version="0.11.4", + ) + provider = _provider() + compensator = GuardrailCompensator(provider, runtime_metadata=meta) + + compensator.submit( + _rules("pii_detection"), + {"content": "x"}, + "before_model", + "2026-06-06T00:00:00Z", + "langchain", + "patch-langchain", + ) + + (request,) = provider.compensate.call_args.args + assert request.agent_framework == "langchain" + assert request.agent_type == "uipath_coded" + assert request.runtime_version == "0.11.4" + + +def test_submit_dedupes_validators() -> None: + """Multiple rules with the same validator collapse on the wire.""" + provider = _provider() + compensator = GuardrailCompensator(provider) + rules = _rules("pii_detection") + _rules("pii_detection", rule_id="R2") + + compensator.submit(rules, {}, "before_model", "ts", "a", "r") + + (request,) = provider.compensate.call_args.args + assert request.validators == ["pii_detection"] + # Per-rule metadata is preserved (one record per rule even with shared validator). + assert len(request.rules) == 2 + + +def test_submit_swallows_provider_errors() -> None: + """A provider exception must never propagate to the caller / agent.""" + provider = _provider() + provider.compensate.side_effect = RuntimeError("network down") + compensator = GuardrailCompensator(provider) + + # Must not raise. + compensator.submit(_rules("x"), {}, "before_model", "ts", "a", "r") + + provider.compensate.assert_called_once() + + +def test_submit_recovers_after_provider_error() -> None: + """A failed call doesn't poison the compensator — the next call still fires.""" + provider = _provider() + provider.compensate.side_effect = [RuntimeError("transient"), None] + compensator = GuardrailCompensator(provider) + + compensator.submit(_rules("x"), {}, "before_model", "ts", "a", "r") + compensator.submit(_rules("x"), {}, "before_model", "ts", "a", "r") + + assert provider.compensate.call_count == 2 + + +# --------------------------------------------------------------------------- +# close — no-op for API symmetry +# --------------------------------------------------------------------------- + + +def test_close_is_a_noop() -> None: + """``close()`` holds no resources to release; calling it twice is safe.""" + c = GuardrailCompensator(_provider()) + c.close() + c.close() # must not raise diff --git a/tests/test_traces_severity.py b/tests/test_traces_severity.py new file mode 100644 index 0000000..f93eab8 --- /dev/null +++ b/tests/test_traces_severity.py @@ -0,0 +1,472 @@ +"""Tests for trace-span verbosity / status semantics. + +``TracesAuditSink`` emits an OpenTelemetry span for every governance +hook end and every rule evaluation. The verdict is split into +``evaluator_result`` (what the rule decided, mode-independent) and +``action_applied`` (what actually happened, derived from +evaluator_result + mode). + +Mode travels with the event (set by the emitter from its +per-instance ``EnforcementMode``) so parallel runtimes running +different modes don't cross-contaminate the sink's view. + +- ``verbosityLevel = 4`` (Error) and ``StatusCode.ERROR`` fire **only** + when ``action_applied = DENY`` — i.e. the runtime actually blocked + the agent (ENFORCE mode + configured action ``deny``). +- ``verbosityLevel = 3`` (Warning) and ``Status.UNSET`` for advisory + outcomes (``action_applied`` in ``{AUDIT, HITL}``). HITL is its own + bucket — escalation pauses for human review, it doesn't fail the + run, so it stays Warning even in ENFORCE mode. +- Hook spans never set Status, regardless of mode or final_action. + They're summary containers; severity belongs on the per-rule span. +- ``ALLOW`` / ``NONE`` results leave verbosityLevel unset (consumers + apply their default) and never call set_status. +""" + +from __future__ import annotations + +from unittest.mock import MagicMock + +import pytest +from uipath.core.governance import EnforcementMode + +from uipath.runtime.governance._audit.base import AuditEvent, EventType +from uipath.runtime.governance._audit.traces import TracesAuditSink + + +@pytest.fixture +def captured_span(monkeypatch: pytest.MonkeyPatch) -> MagicMock: + """Wire ``TracesAuditSink`` to a mock tracer and return the span mock.""" + span = MagicMock(name="span") + tracer = MagicMock(name="tracer") + tracer.start_as_current_span.return_value.__enter__.return_value = span + tracer.start_as_current_span.return_value.__exit__.return_value = False + monkeypatch.setattr(TracesAuditSink, "_get_tracer", lambda self: tracer) + return span + + +def _hook_event(final_action: str, mode: EnforcementMode) -> AuditEvent: + return AuditEvent( + event_type=EventType.HOOK_END, + agent_name="agent", + hook="after_model", + data={ + "total_rules": 1, + "matched_rules": 1 if final_action != "allow" else 0, + "final_action": final_action, + "enforcement_mode": mode, + }, + ) + + +def _rule_event( + matched: bool, action: str, mode: EnforcementMode = EnforcementMode.AUDIT +) -> AuditEvent: + return AuditEvent( + event_type=EventType.RULE_EVALUATION, + agent_name="agent", + hook="after_model", + data={ + "policy_id": "A.10.4", + "rule_name": "commitment-language", + "pack_name": "iso42001", + "matched": matched, + "action": action, + "enforcement_mode": mode, + "status": "MATCHED" if matched else "PASS", + "detail": "Customer-binding commitment detected.", + }, + ) + + +def _span_attrs(span: MagicMock) -> dict[str, object]: + """Return a mapping of attribute name → value for set_attribute calls.""" + attrs: dict[str, object] = {} + for call in span.set_attribute.call_args_list: + key, value = call.args + attrs[key] = value + return attrs + + +# --------------------------------------------------------------------------- +# Hook span — never marked ERROR +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "final_action,mode", + [ + ("deny", EnforcementMode.ENFORCE), + ("deny", EnforcementMode.AUDIT), + ("audit", EnforcementMode.AUDIT), + ("escalate", EnforcementMode.AUDIT), + ("allow", EnforcementMode.AUDIT), + ], +) +def test_hook_span_never_sets_error( + captured_span: MagicMock, final_action: str, mode: EnforcementMode +) -> None: + """Hook spans are summary containers — they never carry an ERROR Status.""" + sink = TracesAuditSink() + sink.emit(_hook_event(final_action=final_action, mode=mode)) + assert not captured_span.set_status.called, ( + f"Hook span should never set_status; called with " + f"final_action={final_action!r}, mode={mode!r}" + ) + + +# --------------------------------------------------------------------------- +# Rule span — enforce-mode DENY is the only Status.ERROR case +# --------------------------------------------------------------------------- + + +def test_enforce_mode_deny_is_error(captured_span: MagicMock) -> None: + """Enforce mode + action=deny = real block → verbosityLevel=4 + Status.ERROR.""" + sink = TracesAuditSink() + sink.emit(_rule_event(matched=True, action="deny", mode=EnforcementMode.ENFORCE)) + + attrs = _span_attrs(captured_span) + assert attrs.get("verbosityLevel") == 4 + assert attrs.get("uipath_governance.evaluator_result") == "DENY" + assert attrs.get("uipath_governance.action_applied") == "DENY" + assert attrs.get("uipath_governance.mode") == "ENFORCE" + + assert captured_span.set_status.called, ( + "Status.ERROR must fire for enforce-mode deny violation" + ) + (status_arg,) = captured_span.set_status.call_args.args + from opentelemetry.trace import Status, StatusCode + + assert isinstance(status_arg, Status) + assert status_arg.status_code is StatusCode.ERROR + description = status_arg.description or "" + assert "commitment-language" in description + assert "deny" in description + + +def test_enforce_mode_escalate_is_hitl_warning(captured_span: MagicMock) -> None: + """Enforce mode + action=escalate = HITL pause, not a block. + + HITL is its own spec bucket distinct from DENY — escalation pauses + for human review, the run isn't failed. So verbosityLevel stays at + Warning and Status is not marked ERROR. + """ + sink = TracesAuditSink() + sink.emit( + _rule_event(matched=True, action="escalate", mode=EnforcementMode.ENFORCE) + ) + + attrs = _span_attrs(captured_span) + assert attrs.get("verbosityLevel") == 3 + assert attrs.get("uipath_governance.evaluator_result") == "HITL" + assert attrs.get("uipath_governance.action_applied") == "HITL" + assert attrs.get("uipath_governance.mode") == "ENFORCE" + assert not captured_span.set_status.called + + +# --------------------------------------------------------------------------- +# Rule span — advisory violations (audit mode, or audit-action rules) +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "action,expected_evaluator", + [("deny", "DENY"), ("audit", "DENY"), ("escalate", "HITL")], +) +def test_audit_mode_violation_is_warning( + captured_span: MagicMock, action: str, expected_evaluator: str +) -> None: + """Audit mode never blocks → action_applied=AUDIT, verbosityLevel=3. + + Surfacing Status.ERROR for an audit-mode violation would falsely + mark the agent's run as failed when the runtime intentionally + let it through. evaluator_result still records the rule's actual + decision (DENY/HITL), independent of mode. + """ + sink = TracesAuditSink() + sink.emit(_rule_event(matched=True, action=action, mode=EnforcementMode.AUDIT)) + + attrs = _span_attrs(captured_span) + assert attrs.get("verbosityLevel") == 3 + assert attrs.get("uipath_governance.evaluator_result") == expected_evaluator + assert attrs.get("uipath_governance.action_applied") == "AUDIT" + assert attrs.get("uipath_governance.mode") == "AUDIT" + + assert not captured_span.set_status.called, ( + f"Audit-mode {action} violation must NOT set Status.ERROR" + ) + + +def test_enforce_mode_audit_action_is_warning(captured_span: MagicMock) -> None: + """Enforce mode + action=audit is a per-rule audit override. + + The rule's configured ``audit`` action means "log this match but + don't block" even when the global mode is ENFORCE. evaluator_result + is DENY (the rule decided to deny), but action_applied is AUDIT + (the per-rule override kicks in), so verbosity stays Warning. + """ + sink = TracesAuditSink() + sink.emit(_rule_event(matched=True, action="audit", mode=EnforcementMode.ENFORCE)) + + attrs = _span_attrs(captured_span) + assert attrs.get("verbosityLevel") == 3 + assert attrs.get("uipath_governance.evaluator_result") == "DENY" + assert attrs.get("uipath_governance.action_applied") == "AUDIT" + assert attrs.get("uipath_governance.mode") == "ENFORCE" + assert not captured_span.set_status.called + + +# --------------------------------------------------------------------------- +# Rule span — no violation, no verbosityLevel attribute (Orchestrator default = 2) +# --------------------------------------------------------------------------- + + +def test_unmatched_rule_no_verbosity_no_error(captured_span: MagicMock) -> None: + """Unmatched evaluations → evaluator_result=ALLOW, action_applied=NONE, quiet.""" + sink = TracesAuditSink() + sink.emit(_rule_event(matched=False, action="deny", mode=EnforcementMode.ENFORCE)) + + attrs = _span_attrs(captured_span) + assert "verbosityLevel" not in attrs + assert attrs.get("uipath_governance.evaluator_result") == "ALLOW" + assert attrs.get("uipath_governance.action_applied") == "NONE" + assert not captured_span.set_status.called + + +def test_matched_allow_action_no_verbosity(captured_span: MagicMock) -> None: + """A rule whose action is 'allow' is an explicit non-violation.""" + sink = TracesAuditSink() + sink.emit(_rule_event(matched=True, action="allow", mode=EnforcementMode.ENFORCE)) + + attrs = _span_attrs(captured_span) + assert "verbosityLevel" not in attrs + assert attrs.get("uipath_governance.evaluator_result") == "ALLOW" + assert attrs.get("uipath_governance.action_applied") == "NONE" + assert not captured_span.set_status.called + + +# --------------------------------------------------------------------------- +# Cross-runtime isolation — the architectural motivation for the refactor +# --------------------------------------------------------------------------- + + +def test_two_events_carry_independent_modes(captured_span: MagicMock) -> None: + """Parallel runtimes (different modes) cannot cross-contaminate the sink. + + Mode travels on each event (set by the emitter from its own + per-instance ``EnforcementMode``), so two consecutive emits with + different modes each render their own correct + ``uipath_governance.mode`` value — no shared state in the sink + that one runtime could clobber for another. + """ + sink = TracesAuditSink() + + sink.emit(_rule_event(matched=True, action="deny", mode=EnforcementMode.ENFORCE)) + sink.emit(_rule_event(matched=True, action="deny", mode=EnforcementMode.AUDIT)) + + # Collect every set_attribute call ordered by emit. + calls = [c.args for c in captured_span.set_attribute.call_args_list] + modes = [v for k, v in calls if k == "uipath_governance.mode"] + actions_applied = [v for k, v in calls if k == "uipath_governance.action_applied"] + assert modes == ["ENFORCE", "AUDIT"] + assert actions_applied == ["DENY", "AUDIT"] + + +# --------------------------------------------------------------------------- +# _get_tracer — deferred init + ImportError fallback +# --------------------------------------------------------------------------- + + +def test_get_tracer_initializes_lazily_and_caches() -> None: + """``_get_tracer`` should populate ``self._tracer`` on first call and + return the same tracer on subsequent calls. This exercises the + real (non-monkeypatched) path — most other tests stub the method. + """ + sink = TracesAuditSink() + # Before first call — deferred, no tracer yet. + assert sink._tracer is None + + tracer_1 = sink._get_tracer() + assert tracer_1 is not None # OTel is installed; a tracer is returned + + tracer_2 = sink._get_tracer() + # Second call returns the cached tracer — no re-init log flood. + assert tracer_2 is tracer_1 + + +def test_get_tracer_returns_none_when_opentelemetry_missing( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """If a downstream host strips OpenTelemetry, ``_get_tracer`` logs a + warning once and caches ``False`` so subsequent calls short-circuit + instead of retrying the import every event. + """ + import builtins + + real_import = builtins.__import__ + + def _blocked_import(name: str, *args, **kwargs): + if name == "opentelemetry" or name.startswith("opentelemetry."): + raise ImportError(f"simulated missing: {name}") + return real_import(name, *args, **kwargs) + + monkeypatch.setattr(builtins, "__import__", _blocked_import) + + sink = TracesAuditSink() + + assert sink._get_tracer() is None + # Cached — no retry. + assert sink._tracer is False + assert sink._get_tracer() is None + + +def test_emit_is_a_noop_when_tracer_unavailable( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """When ``_get_tracer`` returns None, ``emit`` short-circuits inside + both ``_emit_rule_span`` and ``_emit_hook_span`` without touching + the tracer. Regression guard for the early-return branch. + """ + sink = TracesAuditSink() + monkeypatch.setattr(sink, "_get_tracer", lambda: None) + + # Both event types — must not raise, must not create spans. + sink.emit(_hook_event(final_action="deny", mode=EnforcementMode.ENFORCE)) + sink.emit(_rule_event(matched=True, action="deny", mode=EnforcementMode.ENFORCE)) + assert sink.spans_created == 0 + + +# --------------------------------------------------------------------------- +# spans_created — internal counter +# --------------------------------------------------------------------------- + + +def test_spans_created_increments_per_successful_emit( + captured_span: MagicMock, +) -> None: + """The ``spans_created`` counter must reflect every successful span + creation. Consumers use this for smoke-test assertions in + integration tests. + """ + sink = TracesAuditSink() + + assert sink.spans_created == 0 + sink.emit(_rule_event(matched=True, action="deny", mode=EnforcementMode.ENFORCE)) + assert sink.spans_created == 1 + sink.emit(_hook_event(final_action="deny", mode=EnforcementMode.ENFORCE)) + assert sink.spans_created == 2 + + +# --------------------------------------------------------------------------- +# _resolve_mode — enforcement-mode field parsing +# --------------------------------------------------------------------------- + + +def test_resolve_mode_reads_string_field(captured_span: MagicMock) -> None: + """Emitters that forward the raw enum value as a lowercase string + (rather than the ``EnforcementMode`` object) must still resolve to + the correct mode. This exercises the ``isinstance(mode, str)`` + branch of ``_resolve_mode``. + """ + sink = TracesAuditSink() + + ev = AuditEvent( + event_type=EventType.RULE_EVALUATION, + agent_name="agent", + hook="after_model", + data={ + "policy_id": "A.1.1", + "matched": True, + "action": "deny", + "enforcement_mode": "enforce", # string, not EnforcementMode + }, + ) + sink.emit(ev) + + modes = [ + c.args[1] + for c in captured_span.set_attribute.call_args_list + if c.args[0] == "uipath_governance.mode" + ] + assert modes == ["ENFORCE"] + + +def test_resolve_mode_falls_back_to_audit_on_unknown_string( + captured_span: MagicMock, +) -> None: + """An unparseable mode string (contract violation) must not crash + the sink — it falls back to AUDIT so a bad emitter can't kill + governance telemetry. + """ + sink = TracesAuditSink() + + ev = AuditEvent( + event_type=EventType.RULE_EVALUATION, + agent_name="agent", + hook="after_model", + data={ + "policy_id": "A.1.1", + "matched": True, + "action": "deny", + "enforcement_mode": "not-a-real-mode", + }, + ) + sink.emit(ev) + + modes = [ + c.args[1] + for c in captured_span.set_attribute.call_args_list + if c.args[0] == "uipath_governance.mode" + ] + assert modes == ["AUDIT"] # safe default + + +# --------------------------------------------------------------------------- +# _package_version — install-metadata lookup + fallback +# --------------------------------------------------------------------------- + + +def test_package_version_returns_unknown_when_package_not_installed( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """The version helper must degrade gracefully when the + ``uipath-runtime`` package metadata isn't findable (e.g., when + running from a source checkout without an install). + """ + import importlib.metadata + + from uipath.runtime.governance._audit import traces + + def _raise_not_found(name: str) -> str: + raise importlib.metadata.PackageNotFoundError(name) + + monkeypatch.setattr(importlib.metadata, "version", _raise_not_found) + + assert traces._package_version() == "unknown" + + +# --------------------------------------------------------------------------- +# Exception isolation — sink swallows internal errors, per contract +# --------------------------------------------------------------------------- + + +def test_rule_span_exception_is_swallowed( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """A sink emit must never propagate exceptions to the caller — the + audit manager's circuit breaker tracks failures, but the sink + itself catches so a broken tracer can't crash the agent hook. + """ + sink = TracesAuditSink() + + # Tracer whose start_as_current_span raises inside the with-block. + tracer = MagicMock() + tracer.start_as_current_span.side_effect = RuntimeError("tracer boom") + monkeypatch.setattr(sink, "_get_tracer", lambda: tracer) + + # Must not raise. + sink.emit(_rule_event(matched=True, action="deny", mode=EnforcementMode.ENFORCE)) + sink.emit(_hook_event(final_action="deny", mode=EnforcementMode.ENFORCE)) + + # And no span was successfully created. + assert sink.spans_created == 0 diff --git a/tests/test_track_events_sink.py b/tests/test_track_events_sink.py new file mode 100644 index 0000000..ee38f31 --- /dev/null +++ b/tests/test_track_events_sink.py @@ -0,0 +1,416 @@ +"""Tests for :class:`TrackEventAuditSink`. + +Verifies the volume-control filter (``accepts``), event-name vocabulary, +payload shape (runtime metadata + per-event fields), and OTel-span → +``operation_id`` correlation (sink resolves the correlation id from +the live OTel context at emit time, not from the event itself). Uses +a capture-callable in place of the host-supplied ``track_event`` so +no I/O fires. +""" + +from __future__ import annotations + +from datetime import datetime, timezone +from typing import Any + +import pytest +from uipath.core.governance import EnforcementMode + +from uipath.runtime.governance._audit.base import AuditEvent, EventType +from uipath.runtime.governance._audit.metadata import GovernanceRuntimeMetadata +from uipath.runtime.governance._audit.track_events import ( + EVENT_HOOK_SUMMARY, + EVENT_RULE_DENIED, + TrackEventAuditSink, +) + + +class _Capture: + """Stand-in for ``provider.track_event`` — records every call.""" + + def __init__(self) -> None: + self.calls: list[dict[str, Any]] = [] + + def __call__( + self, + *, + event_name: str, + data: dict[str, Any] | None = None, + operation_id: str | None = None, + ) -> None: + self.calls.append( + {"event_name": event_name, "data": data, "operation_id": operation_id} + ) + + +@pytest.fixture +def capture() -> _Capture: + return _Capture() + + +@pytest.fixture +def metadata() -> GovernanceRuntimeMetadata: + return GovernanceRuntimeMetadata( + execution_engine="uipath_native_governance_checker", + agent_type="uipath_coded", + agent_framework="langchain", + runtime_version="9.9.9-test", + ) + + +@pytest.fixture +def sink(capture: _Capture, metadata: GovernanceRuntimeMetadata) -> TrackEventAuditSink: + return TrackEventAuditSink(capture, metadata) + + +def _rule_event( + *, + matched: bool, + action: str = "deny", + mode: EnforcementMode = EnforcementMode.AUDIT, + duration_ms: float = 12.5, + mapped_to_uipath: bool = False, +) -> AuditEvent: + return AuditEvent( + event_type=EventType.RULE_EVALUATION, + agent_name="agent-x", + hook="after_model", + data={ + "policy_id": "A.6.1.4", + "rule_name": "commitment-language", + "pack_name": "iso42001", + "matched": matched, + "action": action, + "enforcement_mode": mode, + "detail": "Detected a commitment phrase.", + "duration_ms": duration_ms, + "mapped_to_uipath": mapped_to_uipath, + }, + timestamp=datetime(2026, 6, 25, 12, 0, 0, tzinfo=timezone.utc), + ) + + +def _hook_event( + *, + mode: EnforcementMode = EnforcementMode.AUDIT, + duration_ms: float = 45.0, + passed_count: int = 4, + denied_count: int = 1, + skipped_policy_names: list[str] | None = None, + guardrail_dispatched_count: int = 0, +) -> AuditEvent: + return AuditEvent( + event_type=EventType.HOOK_END, + agent_name="agent-x", + hook="after_model", + data={ + "total_rules": passed_count + denied_count, + "matched_rules": denied_count, + "final_action": "audit", + "enforcement_mode": mode, + "duration_ms": duration_ms, + "passed_count": passed_count, + "denied_count": denied_count, + "skipped_count": len(skipped_policy_names or []), + "skipped_policy_names": list(skipped_policy_names or []), + "guardrail_dispatched_count": guardrail_dispatched_count, + }, + timestamp=datetime(2026, 6, 25, 12, 0, 0, tzinfo=timezone.utc), + ) + + +# --------------------------------------------------------------------------- +# accepts() — volume-control filter +# --------------------------------------------------------------------------- + + +def test_accepts_matched_rule_evaluation(sink: TrackEventAuditSink) -> None: + assert sink.accepts(_rule_event(matched=True)) is True + + +def test_rejects_unmatched_rule_evaluation(sink: TrackEventAuditSink) -> None: + assert sink.accepts(_rule_event(matched=False)) is False + + +def test_rejects_matched_allow_rule(sink: TrackEventAuditSink) -> None: + """A matched rule with action=allow is a positive informational + match — it should NOT trigger the ``rule.denied`` stream. It rolls + into the hook summary's ``passed_count`` instead. + """ + assert sink.accepts(_rule_event(matched=True, action="allow")) is False + + +def test_direct_emit_of_unmatched_rule_is_noop( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """Defense-in-depth: even if a caller bypasses ``accepts``, passed + rules must not be routed to ``governance.rule.denied``. + + The AuditManager dispatch path always consults ``accepts`` first, + but a direct ``sink.emit(...)`` call (tests, future alternate + dispatch) must still produce zero ``track_event`` calls for a + ``matched=False`` rule. + """ + sink.emit(_rule_event(matched=False)) + assert capture.calls == [] + + +def test_direct_emit_of_matched_allow_rule_is_noop( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """Defense-in-depth equivalent of the matched-but-allow filter.""" + sink.emit(_rule_event(matched=True, action="allow")) + assert capture.calls == [] + + +# --------------------------------------------------------------------------- +# DISABLED mode — zero telemetry across every event type +# --------------------------------------------------------------------------- + + +def test_rejects_disabled_mode_rule_evaluation(sink: TrackEventAuditSink) -> None: + """Governance off → ``accepts`` returns False for rule events.""" + assert ( + sink.accepts(_rule_event(matched=True, mode=EnforcementMode.DISABLED)) is False + ) + + +def test_rejects_disabled_mode_hook_summary(sink: TrackEventAuditSink) -> None: + """Governance off → ``accepts`` returns False for hook summaries.""" + assert sink.accepts(_hook_event(mode=EnforcementMode.DISABLED)) is False + + +def test_direct_emit_of_disabled_rule_is_noop( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """Defense-in-depth: ``emit`` drops DISABLED-mode events too.""" + sink.emit(_rule_event(matched=True, mode=EnforcementMode.DISABLED)) + assert capture.calls == [] + + +def test_direct_emit_of_disabled_hook_is_noop( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """Defense-in-depth for hook summary in DISABLED mode.""" + sink.emit(_hook_event(mode=EnforcementMode.DISABLED)) + assert capture.calls == [] + + +# --------------------------------------------------------------------------- +# Empty hook summary suppression +# --------------------------------------------------------------------------- + + +def test_rejects_empty_hook_summary(sink: TrackEventAuditSink) -> None: + """``total_rules=0`` AND ``skipped_count=0`` → nothing to report.""" + ev = _hook_event(passed_count=0, denied_count=0, skipped_policy_names=[]) + assert sink.accepts(ev) is False + + +def test_accepts_hook_summary_with_only_skipped(sink: TrackEventAuditSink) -> None: + """Hook with ``total=0`` but ``skipped_count>0`` is still operator-useful.""" + ev = _hook_event( + passed_count=0, + denied_count=0, + skipped_policy_names=["A.1.1", "A.1.2"], + ) + assert sink.accepts(ev) is True + + +def test_direct_emit_of_empty_hook_is_noop( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """Defense-in-depth equivalent of the empty-hook filter.""" + sink.emit(_hook_event(passed_count=0, denied_count=0, skipped_policy_names=[])) + assert capture.calls == [] + + +def test_accepts_hook_end(sink: TrackEventAuditSink) -> None: + assert sink.accepts(_hook_event()) is True + + +def test_rejects_other_event_types(sink: TrackEventAuditSink) -> None: + for et in ( + EventType.HOOK_START, + EventType.SESSION_START, + EventType.SESSION_END, + EventType.POLICY_VIOLATION, + EventType.POLICY_ALLOW, + EventType.PACKS_LOADED, + ): + ev = AuditEvent(event_type=et, agent_name="agent-x") + assert sink.accepts(ev) is False, f"sink must drop {et}" + + +# --------------------------------------------------------------------------- +# emit() — rule-denied event shape +# --------------------------------------------------------------------------- + + +def test_rule_denied_event_name_and_operation_id( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """``operation_id`` is the live OTel span's trace id rendered as 32-hex. + + The sink reads from :func:`opentelemetry.trace.get_current_span` at + emit time — the audit manager dispatches synchronously on the + caller's thread, so any span open on the calling thread is visible + to the sink directly. + """ + from opentelemetry.sdk.trace import TracerProvider + + tracer = TracerProvider().get_tracer("test") + with tracer.start_as_current_span("agent-run") as span: + expected = f"{span.get_span_context().trace_id:032x}" + sink.emit(_rule_event(matched=True)) + + assert len(capture.calls) == 1 + call = capture.calls[0] + assert call["event_name"] == EVENT_RULE_DENIED + assert call["operation_id"] == expected + + +def test_rule_denied_payload_carries_metadata( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + sink.emit(_rule_event(matched=True)) + data = capture.calls[0]["data"] + assert data["execution_engine"] == "uipath_native_governance_checker" + assert data["agent_type"] == "uipath_coded" + assert data["agent_framework"] == "langchain" + assert data["runtime_version"] == "9.9.9-test" + assert data["agent_name"] == "agent-x" + assert data["hook"] == "after_model" + + +def test_rule_denied_payload_splits_pack_and_clause( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """``pack`` and ``clause`` are separate fields so consumers can aggregate.""" + sink.emit(_rule_event(matched=True)) + data = capture.calls[0]["data"] + assert data["pack"] == "iso42001" + assert data["clause"] == "A.6.1.4" + assert data["rule_name"] == "commitment-language" + + +def test_rule_denied_audit_mode_collapses_to_audit( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """AUDIT mode never escalates DENY past AUDIT, but evaluator_result is true.""" + sink.emit(_rule_event(matched=True, action="deny", mode=EnforcementMode.AUDIT)) + data = capture.calls[0]["data"] + assert data["mode"] == "AUDIT" + assert data["evaluator_result"] == "DENY" + assert data["action_applied"] == "AUDIT" + + +def test_rule_denied_enforce_mode_deny( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + sink.emit(_rule_event(matched=True, action="deny", mode=EnforcementMode.ENFORCE)) + data = capture.calls[0]["data"] + assert data["mode"] == "ENFORCE" + assert data["evaluator_result"] == "DENY" + assert data["action_applied"] == "DENY" + + +def test_rule_denied_enforce_mode_escalate_is_hitl( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + sink.emit( + _rule_event(matched=True, action="escalate", mode=EnforcementMode.ENFORCE) + ) + data = capture.calls[0]["data"] + assert data["evaluator_result"] == "HITL" + assert data["action_applied"] == "HITL" + + +def test_rule_denied_carries_duration( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + sink.emit(_rule_event(matched=True, duration_ms=42.5)) + assert capture.calls[0]["data"]["duration_ms"] == 42.5 + + +def test_rule_denied_mapped_to_uipath_passes_through( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """Field defaults False for native events but the schema is stable.""" + sink.emit(_rule_event(matched=True, mapped_to_uipath=False)) + assert capture.calls[0]["data"]["mapped_to_uipath"] is False + + +# --------------------------------------------------------------------------- +# emit() — hook-summary event shape +# --------------------------------------------------------------------------- + + +def test_hook_summary_event_name_and_operation_id( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """Same OTel-derived operation_id contract as the rule-denied event.""" + from opentelemetry.sdk.trace import TracerProvider + + tracer = TracerProvider().get_tracer("test") + with tracer.start_as_current_span("agent-run") as span: + expected = f"{span.get_span_context().trace_id:032x}" + sink.emit(_hook_event()) + + assert len(capture.calls) == 1 + assert capture.calls[0]["event_name"] == EVENT_HOOK_SUMMARY + assert capture.calls[0]["operation_id"] == expected + + +def test_hook_summary_carries_counts( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + sink.emit( + _hook_event( + passed_count=10, + denied_count=2, + skipped_policy_names=["A.1.2", "A.3.4"], + guardrail_dispatched_count=3, + ) + ) + data = capture.calls[0]["data"] + assert data["passed_count"] == 10 + assert data["denied_count"] == 2 + assert data["skipped_count"] == 2 + assert data["skipped_policy_names"] == ["A.1.2", "A.3.4"] + assert data["guardrail_dispatched_count"] == 3 + + +def test_hook_summary_duration_ms(sink: TrackEventAuditSink, capture: _Capture) -> None: + sink.emit(_hook_event(duration_ms=123.4)) + assert capture.calls[0]["data"]["duration_ms"] == 123.4 + + +def test_hook_summary_carries_metadata( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """Same per-runtime metadata stamping as rule-denied events.""" + sink.emit(_hook_event()) + data = capture.calls[0]["data"] + assert data["execution_engine"] == "uipath_native_governance_checker" + assert data["agent_type"] == "uipath_coded" + assert data["agent_framework"] == "langchain" + assert data["runtime_version"] == "9.9.9-test" + + +def test_hook_summary_mode_string(sink: TrackEventAuditSink, capture: _Capture) -> None: + sink.emit(_hook_event(mode=EnforcementMode.ENFORCE)) + assert capture.calls[0]["data"]["mode"] == "ENFORCE" + + +# --------------------------------------------------------------------------- +# operation_id fallback when no OTel span is active +# --------------------------------------------------------------------------- + + +def test_operation_id_none_when_no_active_span( + sink: TrackEventAuditSink, capture: _Capture +) -> None: + """No live OTel span → ``operation_id=None`` (consumer fills in its own).""" + sink.emit(_rule_event(matched=True)) + assert capture.calls[0]["operation_id"] is None diff --git a/uv.lock b/uv.lock index 2aaded6..24e8901 100644 --- a/uv.lock +++ b/uv.lock @@ -99,6 +99,132 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/db/3c/33bac158f8ab7f89b2e59426d5fe2e4f63f7ed25df84c036890172b412b5/cfgv-3.5.0-py2.py3-none-any.whl", hash = "sha256:a8dc6b26ad22ff227d2634a65cb388215ce6cc96bbcc5cfde7641ae87e8dacc0", size = 7445, upload-time = "2025-11-19T20:55:50.744Z" }, ] +[[package]] +name = "chardet" +version = "7.4.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/19/b6/9df434a8eeba2e6628c465a1dfa31034228ef79b26f76f46278f4ef7e49d/chardet-7.4.3.tar.gz", hash = "sha256:cc1d4eb92a4ec1c2df3b490836ffa46922e599d34ce0bb75cf41fd2bf6303d56", size = 784800, upload-time = "2026-04-13T21:33:39.803Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/19/52/505c207f334d51e937cbaa27ff95776e16e2d120e13cbe491cd7b3a70b50/chardet-7.4.3-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:25a862cddc6a9ac07023e808aedd297115345fbaabc2690479481ddc0f980e09", size = 870747, upload-time = "2026-04-13T21:32:56.916Z" }, + { url = "https://files.pythonhosted.org/packages/14/4b/d3c79495dee4831b8bebca2790e72cb90f0c5849c940570a7c7e5b70b952/chardet-7.4.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:7005c88da26fd95d8abb8acbe6281d833e9a9181b03cf49b4546c4555389bd97", size = 853210, upload-time = "2026-04-13T21:32:58.309Z" }, + { url = "https://files.pythonhosted.org/packages/b9/99/f6a822ad1bde25a4c38dc3e770485e78e0893dfd871cd6e18ed3ea3a795e/chardet-7.4.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dc50f28bad067393cce0af9091052c3b8df7a23115afd8ba7b2e0947f0cef1f8", size = 873625, upload-time = "2026-04-13T21:32:59.606Z" }, + { url = "https://files.pythonhosted.org/packages/b1/10/31932775c94a86814f76b41c4a772b52abfb0e6125324f32c6da1196c297/chardet-7.4.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4c3da294de1a681097848ab58bd3f2771a674f8039d2d87a5538b28856b815e9", size = 883436, upload-time = "2026-04-13T21:33:01.351Z" }, + { url = "https://files.pythonhosted.org/packages/6c/63/0f43e3acf2c436fdb32a0f904aeb03a2904d2126eed34a042a194d235926/chardet-7.4.3-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:93c45e116dd51b66226a53ade3f9f635e870de5399b90e00ce45dcc311093bf4", size = 876589, upload-time = "2026-04-13T21:33:02.636Z" }, + { url = "https://files.pythonhosted.org/packages/5d/a6/e9b8f8a3e99602792b01fa7d0a731737615ab56d8bfd0b52935a0ef88b85/chardet-7.4.3-cp311-cp311-win_amd64.whl", hash = "sha256:ccc1f83ab4bcfb901cf39e0c4ba6bc6e726fc6264735f10e24ceb5cb47387578", size = 941866, upload-time = "2026-04-13T21:33:04.282Z" }, + { url = "https://files.pythonhosted.org/packages/61/33/29de185079e6675c3f375546e30a559b7ddc75ce972f18d6e566cd9ea4eb/chardet-7.4.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:75d3c65cc16bddf40b8da1fd25ba84fca5f8070f2b14e86083653c1c85aee971", size = 874870, upload-time = "2026-04-13T21:33:05.977Z" }, + { url = "https://files.pythonhosted.org/packages/9c/2f/4c5af01fd1a7506a1d5375403d68925eac70289229492db5aa68b58103d8/chardet-7.4.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:29af5999f654e8729d251f1724a62b538b1262d9292cccaefddf8a02aae1ef6a", size = 854859, upload-time = "2026-04-13T21:33:07.381Z" }, + { url = "https://files.pythonhosted.org/packages/36/21/edb36ad5dfa48d7f8eed97ab43931ecdaa8c15166c21b1d614967e49d681/chardet-7.4.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:626f00299ad62dfe937058a09572beed442ccc7b58f87aa667949b20fd3db235", size = 875032, upload-time = "2026-04-13T21:33:08.741Z" }, + { url = "https://files.pythonhosted.org/packages/e5/59/a32a241d861cf180853a11c8e5a67641cb1b2af13c3a5ccce83ec07e2c9f/chardet-7.4.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9a4904dd5f071b7a7d7f50b4a67a86db3c902d243bf31708f1d5cde2f68239cb", size = 888283, upload-time = "2026-04-13T21:33:10.213Z" }, + { url = "https://files.pythonhosted.org/packages/87/2e/e1ee6a77abf3782c00e05b89c4d4328c8353bf9500661c4348df1dd68614/chardet-7.4.3-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:5d2879598bc220689e8ce509fe9c3f37ad2fca53a36be9c9bd91abdd91dd364f", size = 879974, upload-time = "2026-04-13T21:33:11.448Z" }, + { url = "https://files.pythonhosted.org/packages/32/60/fca69c534602a7ced04280c952a246ad1edde2a6ca3a164f65d32ac41fe7/chardet-7.4.3-cp312-cp312-win_amd64.whl", hash = "sha256:4b2799bd58e7245cfa8d4ab2e8ad1d76a5c3a5b1f32318eb6acca4c69a3e7101", size = 943973, upload-time = "2026-04-13T21:33:12.756Z" }, + { url = "https://files.pythonhosted.org/packages/7c/43/79ac9b4db5bc87020c9dbc419125371d80882d1d197e9c4765ba8682b605/chardet-7.4.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:a9e4486df251b8962e86ea9f139ca235aa6e0542a00f7844c9a04160afb99aa9", size = 873769, upload-time = "2026-04-13T21:33:14.002Z" }, + { url = "https://files.pythonhosted.org/packages/55/5f/25bdec773905bff0ff6cf35ca73b17bd05593b4f87bd8c5fa43705f7167d/chardet-7.4.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:4fbff1907925b0c5a1064cffb5e040cd5e338585c9c552625f30de6bc2f3107a", size = 853991, upload-time = "2026-04-13T21:33:15.564Z" }, + { url = "https://files.pythonhosted.org/packages/b4/07/a29380ee0b215d23d77733b5ad60c5c0c7969650e080c667acdf9462040d/chardet-7.4.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:365135eaf37ba65a828f8e668eb0a8c38c479dcbec724dc25f4dfd781049c357", size = 874024, upload-time = "2026-04-13T21:33:16.915Z" }, + { url = "https://files.pythonhosted.org/packages/a8/b1/3338e121cbd4c8a126b8ccb1061170c2ce51a53f678c502793ea49c6fd6d/chardet-7.4.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bfc134b70c846c21ead8e43ada3ae1a805fff732f6922f8abcf2ff27b8f6493d", size = 887410, upload-time = "2026-04-13T21:33:18.368Z" }, + { url = "https://files.pythonhosted.org/packages/63/1c/44a9a9e0c59c185a5d307ceaeee8768afa1558f0a24f7a4b5fa11b67586b/chardet-7.4.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:9acd9988a93e09390f3cd231201ea7166c415eb8da1b735928990ffc05cb9fbb", size = 879269, upload-time = "2026-04-13T21:33:20.377Z" }, + { url = "https://files.pythonhosted.org/packages/1b/b3/5d0e77ea774bd3224321c248880ea0c0379000ac5c2bb6d77609549de247/chardet-7.4.3-cp313-cp313-win_amd64.whl", hash = "sha256:e1b98790c284ff813f18f7cf7de5f05ea2435a080030c7f1a8318f3a4f80b131", size = 944155, upload-time = "2026-04-13T21:33:21.694Z" }, + { url = "https://files.pythonhosted.org/packages/70/a8/bf0811d859e13801279a2ae64f37a408027b282f2047bc0001c75dd356ad/chardet-7.4.3-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:d892d3dcd652fdef53e3d6327d39b17c0df40a899dfc919abaeb64c974497531", size = 872887, upload-time = "2026-04-13T21:33:23.328Z" }, + { url = "https://files.pythonhosted.org/packages/51/ac/b9d68ebddfe1b02c77af5bf81120e12b036b4432dc6af7a303d90e2bc38b/chardet-7.4.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:acc46d1b8b7d5783216afe15db56d1c179b9a40e5a1558bc13164c4fd20674c4", size = 853964, upload-time = "2026-04-13T21:33:24.724Z" }, + { url = "https://files.pythonhosted.org/packages/2a/81/17fa103ea9caf5d325a5e4051ab2ba65996fd66baa60b81ee41af1f54e10/chardet-7.4.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ac3bf11c645734a1701a3804e43eabd98851838192267d08c353a834ab79fea", size = 876006, upload-time = "2026-04-13T21:33:26.098Z" }, + { url = "https://files.pythonhosted.org/packages/c2/20/193faab46a68ea550587331a698c3dca8099f8901d10937c4443135c7ed9/chardet-7.4.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6e3bd9f936e04bae89c254262af08d9e5b98f805175ba1e29d454e6cba3107b7", size = 887680, upload-time = "2026-04-13T21:33:27.49Z" }, + { url = "https://files.pythonhosted.org/packages/40/c6/94a3c673327392652ee8bdea9a45bc8a5f5365197a7387d68f0eed007115/chardet-7.4.3-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:27cc23da03630cdecc9aa81a895aa86629c211f995cd57651f0fbc280717bf93", size = 879865, upload-time = "2026-04-13T21:33:29.052Z" }, + { url = "https://files.pythonhosted.org/packages/b1/2c/cad8b5e3623a987f3c930b68e2bdd06cfc388cd91cd42ed05f1227701b73/chardet-7.4.3-cp314-cp314-win_amd64.whl", hash = "sha256:b95c934b9ad59e2ba8abb9be49df70d3ad1b0d95d864b9fdb7588d4fa8bd921c", size = 939594, upload-time = "2026-04-13T21:33:31.391Z" }, + { url = "https://files.pythonhosted.org/packages/33/e0/d06e42fd6f02a58e5e227e5106587751cb38adcff0aaf949add744b78b6e/chardet-7.4.3-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:c77867f0c1cb8bd819502249fcdc500364aedb07881e11b743726fa2148e7b6e", size = 889714, upload-time = "2026-04-13T21:33:32.772Z" }, + { url = "https://files.pythonhosted.org/packages/d4/ed/40d091954d48abea037baae6be8fb79905e5f78d34d12ea955132c7d8011/chardet-7.4.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:cf1efeaf65a6ef2f5b9cc3a1df6f08ba2831b369ccaa4c7018eaf90aa757bb11", size = 872319, upload-time = "2026-04-13T21:33:34.427Z" }, + { url = "https://files.pythonhosted.org/packages/bb/77/82a46821dbfbdfe062710d2bf2ede13426304e3567a23c57d919c0c31630/chardet-7.4.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9f3504c139a2ad544077dd2d9e412cd08b01786843d76997cd43bb6de311723c", size = 892021, upload-time = "2026-04-13T21:33:35.766Z" }, + { url = "https://files.pythonhosted.org/packages/49/57/42d30c562bda5b4a839766c1aad8d5856b798ad2a1c3247b72a679afec94/chardet-7.4.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:457f619882ba66327d4d8d14c6c342269bdb1e4e1c38e8117df941d14d351b04", size = 902509, upload-time = "2026-04-13T21:33:37.096Z" }, + { url = "https://files.pythonhosted.org/packages/8c/6c/0a40afdb50a0fe041ab95553b835a8160b6cf0e81edf2ae2fe9f5224cbf9/chardet-7.4.3-py3-none-any.whl", hash = "sha256:1173b74051570cf08099d7429d92e4882d375ad4217f92a6e5240ccfb26f231e", size = 626562, upload-time = "2026-04-13T21:33:38.559Z" }, +] + +[[package]] +name = "charset-normalizer" +version = "3.4.7" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/e7/a1/67fe25fac3c7642725500a3f6cfe5821ad557c3abb11c9d20d12c7008d3e/charset_normalizer-3.4.7.tar.gz", hash = "sha256:ae89db9e5f98a11a4bf50407d4363e7b09b31e55bc117b4f7d80aab97ba009e5", size = 144271, upload-time = "2026-04-02T09:28:39.342Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c2/d7/b5b7020a0565c2e9fa8c09f4b5fa6232feb326b8c20081ccded47ea368fd/charset_normalizer-3.4.7-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:7641bb8895e77f921102f72833904dcd9901df5d6d72a2ab8f31d04b7e51e4e7", size = 309705, upload-time = "2026-04-02T09:26:02.191Z" }, + { url = "https://files.pythonhosted.org/packages/5a/53/58c29116c340e5456724ecd2fff4196d236b98f3da97b404bc5e51ac3493/charset_normalizer-3.4.7-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:202389074300232baeb53ae2569a60901f7efadd4245cf3a3bf0617d60b439d7", size = 206419, upload-time = "2026-04-02T09:26:03.583Z" }, + { url = "https://files.pythonhosted.org/packages/b2/02/e8146dc6591a37a00e5144c63f29fb7c97a734ea8a111190783c0e60ab63/charset_normalizer-3.4.7-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:30b8d1d8c52a48c2c5690e152c169b673487a2a58de1ec7393196753063fcd5e", size = 227901, upload-time = "2026-04-02T09:26:04.738Z" }, + { url = "https://files.pythonhosted.org/packages/fb/73/77486c4cd58f1267bf17db420e930c9afa1b3be3fe8c8b8ebbebc9624359/charset_normalizer-3.4.7-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:532bc9bf33a68613fd7d65e4b1c71a6a38d7d42604ecf239c77392e9b4e8998c", size = 222742, upload-time = "2026-04-02T09:26:06.36Z" }, + { url = "https://files.pythonhosted.org/packages/a1/fa/f74eb381a7d94ded44739e9d94de18dc5edc9c17fb8c11f0a6890696c0a9/charset_normalizer-3.4.7-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:2fe249cb4651fd12605b7288b24751d8bfd46d35f12a20b1ba33dea122e690df", size = 214061, upload-time = "2026-04-02T09:26:08.347Z" }, + { url = "https://files.pythonhosted.org/packages/dc/92/42bd3cefcf7687253fb86694b45f37b733c97f59af3724f356fa92b8c344/charset_normalizer-3.4.7-cp311-cp311-manylinux_2_31_armv7l.whl", hash = "sha256:65bcd23054beab4d166035cabbc868a09c1a49d1efe458fe8e4361215df40265", size = 199239, upload-time = "2026-04-02T09:26:09.823Z" }, + { url = "https://files.pythonhosted.org/packages/4c/3d/069e7184e2aa3b3cddc700e3dd267413dc259854adc3380421c805c6a17d/charset_normalizer-3.4.7-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:08e721811161356f97b4059a9ba7bafb23ea5ee2255402c42881c214e173c6b4", size = 210173, upload-time = "2026-04-02T09:26:10.953Z" }, + { url = "https://files.pythonhosted.org/packages/62/51/9d56feb5f2e7074c46f93e0ebdbe61f0848ee246e2f0d89f8e20b89ebb8f/charset_normalizer-3.4.7-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:e060d01aec0a910bdccb8be71faf34e7799ce36950f8294c8bf612cba65a2c9e", size = 209841, upload-time = "2026-04-02T09:26:12.142Z" }, + { url = "https://files.pythonhosted.org/packages/d2/59/893d8f99cc4c837dda1fe2f1139079703deb9f321aabcb032355de13b6c7/charset_normalizer-3.4.7-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:38c0109396c4cfc574d502df99742a45c72c08eff0a36158b6f04000043dbf38", size = 200304, upload-time = "2026-04-02T09:26:13.711Z" }, + { url = "https://files.pythonhosted.org/packages/7d/1d/ee6f3be3464247578d1ed5c46de545ccc3d3ff933695395c402c21fa6b77/charset_normalizer-3.4.7-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:1c2a768fdd44ee4a9339a9b0b130049139b8ce3c01d2ce09f67f5a68048d477c", size = 229455, upload-time = "2026-04-02T09:26:14.941Z" }, + { url = "https://files.pythonhosted.org/packages/54/bb/8fb0a946296ea96a488928bdce8ef99023998c48e4713af533e9bb98ef07/charset_normalizer-3.4.7-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:1a87ca9d5df6fe460483d9a5bbf2b18f620cbed41b432e2bddb686228282d10b", size = 210036, upload-time = "2026-04-02T09:26:16.478Z" }, + { url = "https://files.pythonhosted.org/packages/9a/bc/015b2387f913749f82afd4fcba07846d05b6d784dd16123cb66860e0237d/charset_normalizer-3.4.7-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:d635aab80466bc95771bb78d5370e74d36d1fe31467b6b29b8b57b2a3cd7d22c", size = 224739, upload-time = "2026-04-02T09:26:17.751Z" }, + { url = "https://files.pythonhosted.org/packages/17/ab/63133691f56baae417493cba6b7c641571a2130eb7bceba6773367ab9ec5/charset_normalizer-3.4.7-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:ae196f021b5e7c78e918242d217db021ed2a6ace2bc6ae94c0fc596221c7f58d", size = 216277, upload-time = "2026-04-02T09:26:18.981Z" }, + { url = "https://files.pythonhosted.org/packages/06/6d/3be70e827977f20db77c12a97e6a9f973631a45b8d186c084527e53e77a4/charset_normalizer-3.4.7-cp311-cp311-win32.whl", hash = "sha256:adb2597b428735679446b46c8badf467b4ca5f5056aae4d51a19f9570301b1ad", size = 147819, upload-time = "2026-04-02T09:26:20.295Z" }, + { url = "https://files.pythonhosted.org/packages/20/d9/5f67790f06b735d7c7637171bbfd89882ad67201891b7275e51116ed8207/charset_normalizer-3.4.7-cp311-cp311-win_amd64.whl", hash = "sha256:8e385e4267ab76874ae30db04c627faaaf0b509e1ccc11a95b3fc3e83f855c00", size = 159281, upload-time = "2026-04-02T09:26:21.74Z" }, + { url = "https://files.pythonhosted.org/packages/ca/83/6413f36c5a34afead88ce6f66684d943d91f233d76dd083798f9602b75ae/charset_normalizer-3.4.7-cp311-cp311-win_arm64.whl", hash = "sha256:d4a48e5b3c2a489fae013b7589308a40146ee081f6f509e047e0e096084ceca1", size = 147843, upload-time = "2026-04-02T09:26:22.901Z" }, + { url = "https://files.pythonhosted.org/packages/0c/eb/4fc8d0a7110eb5fc9cc161723a34a8a6c200ce3b4fbf681bc86feee22308/charset_normalizer-3.4.7-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:eca9705049ad3c7345d574e3510665cb2cf844c2f2dcfe675332677f081cbd46", size = 311328, upload-time = "2026-04-02T09:26:24.331Z" }, + { url = "https://files.pythonhosted.org/packages/f8/e3/0fadc706008ac9d7b9b5be6dc767c05f9d3e5df51744ce4cc9605de7b9f4/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6178f72c5508bfc5fd446a5905e698c6212932f25bcdd4b47a757a50605a90e2", size = 208061, upload-time = "2026-04-02T09:26:25.568Z" }, + { url = "https://files.pythonhosted.org/packages/42/f0/3dd1045c47f4a4604df85ec18ad093912ae1344ac706993aff91d38773a2/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e1421b502d83040e6d7fb2fb18dff63957f720da3d77b2fbd3187ceb63755d7b", size = 229031, upload-time = "2026-04-02T09:26:26.865Z" }, + { url = "https://files.pythonhosted.org/packages/dc/67/675a46eb016118a2fbde5a277a5d15f4f69d5f3f5f338e5ee2f8948fcf43/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:edac0f1ab77644605be2cbba52e6b7f630731fc42b34cb0f634be1a6eface56a", size = 225239, upload-time = "2026-04-02T09:26:28.044Z" }, + { url = "https://files.pythonhosted.org/packages/4b/f8/d0118a2f5f23b02cd166fa385c60f9b0d4f9194f574e2b31cef350ad7223/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5649fd1c7bade02f320a462fdefd0b4bd3ce036065836d4f42e0de958038e116", size = 216589, upload-time = "2026-04-02T09:26:29.239Z" }, + { url = "https://files.pythonhosted.org/packages/b1/f1/6d2b0b261b6c4ceef0fcb0d17a01cc5bc53586c2d4796fa04b5c540bc13d/charset_normalizer-3.4.7-cp312-cp312-manylinux_2_31_armv7l.whl", hash = "sha256:203104ed3e428044fd943bc4bf45fa73c0730391f9621e37fe39ecf477b128cb", size = 202733, upload-time = "2026-04-02T09:26:30.5Z" }, + { url = "https://files.pythonhosted.org/packages/6f/c0/7b1f943f7e87cc3db9626ba17807d042c38645f0a1d4415c7a14afb5591f/charset_normalizer-3.4.7-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:298930cec56029e05497a76988377cbd7457ba864beeea92ad7e844fe74cd1f1", size = 212652, upload-time = "2026-04-02T09:26:31.709Z" }, + { url = "https://files.pythonhosted.org/packages/38/dd/5a9ab159fe45c6e72079398f277b7d2b523e7f716acc489726115a910097/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:708838739abf24b2ceb208d0e22403dd018faeef86ddac04319a62ae884c4f15", size = 211229, upload-time = "2026-04-02T09:26:33.282Z" }, + { url = "https://files.pythonhosted.org/packages/d5/ff/531a1cad5ca855d1c1a8b69cb71abfd6d85c0291580146fda7c82857caa1/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:0f7eb884681e3938906ed0434f20c63046eacd0111c4ba96f27b76084cd679f5", size = 203552, upload-time = "2026-04-02T09:26:34.845Z" }, + { url = "https://files.pythonhosted.org/packages/c1/4c/a5fb52d528a8ca41f7598cb619409ece30a169fbdf9cdce592e53b46c3a6/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:4dc1e73c36828f982bfe79fadf5919923f8a6f4df2860804db9a98c48824ce8d", size = 230806, upload-time = "2026-04-02T09:26:36.152Z" }, + { url = "https://files.pythonhosted.org/packages/59/7a/071feed8124111a32b316b33ae4de83d36923039ef8cf48120266844285b/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:aed52fea0513bac0ccde438c188c8a471c4e0f457c2dd20cdbf6ea7a450046c7", size = 212316, upload-time = "2026-04-02T09:26:37.672Z" }, + { url = "https://files.pythonhosted.org/packages/fd/35/f7dba3994312d7ba508e041eaac39a36b120f32d4c8662b8814dab876431/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:fea24543955a6a729c45a73fe90e08c743f0b3334bbf3201e6c4bc1b0c7fa464", size = 227274, upload-time = "2026-04-02T09:26:38.93Z" }, + { url = "https://files.pythonhosted.org/packages/8a/2d/a572df5c9204ab7688ec1edc895a73ebded3b023bb07364710b05dd1c9be/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:bb6d88045545b26da47aa879dd4a89a71d1dce0f0e549b1abcb31dfe4a8eac49", size = 218468, upload-time = "2026-04-02T09:26:40.17Z" }, + { url = "https://files.pythonhosted.org/packages/86/eb/890922a8b03a568ca2f336c36585a4713c55d4d67bf0f0c78924be6315ca/charset_normalizer-3.4.7-cp312-cp312-win32.whl", hash = "sha256:2257141f39fe65a3fdf38aeccae4b953e5f3b3324f4ff0daf9f15b8518666a2c", size = 148460, upload-time = "2026-04-02T09:26:41.416Z" }, + { url = "https://files.pythonhosted.org/packages/35/d9/0e7dffa06c5ab081f75b1b786f0aefc88365825dfcd0ac544bdb7b2b6853/charset_normalizer-3.4.7-cp312-cp312-win_amd64.whl", hash = "sha256:5ed6ab538499c8644b8a3e18debabcd7ce684f3fa91cf867521a7a0279cab2d6", size = 159330, upload-time = "2026-04-02T09:26:42.554Z" }, + { url = "https://files.pythonhosted.org/packages/9e/5d/481bcc2a7c88ea6b0878c299547843b2521ccbc40980cb406267088bc701/charset_normalizer-3.4.7-cp312-cp312-win_arm64.whl", hash = "sha256:56be790f86bfb2c98fb742ce566dfb4816e5a83384616ab59c49e0604d49c51d", size = 147828, upload-time = "2026-04-02T09:26:44.075Z" }, + { url = "https://files.pythonhosted.org/packages/c1/3b/66777e39d3ae1ddc77ee606be4ec6d8cbd4c801f65e5a1b6f2b11b8346dd/charset_normalizer-3.4.7-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:f496c9c3cc02230093d8330875c4c3cdfc3b73612a5fd921c65d39cbcef08063", size = 309627, upload-time = "2026-04-02T09:26:45.198Z" }, + { url = "https://files.pythonhosted.org/packages/2e/4e/b7f84e617b4854ade48a1b7915c8ccfadeba444d2a18c291f696e37f0d3b/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ea948db76d31190bf08bd371623927ee1339d5f2a0b4b1b4a4439a65298703c", size = 207008, upload-time = "2026-04-02T09:26:46.824Z" }, + { url = "https://files.pythonhosted.org/packages/c4/bb/ec73c0257c9e11b268f018f068f5d00aa0ef8c8b09f7753ebd5f2880e248/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a277ab8928b9f299723bc1a2dabb1265911b1a76341f90a510368ca44ad9ab66", size = 228303, upload-time = "2026-04-02T09:26:48.397Z" }, + { url = "https://files.pythonhosted.org/packages/85/fb/32d1f5033484494619f701e719429c69b766bfc4dbc61aa9e9c8c166528b/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3bec022aec2c514d9cf199522a802bd007cd588ab17ab2525f20f9c34d067c18", size = 224282, upload-time = "2026-04-02T09:26:49.684Z" }, + { url = "https://files.pythonhosted.org/packages/fa/07/330e3a0dda4c404d6da83b327270906e9654a24f6c546dc886a0eb0ffb23/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e044c39e41b92c845bc815e5ae4230804e8e7bc29e399b0437d64222d92809dd", size = 215595, upload-time = "2026-04-02T09:26:50.915Z" }, + { url = "https://files.pythonhosted.org/packages/e3/7c/fc890655786e423f02556e0216d4b8c6bcb6bdfa890160dc66bf52dee468/charset_normalizer-3.4.7-cp313-cp313-manylinux_2_31_armv7l.whl", hash = "sha256:f495a1652cf3fbab2eb0639776dad966c2fb874d79d87ca07f9d5f059b8bd215", size = 201986, upload-time = "2026-04-02T09:26:52.197Z" }, + { url = "https://files.pythonhosted.org/packages/d8/97/bfb18b3db2aed3b90cf54dc292ad79fdd5ad65c4eae454099475cbeadd0d/charset_normalizer-3.4.7-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e712b419df8ba5e42b226c510472b37bd57b38e897d3eca5e8cfd410a29fa859", size = 211711, upload-time = "2026-04-02T09:26:53.49Z" }, + { url = "https://files.pythonhosted.org/packages/6f/a5/a581c13798546a7fd557c82614a5c65a13df2157e9ad6373166d2a3e645d/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:7804338df6fcc08105c7745f1502ba68d900f45fd770d5bdd5288ddccb8a42d8", size = 210036, upload-time = "2026-04-02T09:26:54.975Z" }, + { url = "https://files.pythonhosted.org/packages/8c/bf/b3ab5bcb478e4193d517644b0fb2bf5497fbceeaa7a1bc0f4d5b50953861/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:481551899c856c704d58119b5025793fa6730adda3571971af568f66d2424bb5", size = 202998, upload-time = "2026-04-02T09:26:56.303Z" }, + { url = "https://files.pythonhosted.org/packages/e7/4e/23efd79b65d314fa320ec6017b4b5834d5c12a58ba4610aa353af2e2f577/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:f59099f9b66f0d7145115e6f80dd8b1d847176df89b234a5a6b3f00437aa0832", size = 230056, upload-time = "2026-04-02T09:26:57.554Z" }, + { url = "https://files.pythonhosted.org/packages/b9/9f/1e1941bc3f0e01df116e68dc37a55c4d249df5e6fa77f008841aef68264f/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:f59ad4c0e8f6bba240a9bb85504faa1ab438237199d4cce5f622761507b8f6a6", size = 211537, upload-time = "2026-04-02T09:26:58.843Z" }, + { url = "https://files.pythonhosted.org/packages/80/0f/088cbb3020d44428964a6c97fe1edfb1b9550396bf6d278330281e8b709c/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:3dedcc22d73ec993f42055eff4fcfed9318d1eeb9a6606c55892a26964964e48", size = 226176, upload-time = "2026-04-02T09:27:00.437Z" }, + { url = "https://files.pythonhosted.org/packages/6a/9f/130394f9bbe06f4f63e22641d32fc9b202b7e251c9aef4db044324dac493/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:64f02c6841d7d83f832cd97ccf8eb8a906d06eb95d5276069175c696b024b60a", size = 217723, upload-time = "2026-04-02T09:27:02.021Z" }, + { url = "https://files.pythonhosted.org/packages/73/55/c469897448a06e49f8fa03f6caae97074fde823f432a98f979cc42b90e69/charset_normalizer-3.4.7-cp313-cp313-win32.whl", hash = "sha256:4042d5c8f957e15221d423ba781e85d553722fc4113f523f2feb7b188cc34c5e", size = 148085, upload-time = "2026-04-02T09:27:03.192Z" }, + { url = "https://files.pythonhosted.org/packages/5d/78/1b74c5bbb3f99b77a1715c91b3e0b5bdb6fe302d95ace4f5b1bec37b0167/charset_normalizer-3.4.7-cp313-cp313-win_amd64.whl", hash = "sha256:3946fa46a0cf3e4c8cb1cc52f56bb536310d34f25f01ca9b6c16afa767dab110", size = 158819, upload-time = "2026-04-02T09:27:04.454Z" }, + { url = "https://files.pythonhosted.org/packages/68/86/46bd42279d323deb8687c4a5a811fd548cb7d1de10cf6535d099877a9a9f/charset_normalizer-3.4.7-cp313-cp313-win_arm64.whl", hash = "sha256:80d04837f55fc81da168b98de4f4b797ef007fc8a79ab71c6ec9bc4dd662b15b", size = 147915, upload-time = "2026-04-02T09:27:05.971Z" }, + { url = "https://files.pythonhosted.org/packages/97/c8/c67cb8c70e19ef1960b97b22ed2a1567711de46c4ddf19799923adc836c2/charset_normalizer-3.4.7-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:c36c333c39be2dbca264d7803333c896ab8fa7d4d6f0ab7edb7dfd7aea6e98c0", size = 309234, upload-time = "2026-04-02T09:27:07.194Z" }, + { url = "https://files.pythonhosted.org/packages/99/85/c091fdee33f20de70d6c8b522743b6f831a2f1cd3ff86de4c6a827c48a76/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1c2aed2e5e41f24ea8ef1590b8e848a79b56f3a5564a65ceec43c9d692dc7d8a", size = 208042, upload-time = "2026-04-02T09:27:08.749Z" }, + { url = "https://files.pythonhosted.org/packages/87/1c/ab2ce611b984d2fd5d86a5a8a19c1ae26acac6bad967da4967562c75114d/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:54523e136b8948060c0fa0bc7b1b50c32c186f2fceee897a495406bb6e311d2b", size = 228706, upload-time = "2026-04-02T09:27:09.951Z" }, + { url = "https://files.pythonhosted.org/packages/a8/29/2b1d2cb00bf085f59d29eb773ce58ec2d325430f8c216804a0a5cd83cbca/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:715479b9a2802ecac752a3b0efa2b0b60285cf962ee38414211abdfccc233b41", size = 224727, upload-time = "2026-04-02T09:27:11.175Z" }, + { url = "https://files.pythonhosted.org/packages/47/5c/032c2d5a07fe4d4855fea851209cca2b6f03ebeb6d4e3afdb3358386a684/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bd6c2a1c7573c64738d716488d2cdd3c00e340e4835707d8fdb8dc1a66ef164e", size = 215882, upload-time = "2026-04-02T09:27:12.446Z" }, + { url = "https://files.pythonhosted.org/packages/2c/c2/356065d5a8b78ed04499cae5f339f091946a6a74f91e03476c33f0ab7100/charset_normalizer-3.4.7-cp314-cp314-manylinux_2_31_armv7l.whl", hash = "sha256:c45e9440fb78f8ddabcf714b68f936737a121355bf59f3907f4e17721b9d1aae", size = 200860, upload-time = "2026-04-02T09:27:13.721Z" }, + { url = "https://files.pythonhosted.org/packages/0c/cd/a32a84217ced5039f53b29f460962abb2d4420def55afabe45b1c3c7483d/charset_normalizer-3.4.7-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3534e7dcbdcf757da6b85a0bbf5b6868786d5982dd959b065e65481644817a18", size = 211564, upload-time = "2026-04-02T09:27:15.272Z" }, + { url = "https://files.pythonhosted.org/packages/44/86/58e6f13ce26cc3b8f4a36b94a0f22ae2f00a72534520f4ae6857c4b81f89/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:e8ac484bf18ce6975760921bb6148041faa8fef0547200386ea0b52b5d27bf7b", size = 211276, upload-time = "2026-04-02T09:27:16.834Z" }, + { url = "https://files.pythonhosted.org/packages/8f/fe/d17c32dc72e17e155e06883efa84514ca375f8a528ba2546bee73fc4df81/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:a5fe03b42827c13cdccd08e6c0247b6a6d4b5e3cdc53fd1749f5896adcdc2356", size = 201238, upload-time = "2026-04-02T09:27:18.229Z" }, + { url = "https://files.pythonhosted.org/packages/6a/29/f33daa50b06525a237451cdb6c69da366c381a3dadcd833fa5676bc468b3/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:2d6eb928e13016cea4f1f21d1e10c1cebd5a421bc57ddf5b1142ae3f86824fab", size = 230189, upload-time = "2026-04-02T09:27:19.445Z" }, + { url = "https://files.pythonhosted.org/packages/b6/6e/52c84015394a6a0bdcd435210a7e944c5f94ea1055f5cc5d56c5fe368e7b/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:e74327fb75de8986940def6e8dee4f127cc9752bee7355bb323cc5b2659b6d46", size = 211352, upload-time = "2026-04-02T09:27:20.79Z" }, + { url = "https://files.pythonhosted.org/packages/8c/d7/4353be581b373033fb9198bf1da3cf8f09c1082561e8e922aa7b39bf9fe8/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:d6038d37043bced98a66e68d3aa2b6a35505dc01328cd65217cefe82f25def44", size = 227024, upload-time = "2026-04-02T09:27:22.063Z" }, + { url = "https://files.pythonhosted.org/packages/30/45/99d18aa925bd1740098ccd3060e238e21115fffbfdcb8f3ece837d0ace6c/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:7579e913a5339fb8fa133f6bbcfd8e6749696206cf05acdbdca71a1b436d8e72", size = 217869, upload-time = "2026-04-02T09:27:23.486Z" }, + { url = "https://files.pythonhosted.org/packages/5c/05/5ee478aa53f4bb7996482153d4bfe1b89e0f087f0ab6b294fcf92d595873/charset_normalizer-3.4.7-cp314-cp314-win32.whl", hash = "sha256:5b77459df20e08151cd6f8b9ef8ef1f961ef73d85c21a555c7eed5b79410ec10", size = 148541, upload-time = "2026-04-02T09:27:25.146Z" }, + { url = "https://files.pythonhosted.org/packages/48/77/72dcb0921b2ce86420b2d79d454c7022bf5be40202a2a07906b9f2a35c97/charset_normalizer-3.4.7-cp314-cp314-win_amd64.whl", hash = "sha256:92a0a01ead5e668468e952e4238cccd7c537364eb7d851ab144ab6627dbbe12f", size = 159634, upload-time = "2026-04-02T09:27:26.642Z" }, + { url = "https://files.pythonhosted.org/packages/c6/a3/c2369911cd72f02386e4e340770f6e158c7980267da16af8f668217abaa0/charset_normalizer-3.4.7-cp314-cp314-win_arm64.whl", hash = "sha256:67f6279d125ca0046a7fd386d01b311c6363844deac3e5b069b514ba3e63c246", size = 148384, upload-time = "2026-04-02T09:27:28.271Z" }, + { url = "https://files.pythonhosted.org/packages/94/09/7e8a7f73d24dba1f0035fbbf014d2c36828fc1bf9c88f84093e57d315935/charset_normalizer-3.4.7-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:effc3f449787117233702311a1b7d8f59cba9ced946ba727bdc329ec69028e24", size = 330133, upload-time = "2026-04-02T09:27:29.474Z" }, + { url = "https://files.pythonhosted.org/packages/8d/da/96975ddb11f8e977f706f45cddd8540fd8242f71ecdb5d18a80723dcf62c/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fbccdc05410c9ee21bbf16a35f4c1d16123dcdeb8a1d38f33654fa21d0234f79", size = 216257, upload-time = "2026-04-02T09:27:30.793Z" }, + { url = "https://files.pythonhosted.org/packages/e5/e8/1d63bf8ef2d388e95c64b2098f45f84758f6d102a087552da1485912637b/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:733784b6d6def852c814bce5f318d25da2ee65dd4839a0718641c696e09a2960", size = 234851, upload-time = "2026-04-02T09:27:32.44Z" }, + { url = "https://files.pythonhosted.org/packages/9b/40/e5ff04233e70da2681fa43969ad6f66ca5611d7e669be0246c4c7aaf6dc8/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a89c23ef8d2c6b27fd200a42aa4ac72786e7c60d40efdc76e6011260b6e949c4", size = 233393, upload-time = "2026-04-02T09:27:34.03Z" }, + { url = "https://files.pythonhosted.org/packages/be/c1/06c6c49d5a5450f76899992f1ee40b41d076aee9279b49cf9974d2f313d5/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6c114670c45346afedc0d947faf3c7f701051d2518b943679c8ff88befe14f8e", size = 223251, upload-time = "2026-04-02T09:27:35.369Z" }, + { url = "https://files.pythonhosted.org/packages/2b/9f/f2ff16fb050946169e3e1f82134d107e5d4ae72647ec8a1b1446c148480f/charset_normalizer-3.4.7-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:a180c5e59792af262bf263b21a3c49353f25945d8d9f70628e73de370d55e1e1", size = 206609, upload-time = "2026-04-02T09:27:36.661Z" }, + { url = "https://files.pythonhosted.org/packages/69/d5/a527c0cd8d64d2eab7459784fb4169a0ac76e5a6fc5237337982fd61347e/charset_normalizer-3.4.7-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3c9a494bc5ec77d43cea229c4f6db1e4d8fe7e1bbffa8b6f0f0032430ff8ab44", size = 220014, upload-time = "2026-04-02T09:27:38.019Z" }, + { url = "https://files.pythonhosted.org/packages/7e/80/8a7b8104a3e203074dc9aa2c613d4b726c0e136bad1cc734594b02867972/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8d828b6667a32a728a1ad1d93957cdf37489c57b97ae6c4de2860fa749b8fc1e", size = 218979, upload-time = "2026-04-02T09:27:39.37Z" }, + { url = "https://files.pythonhosted.org/packages/02/9a/b759b503d507f375b2b5c153e4d2ee0a75aa215b7f2489cf314f4541f2c0/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:cf1493cd8607bec4d8a7b9b004e699fcf8f9103a9284cc94962cb73d20f9d4a3", size = 209238, upload-time = "2026-04-02T09:27:40.722Z" }, + { url = "https://files.pythonhosted.org/packages/c2/4e/0f3f5d47b86bdb79256e7290b26ac847a2832d9a4033f7eb2cd4bcf4bb5b/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:0c96c3b819b5c3e9e165495db84d41914d6894d55181d2d108cc1a69bfc9cce0", size = 236110, upload-time = "2026-04-02T09:27:42.33Z" }, + { url = "https://files.pythonhosted.org/packages/96/23/bce28734eb3ed2c91dcf93abeb8a5cf393a7b2749725030bb630e554fdd8/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:752a45dc4a6934060b3b0dab47e04edc3326575f82be64bc4fc293914566503e", size = 219824, upload-time = "2026-04-02T09:27:43.924Z" }, + { url = "https://files.pythonhosted.org/packages/2c/6f/6e897c6984cc4d41af319b077f2f600fc8214eb2fe2d6bcb79141b882400/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:8778f0c7a52e56f75d12dae53ae320fae900a8b9b4164b981b9c5ce059cd1fcb", size = 233103, upload-time = "2026-04-02T09:27:45.348Z" }, + { url = "https://files.pythonhosted.org/packages/76/22/ef7bd0fe480a0ae9b656189ec00744b60933f68b4f42a7bb06589f6f576a/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ce3412fbe1e31eb81ea42f4169ed94861c56e643189e1e75f0041f3fe7020abe", size = 225194, upload-time = "2026-04-02T09:27:46.706Z" }, + { url = "https://files.pythonhosted.org/packages/c5/a7/0e0ab3e0b5bc1219bd80a6a0d4d72ca74d9250cb2382b7c699c147e06017/charset_normalizer-3.4.7-cp314-cp314t-win32.whl", hash = "sha256:c03a41a8784091e67a39648f70c5f97b5b6a37f216896d44d2cdcb82615339a0", size = 159827, upload-time = "2026-04-02T09:27:48.053Z" }, + { url = "https://files.pythonhosted.org/packages/7a/1d/29d32e0fb40864b1f878c7f5a0b343ae676c6e2b271a2d55cc3a152391da/charset_normalizer-3.4.7-cp314-cp314t-win_amd64.whl", hash = "sha256:03853ed82eeebbce3c2abfdbc98c96dc205f32a79627688ac9a27370ea61a49c", size = 174168, upload-time = "2026-04-02T09:27:49.795Z" }, + { url = "https://files.pythonhosted.org/packages/de/32/d92444ad05c7a6e41fb2036749777c163baf7a0301a040cb672d6b2b1ae9/charset_normalizer-3.4.7-cp314-cp314t-win_arm64.whl", hash = "sha256:c35abb8bfff0185efac5878da64c45dafd2b37fb0383add1be155a763c1f083d", size = 153018, upload-time = "2026-04-02T09:27:51.116Z" }, + { url = "https://files.pythonhosted.org/packages/db/8f/61959034484a4a7c527811f4721e75d02d653a35afb0b6054474d8185d4c/charset_normalizer-3.4.7-py3-none-any.whl", hash = "sha256:3dce51d0f5e7951f8bb4900c257dad282f49190fdbebecd4ba99bcc41fef404d", size = 61958, upload-time = "2026-04-02T09:28:37.794Z" }, +] + [[package]] name = "colorama" version = "0.4.6" @@ -821,6 +947,21 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" }, ] +[[package]] +name = "requests" +version = "2.34.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "certifi" }, + { name = "charset-normalizer" }, + { name = "idna" }, + { name = "urllib3" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/ac/c3/e2a2b89f2d3e2179abd6d00ebd70bff6273f37fb3e0cc209f48b39d00cbf/requests-2.34.2.tar.gz", hash = "sha256:f288924cae4e29463698d6d60bc6a4da69c89185ad1e0bcc4104f584e960b9ed", size = 142856, upload-time = "2026-05-14T19:25:27.735Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a0/f4/c67b0b3f1b9245e8d266f0f112c500d50e5b4e83cb6f3b71b6528104182a/requests-2.34.2-py3-none-any.whl", hash = "sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0", size = 73075, upload-time = "2026-05-14T19:25:26.443Z" }, +] + [[package]] name = "rich" version = "14.2.0" @@ -998,24 +1139,26 @@ wheels = [ [[package]] name = "uipath-core" -version = "0.5.26" +version = "0.5.28" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "opentelemetry-instrumentation" }, { name = "opentelemetry-sdk" }, { name = "pydantic" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/ae/9d/f2fd705cbe404e53150ebee4a7208df158ea0e307ade455dc2a3ee16fd12/uipath_core-0.5.26.tar.gz", hash = "sha256:c34f1d7bc823e4a45b8e21ae590d74b6ae9e2caab839c855e376c5f38ffa3e29", size = 130421, upload-time = "2026-06-29T15:43:31.882Z" } +sdist = { url = "https://files.pythonhosted.org/packages/4c/f9/8d2f1d98cbebbcf059cf4561f38f34ad4cd58423e4f15cad22bd297a2563/uipath_core-0.5.28.tar.gz", hash = "sha256:942987f6b612c64f93d612ad7b242276ed75f129fdd8f25bc71c24ec8887e388", size = 130578, upload-time = "2026-06-30T14:04:48.841Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/b6/71/b0947b61fe5b45a8642774a02bffa23371c38556fe877b37c8313bbea5f7/uipath_core-0.5.26-py3-none-any.whl", hash = "sha256:ad81607910ccf567721e31c2de557e100a46228f7e1277cfe37d71f6d472b06a", size = 54787, upload-time = "2026-06-29T15:43:30.642Z" }, + { url = "https://files.pythonhosted.org/packages/e8/1e/385bb166232a57ebe938cc57ad2717f350bc922bb5d2ce31af84306b7569/uipath_core-0.5.28-py3-none-any.whl", hash = "sha256:b952a46a21710073cbc16d6d5684e9aa645c107f57a636b778cfb94aa81a1e48", size = 54980, upload-time = "2026-06-30T14:04:47.374Z" }, ] [[package]] name = "uipath-runtime" -version = "0.11.5" +version = "0.11.6" source = { editable = "." } dependencies = [ + { name = "chardet" }, { name = "uipath-core" }, + { name = "vadersentiment" }, ] [package.dev-dependencies] @@ -1034,7 +1177,11 @@ dev = [ ] [package.metadata] -requires-dist = [{ name = "uipath-core", specifier = ">=0.5.26,<0.6.0" }] +requires-dist = [ + { name = "chardet", specifier = ">=5.2.0,<8.0" }, + { name = "uipath-core", specifier = ">=0.5.28,<0.6.0" }, + { name = "vadersentiment", specifier = ">=3.3.2,<4.0" }, +] [package.metadata.requires-dev] dev = [ @@ -1051,6 +1198,27 @@ dev = [ { name = "rust-just", specifier = ">=1.39.0" }, ] +[[package]] +name = "urllib3" +version = "2.7.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" }, +] + +[[package]] +name = "vadersentiment" +version = "3.3.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "requests" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/77/8c/4a48c10a50f750ae565e341e697d74a38075a3e43ff0df6f1ab72e186902/vaderSentiment-3.3.2.tar.gz", hash = "sha256:5d7c06e027fc8b99238edb0d53d970cf97066ef97654009890b83703849632f9", size = 2466783, upload-time = "2020-05-22T15:06:32.81Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/76/fc/310e16254683c1ed35eeb97386986d6c00bc29df17ce280aed64d55537e9/vaderSentiment-3.3.2-py2.py3-none-any.whl", hash = "sha256:3bf1d243b98b1afad575b9f22bc2cb1e212b94ff89ca74f8a23a588d024ea311", size = 125950, upload-time = "2020-05-22T15:07:00.052Z" }, +] + [[package]] name = "virtualenv" version = "20.35.4"