Package org.codelibs.fess.chat

Interface ChatPhaseCallback

public interface ChatPhaseCallback
Callback interface for receiving notifications about chat processing phases. Used for SSE streaming to notify clients about the current processing state.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    PHASE_ANSWER
    Phase name for answer generation
    static final String
    PHASE_EVALUATE
    Phase name for result evaluation
    static final String
    PHASE_FETCH
    Phase name for content retrieval
    static final String
    PHASE_INTENT
    Phase name for intent detection
    static final String
    PHASE_SEARCH
    Phase name for document search

  • Method Summary

    Modifier and Type
    Method
    Description
    static ChatPhaseCallback
    noOp()
    Returns a no-op callback implementation.
    void
    onChunk(String content, boolean done)
    Called when a chunk of the response is available during streaming.
    void
    onError(String phase, String error)
    Called when an error occurs during processing.
    default void
    onFallback(String phase, String reason, String originalQuery, String newQuery)
    Called when the search query is regenerated due to no or no-relevant results.
    void
    onPhaseComplete(String phase)
    Called when a processing phase completes.
    default void
    onPhaseComplete(String phase, Map<String,Object> payload)
    Called when a processing phase completes with metadata payload (e.g., hit counts).
    void
    onPhaseStart(String phase, String message)
    Called when a processing phase starts.
    default void
    onPhaseStart(String phase, String message, String keywords)
    Called when a processing phase starts with additional context data.
    default void
    onRetry(String phase, String operation, int attempt, int maxAttempts, long sleepMs, String cause)
    Called when the underlying LLM call is being retried.
    default void
    onWaiting(String phase, String reason, long elapsedMs, long timeoutMs)
    Called when the request is waiting for a concurrency permit.
    default void
    onWarning(String phase, String code, String detail)
    Called when an internal silent fallback occurs (e.g., reasoning model token exhaustion).

  • Field Details

  • Method Details

    • onPhaseStart

      void onPhaseStart(String phase, String message)
      Called when a processing phase starts.
      Parameters:
      phase - the phase name (e.g., "intent", "search", "evaluate", "fetch", "answer")
      message - a human-readable message describing what's happening

    • onPhaseStart

      default void onPhaseStart(String phase, String message, String keywords)
      Called when a processing phase starts with additional context data.
      Parameters:
      phase - the phase name (e.g., "intent", "search", "evaluate", "fetch", "answer")
      message - a human-readable message describing what's happening
      keywords - the search keywords (for search phase)

    • onPhaseComplete

      void onPhaseComplete(String phase)
      Called when a processing phase completes.
      Parameters:
      phase - the phase name that completed

    • onPhaseComplete

      default void onPhaseComplete(String phase, Map<String,Object> payload)
      Called when a processing phase completes with metadata payload (e.g., hit counts). Default implementation delegates to onPhaseComplete(String) ignoring the payload.
      Parameters:
      phase - the phase name that completed
      payload - optional metadata such as hitCount; never null

    • onChunk

      void onChunk(String content, boolean done)
      Called when a chunk of the response is available during streaming.
      Parameters:
      content - the content chunk
      done - true if this is the final chunk

    • onError

      void onError(String phase, String error)
      Called when an error occurs during processing.
      Parameters:
      phase - the phase where the error occurred
      error - the error message

    • onRetry

      default void onRetry(String phase, String operation, int attempt, int maxAttempts, long sleepMs, String cause)
      Called when the underlying LLM call is being retried.
      Parameters:
      phase - the phase where the retry occurs
      operation - log label for the LLM operation (e.g., "streamChat")
      attempt - 1-based attempt index that just failed
      maxAttempts - total attempts including the first
      sleepMs - milliseconds the client will sleep before the next attempt
      cause - short cause description (e.g., "status:429" or "exception:IOException")

    • onWaiting

      default void onWaiting(String phase, String reason, long elapsedMs, long timeoutMs)
      Called when the request is waiting for a concurrency permit.
      Parameters:
      phase - the phase where waiting occurs
      reason - short reason code (currently always "concurrency_limit")
      elapsedMs - milliseconds already spent waiting
      timeoutMs - maximum milliseconds the client will wait

    • onFallback

      default void onFallback(String phase, String reason, String originalQuery, String newQuery)
      Called when the search query is regenerated due to no or no-relevant results.
      Parameters:
      phase - the phase where fallback occurs (typically "search")
      reason - short reason code (e.g., "no_results", "no_relevant_results")
      originalQuery - the query that produced no useful results
      newQuery - the regenerated query that will be retried

    • onWarning

      default void onWarning(String phase, String code, String detail)
      Called when an internal silent fallback occurs (e.g., reasoning model token exhaustion).
      Parameters:
      phase - the phase where the warning occurred
      code - short machine-readable warning code (e.g., "reasoning_token_exhausted")
      detail - short human-readable detail or related fallback action

    • noOp

      static ChatPhaseCallback noOp()
      Returns a no-op callback implementation.
      Returns:
      a callback that does nothing