Package com.tnsai.rag

Enum Class RetrievalException.Reason

java.lang.Object
java.lang.Enum<RetrievalException.Reason>
com.tnsai.rag.RetrievalException.Reason
All Implemented Interfaces:
Serializable, Comparable<RetrievalException.Reason>, Constable
Enclosing class:
RetrievalException
public static enum RetrievalException.Reason extends Enum<RetrievalException.Reason>
Stable failure categories shared by chat and action entry points.

Each constant is fixed on one side of the @Search.onFailure boundary, and surfacesAboveFailurePolicy() is the authoritative answer. A declaration that cannot be honoured must fail the caller; a transport failure is what the failure policy exists to absorb. Routing a declaration fault through the policy is the defect this taxonomy exists to prevent: onFailure = CONTINUE would leave the caller ungrounded while reporting success.

  • Enum Constant Details

    • CONFIGURATION

      public static final RetrievalException.Reason CONFIGURATION
      The retrieval declaration cannot be honoured. Surfaces above the failure policy.

    • TIMEOUT

      public static final RetrievalException.Reason TIMEOUT
      The absolute request deadline elapsed. Transport-class, so the failure policy applies.

    • PROVIDER_UNAVAILABLE

      public static final RetrievalException.Reason PROVIDER_UNAVAILABLE
      No RetrievalEngineProvider is installed, or a provider refused to build an engine for the owner's source set. This is a deployment fault rather than a transient one — an agent with no retrieval runtime at all would otherwise answer ungrounded while reporting success — so it surfaces above the failure policy.

    • EXECUTION

      public static final RetrievalException.Reason EXECUTION
      The retrieval backend threw or returned no result, including a backend that is unreachable at this moment. Transport-class, so the failure policy applies.

    • ENGINE_CLOSED

      public static final RetrievalException.Reason ENGINE_CLOSED
      Retrieval was attempted on a closed engine. A lifecycle programming error; swallowing it would mask the defect and silently degrade every later invocation, so it surfaces above the failure policy.

    • SOURCE_LOADING

      public static final RetrievalException.Reason SOURCE_LOADING
      A declared source could not be loaded completely. Unlike a successfully loaded source with no documents, this is a failure that the declared failure policy may handle.

  • Method Details

    • values

      public static RetrievalException.Reason[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static RetrievalException.Reason valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • surfacesAboveFailurePolicy

      public boolean surfacesAboveFailurePolicy()
      Returns whether this failure must reach the caller unmodified rather than being absorbed by @Search.onFailure.
      Returns:
      true for declaration and lifecycle faults, false for transport faults the policy may handle