@jsonstudio/llms 0.4.2

package/dist/sse/types/responses-types.js

@@ -0,0 +1,38 @@
+/**
+ * Responses协议相关类型定义
+ * 支持OpenAI Responses API的JSON↔SSE双向转换
+ */
+// 重新导出基础事件类型
+export * from './sse-events.js';
+// Responses转换错误代码
+export const RESPONSES_CONVERSION_ERROR_CODES = {
+    TIMEOUT: 'RESPONSES_TIMEOUT',
+    INVALID_EVENT: 'RESPONSES_INVALID_EVENT',
+    SEQUENCE_ERROR: 'RESPONSES_SEQUENCE_ERROR',
+    OUTPUT_ITEM_ERROR: 'RESPONSES_OUTPUT_ITEM_ERROR',
+    CONTENT_PART_ERROR: 'RESPONSES_CONTENT_PART_ERROR',
+    PARSE_ERROR: 'RESPONSES_PARSE_ERROR',
+    VALIDATION_ERROR: 'RESPONSES_VALIDATION_ERROR',
+    STREAM_ERROR: 'RESPONSES_STREAM_ERROR'
+};
+// 默认Responses转换配置
+export const DEFAULT_RESPONSES_CONVERSION_CONFIG = {
+    defaultTimeoutMs: 30000,
+    heartbeatIntervalMs: 15000,
+    eventTimeoutMs: 5000,
+    defaultChunkSize: 12,
+    defaultDelayMs: 8,
+    reasoningChunkSize: 24,
+    textChunkSize: 12,
+    functionCallChunkSize: 24,
+    enableEventValidation: true,
+    enableSequenceValidation: true,
+    strictMode: false,
+    validateOutputItems: true,
+    maxConcurrentOutputItems: 10,
+    maxConcurrentContentParts: 50,
+    eventBufferSize: 1000,
+    debugMode: false,
+    logLevel: 'info',
+    enableMetrics: true
+};

package/dist/sse/types/sse-events.d.ts

@@ -0,0 +1,180 @@
+/**
+ * SSE事件类型定义
+ * 基于OpenAI Responses协议的事件规范
+ */
+export type SseEventType = 'response.created' | 'response.in_progress' | 'response.completed' | 'response.required_action' | 'response.done' | 'response.output_item.added' | 'response.output_item.done' | 'response.content_part.added' | 'response.content_part.done' | 'response.output_text.delta' | 'response.output_text.done' | 'response.reasoning_text.delta' | 'response.reasoning_text.done' | 'response.function_call_arguments.delta' | 'response.function_call_arguments.done';
+export interface BaseSseEvent {
+    type: SseEventType;
+    timestamp?: string;
+    sequence_number: number;
+}
+export interface ResponseCreatedEvent extends BaseSseEvent {
+    type: 'response.created';
+    response: {
+        id: string;
+        object: 'response';
+        created_at: number;
+        status: 'in_progress';
+        model: string;
+        output: OutputItem[];
+        previous_response_id: string | null;
+    };
+}
+export interface ResponseInProgressEvent extends BaseSseEvent {
+    type: 'response.in_progress';
+    response: ResponseObject;
+}
+export interface ResponseCompletedEvent extends BaseSseEvent {
+    type: 'response.completed';
+    response: ResponseObject;
+}
+export interface ResponseRequiredActionEvent extends BaseSseEvent {
+    type: 'response.required_action';
+    response: ResponseObject;
+    required_action: RequiredAction;
+}
+export interface ResponseDoneEvent extends BaseSseEvent {
+    type: 'response.done';
+}
+export interface OutputItemAddedEvent extends BaseSseEvent {
+    type: 'response.output_item.added';
+    output_index: number;
+    item: OutputItem;
+}
+export interface OutputItemDoneEvent extends BaseSseEvent {
+    type: 'response.output_item.done';
+    output_index: number;
+    item: OutputItem;
+}
+export interface ContentPartAddedEvent extends BaseSseEvent {
+    type: 'response.content_part.added';
+    item_id: string;
+    output_index: number;
+    content_index: number;
+    part: ContentPart;
+}
+export interface ContentPartDoneEvent extends BaseSseEvent {
+    type: 'response.content_part.done';
+    item_id: string;
+    output_index: number;
+    content_index: number;
+    part: ContentPart;
+}
+export interface OutputTextDeltaEvent extends BaseSseEvent {
+    type: 'response.output_text.delta';
+    item_id: string;
+    output_index: number;
+    content_index: number;
+    delta: string;
+    logprobs?: any[];
+}
+export interface OutputTextDoneEvent extends BaseSseEvent {
+    type: 'response.output_text.done';
+    item_id: string;
+    output_index: number;
+    content_index: number;
+}
+export interface ReasoningTextDeltaEvent extends BaseSseEvent {
+    type: 'response.reasoning_text.delta';
+    item_id: string;
+    output_index: number;
+    content_index: number;
+    delta: string;
+}
+export interface ReasoningTextDoneEvent extends BaseSseEvent {
+    type: 'response.reasoning_text.done';
+    item_id: string;
+    output_index: number;
+    content_index: number;
+    text: string;
+}
+export interface FunctionCallArgumentsDeltaEvent extends BaseSseEvent {
+    type: 'response.function_call_arguments.delta';
+    item_id: string;
+    output_index: number;
+    delta: string;
+}
+export interface FunctionCallArgumentsDoneEvent extends BaseSseEvent {
+    type: 'response.function_call_arguments.done';
+    item_id: string;
+    output_index: number;
+    arguments: string;
+}
+export type SseEvent = ResponseCreatedEvent | ResponseInProgressEvent | ResponseCompletedEvent | ResponseRequiredActionEvent | ResponseDoneEvent | OutputItemAddedEvent | OutputItemDoneEvent | ContentPartAddedEvent | ContentPartDoneEvent | OutputTextDeltaEvent | OutputTextDoneEvent | ReasoningTextDeltaEvent | ReasoningTextDoneEvent | FunctionCallArgumentsDeltaEvent | FunctionCallArgumentsDoneEvent;
+export interface ResponseObject {
+    id: string;
+    object: 'response';
+    created_at: number;
+    status: 'in_progress' | 'requires_action' | 'completed';
+    model: string;
+    output: OutputItem[];
+    usage?: UsageInfo;
+    previous_response_id: string | null;
+    required_action?: RequiredAction;
+    output_text?: string;
+}
+export interface OutputItem {
+    id: string;
+    type: 'reasoning' | 'message' | 'function_call' | 'system_message';
+    status?: 'in_progress' | 'completed';
+    content?: ContentPart[];
+    summary?: any[];
+    role?: string;
+    arguments?: string;
+    call_id?: string;
+    name?: string;
+    message?: MessageContent;
+}
+export interface ContentPart {
+    type: 'reasoning_text' | 'output_text' | 'input_text' | 'commentary';
+    text: string;
+}
+export interface MessageContent {
+    id?: string;
+    role: string;
+    status?: string;
+    content: ContentPart[];
+}
+export interface UsageInfo {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    output_tokens_details?: {
+        reasoning_tokens: number;
+    };
+}
+export interface RequiredAction {
+    type: 'submit_tool_outputs';
+    submit_tool_outputs: {
+        tool_calls: ToolCall[];
+    };
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface SseEventStats {
+    totalEvents: number;
+    eventTypes: Record<SseEventType, number>;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    outputItemsCount: number;
+    contentPartsCount: number;
+    deltaEventsCount: number;
+}
+export interface EventValidationRule {
+    type: SseEventType;
+    requiredFields: string[];
+    optionalFields: string[];
+    dependencies: Array<{
+        field: string;
+        condition: (event: any) => boolean;
+        requiredFields: string[];
+    }>;
+}
+export declare const SSE_EVENT_VALIDATION_RULES: Record<SseEventType, EventValidationRule>;

package/dist/sse/types/sse-events.js

@@ -0,0 +1,150 @@
+/**
+ * SSE事件类型定义
+ * 基于OpenAI Responses协议的事件规范
+ */
+// 预定义的验证规则
+export const SSE_EVENT_VALIDATION_RULES = {
+    'response.created': {
+        type: 'response.created',
+        requiredFields: ['type', 'response'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: [
+            {
+                field: 'response',
+                condition: (e) => !!e.response,
+                requiredFields: ['id', 'object', 'created_at', 'status', 'model', 'output', 'previous_response_id']
+            }
+        ]
+    },
+    'response.in_progress': {
+        type: 'response.in_progress',
+        requiredFields: ['type', 'response'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: [
+            {
+                field: 'response',
+                condition: (e) => !!e.response,
+                requiredFields: ['id', 'object', 'created_at', 'status', 'model']
+            }
+        ]
+    },
+    'response.completed': {
+        type: 'response.completed',
+        requiredFields: ['type', 'response'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: [
+            {
+                field: 'response',
+                condition: (e) => !!e.response,
+                requiredFields: ['id', 'object', 'created_at', 'status', 'model', 'output', 'usage']
+            }
+        ]
+    },
+    'response.required_action': {
+        type: 'response.required_action',
+        requiredFields: ['type', 'response', 'required_action'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: [
+            {
+                field: 'response',
+                condition: (e) => !!e.response,
+                requiredFields: ['id', 'object', 'created_at', 'status', 'model']
+            },
+            {
+                field: 'required_action',
+                condition: (e) => !!e.required_action,
+                requiredFields: ['type', 'submit_tool_outputs']
+            }
+        ]
+    },
+    'response.done': {
+        type: 'response.done',
+        requiredFields: ['type'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: []
+    },
+    'response.output_item.added': {
+        type: 'response.output_item.added',
+        requiredFields: ['type', 'output_index', 'item'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: [
+            {
+                field: 'item',
+                condition: (e) => !!e.item,
+                requiredFields: ['id', 'type']
+            }
+        ]
+    },
+    'response.output_item.done': {
+        type: 'response.output_item.done',
+        requiredFields: ['type', 'output_index', 'item'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: [
+            {
+                field: 'item',
+                condition: (e) => !!e.item,
+                requiredFields: ['id', 'type']
+            }
+        ]
+    },
+    'response.content_part.added': {
+        type: 'response.content_part.added',
+        requiredFields: ['type', 'item_id', 'output_index', 'content_index', 'part'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: [
+            {
+                field: 'part',
+                condition: (e) => !!e.part,
+                requiredFields: ['type', 'text']
+            }
+        ]
+    },
+    'response.content_part.done': {
+        type: 'response.content_part.done',
+        requiredFields: ['type', 'item_id', 'output_index', 'content_index', 'part'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: [
+            {
+                field: 'part',
+                condition: (e) => !!e.part,
+                requiredFields: ['type', 'text']
+            }
+        ]
+    },
+    'response.output_text.delta': {
+        type: 'response.output_text.delta',
+        requiredFields: ['type', 'item_id', 'output_index', 'content_index', 'delta'],
+        optionalFields: ['timestamp', 'sequence_number', 'logprobs'],
+        dependencies: []
+    },
+    'response.output_text.done': {
+        type: 'response.output_text.done',
+        requiredFields: ['type', 'item_id', 'output_index', 'content_index'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: []
+    },
+    'response.reasoning_text.delta': {
+        type: 'response.reasoning_text.delta',
+        requiredFields: ['type', 'item_id', 'output_index', 'content_index', 'delta'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: []
+    },
+    'response.reasoning_text.done': {
+        type: 'response.reasoning_text.done',
+        requiredFields: ['type', 'item_id', 'output_index', 'content_index', 'text'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: []
+    },
+    'response.function_call_arguments.delta': {
+        type: 'response.function_call_arguments.delta',
+        requiredFields: ['type', 'item_id', 'output_index', 'delta'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: []
+    },
+    'response.function_call_arguments.done': {
+        type: 'response.function_call_arguments.done',
+        requiredFields: ['type', 'item_id', 'output_index', 'arguments'],
+        optionalFields: ['timestamp', 'sequence_number'],
+        dependencies: []
+    }
+};

package/dist/sse/types/stream-state.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 流状态管理类型定义
+ * 管理JSON↔SSE双向转换过程中的流状态
+ */
+import { SseEvent, SseEventType } from './sse-events.js';
+export declare enum StreamState {
+    IDLE = "idle",
+    STARTING = "starting",
+    ACTIVE = "active",
+    PAUSED = "paused",
+    COMPLETING = "completing",
+    COMPLETED = "completed",
+    ERROR = "error",
+    TIMEOUT = "timeout",
+    ABORTED = "aborted"
+}
+export declare enum StreamDirection {
+    JSON_TO_SSE = "json_to_sse",
+    SSE_TO_JSON = "sse_to_json"
+}
+export interface BaseStreamState {
+    direction: StreamDirection;
+    requestId: string;
+    model: string;
+    status: StreamState;
+    startTime: number;
+    endTime?: number;
+    lastActivityTime: number;
+    totalEventsProcessed: number;
+    bytesProcessed: number;
+    errorCount: number;
+    timeoutCount: number;
+}
+export interface JsonToSseStreamState extends BaseStreamState {
+    direction: StreamDirection.JSON_TO_SSE;
+    inputJson: any;
+    options: any;
+    currentOutputIndex: number;
+    currentSequenceNumber: number;
+    outputItemsGenerated: number;
+    contentPartsGenerated: number;
+    deltaEventsGenerated: number;
+    isHeartbeatActive: boolean;
+    lastHeartbeatTime?: number;
+    chunksRemaining?: number;
+    estimatedTotalEvents?: number;
+}
+export interface SseToJsonStreamState extends BaseStreamState {
+    direction: StreamDirection.SSE_TO_JSON;
+    options: any;
+    expectedEventTypes: Set<SseEventType>;
+    receivedEventTypes: Set<SseEventType>;
+    lastSequenceNumber: number;
+    expectedSequenceNumbers: Set<number>;
+    missingSequenceNumbers: Set<number>;
+    isResponseCreated: boolean;
+    isResponseCompleted: boolean;
+    isRequiredActionReceived: boolean;
+    aggregatedEvents: SseEvent[];
+    partialJson: any;
+}
+export interface StreamStatistics {
+    duration: number;
+    eventsPerSecond: number;
+    bytesPerSecond: number;
+    eventTypeCounts: Record<SseEventType, number>;
+    totalDeltaEvents: number;
+    totalItemEvents: number;
+    totalResponseEvents: number;
+    errorRate: number;
+    timeoutRate: number;
+    sequenceErrorCount: number;
+    averageEventProcessingTime: number;
+    maxEventProcessingTime: number;
+    minEventProcessingTime: number;
+    memoryUsage: number;
+    cpuUsage: number;
+    bufferUtilization: number;
+}
+export interface StreamMetrics {
+    eventTimestamps: Array<{
+        eventType: SseEventType;
+        timestamp: number;
+        sequenceNumber: number;
+    }>;
+    sequenceGaps: Array<{
+        start: number;
+        end: number;
+        size: number;
+    }>;
+    backpressureEvents: number;
+    maxBufferSize: number;
+    averageBufferSize: number;
+    retryAttempts: number;
+    successfulRetries: number;
+    timeoutEvents: Array<{
+        eventType?: SseEventType;
+        timeoutDuration: number;
+        timestamp: number;
+    }>;
+}
+export interface StreamConfig {
+    idleTimeoutMs: number;
+    totalTimeoutMs: number;
+    heartbeatTimeoutMs: number;
+    maxBufferSize: number;
+    highWaterMark: number;
+    lowWaterMark: number;
+    enableBackpressure: boolean;
+    backpressureThreshold: number;
+    backpressureStrategy: 'drop' | 'buffer' | 'error';
+    maxRetries: number;
+    retryDelayMs: number;
+    retryBackoffMultiplier: number;
+    enableMetrics: boolean;
+    metricsIntervalMs: number;
+    enableDetailedLogging: boolean;
+    maxConcurrentEvents: number;
+    eventProcessingTimeoutMs: number;
+    gcThreshold: number;
+}
+export declare const DEFAULT_STREAM_CONFIG: StreamConfig;
+export interface StreamEvent {
+    type: 'state_change' | 'error' | 'timeout' | 'metrics' | 'heartbeat' | 'completion';
+    timestamp: number;
+    requestId: string;
+    data: any;
+}
+export interface StateChangeEvent extends StreamEvent {
+    type: 'state_change';
+    data: {
+        oldState: StreamState;
+        newState: StreamState;
+        reason?: string;
+    };
+}
+export interface StreamErrorEvent extends StreamEvent {
+    type: 'error';
+    data: {
+        error: Error;
+        eventType?: SseEventType;
+        sequenceNumber?: number;
+        recoverable: boolean;
+    };
+}
+export interface StreamTimeoutEvent extends StreamEvent {
+    type: 'timeout';
+    data: {
+        timeoutType: 'idle' | 'total' | 'heartbeat' | 'event_processing';
+        timeoutDuration: number;
+        lastActivityTime: number;
+    };
+}
+export interface StreamMetricsEvent extends StreamEvent {
+    type: 'metrics';
+    data: StreamStatistics;
+}
+export interface StreamHeartbeatEvent extends StreamEvent {
+    type: 'heartbeat';
+    data: {
+        interval: number;
+        eventsSinceLastHeartbeat: number;
+    };
+}
+export interface StreamCompletionEvent extends StreamEvent {
+    type: 'completion';
+    data: {
+        finalState: StreamState;
+        totalEvents: number;
+        totalDuration: number;
+        success: boolean;
+    };
+}
+export type StreamEventData = StateChangeEvent | StreamErrorEvent | StreamTimeoutEvent | StreamMetricsEvent | StreamHeartbeatEvent | StreamCompletionEvent;
+export interface StreamStateListener {
+    onStateChange(event: StateChangeEvent): void;
+    onError(event: StreamErrorEvent): void;
+    onTimeout(event: StreamTimeoutEvent): void;
+    onMetrics(event: StreamMetricsEvent): void;
+    onHeartbeat(event: StreamHeartbeatEvent): void;
+    onCompletion(event: StreamCompletionEvent): void;
+}
+export interface StreamStateManager {
+    getCurrentState(): StreamState;
+    setState(newState: StreamState, reason?: string): void;
+    transitionTo(newState: StreamState, condition?: () => boolean): boolean;
+    updateActivity(): void;
+    isIdle(): boolean;
+    isCompleted(): boolean;
+    isError(): boolean;
+    processEvent(event: SseEvent): void;
+    incrementEventCount(): void;
+    incrementErrorCount(): void;
+    getStatistics(): StreamStatistics;
+    getMetrics(): StreamMetrics;
+    addListener(listener: StreamStateListener): void;
+    removeListener(listener: StreamStateListener): void;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    complete(): void;
+    abort(error?: Error): void;
+    reset(): void;
+}

package/dist/sse/types/stream-state.js

@@ -0,0 +1,44 @@
+/**
+ * 流状态管理类型定义
+ * 管理JSON↔SSE双向转换过程中的流状态
+ */
+// 流状态枚举
+export var StreamState;
+(function (StreamState) {
+    StreamState["IDLE"] = "idle";
+    StreamState["STARTING"] = "starting";
+    StreamState["ACTIVE"] = "active";
+    StreamState["PAUSED"] = "paused";
+    StreamState["COMPLETING"] = "completing";
+    StreamState["COMPLETED"] = "completed";
+    StreamState["ERROR"] = "error";
+    StreamState["TIMEOUT"] = "timeout";
+    StreamState["ABORTED"] = "aborted";
+})(StreamState || (StreamState = {}));
+// 流方向
+export var StreamDirection;
+(function (StreamDirection) {
+    StreamDirection["JSON_TO_SSE"] = "json_to_sse";
+    StreamDirection["SSE_TO_JSON"] = "sse_to_json";
+})(StreamDirection || (StreamDirection = {}));
+// 默认流配置
+export const DEFAULT_STREAM_CONFIG = {
+    idleTimeoutMs: 30000,
+    totalTimeoutMs: 300000, // 5分钟
+    heartbeatTimeoutMs: 60000,
+    maxBufferSize: 10000,
+    highWaterMark: 8000,
+    lowWaterMark: 2000,
+    enableBackpressure: true,
+    backpressureThreshold: 0.8,
+    backpressureStrategy: 'buffer',
+    maxRetries: 3,
+    retryDelayMs: 1000,
+    retryBackoffMultiplier: 2,
+    enableMetrics: true,
+    metricsIntervalMs: 5000,
+    enableDetailedLogging: false,
+    maxConcurrentEvents: 50,
+    eventProcessingTimeoutMs: 5000,
+    gcThreshold: 1000
+};