Class GuardrailRefusal

java.lang.Object
org.springframework.ai.chat.model.GuardrailRefusal

public final class GuardrailRefusal extends Object
Marks a reply that a guardrail put in place of the model's answer.

A guardrail that refuses a turn answers with words of its own, such as "I can't help with that". To the rest of the chain that reply looks like any other, yet it is not what the model said: validating it as the requested output, judging it or asking the model again would be pointless. A guardrail therefore builds its refusal with generation(String), which sets FINISH_REASON as the finish reason, and a component that needs to tell the two apart checks isRefusal(ChatResponse).

The marker is honoured where a refusal would otherwise be taken for structured output: ChatClient.entity(...) throws a GuardrailRefusalException and the StructuredOutputValidationAdvisor returns the refusal without validating it. Other components, the memory advisors among them, treat a refusal as any other reply. The marker is the finish reason of the generation, so a component that rebuilds the generation from its text loses it.

Since:
2.1.0
Author:
Christian Tzolov
  • Field Details

    • FINISH_REASON

      public static final String FINISH_REASON
      The finish reason of a Generation that carries a guardrail's refusal, telling it apart from an answer of the model.
      See Also:
  • Method Details

    • generation

      public static Generation generation(String text)
      Builds the generation that carries a refusal.
      Parameters:
      text - what the refusal says
      Returns:
      an assistant message with the text, finished with FINISH_REASON in the FinishReasonCategory.FILTERED category
    • isRefusal

      public static boolean isRefusal(@Nullable ChatResponse response)
      Whether a response is a guardrail's refusal rather than an answer of the model. As with ChatResponse.hasToolCalls(), one generation is enough: a response of which a guardrail refused any part is a refused turn.
      Parameters:
      response - the response, possibly null
      Returns:
      true when the response has the FINISH_REASON finish reason
    • isRefusal

      public static boolean isRefusal(@Nullable Generation generation)
      Whether a generation carries a guardrail's refusal rather than an answer of the model.
      Parameters:
      generation - the generation, possibly null
      Returns:
      true when it finished with FINISH_REASON, in any case
    • text

      public static @Nullable String text(@Nullable ChatResponse response)
      What the guardrail said in place of an answer.
      Parameters:
      response - the response, possibly null
      Returns:
      the text of the refusal, or null when the response is not a refusal or the refusal has no text