feat(business-rules): add BusinessRulesService with run()

[ashishupadhyay88]

Summary

Jira: MST-15365

Adds sdk.business_rules, a client for the Business Rules service. It runs a business rule deployed to Orchestrator against one input.

This is PR 1 of 2. #1917 adds debug runs of undeployed rules, with the SDK picking the endpoint.

from uipath.platform import UiPath
from uipath.platform.business_rules import BusinessRuleCaller, TraceContext

result = UiPath().business_rules.run(
    "Loan Pricing",                  # rule name first, like processes.invoke(name, input_arguments)
    {"creditScore": 740},
    version="1.0.3",                 # optional; active version if omitted
    folder_path="Finance",           # or folder_key=..., or UIPATH_FOLDER_KEY / _PATH
    decision_names=["RiskGrade"],    # optional; every decision if omitted
    caller=BusinessRuleCaller(run_key="…"),                        # optional; defaults from the job
    trace_context=TraceContext(trace_id="…", parent_span_id="…"),  # optional; automatic if omitted
)
result.status                 # Success | PartialSuccess | AllFailed
result.decisions[0].outputs   # {"Grade": "B", "Rate": 3.5}

Errors from the service come back as EnrichedException, with the service's own code:

from uipath.platform.errors import EnrichedException

try:
    UiPath().business_rules.run("Missing Rule", {"creditScore": 740}, folder_path="Finance")
except EnrichedException as e:
    e.status_code             # 404
    e.error_info.error_code   # "RULE_NOT_FOUND"
    e.error_info.message      # "no such rule"

run_async() has the same signature, for callers already running on an event loop, such as LangGraph or FastAPI.

Flow

flowchart LR
    A["run(name, input)"] --> F{"Folder key?<br/>folder_key, folder_path<br/>or the environment"}
    F -- no --> X["ValueError<br/>nothing sent"]
    F -- yes --> E["POST /evaluate<br/>x-uipath-folderkey"]
    E -- "200 / 207" --> R["BusinessRuleRunResult"]
    E -- "4xx / 5xx" --> ER["EnrichedException"]

Loading

Before sending, the SDK applies any businessRule binding and checks the rule name and input. BaseService adds the token, the org/tenant URL, the trace header and retries. The Design section below has the details.

Design

The contract follows the service after UiPath/business-rules#124, #126 and #130, and the .NET client 2.0.0 (UiPath/business-rules#131). The call shape follows this SDK's resource conventions.

• Name first, like every resource call. run(name, input, *, version=None, …) matches processes.invoke(name, input_arguments). The endpoint and the request builder (_evaluate_spec) are private.
• One input on the wire. The request sends input and the response is read from result. The deprecated inputs batch is never sent, and a successful response without result raises ValueError.
• The folder is named by key only.
  • folder_key is sent as is; folder_path is looked up through FolderService and sent as its key. Only x-uipath-folderkey goes on the wire, never the numeric folder id.
  • Required: one of the two, or the env (UIPATH_FOLDER_KEY, then UIPATH_FOLDER_PATH). A blank value counts as not given. Without a folder, run() raises before anything is sent.
  • Exclusive: folder_key and folder_path together are a ValueError, as in header_folder() across the SDK.
• No explain. The service decides what it traces.
• Caller audit. caller is sent for the execution audit. Each BusinessRuleCaller field defaults to the job's value: resource_key from UIPATH_PROCESS_UUID, run_key from UIPATH_JOB_KEY, folder_key from UIPATH_FOLDER_KEY. That last one is the caller's folder, not the rule's. Blank fields are left out, and so is caller when every field is blank.
• Resource overrides. A solution's businessRule bindings can remap the rule name and folder per environment, through a private helper decorated with @resource_override(resource_type="businessRule"). When a binding remaps the rule, its folder replaces the caller's, including a folder_key.
• Checks before sending:
  • rule names checked with the service's own allowlist (BusinessRuleNames.requireSafe): letters and numbers in any script, space and '._()[]{}+,&@!~=:;-, at most 256 characters, never ... The SDK accepts exactly the names the service accepts; the error names the characters it refused
  • input a mapping with at most 256 keys
• Status. An input-level error means AllFailed. Otherwise the status comes from how many decisions failed. A 207 partial result is returned normally, with top_level_error when the service reports one.
• Errors. Three kinds, each reaching the caller:
  • a call the SDK can refuse itself (no folder, unsafe name, input not a mapping) raises ValueError, and nothing is sent;
  • a 4xx or 5xx from the service, after the platform's retries, raises EnrichedException with status_code, the response body, and error_info.error_code / error_info.message read from the service's {"error": {"code", "message"}} envelope;
  • a decision or input that failed inside a 200 / 207 comes back in the result, as decision.error or errors, with the status set accordingly.
• Tracing: the service records the run; the SDK opens no span.
  • run() / run_async() are deliberately not @traced. The service publishes the run's decision and rule spans to Trace View, so a client span would only wrap them and record the rule's input and outputs on the client. The .NET client opens no spans and never logs input data either.
  • x-uipath-traceparent-id names the caller's current span by default (trace id from UIPATH_TRACE_ID when set), so the service's spans nest directly under the caller's. Outside any trace no header is sent, and the service starts a trace of its own.
  • Callers can override it with trace_context=TraceContext(trace_id, parent_span_id), the same shape as .NET's, with the ids checked when it's created.
  • The explicit value travels in the headers handed to BaseService, as a small dict that ignores BaseService's later write of the ambient header. There are no request hooks and no change to BaseService, and it survives retries.
• Inherited from BaseService:
  • bearer auth, including S2S
  • URL scoping
  • retries on timeouts and 408, 429, 502, 503, 504, 524 (the shared platform policy; nothing business-rules specific)
  • UIPATH_SERVICE_URL_BUSINESSRULES local override

For reviewers

• Account and tenant headers. The SDK doesn't send x-uipath-internal-accountid / -tenantid; the gateway adds them, confirmed on alpha.
• Shared code. Two small additions:
  • "businessRule" in GenericResourceOverwrite (common/_bindings.py), as feat: add memorySpace to resource overwrite types #1586 / fix: accept remoteA2aAgent in GenericResourceOverwrite #1581 did for their kinds.
  • a businessrules_ error extractor (errors/_extractors/_businessrules.py, registered in _router.py). The service nests its error as {"error": {"code", "message"}}; the generic extractor reads only the message from there, so EnrichedException.error_info.error_code was None. It now carries the service's code (RULE_NOT_FOUND, INVALID_REQUEST, …), like .NET's BusinessRulesException.Code. Other shapes, such as gateway errors, still go through the generic extractor.
• Version bump. uipath-platform goes to 0.2.35 (main released 0.2.34). uv lock --check passes for both packages.
• Latest commits, since the first review:
  • Contract update (ca881df3): the service's single-input contract. input / result, no explain, folder key only (organization_unit_id removed), caller added, RunMode / result.mode removed.
  • Service error codes (a8bb4596): the businessrules_ error extractor above.
  • Control characters (e29c9161): a rule name now refuses only Unicode Cc, the same set as .NET's char.IsControl. Before, str.isprintable() also refused non-breaking and zero-width spaces, so a name pasted from a document could pass .NET and fail here.
  • SDK conventions (ce7fe087): the request builder is a method (self._evaluate_spec), folder resolution is _resolve_folder_key / _resolve_folder_key_async as in context grounding, memory and AgentHub, helpers have clearer names, and a folder_path matching no folder now says so. No behaviour change.
  • Docs page (ce7fe087): docs/core/business_rules.md and a Business Rules entry under Services in mkdocs.yml, so sdk.business_rules appears in the published SDK docs. Checked with mkdocs build.
  • No client span (2c8bcb03): @traced removed from run() / run_async(), as described under Tracing.
  • Shared sync/async steps (fa84d396): run() and run_async() no longer repeat each other. _prepare_run() applies the binding, validates and picks the folder; only the folder lookup and the request() call differ. request() stays in the public methods, because BaseService names x-uipath-user-agent after the method that calls it; a test now pins run_async's user agent too.
  • Readable names (39b9ea67): locals and internal parameters renamed (run_target, request_spec, business_rule_name, request_body, wire_response, …). The public run(name, input) is unchanged.
  • Rule-name allowlist (4a2c2ec5), answering the review question: Orchestrator only bounds a name at creation ([Required], [MaxLength(100)], no character rules), while the service refuses anything outside its allowlist. The SDK's blocklist let names like Loan#1 through to a 400; it now uses the service's allowlist. Verified on alpha: 24 names sent straight to the service, 0 disagreements with the SDK.
  • Up to date with main (05748b93).
• Copilot threads (binding folder over folder_key; non-dict input) were fixed in 162cf34a and are resolved.

Test plan

• 80 tests in tests/services/test_business_rules_service.py, covering:
  • request body and headers (input, no inputs or explain)
  • folder key and path, the env fallbacks and their order, a required folder, blank values, a path that matches no folder
  • caller defaults from the env, explicit fields, blank fields, no caller
  • input checks, and the rule-name allowlist: 19 names the service refuses (#, ?, *, $, ", |, emoji, non-breaking / zero-width space, control characters, /, \, %, .., over 256) and 8 it accepts
  • each status, 207 responses, a response without result, error responses
  • explicit vs automatic trace (no leak, survives a retry); the header naming the caller's own span, sync and async; no header outside a trace; and, with a real tracer provider, no client span recorded
  • businessRule overrides (including over folder_key)
  • run_async
• 3 tests in tests/errors/test_enriched_exception.py for the error extractor: the service's envelope, a code without a message, and other shapes falling back to the generic extractor.
• The full uipath-platform suite passes: 1855 passed, 7 skipped (live credentials).
• ruff check, ruff format --check and mypy src tests are clean.
• Real alpha (bruleswe/DefaultTenant), checked on the wire:
  • folder_path="Shared" → looked up, only x-uipath-folderkey sent → Success
  • run_async with folder_key and decision_names → only that decision
  • an unknown rule → 404 EnrichedException; no folder → ValueError, nothing sent
  • a service 401 → error_info.error_code == "UNAUTHENTICATED"
  • rule names: 24 names sent straight to the service (skipping the SDK check); the service refused exactly the ones the SDK refuses

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Fix the folder key/path presence check and add coverage for the documented UIPATH_FOLDER_PATH fallback.

Review effort: Lite
Findings: 1

Open (1)

• Add coverage for UIPATH_FOLDER_PATH fallback · New

What changed in this PR

Adds Business Rules evaluation support to uipath-platform, including sync/async APIs, validation, folder resolution, and response handling.

Changes:

• Added Business Rules models and service client.
• Exposed UiPath.business_rules.
• Added tests, documentation, and version updates.

File	Reviewed changes
packages/​uipath/​uv.lock	Dependency lock update
packages/​uipath-platform/​uv.lock	Platform version lock update
packages/​uipath-platform/​tests/​services/​test_business_rules_service.py	Service behavior tests
packages/​uipath-platform/​src/​uipath/​platform/​business_rules/​business_rules.py	Evaluation models and statuses
packages/​uipath-platform/​src/​uipath/​platform/​business_rules/​_business_rules_service.py	Evaluation service, validation, folder resolution, and response mapping
packages/​uipath-platform/​src/​uipath/​platform/​business_rules/​__init__.py	Public API exports
packages/​uipath-platform/​src/​uipath/​platform/​_uipath.py	business_rules client integration
packages/​uipath-platform/​pyproject.toml	Package version bump
packages/​uipath-platform/​CLAUDE.md	Service documentation

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ashishupadhyay88]

Tested against alpha

This tests run() / run_async() with DeployedRunContext, on commit 3795b306.

Setup

• Tenant: alpha.uipath.com/bruleswe/DefaultTenant
• Login: uipath auth --alpha (user token)
• Folder: Shared/Solution_ashish1 (key 4973409f-…)
• Rule: Business Rules
• Input: {"age": 14}

#	Call	Result
1	run(..., deployed=DeployedRunContext(rule_name="Business Rules"), folder_path=...)	✅ Success: {"category": "minor"}, service reported version 1.1.4
2	same + version="1.1.4"	✅ Success, same output
3	same + explain=True	✅ Success, same output (no 400: folder key sent)
4	version="1.1.4" + explain=True	✅ Success, same output
5	run_async(...), same as 1	✅ Success, same output
6	unknown rule name	✅ EnrichedException 404 RULE_NOT_FOUND (service's own error body)

What this confirms

• Gateway headers. The request went through the real gateway: POST https://alpha.uipath.com/bruleswe/DefaultTenant/businessrules_/v1/business-rules/evaluate. The service returns 400 if the account or tenant header is missing, so the gateway adds x-uipath-internal-accountid / -tenantid, and the SDK doesn't need to send them. This settles the open reviewer question.
• Folder path. folder_path was turned into a key and sent as x-uipath-folderkey.
• Result handling. The single input was sent as input-1, and the result was picked out and mapped to mode: Deployed / status: Success.

Checks in the locked uv environment (Python 3.11)

• uv lock --check passes for uipath-platform and uipath, so the hand-edited lockfile versions are consistent.
• 20 Business Rules tests pass.
• The full suite passes: 1767 passed, 7 skipped.
• ruff check, ruff format --check and mypy src tests are clean.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Address non-mapping input validation and malformed trace ID validation.

Review effort: Lite
Findings: None

Resolved since last review (1)

• Add coverage for UIPATH_FOLDER_PATH fallback

[NishankSiddharth]

do we need to add get, list methods for business rules (listing BRs, getting details for BRs)?

[Copilot]

Copilot review overview

🟡 Changes recommended

Three unresolved moderate findings remain in the Business Rules service implementation.

Review effort: Lite
Findings: 2

Open (2)

• Clear folder selector when applying business rule override · New
• Reject non-dict inputs before sending requests · New

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
99.1% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud