fix(guardrails): build attachment references per entry and trim comments

A malformed registry value could raise while being pre-filtered, and an
invalid candidate consumed one of the five reference slots. References are
now built per entry with safe attribute access and the loop stops after
five successfully built ones. Module and node comments cut to what is
needed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: apetraru-uipath

src/uipath_langchain/agent/guardrails/attachment_refs.py

@@ -1,60 +1,37 @@
 """Project a run's job-attachment registry into guardrail attachment references.
 
-Only the ``llm_as_judge`` validator consumes attachments today, only behind a feature flag,
-and only when the guardrail's author scoped it to files, so all three gates live here: there
-is no point building a reference for a validator -- or a guardrail configuration -- that will
-ignore the result.
-
-The runtime no longer resolves attachments to a URL. It only forwards the Orchestrator
-attachment id, file name and mime type; helix resolves the id through its own Orchestrator
-client (folder-scoped when the run's folder key is available), so Orchestrator's own access
-control decides whether the file can be read at all. That also means this module makes no
-network call of its own any more -- there is nothing here that can fail transiently.
-
-Nothing in this module raises. The low-code guardrail node re-raises any exception it sees
-(see ``guardrail_nodes._create_guardrail_node``), which terminates the agent run — so a
-malformed attachment must never escape. An unreadable file degrades to "the guardrail
-evaluates the text payload alone", which is the safer failure direction for a guardrail.
+Only the ``llm_as_judge`` validator uses attachments, behind a feature flag, and only when
+the guardrail is not scoped to prompts. The runtime forwards id, file name and mime type;
+the backend resolves the id through Orchestrator.
+
+Nothing in this module raises: the guardrail node re-raises any exception, which would end
+the run over a single malformed attachment.
 """
 
 import logging
 import uuid
+from typing import Any
 
 from uipath.core.feature_flags import FeatureFlags
 from uipath.platform.attachments import Attachment
 from uipath.platform.guardrails import BuiltInValidatorGuardrail, GuardrailAttachment
 
 logger = logging.getLogger(__name__)
 
-#: Kill switch. Names are case-sensitive and the env var is an exact concatenation:
-#: ``UIPATH_FEATURE_GuardrailAttachmentsEnabled``.
+#: Env var: ``UIPATH_FEATURE_GuardrailAttachmentsEnabled`` (case-sensitive).
 GUARDRAIL_ATTACHMENTS_FEATURE_FLAG = "GuardrailAttachmentsEnabled"
 
-#: The only validator that can read file contents today. The backend enforces this too.
 _LLM_AS_JUDGE = "llm_as_judge"
-
-#: Matches the ceiling the validate API enforces; resolving more would be wasted work.
+#: Limits enforced by the validate API.
 _MAX_ATTACHMENTS = 5
-
-#: The validate API rejects longer file names with a 400.
 _MAX_FILE_NAME_LENGTH = 260
-
-#: Optional guardrail parameter scoping the evaluation to ``Prompts``, ``Files`` or ``Both``.
-#: Parameter ids are matched case-insensitively, as the backend does.
+#: ``appliesTo`` guardrail parameter; only ``Prompts`` excludes files (default is ``Both``).
 _APPLIES_TO_PARAMETER = "appliesto"
-
-#: The one value that puts files out of scope. Anything else -- including an absent parameter,
-#: which is every guardrail configured before it existed -- keeps them in, matching the
-#: backend's default of "Both". Narrowing on an unrecognized value would silently stop
-#: scanning files for a guardrail whose author never asked for that.
 _PROMPTS_ONLY = "prompts"
 
-#: What the backend can inspect. The runtime only forwards references — the backend decides
-#: how to read each type, so this set exists to avoid spending an Orchestrator round-trip on a
-#: file that would be skipped anyway.
+#: Types the backend can inspect; anything else is not worth forwarding.
 SUPPORTED_MIME_TYPES = frozenset(
     {
-        # Already text: the backend decodes these and inlines them into the judged payload.
         "text/plain",
         "text/csv",
         "application/csv",
@@ -63,7 +40,6 @@
         "application/json",
         "text/xml",
         "application/xml",
-        # Binary: the backend sends these to a vision-capable judge model as content parts.
         "application/pdf",
         "image/png",
         "image/jpeg",
@@ -74,7 +50,6 @@
 
 
 def _is_enabled(guardrail: BuiltInValidatorGuardrail) -> bool:
-    """Both gates: the validator must be the judge and the feature flag must be on."""
     if getattr(guardrail, "validator_type", None) != _LLM_AS_JUDGE:
         return False
     return FeatureFlags.is_flag_enabled(
@@ -83,12 +58,6 @@ def _is_enabled(guardrail: BuiltInValidatorGuardrail) -> bool:
 
 
 def _scope_includes_files(guardrail: BuiltInValidatorGuardrail) -> bool:
-    """Whether the guardrail's ``appliesTo`` parameter puts the run's files in scope.
-
-    The backend gates on this too, but only after helix has already resolved each id
-    through Orchestrator. Reading it here is what actually avoids sending references --
-    and the Orchestrator lookups they trigger downstream -- for a prompts-only guardrail.
-    """
     try:
         for parameter in getattr(guardrail, "validator_parameters", None) or []:
             if str(getattr(parameter, "id", "")).lower() != _APPLIES_TO_PARAMETER:
@@ -97,8 +66,6 @@ def _scope_includes_files(guardrail: BuiltInValidatorGuardrail) -> bool:
             if isinstance(value, str):
                 return value.strip().lower() != _PROMPTS_ONLY
     except Exception:
-        # This module promises never to raise: the caller re-raises, which ends the run. A
-        # parameter list that is not shaped as expected falls back to the backend's default.
         logger.debug(
             "Could not read the guardrail scope; assuming files apply.", exc_info=True
         )
@@ -109,16 +76,10 @@ async def resolve_guardrail_attachments(
     job_attachments: dict[str, Attachment],
     guardrail: BuiltInValidatorGuardrail,
 ) -> list[GuardrailAttachment]:
-    """Resolve the run's job attachments into references the guardrails API can read.
+    """Return up to five attachment references for the guardrail, or an empty list.
 
-    Args:
-        job_attachments: The per-run registry from ``state.inner_state.job_attachments``.
-        guardrail: The guardrail about to be evaluated; gates on its validator type.
-
-    Returns:
-        Attachment references, or an empty list when the feature is off, the validator
-        cannot use them, the guardrail is scoped to prompts only, or none are of a
-        supported type. Never raises.
+    Empty when the feature is off, the validator is not the judge, the guardrail is scoped
+    to prompts, or no attachment is of a supported type. Never raises.
     """
     if not job_attachments or not _is_enabled(guardrail):
         return []
@@ -129,48 +90,32 @@ async def resolve_guardrail_attachments(
         )
         return []
 
-    candidates = [
-        attachment
-        for attachment in job_attachments.values()
-        if attachment.id is not None
-        and (attachment.mime_type or "").lower() in SUPPORTED_MIME_TYPES
-    ][:_MAX_ATTACHMENTS]
-
     references: list[GuardrailAttachment] = []
-    for attachment in candidates:
+    for attachment in job_attachments.values():
         reference = _to_reference(attachment)
         if reference is not None:
             references.append(reference)
+            if len(references) == _MAX_ATTACHMENTS:
+                break
     return references
 
 
-def _to_reference(attachment: Attachment) -> GuardrailAttachment | None:
-    """Project one job attachment into a reference, or None if it cannot be forwarded."""
-    attachment_id = str(attachment.id)
-    try:
-        uuid.UUID(attachment_id)
-    except (ValueError, AttributeError, TypeError):
-        # The validate API requires a GUID; helix has nothing to resolve otherwise.
-        logger.warning(
-            "Attachment '%s' has a non-UUID id; skipping for guardrail inspection.",
-            getattr(attachment, "full_name", "?"),
-        )
-        return None
+def _to_reference(attachment: Any) -> GuardrailAttachment | None:
+    """Build one reference, or None when the attachment cannot be forwarded."""
     try:
-        # The validate API caps file names at 260 characters; a longer name would be a 400
-        # for the whole request, and this is a display label, not an identifier.
-        file_name = (attachment.full_name or "")[:_MAX_FILE_NAME_LENGTH]
+        mime_type = str(getattr(attachment, "mime_type", "") or "")
+        if mime_type.lower() not in SUPPORTED_MIME_TYPES:
+            return None
+        attachment_id = str(uuid.UUID(str(getattr(attachment, "id", None))))
+        file_name = str(getattr(attachment, "full_name", "") or "")
         return GuardrailAttachment(
             id=attachment_id,
-            file_name=file_name,
-            mime_type=attachment.mime_type,
+            file_name=file_name[:_MAX_FILE_NAME_LENGTH],
+            mime_type=mime_type,
         )
     except Exception:
-        # Deliberately broad: this module promises never to raise, and the caller
-        # re-raises, which would end the run over a single malformed attachment.
         logger.warning(
-            "Could not build a guardrail reference for attachment '%s'; "
-            "the guardrail will evaluate without it.",
+            "Skipping attachment '%s' for guardrail inspection: invalid reference.",
             getattr(attachment, "full_name", "?"),
             exc_info=True,
         )

src/uipath_langchain/agent/guardrails/guardrail_nodes.py

@@ -37,7 +37,7 @@
 
 logger = logging.getLogger(__name__)
 
-#: Guardrail scopes whose evaluations may inspect attached files. Deliberately not TOOL.
+#: Scopes whose guardrails may inspect attached files (tool scope excluded on purpose).
 _ATTACHMENT_SCOPES = frozenset({GuardrailScope.AGENT, GuardrailScope.LLM})
 
 
@@ -83,14 +83,6 @@ async def _evaluate_builtin_guardrail(
 ):
     """Evaluate built-in validator guardrail.
 
-    Takes the already-generated payload rather than the generator: the caller needs the
-    same payload for observability metadata, and generating it twice would double any
-    work the generator does.
-
-    ``evaluate_guardrail`` is a synchronous HTTP call, so it is offloaded to a thread
-    rather than blocking the event loop for the whole round-trip — which now includes the
-    backend fetching and decoding each attachment.
-
     Args:
         guardrail: The built-in validator guardrail to evaluate.
         text: The payload text to validate.
@@ -108,11 +100,8 @@ async def _evaluate_builtin_guardrail(
             attachments=attachments,
         )
     except EnrichedException as exc:
-        # A 400 on a request that carried attachments means the backend rejected the
-        # attachment references themselves (bad id, oversize name, unresolvable
-        # attachment...). A guardrail must never fail the run because of a file, so
-        # evaluate the text payload alone. Any other status is a genuine failure and
-        # propagates as before.
+        # A 400 with attachments means the references were rejected; a file must never
+        # fail the run, so evaluate the text alone.
         if not attachments or exc.status_code != 400:
             raise
         logger.warning(
@@ -239,17 +228,13 @@ async def node(
                     output_data_extractor,
                 )
             elif isinstance(guardrail, BuiltInValidatorGuardrail):
-                # Generate and store payload for observability. Generated once and passed
-                # down: it used to run again inside _evaluate_builtin_guardrail.
+                # Generate and store payload for observability
                 payload = payload_generator(state)
                 if execution_stage == ExecutionStage.PRE_EXECUTION:
                     metadata["payload"]["input"] = payload
                 else:
                     metadata["payload"]["output"] = payload
 
-                # File contents reach the judge at Agent and LLM scope only. Tool scope is
-                # excluded on purpose: a tool-scope judge would forward attachment
-                # references on every tool call, over a registry that only grows.
                 attachments = (
                     await resolve_guardrail_attachments(
                         state.inner_state.job_attachments, guardrail

tests/agent/guardrails/test_attachment_refs.py

@@ -1,6 +1,7 @@
 """Tests for projecting the job-attachment registry into guardrail attachment refs."""
 
 import uuid
+from typing import Any
 from unittest.mock import MagicMock
 
 import pytest
@@ -9,6 +10,7 @@
 from uipath.platform.guardrails.guardrails import EnumParameterValue
 
 from uipath_langchain.agent.guardrails.attachment_refs import (
+    _MAX_ATTACHMENTS,
     GUARDRAIL_ATTACHMENTS_FEATURE_FLAG,
     resolve_guardrail_attachments,
 )
@@ -121,6 +123,26 @@ async def test_caps_attachment_count(self, monkeypatch):
 
         assert len(result) == 5
 
+    async def test_malformed_entry_neither_raises_nor_consumes_a_slot(
+        self, monkeypatch
+    ):
+        """One bad registry value must not end the run or hide a later valid file."""
+        monkeypatch.setenv(_ENV_FLAG, "true")
+        registry: dict[str, Any] = {"bad": object()}
+        for index in range(_MAX_ATTACHMENTS):
+            attachment_id = str(uuid.uuid4())
+            registry[attachment_id] = Attachment(
+                id=uuid.UUID(attachment_id),
+                full_name=f"{index}.csv",
+                mime_type="text/csv",
+            )
+
+        result = await resolve_guardrail_attachments(registry, _judge())
+
+        assert [a.file_name for a in result] == [
+            f"{i}.csv" for i in range(_MAX_ATTACHMENTS)
+        ]
+
     async def test_returns_empty_for_empty_registry(self, monkeypatch):
         monkeypatch.setenv(_ENV_FLAG, "true")