Interface GuardrailService

All Known Implementing Classes:
AbstractGuardrailService
public interface GuardrailService
Defines a service for executing guardrails associated with methods in an AI service. Guardrails are constraints or validations applied either to input or output of a method.

  • Method Details

    • aiServiceClass

      Class<?> aiServiceClass()
      Retrieves the class representing the AI service to which the guardrails apply.
      Returns:
      The Class object representing the AI service.

    • executeInputGuardrails

      <MethodKey> InputGuardrailResult executeInputGuardrails(MethodKey method, InputGuardrailRequest request)
      Executes the input guardrails associated with a given Method
      Type Parameters:
      MethodKey - > The type of the method key, representing a unique identifier for methods.
      Parameters:
      method - The method whose input guardrails are to be executed.
      request - The parameters to validate against the input guardrails. Must not be null.
      Returns:
      The result of executing the input guardrails, encapsulated in an InputGuardrailResult. If no guardrails are associated with the method, a successful result is returned by default.

    • executeInputGuardrailsAsync

      @Experimental default <MethodKey> CompletableFuture<InputGuardrailResult> executeInputGuardrailsAsync(MethodKey method, InputGuardrailRequest request)
      Non-blocking counterpart of executeInputGuardrails(Object, InputGuardrailRequest).

      The default implementation returns a failed future carrying AsyncNotSupportedException; the internal implementation (AbstractGuardrailService) overrides it, and only implementors that opt into the non-blocking AI Service modes need to provide it.

      Type Parameters:
      MethodKey - The type of the method key, representing a unique identifier for methods.
      Parameters:
      method - The method whose input guardrails are to be executed.
      request - The parameters to validate against the input guardrails. Must not be null.
      Returns:
      A CompletableFuture that completes with the InputGuardrailResult.
      Since:
      1.20.0

    • executeGuardrails

      default <MethodKey> UserMessage executeGuardrails(MethodKey method, InputGuardrailRequest request)
      Executes the input guardrails associated with the given method and parameters, and retrieves a modified or validated UserMessage based on the result.
      Type Parameters:
      MethodKey - The type of the method key, representing a unique identifier for methods.
      Parameters:
      method - The method whose input guardrails are to be executed. Nullable.
      request - The parameters to validate against the input guardrails. Must not be null.
      Returns:
      A UserMessage derived from the provided parameters and the result of the input guardrails execution. If guardrails are applied successfully, a potentially rewritten user message is returned. If no guardrails are associated with the method, the original user message is returned.

    • executeGuardrailsAsync

      @Experimental default <MethodKey> CompletableFuture<UserMessage> executeGuardrailsAsync(MethodKey method, InputGuardrailRequest request)
      Non-blocking counterpart of executeGuardrails(Object, InputGuardrailRequest): runs the input guardrails without blocking the calling thread and yields the (possibly rewritten) UserMessage.
      Since:
      1.20.0

    • executeOutputGuardrails

      <MethodKey> OutputGuardrailResult executeOutputGuardrails(MethodKey method, OutputGuardrailRequest request)
      Executes the output guardrails associated with a given Method.
      Type Parameters:
      MethodKey - > The type of the method key, representing a unique identifier for methods.
      Parameters:
      method - The method whose output guardrails are to be executed.
      request - The parameters to validate against the output guardrails. Must not be null.
      Returns:
      The result of executing the output guardrails, encapsulated in an OutputGuardrailResult. If no guardrails are associated with the method, a successful result is returned by default.

    • executeOutputGuardrailsAsync

      @Experimental default <MethodKey> CompletableFuture<OutputGuardrailResult> executeOutputGuardrailsAsync(MethodKey method, OutputGuardrailRequest request)
      Non-blocking counterpart of executeOutputGuardrails(Object, OutputGuardrailRequest).

      The default implementation returns a failed future carrying AsyncNotSupportedException; the internal implementation (AbstractGuardrailService) overrides it, and only implementors that opt into the non-blocking AI Service modes need to provide it.

      Type Parameters:
      MethodKey - The type of the method key, representing a unique identifier for methods.
      Parameters:
      method - The method whose output guardrails are to be executed.
      request - The parameters to validate against the output guardrails. Must not be null.
      Returns:
      A CompletableFuture that completes with the OutputGuardrailResult.
      Since:
      1.20.0

    • hasInputGuardrails

      <MethodKey> boolean hasInputGuardrails(MethodKey method)
      Whether or not a method has any input guardrails associated with it
      Type Parameters:
      MethodKey - > The type of the method key, representing a unique identifier for methods.
      Parameters:
      method - The method
      Returns:
      true If method has input guardrails. false otherwise

    • hasOutputGuardrails

      <MethodKey> boolean hasOutputGuardrails(MethodKey method)
      Whether or not a method has any output guardrails associated with it
      Type Parameters:
      MethodKey - > The type of the method key, representing a unique identifier for methods.
      Parameters:
      method - The method
      Returns:
      true If method has output guardrails. false otherwise

    • executeGuardrails

      default <MethodKey, T> T executeGuardrails(MethodKey method, OutputGuardrailRequest request)
      Executes the guardrails associated with a given method and parameters, returning the appropriate response.
      Type Parameters:
      MethodKey - The type of the method key, representing a unique identifier for methods.
      T - The type of response to produce
      Parameters:
      method - The method whose output guardrails are to be executed. Nullable.
      request - The parameters to validate against the output guardrails. Must not be null.
      Returns:
      A ChatResponse that encapsulates the output of executing the guardrails based on the provided parameters.

    • executeGuardrailsAsync

      @Experimental default <MethodKey, T> CompletableFuture<T> executeGuardrailsAsync(MethodKey method, OutputGuardrailRequest request)
      Non-blocking counterpart of executeGuardrails(Object, OutputGuardrailRequest) for the asynchronous (CompletableFuture) and reactive (Flow.Publisher) AI Service modes. The output guardrails — including any reprompt round-trips to the model — run without blocking the calling thread; a guardrail that performs blocking I/O keeps the calling thread free only if it overrides Guardrail.validateAsync(dev.langchain4j.guardrail.GuardrailRequest).
      Since:
      1.20.0

    • builder

      static GuardrailService.Builder builder(Class<?> aiServiceClass)
      Creates a new instance of GuardrailService.Builder for the specified AI service class.

      Attempts to retrieve an instance through a GuardrailServiceBuilderFactory, if available. If no factory is present, it uses its own default instance.

      Parameters:
      aiServiceClass - The Class object representing the AI service for which the builder is being created.
      Returns:
      A GuardrailService.Builder instance initialized with the specified AI service class.