feat(stream): Refactored typing, removed unecessary method, improved docstring, added tests.

Author: Murike

src/types/base.types.ts

@@ -0,0 +1,22 @@
+/**
+ * JSON-serializable value type.
+ * Represents any value that can be serialized to JSON.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * JSON-serializable object type.
+ * Allows undefined values which will be omitted during JSON serialization.
+ */
+export type JsonObject = { [key: string]: JsonValue | undefined };
+
+/**
+ * JSON-serializable array type.
+ */
+export type JsonArray = JsonValue[];

src/types/logging/logger.types.ts

@@ -9,16 +9,15 @@ import type {
   ToolSpan,
   WorkflowSpan,
   AgentSpan,
-  Event,
-  JsonObject
+  Event
 } from './span.types';
 import type {
   LlmSpanAllowedInputType,
   LlmSpanAllowedOutputType,
   RetrieverSpanAllowedOutputType
 } from './step.types';
 import type { AgentType, Payload, ProtectResponse } from '../new-api.types';
-
+import type { JsonObject } from '../base.types';
 export interface GalileoLoggerConfig {
   projectName?: string;
   logStreamName?: string;
@@ -434,8 +433,7 @@ export interface IGalileoLoggerBatch {
  * This is the main interface that the GalileoLogger class implements.
  */
 export interface IGalileoLogger
-  extends
-    IGalileoLoggerCore,
+  extends IGalileoLoggerCore,
     IGalileoLoggerSession,
     IGalileoLoggerTrace,
     IGalileoLoggerSpan,

src/types/logging/span.types.ts

@@ -20,29 +20,7 @@ import {
 import type { Document } from '../document.types';
 import type { MetricValueType } from '../metrics.types';
 import { AgentType } from '../new-api.types';
-
-/**
- * JSON-serializable value type.
- * Represents any value that can be serialized to JSON.
- */
-export type JsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonValue[]
-  | { [key: string]: JsonValue };
-
-/**
- * JSON-serializable object type.
- * Allows undefined values which will be omitted during JSON serialization.
- */
-export type JsonObject = { [key: string]: JsonValue | undefined };
-
-/**
- * JSON-serializable array type.
- */
-export type JsonArray = JsonValue[];
+import type { JsonValue, JsonObject, JsonArray } from '../base.types';
 
 /**
  * Types of events that can appear in reasoning/multi-turn model outputs.
@@ -376,10 +354,8 @@ export interface RetrieverSpanOptions extends BaseSpanOptions {
   redactedOutput?: RetrieverSpanAllowedOutputType;
 }
 
-export interface SerializedRetrieverSpan extends Omit<
-  SerializedStep,
-  'output'
-> {
+export interface SerializedRetrieverSpan
+  extends Omit<SerializedStep, 'output'> {
   output: JsonArray;
 }
 
@@ -408,10 +384,11 @@ export class RetrieverSpan extends BaseStep {
   }
 }
 
-export interface ToolSpanOptions extends Omit<
-  BaseSpanOptions,
-  'input' | 'redactedInput' | 'output' | 'redactedOutput'
-> {
+export interface ToolSpanOptions
+  extends Omit<
+    BaseSpanOptions,
+    'input' | 'redactedInput' | 'output' | 'redactedOutput'
+  > {
   input: JsonValue;
   redactedInput?: JsonValue;
   output?: JsonValue;

src/types/logging/step.types.ts

@@ -3,7 +3,7 @@ import type { components } from '../api.types';
 import { Document } from '../document.types';
 import { isMessage, type Message } from '../message.types';
 import type { MetricValueType } from '../metrics.types';
-import type { JsonArray } from './span.types';
+import type { JsonArray } from '../base.types';
 
 export type StepAllowedInputType =
   | string
@@ -111,10 +111,11 @@ export interface BaseStepOptions {
   id?: string;
 }
 
-export interface SerializedStep extends Omit<
-  BaseStepOptions,
-  'metrics' | 'createdAt' | 'output' | 'redactedOutput'
-> {
+export interface SerializedStep
+  extends Omit<
+    BaseStepOptions,
+    'metrics' | 'createdAt' | 'output' | 'redactedOutput'
+  > {
   metrics?: SerializedMetrics;
   type: StepType;
   createdAt: string;

src/utils/galileo-logger.ts

@@ -10,9 +10,9 @@ import {
   type Span,
   StepWithChildSpans,
   ToolSpan,
-  WorkflowSpan,
-  type JsonObject
+  WorkflowSpan
 } from '../types/logging/span.types';
+import type { JsonObject } from '../types/base.types';
 import { type SpanSchema, Trace } from '../types/logging/trace.types';
 import {
   type RetrieverSpanAllowedOutputType,
@@ -126,6 +126,8 @@ class GalileoLogger implements IGalileoLogger {
       if (config.spanId) {
         await logger.initSpan(config.spanId);
       }
+    } else if (config.traceId || config.spanId) {
+      throw new Error('traceId and spanId can only be used in streaming mode.');
     }
 
     return logger;
@@ -1207,6 +1209,13 @@ class GalileoLogger implements IGalileoLogger {
    */
   async flush(): Promise<Trace[]> {
     try {
+      if (this.mode === 'streaming') {
+        console.warn(
+          'Flushing in streaming mode is not supported. Traces are automatically ingested as they are created.'
+        );
+        return [];
+      }
+
       if (!this.traces.length) {
         console.warn('No traces to flush.');
         return [];

src/utils/streaming/base-streaming-adapter.ts

@@ -10,6 +10,7 @@ import {
   LlmSpanAllowedInputType,
   LlmSpanAllowedOutputType
 } from '../../types/logging/step.types';
+import { JsonObject } from '../../types/base.types';
 
 /**
  * Tool definition type (matches LlmSpan tools type)
@@ -26,7 +27,7 @@ export interface BaseStreamingAdapterConfig {
     model?: string;
     metadata?: Record<string, string>;
     name?: string;
-    tools?: ToolDefinition[];
+    tools?: JsonObject[];
     temperature?: number;
   };
   shouldCompleteTrace: boolean;
@@ -107,15 +108,6 @@ export abstract class BaseStreamingAdapter {
     this.finalizer.finalize(output, statusCode);
   }
 
-  /**
-   * Update span incrementally during streaming (for real-time updates)
-   * Delegates to finalizer which uses mocked logger methods
-   * @param output Current output state (can be partial)
-   */
-  protected updateSpanIncremental(output: LlmSpanAllowedOutputType): void {
-    this.finalizer.updateSpanIncremental(output);
-  }
-
   /**
    * Get current metrics
    * @returns Complete metrics result

src/utils/streaming/finalizer.ts

@@ -4,9 +4,7 @@ import type {
   LlmSpanAllowedInputType,
   LlmSpanAllowedOutputType
 } from '../../types/logging/step.types';
-import type { Span } from '../../types/logging/span.types';
-import { Trace } from '../../types/logging/trace.types';
-import type { ToolDefinition } from './base-streaming-adapter';
+import type { JsonObject } from '../../types/base.types';
 
 /**
  * Configuration for streaming finalization
@@ -19,7 +17,7 @@ export interface StreamingFinalizerConfig {
     model?: string;
     metadata?: Record<string, string>;
     name?: string;
-    tools?: ToolDefinition[];
+    tools?: JsonObject[];
     temperature?: number;
   };
   shouldCompleteTrace: boolean;
@@ -82,32 +80,4 @@ export class StreamingFinalizer {
       });
     }
   }
-
-  /**
-   * Update span incrementally during streaming (for real-time updates)
-   * @param output Current output state (can be partial)
-   * @param spanId Optional span ID if available (currently unused, reserved for future use)
-   */
-  updateSpanIncremental(
-    output: LlmSpanAllowedOutputType,
-    spanId?: string
-  ): void {
-    void spanId;
-    // Get current parent span or trace
-    const currentParent = this.logger.currentParent();
-
-    if (!currentParent) {
-      // No active span/trace, skip incremental update
-      return;
-    }
-
-    // Call streaming update methods (mock implementations in GalileoLogger)
-    if (currentParent instanceof Trace) {
-      // Update trace with partial output during streaming
-      this.logger._updateTraceStreaming(currentParent, output, false);
-    } else {
-      // currentParent is a Span (WorkflowSpan, AgentSpan, LlmSpan, etc.)
-      this.logger._updateSpanStreaming(currentParent as Span, output);
-    }
-  }
 }

src/utils/task-handler.ts

@@ -171,6 +171,13 @@ export class TaskHandler {
     return newTask;
   }
 
+  /**
+   * Submits a task for execution with optional parent dependency tracking.
+   * @param taskId - The unique identifier for the task.
+   * @param asyncFn - The async function to execute. Use async/await syntax to ensure synchronous errors are converted to rejected promises.
+   * @param parentTaskId - (Optional) The ID of a parent task this task depends on. If provided, this task waits for parent completion.
+   * @returns A promise that resolves to the task result or rejects if the task or its parent fails.
+   */
   async submitTask<T>(
     taskId: string,
     asyncFn: () => Promise<T>,