feat(governance): enforcement-mode config, policy models, deps

pyproject.toml

@@ -5,7 +5,13 @@ description = "Runtime abstractions and interfaces for building agents and autom
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
 dependencies = [
-  "uipath-core>=0.5.17, <0.6.0"
+  "uipath-core>=0.5.18, <0.6.0",
+  # Governance native-evaluator deps. Live here because the native
+  # evaluator implementation lives in uipath.runtime.governance.native;
+  # uipath-core only carries the small governance contracts.
+  "pyyaml>=6.0",
+  "vaderSentiment>=3.3.2",   # sentiment_concern (A.3.3)
+  "chardet>=5.2.0",          # encoding_concern (A.7.4)
 ]
 classifiers = [
   "Intended Audience :: Developers",
@@ -40,6 +46,7 @@ dev = [
   "pytest-cov>=4.1.0",
   "pytest-mock>=3.11.1",
   "pre-commit>=4.1.0",
+  "types-PyYAML>=6.0",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -83,6 +90,25 @@ no_implicit_reexport = true
 
 disallow_untyped_defs = false
 
+# Third-party governance-evaluator libs have no type stubs / py.typed marker
+[[tool.mypy.overrides]]
+module = [
+  "yaml",
+  "vaderSentiment.*",
+  "chardet",
+  "price_parser",
+  # uipath.platform.common is imported lazily from traces.py / audit
+  # sinks to read UiPathConfig context attributes. It's first-party but
+  # not a uipath-runtime dep, so its stubs aren't installable here.
+  "uipath.platform.*",
+  # Optional framework adapters; the absence of the framework simply
+  # means the adapter no-ops at import time.
+  "agents",
+  "langchain_core.*",
+  "langgraph.*",
+]
+ignore_missing_imports = true
+
 [tool.pydantic-mypy]
 init_forbid_extra = true
 init_typed = true

src/uipath/runtime/governance/config.py

@@ -0,0 +1,85 @@
+"""Runtime-level governance enforcement-mode state.
+
+The feature-flag gate (``is_governance_enabled``) lives in
+:mod:`uipath.core.governance.config` because it is process-level and
+must be resolvable by callers that do not depend on
+``uipath-runtime``. The enforcement mode is *per-policy* — set by the
+backend on each policy fetch via the ``/runtime/policy`` endpoint —
+and therefore lives here in the runtime package alongside the policy
+loader that applies it.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+ENV_ENFORCEMENT_MODE = "UIPATH_GOVERNANCE_MODE"
+
+
+class EnforcementMode(str, Enum):
+    """Governance enforcement modes."""
+
+    AUDIT = "audit"  # Evaluate and log; never block.
+    ENFORCE = "enforce"  # Block on DENY rules.
+    DISABLED = "disabled"  # Skip evaluation entirely.
+
+
+_enforcement_mode: EnforcementMode | None = None
+
+
+def get_enforcement_mode() -> EnforcementMode:
+    """Return the current enforcement mode.
+
+    The mode is cached after first read. Resolution order:
+
+    1. A value previously set via :func:`set_enforcement_mode` (the
+       policy loader calls this with the backend-supplied mode on every
+       successful policy fetch — that's the canonical source).
+    2. ``UIPATH_GOVERNANCE_MODE`` env var (developer override).
+    3. Default :attr:`EnforcementMode.AUDIT` — evaluate and log without
+       blocking. The wrapper attaches at runtime construction so the
+       background policy fetch can run; if the backend returns
+       ``disabled``, ``set_enforcement_mode`` flips the cache and
+       subsequent ``evaluate()`` calls short-circuit (the evaluator
+       skips evaluation in disabled mode). Defaulting to AUDIT avoids
+       the chicken-and-egg where a DISABLED
+       default would short-circuit before the policy fetch could ever
+       opt the tenant in.
+    """
+    global _enforcement_mode
+    if _enforcement_mode is not None:
+        return _enforcement_mode
+
+    mode_str = os.getenv(ENV_ENFORCEMENT_MODE, "audit").lower()
+    try:
+        _enforcement_mode = EnforcementMode(mode_str)
+    except ValueError:
+        logger.warning(
+            "Invalid %s=%r; defaulting to %s",
+            ENV_ENFORCEMENT_MODE,
+            mode_str,
+            EnforcementMode.AUDIT.value,
+        )
+        _enforcement_mode = EnforcementMode.AUDIT
+
+    return _enforcement_mode
+
+
+def set_enforcement_mode(mode: EnforcementMode) -> None:
+    """Set the enforcement mode programmatically.
+
+    The policy loader calls this with the backend-supplied mode on each
+    fetch so the evaluator picks up the platform-controlled value.
+    """
+    global _enforcement_mode
+    _enforcement_mode = mode
+
+
+def reset_enforcement_mode() -> None:
+    """Clear cached enforcement mode (intended for tests)."""
+    global _enforcement_mode
+    _enforcement_mode = None

src/uipath/runtime/governance/native/models.py

@@ -0,0 +1,153 @@
+"""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"
+
+
+@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: str = "all"  # "all" (AND) or "any" (OR)
+
+
+@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."""
+
+    hook: LifecycleHook
+    agent_name: str
+    runtime_id: str
+    trace_id: str
+
+    # Content fields (populated based on hook)
+    agent_input: str = ""
+    agent_output: str = ""
+    model_input: str = ""
+    model_output: str = ""
+    model_name: str = (
+        ""  # LLM model name (e.g., "gpt-4", "claude-3-opus") - available at agent start
+    )
+    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())

tests/conftest.py

@@ -17,3 +17,33 @@ def temp_dir() -> Generator[str, None, None]:
     """Provide a temporary directory for test files."""
     with tempfile.TemporaryDirectory() as tmp_dir:
         yield tmp_dir
+
+
+@pytest.fixture(autouse=True)
+def _reset_governance_process_state() -> Generator[None, None, None]:
+    """Clear process-level governance state around every test.
+
+    The native governance layer keeps two pieces of state at module scope:
+    the conversational/autonomous selector consumed by the policy fetch,
+    and the memoized job-context. Both are stable per process in
+    production but leak across tests when not reset, masking ordering
+    bugs and producing flakes.
+
+    ``backend_client`` is imported lazily and guarded: this shared
+    conftest ships alongside the foundation slice, where that module may
+    not exist yet, and the reset is simply a no-op until it does.
+    """
+    try:
+        from uipath.runtime.governance.native.backend_client import (
+            resolve_job_context,
+            set_agent_conversational,
+        )
+    except ImportError:
+        yield
+        return
+
+    set_agent_conversational(None)
+    resolve_job_context.cache_clear()
+    yield
+    set_agent_conversational(None)
+    resolve_job_context.cache_clear()