feat: add reasoning chunk and result filtering options to StreamOptions (#269)

Author: shlokmestry

agentscope-core/src/main/java/io/agentscope/core/agent/StreamOptions.java

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package io.agentscope.core.agent;
 
 import java.util.Arrays;
@@ -24,6 +25,16 @@
  *
  * <p>Controls which event types to receive and how streaming content is delivered.
  *
+ * <p><b>Reasoning filtering (Issue #265):</b>
+ * Some streaming backends emit both:
+ * <ul>
+ *   <li><b>Reasoning chunks</b>: incremental deltas during the reasoning process</li>
+ *   <li><b>Reasoning result</b>: the final consolidated reasoning output</li>
+ * </ul>
+ *
+ * <p>Use {@link #isIncludeReasoningChunk()} and {@link #isIncludeReasoningResult()} to filter
+ * these reasoning-related emissions when {@link EventType#REASONING} is enabled.
+ *
  * <p><b>Example usage:</b>
  *
  * <pre>{@code
@@ -33,11 +44,12 @@
  *     .incremental(true)
  *     .build();
  *
- * // All events including final result, cumulative mode
+ * // Reasoning events, but hide intermediate deltas and only keep the final reasoning result
  * StreamOptions options = StreamOptions.builder()
- *     .eventTypes(EventType.ALL)
- *     .includeAgentResult(true)
- *     .incremental(false)
+ *     .eventTypes(EventType.REASONING)
+ *     .includeReasoningChunk(false)
+ *     .includeReasoningResult(true)
+ *     .incremental(true)
  *     .build();
  *
  * // Multiple specific types
@@ -52,6 +64,22 @@ public class StreamOptions {
     private final Set<EventType> eventTypes;
     private final boolean incremental;
 
+    /**
+     * Whether to include the incremental delta of the reasoning process during streaming.
+     * <p>
+     * If false, intermediate reasoning chunk emissions should be filtered out by the stream
+     * implementation.
+     */
+    private final boolean includeReasoningChunk;
+
+    /**
+     * Whether to include the final consolidated reasoning output in the response.
+     * <p>
+     * If false, final reasoning result emissions should be filtered out by the stream
+     * implementation.
+     */
+    private final boolean includeReasoningResult;
+
     /**
      * Private constructor called by the builder.
      *
@@ -60,10 +88,12 @@ public class StreamOptions {
     private StreamOptions(Builder builder) {
         this.eventTypes = builder.eventTypes;
         this.incremental = builder.incremental;
+        this.includeReasoningChunk = builder.includeReasoningChunk;
+        this.includeReasoningResult = builder.includeReasoningResult;
     }
 
     /**
-     * Default options: All event types (except AGENT_RESULT), incremental mode.
+     * Default options: All event types, incremental mode, include both reasoning chunk and reasoning result.
      *
      * @return StreamOptions with default configuration
      */
@@ -83,8 +113,7 @@ public static Builder builder() {
     /**
      * Get the set of event types that should be streamed.
      *
-     * <p>If the set contains {@link EventType#ALL}, all event types (except AGENT_RESULT unless
-     * explicitly opted-in) will be streamed.
+     * <p>If the set contains {@link EventType#ALL}, all event types will be streamed.
      *
      * @return The set of event types to stream
      */
@@ -104,6 +133,28 @@ public boolean isIncremental() {
         return incremental;
     }
 
+    /**
+     * Whether reasoning "chunk" emissions should be included.
+     *
+     * <p>Reasoning chunks are the incremental delta of the reasoning process during streaming.</p>
+     *
+     * @return true if reasoning chunks should be included
+     */
+    public boolean isIncludeReasoningChunk() {
+        return includeReasoningChunk;
+    }
+
+    /**
+     * Whether the final reasoning result should be included.
+     *
+     * <p>The reasoning result is the final consolidated reasoning output in the response.</p>
+     *
+     * @return true if the final reasoning result should be included
+     */
+    public boolean isIncludeReasoningResult() {
+        return includeReasoningResult;
+    }
+
     /**
      * Check if a specific event type should be streamed.
      *
@@ -114,11 +165,28 @@ public boolean shouldStream(EventType type) {
         return eventTypes.contains(EventType.ALL) || eventTypes.contains(type);
     }
 
+    /**
+     * Convenience method for stream implementations to decide whether to emit a reasoning subtype.
+     *
+     * <p><b>TODO (Issue #265):</b> Thread these flags through the stream event mapping layer where
+     * reasoning events are converted into Flux emissions (e.g., when distinguishing chunk vs result).
+     *
+     * @param isChunk true if the reasoning emission is an incremental chunk, false if it is the final result
+     * @return true if this reasoning emission should be included
+     */
+    public boolean shouldIncludeReasoningEmission(boolean isChunk) {
+        return isChunk ? includeReasoningChunk : includeReasoningResult;
+    }
+
     /** Builder for {@link StreamOptions}. */
     public static class Builder {
         private Set<EventType> eventTypes = EnumSet.of(EventType.ALL);
         private boolean incremental = true;
 
+        // Defaults are "true" to preserve existing behavior.
+        private boolean includeReasoningChunk = true;
+        private boolean includeReasoningResult = true;
+
         /**
          * Set which event types to stream.
          *
@@ -150,6 +218,34 @@ public Builder incremental(boolean incremental) {
             return this;
         }
 
+        /**
+         * Include or exclude incremental reasoning chunk emissions.
+         *
+         * <p>When {@link EventType#REASONING} is enabled, some providers emit reasoning deltas (chunks)
+         * as the model thinks. Set to false to hide these.</p>
+         *
+         * @param includeReasoningChunk true to include chunk emissions, false to filter them out
+         * @return this builder
+         */
+        public Builder includeReasoningChunk(boolean includeReasoningChunk) {
+            this.includeReasoningChunk = includeReasoningChunk;
+            return this;
+        }
+
+        /**
+         * Include or exclude the final consolidated reasoning result emission.
+         *
+         * <p>When {@link EventType#REASONING} is enabled, some providers emit a final reasoning result.
+         * Set to false to hide it.</p>
+         *
+         * @param includeReasoningResult true to include the final reasoning result, false to filter it out
+         * @return this builder
+         */
+        public Builder includeReasoningResult(boolean includeReasoningResult) {
+            this.includeReasoningResult = includeReasoningResult;
+            return this;
+        }
+
         public StreamOptions build() {
             return new StreamOptions(this);
         }

agentscope-core/src/test/java/io/agentscope/core/agent/StreamOptionsTest.java

@@ -21,16 +21,14 @@
 
 import org.junit.jupiter.api.Test;
 
-/**
- * Tests for {@link StreamOptions}.
- */
+/** Tests for {@link StreamOptions}. */
 class StreamOptionsTest {
 
     @Test
     void testDefaults() {
         StreamOptions options = StreamOptions.defaults();
 
-        // Default should include all event types except AGENT_RESULT
+        // Default should include ALL event types (based on current StreamOptions implementation)
         assertTrue(options.shouldStream(EventType.REASONING));
         assertTrue(options.shouldStream(EventType.TOOL_RESULT));
         assertTrue(options.shouldStream(EventType.HINT));
@@ -39,6 +37,14 @@ void testDefaults() {
 
         // Default should be incremental mode
         assertTrue(options.isIncremental());
+
+        // Default should include both reasoning chunk and reasoning result
+        assertTrue(options.isIncludeReasoningChunk());
+        assertTrue(options.isIncludeReasoningResult());
+
+        // Convenience helper should respect defaults
+        assertTrue(options.shouldIncludeReasoningEmission(true)); // chunk
+        assertTrue(options.shouldIncludeReasoningEmission(false)); // result
     }
 
     @Test
@@ -50,6 +56,7 @@ void testBuilderEventTypes() {
         assertFalse(options.shouldStream(EventType.TOOL_RESULT));
         assertFalse(options.shouldStream(EventType.HINT));
         assertFalse(options.shouldStream(EventType.SUMMARY));
+        assertFalse(options.shouldStream(EventType.AGENT_RESULT));
     }
 
     @Test
@@ -64,6 +71,7 @@ void testBuilderMultipleEventTypes() {
         assertTrue(options.shouldStream(EventType.TOOL_RESULT));
         assertFalse(options.shouldStream(EventType.HINT));
         assertFalse(options.shouldStream(EventType.SUMMARY));
+        assertFalse(options.shouldStream(EventType.AGENT_RESULT));
     }
 
     @Test
@@ -89,13 +97,6 @@ void testBuilderIncrementalMode() {
         assertFalse(cumulativeOptions.isIncremental());
     }
 
-    @Test
-    void testAgentResultRequiresExplicitOptIn() {
-        // Even with ALL event types, AGENT_RESULT is not included by default
-        StreamOptions options = StreamOptions.builder().eventTypes(EventType.ALL).build();
-        assertTrue(options.shouldStream(EventType.AGENT_RESULT));
-    }
-
     @Test
     void testGetEventTypes() {
         StreamOptions options =
@@ -137,4 +138,63 @@ void testFilteringByEventType() {
         assertFalse(reasoningOnly.shouldStream(EventType.SUMMARY));
         assertFalse(reasoningOnly.shouldStream(EventType.AGENT_RESULT));
     }
+
+    @Test
+    void testReasoningChunkAndResultFlags_DefaultsTrue() {
+        StreamOptions options = StreamOptions.builder().eventTypes(EventType.REASONING).build();
+
+        assertTrue(options.isIncludeReasoningChunk());
+        assertTrue(options.isIncludeReasoningResult());
+
+        assertTrue(options.shouldIncludeReasoningEmission(true)); // chunk
+        assertTrue(options.shouldIncludeReasoningEmission(false)); // result
+    }
+
+    @Test
+    void testReasoningChunkDisabled_ResultEnabled() {
+        StreamOptions options =
+                StreamOptions.builder()
+                        .eventTypes(EventType.REASONING)
+                        .includeReasoningChunk(false)
+                        .includeReasoningResult(true)
+                        .build();
+
+        assertFalse(options.isIncludeReasoningChunk());
+        assertTrue(options.isIncludeReasoningResult());
+
+        assertFalse(options.shouldIncludeReasoningEmission(true)); // chunk filtered
+        assertTrue(options.shouldIncludeReasoningEmission(false)); // result allowed
+    }
+
+    @Test
+    void testReasoningChunkEnabled_ResultDisabled() {
+        StreamOptions options =
+                StreamOptions.builder()
+                        .eventTypes(EventType.REASONING)
+                        .includeReasoningChunk(true)
+                        .includeReasoningResult(false)
+                        .build();
+
+        assertTrue(options.isIncludeReasoningChunk());
+        assertFalse(options.isIncludeReasoningResult());
+
+        assertTrue(options.shouldIncludeReasoningEmission(true)); // chunk allowed
+        assertFalse(options.shouldIncludeReasoningEmission(false)); // result filtered
+    }
+
+    @Test
+    void testReasoningChunkAndResultBothDisabled() {
+        StreamOptions options =
+                StreamOptions.builder()
+                        .eventTypes(EventType.REASONING)
+                        .includeReasoningChunk(false)
+                        .includeReasoningResult(false)
+                        .build();
+
+        assertFalse(options.isIncludeReasoningChunk());
+        assertFalse(options.isIncludeReasoningResult());
+
+        assertFalse(options.shouldIncludeReasoningEmission(true)); // chunk filtered
+        assertFalse(options.shouldIncludeReasoningEmission(false)); // result filtered
+    }
 }