Interface Guardrail<P extends GuardrailRequest, R extends GuardrailResult<R>>

Type Parameters:
P - The type of the GuardrailRequest
R - The type of the GuardrailResult
All Known Subinterfaces:
InputGuardrail, OutputGuardrail
All Known Implementing Classes:
JsonExtractorOutputGuardrail, MessageModeratorInputGuardrail, PatternBasedPromptInjectionGuardrail
public interface Guardrail<P extends GuardrailRequest, R extends GuardrailResult<R>>
A guardrail is a rule that is applied when interacting with an LLM either to the input (the user message) or to the output of the model to ensure that they are safe and meet the expectations of the model.

  • Method Summary

    Modifier and Type
    Method
    Description
    default String
    name()
    Returns the logical name of this guardrail.
    R
    validate(P request)
    Validate the interaction between the model and the user in one of the two directions.
    default CompletableFuture<R>
    validateAsync(P request)
    Non-blocking counterpart of validate(GuardrailRequest), invoked by the asynchronous (CompletableFuture/CompletionStage) and reactive (Flow.Publisher) AI Service modes.

  • Method Details

    • name

      default String name()
      Returns the logical name of this guardrail. Wrappers/decorators can override this method to expose the wrapped guardrail's name.
      Returns:
      the logical guardrail name

    • validate

      R validate(P request)
      Validate the interaction between the model and the user in one of the two directions.
      Parameters:
      request - The parameters of the request or the response to be validated
      Returns:
      The result of the validation

    • validateAsync

      @Experimental default CompletableFuture<R> validateAsync(P request)
      Non-blocking counterpart of validate(GuardrailRequest), invoked by the asynchronous (CompletableFuture/CompletionStage) and reactive (Flow.Publisher) AI Service modes.

      Returns a CompletableFuture (rather than a plain CompletionStage) because guardrails sit in the cancellable execution path: the AI Service may cancel an in-flight validation when the invocation is cancelled (best-effort, mirroring ToolExecutor). A guardrail backed by a cancellation-aware async client should honor that cancellation.

      The default implementation returns a failed future carrying AsyncNotSupportedException: a guardrail must opt in to the non-blocking paths rather than have its (potentially blocking) validate(GuardrailRequest) silently run on the model-delivery thread. A guardrail that performs blocking I/O (e.g. calling a remote moderation or PII service) must override this method to return a future completed off the calling thread (for instance via an async client, or CompletableFuture.supplyAsync(..., executor) onto its own executor). A guardrail that does not perform blocking I/O may simply return CompletableFuture.completedFuture(validate(request)).

      This mirrors ChatMemoryStore and ToolExecutor, whose asynchronous counterparts likewise report "not implemented" through the returned future rather than throwing.

      Parameters:
      request - The parameters of the request or the response to be validated
      Returns:
      A CompletableFuture that completes with the result of the validation
      Since:
      1.20.0