feat: normalize LLM client semantic errors

[cotovanu-cristian]

Summary

Give downstream consumers a stable, provider-independent way to handle LLM client failures — a small semantic error contract on UiPathError — so the agent layer never parses provider exception types or message text.

What changed

• Add and export UiPathLLMErrorCode (currently just UNSUPPORTED_MIME_TYPE) plus optional error_code and diagnostic detail on UiPathError. Purely additive.
• as_uipath_error normalizes on two fixed paths: HTTP-status-bearing errors map to UiPathAPIError subclasses (status authoritative); response-less client-side rejections run the _CLIENT_SIDE_CLASSIFIERS registry.
• Recognize Bedrock Converse unsupported-MIME ValueError chains via the _UNSUPPORTED_MIME_MATCHERS seam → UNSUPPORTED_MIME_TYPE.
• Bump uipath-llm-client to 1.16.2.

Key decisions

• Recognition keyed by semantic code, not by provider. A code that providers surface differently is one classifier over N matcher predicates (_UNSUPPORTED_MIME_MATCHERS); adding a provider surfacing is one predicate and as_uipath_error never grows a new branch. Rejected: a per-provider catch in the general layer, which leaks provider shape into the normalizer.
• HTTP status stays authoritative. A real httpx.Response is mapped before any client-side classifier runs, so an incidental ValueError in __context__ can't mislabel a genuine HTTP error.

How it flows

flowchart TD
    E[provider or SDK exception] --> R{httpx.Response in cause chain?}
    R -->|yes| S[map status to UiPathAPIError subclass]
    R -->|no| C{client-side classifier match?}
    C -->|yes| K[UiPathError with stable error_code]
    C -->|no| G[UiPathError root]

Loading

Test plan

• uv run pytest tests/langchain/features/test_exception_wrapping.py tests/core/features/test_exception_wrapping.py tests/core/features/test_exceptions.py -q — 96 passed
• uv run ruff check . clean · uv run pyright 0 errors

Known limitations

Two extensibility follow-ups for this pattern, deliberately out of scope until a real second surfacing lands:

• Semantic code on the HTTP path. A condition arriving as an HTTP 400 (e.g. an OpenAI content rejection) gets only the status class today, not a semantic error_code. Next: let the status-bearing branch attach a code on top of the status class, matched against the response body only (preserving the "real response outranks incidental chain match" guard). Markers aren't guessed before a provider actually surfaces it.
• Downstream duplication. uipath-langchain/chat/provider_errors.py re-derives status codes per-provider — the coupling this contract removes. Load-bearing only for the legacy use_new_llm_clients=False boto3 path that bypasses wrap_provider_errors; route it through the wrapper, then delete it.

Breaking changes: none — purely additive (new enum + optional fields); existing UiPathError/UiPathAPIError catch behavior unchanged.