feat(business-rules): add debug runs to run()

Adds DebugRunContext, the second run context of run()/run_async(), for
undeployed DMNs read from a Studio project. As in the .NET client's
RunAsync, exactly one of deployed/debug must be set and it selects the
endpoint:

- DeployedRunContext -> /v1/business-rules/evaluate
- DebugRunContext(project_id | rule_name, file_name, job_key,
  organization_unit_id) -> /v1/business-rules/debug/evaluate

A debug run named by rule_name also needs job_key (defaults to
UIPATH_JOB_KEY) and organization_unit_id. Following business-rules#104,
explain=True needs a folder key in both modes, and debug runs send the
key whenever one is known so their spans can be stored.

BusinessRuleRunResult gains project_id and file_name for debug runs, and
RunMode gains DEBUG. Bumps uipath-platform to 0.2.34.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: ashishupadhyay88

packages/uipath-platform/CLAUDE.md

@@ -96,7 +96,7 @@ Services provide both sync and async variants (e.g., `.invoke()` and `.invoke_as
 | `action_center/` | Task management for human-in-the-loop workflows |
 | `agenthub/` | System agents and LLM model discovery |
 | `automation_tracker/` | Business Transaction Service (BTS) for Process Mining |
-| `business_rules/` | DMN business rule runs for rules deployed to Orchestrator, behind one `run()` |
+| `business_rules/` | DMN business rule runs: deployed rules or undeployed Studio-project DMNs, behind one `run()` |
 | `chat/` | LLM gateway, conversations, throttling |
 | `connections/` | External connection management |
 | `context_grounding/` | RAG services (DeepRAG, batch RAG, ephemeral indexes) |

packages/uipath-platform/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-platform"
-version = "0.2.33"
+version = "0.2.34"
 description = "HTTP client library for programmatic access to UiPath Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath-platform/src/uipath/platform/business_rules/__init__.py

@@ -1,8 +1,8 @@
 """Business Rules service package.
 
-Provides the ``BusinessRulesService`` client for running DMN decision models
-deployed to Orchestrator as UiPath Business Rules, and the Pydantic models for
-its run context and results.
+Provides the ``BusinessRulesService`` client for running DMN decision models,
+either deployed to Orchestrator as UiPath Business Rules or read from a Studio
+project, and the Pydantic models for its run contexts and results.
 """
 
 from ._business_rules_service import BusinessRulesService
@@ -11,6 +11,7 @@
     BusinessRuleError,
     BusinessRuleRunResult,
     BusinessRuleStatus,
+    DebugRunContext,
     DeployedRunContext,
     RunMode,
 )
@@ -21,6 +22,7 @@
     "BusinessRuleRunResult",
     "BusinessRuleStatus",
     "BusinessRulesService",
+    "DebugRunContext",
     "DeployedRunContext",
     "RunMode",
 ]

packages/uipath-platform/src/uipath/platform/business_rules/_business_rules_service.py

@@ -1,14 +1,15 @@
 """Business Rules service for UiPath Platform.
 
-Runs DMN decision models deployed to Orchestrator as business rules.
+Runs DMN decision models: a business rule deployed to Orchestrator, or an
+undeployed DMN read straight from a Studio project.
 """
 
 from typing import Any, Dict, List, Optional, Tuple
 
 from uipath.core.tracing import traced
 
 from ..common._base_service import BaseService
-from ..common._config import UiPathApiConfig
+from ..common._config import UiPathApiConfig, UiPathConfig
 from ..common._execution_context import UiPathExecutionContext
 from ..common._folder_context import FolderContext
 from ..common._models import Endpoint, RequestSpec
@@ -19,13 +20,18 @@
     BusinessRuleError,
     BusinessRuleRunResult,
     BusinessRuleStatus,
+    DebugRunContext,
     DeployedRunContext,
     RunMode,
     _WireResponse,
     _WireResult,
 )
 
 _EVALUATE_ENDPOINT = Endpoint("businessrules_/v1/business-rules/evaluate")
+_DEBUG_EVALUATE_ENDPOINT = Endpoint("businessrules_/v1/business-rules/debug/evaluate")
+
+_HEADER_ORGANIZATION_UNIT_ID = "x-uipath-organizationunitid"
+_HEADER_JOB_KEY = "x-uipath-jobkey"
 
 # The service's contract is a batch; this SDK submits exactly one input under this id.
 _SINGLE_INPUT_ID = "input-1"
@@ -37,8 +43,9 @@ class BusinessRulesService(FolderContext, BaseService):
     """Service for running UiPath Business Rules (DMN decision models).
 
     Each call runs one input and returns the decisions it produced. Which model
-    runs is set by the run context; ``deployed`` names a rule deployed to
-    Orchestrator. The caller never picks a service endpoint.
+    runs is set by the run context: ``deployed`` for a rule deployed to
+    Orchestrator, ``debug`` for an undeployed DMN in a Studio project. The caller
+    never picks a service endpoint.
     """
 
     def __init__(
@@ -55,25 +62,32 @@ def run(
         self,
         input: Dict[str, Any],
         *,
-        deployed: DeployedRunContext,
+        deployed: Optional[DeployedRunContext] = None,
+        debug: Optional[DebugRunContext] = None,
         decision_names: Optional[List[str]] = None,
         explain: bool = False,
         folder_key: Optional[str] = None,
         folder_path: Optional[str] = None,
     ) -> BusinessRuleRunResult:
         """Run a business rule against one input.
 
+        Exactly one of ``deployed`` and ``debug`` must be set, and it decides which
+        model runs.
+
         Args:
             input: The input to run, keyed by DMN input name. Declared inputs absent
                 from it bind to null.
-            deployed: The business rule deployed to Orchestrator to run.
+            deployed: A business rule deployed to Orchestrator.
+            debug: An undeployed DMN in a Studio project.
             decision_names: The decisions to evaluate; defaults to the whole model.
             explain: Whether to record condition-level explanations in the trace.
+                Requires a folder.
             folder_key: The key of the folder to run in.
             folder_path: The path of the folder to run in. Resolved to a key, since
                 the service accepts folder keys only.
 
-        A folder is required. When neither ``folder_key`` nor ``folder_path`` is given, it falls back to
+        A folder is required for a deployed rule and whenever ``explain`` is set.
+        When neither ``folder_key`` nor ``folder_path`` is given, it falls back to
         ``UIPATH_FOLDER_KEY`` and then ``UIPATH_FOLDER_PATH``.
 
         Returns:
@@ -87,24 +101,36 @@ def run(
         Examples:
             ```python
             from uipath.platform import UiPath
-            from uipath.platform.business_rules import DeployedRunContext
+            from uipath.platform.business_rules import (
+                DebugRunContext,
+                DeployedRunContext,
+            )
 
             client = UiPath()
 
+            # A rule deployed to Orchestrator
             result = client.business_rules.run(
                 {"creditScore": 740, "age": 34},
                 deployed=DeployedRunContext(rule_name="Loan Pricing"),
                 folder_path="Finance",
             )
             for decision in result.decisions:
                 print(decision.decision_name, decision.outputs)
+
+            # An undeployed DMN in a Studio project
+            result = client.business_rules.run(
+                {"creditScore": 740},
+                debug=DebugRunContext(project_id="0a1b2c3d-...", file_name="Loan.dmn"),
+            )
             ```
         """
-        _validate_run(input, deployed)
+        _validate_run(input, deployed, debug)
         key, path = self._folder_source(folder_key, folder_path)
         if path:
             key = self._folders_service.retrieve_folder_key(path)
-        mode, spec = self._run_spec(input, deployed, decision_names, explain, key)
+        mode, spec = self._run_spec(
+            input, deployed, debug, decision_names, explain, key
+        )
         response = self.request(
             spec.method,
             url=spec.endpoint,
@@ -119,20 +145,26 @@ async def run_async(
         self,
         input: Dict[str, Any],
         *,
-        deployed: DeployedRunContext,
+        deployed: Optional[DeployedRunContext] = None,
+        debug: Optional[DebugRunContext] = None,
         decision_names: Optional[List[str]] = None,
         explain: bool = False,
         folder_key: Optional[str] = None,
         folder_path: Optional[str] = None,
     ) -> BusinessRuleRunResult:
         """Asynchronously run a business rule against one input.
 
+        Exactly one of ``deployed`` and ``debug`` must be set, and it decides which
+        model runs.
+
         Args:
             input: The input to run, keyed by DMN input name. Declared inputs absent
                 from it bind to null.
-            deployed: The business rule deployed to Orchestrator to run.
+            deployed: A business rule deployed to Orchestrator.
+            debug: An undeployed DMN in a Studio project.
             decision_names: The decisions to evaluate; defaults to the whole model.
             explain: Whether to record condition-level explanations in the trace.
+                Requires a folder.
             folder_key: The key of the folder to run in.
             folder_path: The path of the folder to run in. Resolved to a key, since
                 the service accepts folder keys only.
@@ -145,11 +177,13 @@ async def run_async(
             ValueError: If the request is invalid or a required folder is missing.
             EnrichedException: If the service rejects the request.
         """
-        _validate_run(input, deployed)
+        _validate_run(input, deployed, debug)
         key, path = self._folder_source(folder_key, folder_path)
         if path:
             key = await self._folders_service.retrieve_folder_key_async(path)
-        mode, spec = self._run_spec(input, deployed, decision_names, explain, key)
+        mode, spec = self._run_spec(
+            input, deployed, debug, decision_names, explain, key
+        )
         response = await self.request_async(
             spec.method,
             url=spec.endpoint,
@@ -176,11 +210,19 @@ def _folder_source(
     def _run_spec(
         self,
         input: Dict[str, Any],
-        deployed: DeployedRunContext,
+        deployed: Optional[DeployedRunContext],
+        debug: Optional[DebugRunContext],
         decision_names: Optional[List[str]],
         explain: bool,
         folder_key: Optional[str],
     ) -> Tuple[RunMode, RequestSpec]:
+        if debug is not None:
+            if explain and not folder_key:
+                raise _missing_folder("explain=True")
+            return RunMode.DEBUG, self._debug_spec(
+                input, debug, decision_names, explain, folder_key
+            )
+        assert deployed is not None
         if not folder_key:
             raise _missing_folder("a deployed business rule")
         return RunMode.DEPLOYED, self._evaluate_spec(
@@ -211,6 +253,56 @@ def _evaluate_spec(
             headers={HEADER_FOLDER_KEY: folder_key},
         )
 
+    def _debug_spec(
+        self,
+        input: Dict[str, Any],
+        debug: DebugRunContext,
+        decision_names: Optional[List[str]],
+        explain: bool,
+        folder_key: Optional[str],
+    ) -> RequestSpec:
+        job_key = debug.job_key or UiPathConfig.job_key
+        named = _present(debug.rule_name)
+        if not _present(debug.project_id) and not _present(job_key):
+            raise ValueError(
+                "debug.job_key must be specified when the run is named by rule_name: "
+                "the service resolves the project from the job's lineage. "
+                "Set it or UIPATH_JOB_KEY."
+            )
+        if named and not _present(debug.organization_unit_id):
+            raise ValueError(
+                "debug.organization_unit_id must be specified when the run is named "
+                "by rule_name: it is the folder the job's lineage is read under"
+            )
+
+        body: Dict[str, Any] = {
+            "explain": explain,
+            "inputs": [{"id": _SINGLE_INPUT_ID, "data": input}],
+        }
+        if debug.project_id:
+            body["projectId"] = debug.project_id
+        if named:
+            body["businessRuleName"] = debug.rule_name
+        if debug.file_name:
+            body["fileName"] = debug.file_name
+        if decision_names:
+            body["decisionNames"] = decision_names
+
+        # Folder key: the traces service files the run's spans under it.
+        headers: Dict[str, str] = {}
+        if folder_key:
+            headers[HEADER_FOLDER_KEY] = folder_key
+        if debug.organization_unit_id:
+            headers[_HEADER_ORGANIZATION_UNIT_ID] = debug.organization_unit_id
+        if job_key:
+            headers[_HEADER_JOB_KEY] = job_key
+        return RequestSpec(
+            method="POST",
+            endpoint=_DEBUG_EVALUATE_ENDPOINT,
+            json=body,
+            headers=headers,
+        )
+
 
 def _present(value: Optional[str]) -> bool:
     # Blank counts as absent, matching how the service reads these fields.
@@ -224,10 +316,22 @@ def _missing_folder(needed_for: str) -> ValueError:
     )
 
 
-def _validate_run(input: Dict[str, Any], deployed: DeployedRunContext) -> None:
-    if deployed is None:
-        raise ValueError("deployed must be set")
-    _validate_rule_name(deployed.rule_name, "deployed.rule_name")
+def _validate_run(
+    input: Dict[str, Any],
+    deployed: Optional[DeployedRunContext],
+    debug: Optional[DebugRunContext],
+) -> None:
+    if deployed is None and debug is None:
+        raise ValueError("Exactly one of deployed or debug must be set; neither was")
+    if deployed is not None and debug is not None:
+        raise ValueError("Exactly one of deployed or debug must be set; both were")
+    if deployed is not None:
+        _validate_rule_name(deployed.rule_name, "deployed.rule_name")
+    if debug is not None:
+        if not _present(debug.project_id) and not _present(debug.rule_name):
+            raise ValueError("debug.project_id or debug.rule_name must be specified")
+        if _present(debug.rule_name):
+            _validate_rule_name(debug.rule_name, "debug.rule_name")  # type: ignore[arg-type]
     _validate_input(input)
 
 
@@ -285,12 +389,15 @@ def _single_result(
 
 def _to_run_result(mode: RunMode, response: _WireResponse) -> BusinessRuleRunResult:
     decisions, errors, status = _single_result(response)
+    deployed = mode == RunMode.DEPLOYED
     return BusinessRuleRunResult(
         mode=mode,
         status=status,
         decisions=decisions,
         errors=errors,
         top_level_error=response.error.code if response.error else None,
-        business_rule_name=response.business_rule_name,
-        version=response.version,
+        business_rule_name=response.business_rule_name if deployed else None,
+        version=response.version if deployed else None,
+        project_id=None if deployed else response.project_id,
+        file_name=None if deployed else response.file_name,
     )