1 /*
2 * Copyright 2012-2025 CodeLibs Project and the Others.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
13 * either express or implied. See the License for the specific language
14 * governing permissions and limitations under the License.
15 */
16 package org.codelibs.fess.chat;
17
18 /**
19 * Callback interface for receiving notifications about chat processing phases.
20 * Used for SSE streaming to notify clients about the current processing state.
21 */
22 public interface ChatPhaseCallback {
23
24 /** Phase name for intent detection */
25 String PHASE_INTENT = "intent";
26
27 /** Phase name for document search */
28 String PHASE_SEARCH = "search";
29
30 /** Phase name for result evaluation */
31 String PHASE_EVALUATE = "evaluate";
32
33 /** Phase name for content retrieval */
34 String PHASE_FETCH = "fetch";
35
36 /** Phase name for answer generation */
37 String PHASE_ANSWER = "answer";
38
39 /**
40 * Called when a processing phase starts.
41 *
42 * @param phase the phase name (e.g., "intent", "search", "evaluate", "fetch", "answer")
43 * @param message a human-readable message describing what's happening
44 */
45 void onPhaseStart(String phase, String message);
46
47 /**
48 * Called when a processing phase starts with additional context data.
49 *
50 * @param phase the phase name (e.g., "intent", "search", "evaluate", "fetch", "answer")
51 * @param message a human-readable message describing what's happening
52 * @param keywords the search keywords (for search phase)
53 */
54 default void onPhaseStart(final String phase, final String message, final String keywords) {
55 onPhaseStart(phase, message);
56 }
57
58 /**
59 * Called when a processing phase completes.
60 *
61 * @param phase the phase name that completed
62 */
63 void onPhaseComplete(String phase);
64
65 /**
66 * Called when a chunk of the response is available during streaming.
67 *
68 * @param content the content chunk
69 * @param done true if this is the final chunk
70 */
71 void onChunk(String content, boolean done);
72
73 /**
74 * Called when an error occurs during processing.
75 *
76 * @param phase the phase where the error occurred
77 * @param error the error message
78 */
79 void onError(String phase, String error);
80
81 /**
82 * Returns a no-op callback implementation.
83 *
84 * @return a callback that does nothing
85 */
86 static ChatPhaseCallback noOp() {
87 return new ChatPhaseCallback() {
88 @Override
89 public void onPhaseStart(final String phase, final String message) {
90 // no-op
91 }
92
93 @Override
94 public void onPhaseComplete(final String phase) {
95 // no-op
96 }
97
98 @Override
99 public void onChunk(final String content, final boolean done) {
100 // no-op
101 }
102
103 @Override
104 public void onError(final String phase, final String error) {
105 // no-op
106 }
107 };
108 }
109 }