@jsonstudio/llms 0.4.2

package/dist/sse/sse-to-json/responses-sse-to-json-converter.js

@@ -0,0 +1,270 @@
+/**
+ * Responses SSE → JSON转换器（重构版本）
+ * 使用函数化架构：解析 + 构建 + 验证分离
+ */
+import { Readable } from 'stream';
+import { ErrorUtils } from '../shared/utils.js';
+import { createSseParser } from './parsers/sse-parser.js';
+import { createResponseBuilder } from './builders/response-builder.js';
+/**
+ * 重构后的Responses SSE到JSON转换器
+ * 采用函数化架构，专注于编排而非具体业务逻辑
+ */
+export class ResponsesSseToJsonConverterRefactored {
+    config = {
+        timeoutMs: 30000,
+        enableEventValidation: true,
+        enableSequenceValidation: false,
+        strictMode: false,
+        validateOutputItems: true
+    };
+    contexts = new Map();
+    constructor(config) {
+        if (config) {
+            this.config = { ...this.config, ...config };
+        }
+    }
+    /**
+     * 将SSE流转换为Responses响应
+     */
+    async convertSseToJson(sseStream, options) {
+        // 1. 创建上下文
+        const context = this.createContext(options);
+        this.contexts.set(options.requestId, context);
+        try {
+            // 2. 创建解析器
+            const parser = createSseParser({
+                enableStrictValidation: this.config.enableEventValidation,
+                enableEventRecovery: !this.config.strictMode
+            });
+            // 3. 创建响应构建器
+            const responseBuilder = createResponseBuilder({
+                enableStrictValidation: false,
+                enableEventRecovery: !this.config.strictMode,
+                maxOutputItems: 50,
+                maxContentParts: 100
+            });
+            // 4. 创建可读流（适配不同的输入源）
+            const readableStream = this.createReadableStream(sseStream);
+            // 5. 流式处理SSE数据（按增量缓冲解析，避免跨 chunk 的事件被截断）
+            // 注意：不要对每个 chunk 独立 parse；必须使用一个持续的 async 解析器维持缓冲区。
+            async function* chunkStrings(stream) {
+                for await (const chunk of stream) {
+                    yield typeof chunk === 'string' ? chunk : chunk.toString();
+                }
+            }
+            for await (const parseResult of parser.parseStreamAsync(chunkStrings(readableStream))) {
+                if (context.isCompleted)
+                    break;
+                if (parseResult.success && parseResult.event) {
+                    const event = parseResult.event;
+                    // 验证序列号
+                    if (this.config.enableSequenceValidation && !this.validateSequenceNumber(event, context)) {
+                        throw new Error(`Invalid sequence number: ${event.sequenceNumber}`);
+                    }
+                    // 处理事件
+                    const success = responseBuilder.processEvent(event);
+                    if (!success && this.config.strictMode) {
+                        const result = responseBuilder.getResult();
+                        throw new Error(`Failed to process event: ${result.error?.message}`);
+                    }
+                    // 更新统计
+                    this.updateStats(context, event);
+                    // 回调
+                    if (options.onEvent) {
+                        options.onEvent(event);
+                    }
+                }
+                else if (!parseResult.success && this.config.strictMode) {
+                    throw new Error(`Failed to parse SSE event: ${parseResult.error}`);
+                }
+            }
+            // 6. 获取最终结果
+            const result = responseBuilder.getResult();
+            if (!result.success) {
+                // 容错：若已观察到 response.completed 事件或整体已完成，但构建器仍报告未完成，
+                // 这里按已完成处理，避免上游省略 response.done 导致误报失败。
+                const seenCompleted = context.eventStats.eventTypes['response.completed'] > 0;
+                if (seenCompleted) {
+                    const maybe = responseBuilder.getResult();
+                    if (maybe.success && maybe.response) {
+                        return maybe.response;
+                    }
+                }
+                throw result.error || new Error('Failed to build response');
+            }
+            // 7. 标记完成
+            context.isCompleted = true;
+            context.endTime = Date.now();
+            context.duration = context.endTime - context.startTime;
+            // 8. 调用完成回调
+            if (options.onCompletion) {
+                options.onCompletion(result.response);
+            }
+            return result.response;
+        }
+        catch (error) {
+            context.isCompleted = true;
+            context.endTime = Date.now();
+            context.duration = context.endTime - context.startTime;
+            // 调用错误回调
+            if (options.onError) {
+                options.onError(error);
+            }
+            throw this.wrapError('SSE_TO_JSON_ERROR', error, options.requestId);
+        }
+        finally {
+            // 清理上下文
+            this.clearContext(options.requestId);
+        }
+    }
+    /**
+     * 创建可读流
+     */
+    createReadableStream(sseStream) {
+        if (sseStream instanceof Readable) {
+            return sseStream;
+        }
+        // 如果是异步可迭代对象，包装为流
+        return Readable.from(this.convertAsyncIterableToStream(sseStream));
+    }
+    /**
+     * 将异步可迭代对象转换为流
+     */
+    async *convertAsyncIterableToStream(sseStream) {
+        for await (const chunk of sseStream) {
+            if (typeof chunk === 'string') {
+                yield Buffer.from(chunk);
+            }
+            else if (Buffer.isBuffer(chunk)) {
+                yield chunk;
+            }
+            else {
+                // 假设是SSE事件对象，序列化为SSE格式
+                const serialized = this.serializeEventToSSE(chunk);
+                yield Buffer.from(serialized);
+            }
+        }
+    }
+    /**
+     * 将事件对象序列化为SSE格式（简单实现）
+     */
+    serializeEventToSSE(event) {
+        const data = event.data ? JSON.stringify(event.data) : '';
+        return `event: ${event.type}\ndata: ${data}\n\n`;
+    }
+    /**
+     * 验证序列号
+     */
+    validateSequenceNumber(event, context) {
+        if (typeof event.sequenceNumber !== 'number') {
+            context.lastSequenceNumber += 1;
+            event.sequenceNumber = context.lastSequenceNumber;
+            return true;
+        }
+        if (event.sequenceNumber <= context.lastSequenceNumber) {
+            return false;
+        }
+        context.lastSequenceNumber = event.sequenceNumber;
+        return true;
+    }
+    /**
+     * 更新统计信息
+     */
+    updateStats(context, event) {
+        context.eventStats.totalEvents++;
+        context.eventStats.eventTypes[event.type] = (context.eventStats.eventTypes[event.type] || 0) + 1;
+        // 根据事件类型更新特定统计
+        switch (event.type) {
+            case 'response.created':
+            case 'response.in_progress':
+            case 'response.completed':
+            case 'response.required_action':
+            case 'response.done':
+                context.eventStats.messageEventsCount++;
+                break;
+            case 'response.output_item.added':
+            case 'response.output_item.done':
+                context.eventStats.outputItemsCount++;
+                break;
+            case 'response.content_part.added':
+            case 'response.content_part.done':
+                context.eventStats.contentPartsCount++;
+                break;
+            case 'response.output_text.delta':
+            case 'response.output_text.done':
+                context.eventStats.deltaEventsCount++;
+                break;
+            case 'response.reasoning_text.delta':
+            case 'response.reasoning_text.done':
+                context.eventStats.reasoningEventsCount++;
+                break;
+            case 'response.function_call_arguments.delta':
+            case 'response.function_call_arguments.done':
+                context.eventStats.functionCallEventsCount++;
+                break;
+            case 'response.error':
+                context.eventStats.errorCount++;
+                break;
+        }
+        // 更新时间戳
+        context.eventStats.lastEventTime = event.timestamp;
+    }
+    /**
+     * 包装错误
+     */
+    wrapError(code, originalError, requestId) {
+        return ErrorUtils.createError(`${code}: ${originalError.message}`, code, { requestId, originalError });
+    }
+    /**
+     * 创建上下文
+     */
+    createContext(options) {
+        const eventStats = {
+            totalEvents: 0,
+            eventTypes: {},
+            startTime: Date.now(),
+            outputItemsCount: 0,
+            contentPartsCount: 0,
+            deltaEventsCount: 0,
+            reasoningEventsCount: 0,
+            functionCallEventsCount: 0,
+            messageEventsCount: 0,
+            errorCount: 0
+        };
+        return {
+            requestId: options.requestId,
+            model: options.model,
+            options,
+            startTime: Date.now(),
+            aggregatedEvents: [],
+            currentResponse: {},
+            outputItemBuilders: new Map(),
+            eventStats,
+            isCompleted: false,
+            isResponseCreated: false,
+            isInProgress: false,
+            lastSequenceNumber: -1
+        };
+    }
+    /**
+     * 获取上下文
+     */
+    getContext(requestId) {
+        return this.contexts.get(requestId);
+    }
+    /**
+     * 清理上下文
+     */
+    clearContext(requestId) {
+        this.contexts.delete(requestId);
+    }
+    /**
+     * 获取所有活跃的上下文
+     */
+    getActiveContexts() {
+        return new Map(this.contexts);
+    }
+}
+// 为了向后兼容，导出原有名称
+export const ResponsesSseToJsonConverter = ResponsesSseToJsonConverterRefactored;

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

@@ -0,0 +1,87 @@
+/**
+ * Minimal Anthropic SSE/JSON types for v3 SSE converters
+ * Only covers text and basic tool_use blocks needed for roundtrip.
+ */
+export interface AnthropicContentTextBlock {
+    type: 'text';
+    text: string;
+}
+export interface AnthropicContentToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface AnthropicContentToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: unknown;
+    is_error?: boolean;
+}
+export type AnthropicContentBlock = AnthropicContentTextBlock | AnthropicContentToolUseBlock | AnthropicContentToolResultBlock;
+export interface AnthropicMessageResponse {
+    id: string;
+    type: 'message';
+    role: 'assistant' | 'user';
+    model: string;
+    content: AnthropicContentBlock[];
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+    stop_reason?: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use';
+}
+export type AnthropicSseEventType = 'message_start' | 'content_block_start' | 'content_block_delta' | 'content_block_stop' | 'message_delta' | 'message_stop';
+export interface AnthropicSseEventBase<T extends AnthropicSseEventType = AnthropicSseEventType> {
+    type: T;
+}
+export interface AnthropicSseEventMessageStart extends AnthropicSseEventBase<'message_start'> {
+    message: {
+        id: string;
+        type: 'message';
+        role: 'assistant';
+        model: string;
+    };
+}
+export interface AnthropicSseEventContentBlockStart extends AnthropicSseEventBase<'content_block_start'> {
+    index: number;
+    content_block: {
+        type: 'text';
+        text?: string;
+    } | {
+        type: 'tool_use';
+        id: string;
+        name: string;
+        input?: Record<string, unknown>;
+    };
+}
+export interface AnthropicSseEventContentBlockDelta extends AnthropicSseEventBase<'content_block_delta'> {
+    index: number;
+    delta: {
+        type: 'text_delta';
+        text: string;
+    } | {
+        type: 'input_json_delta';
+        partial_json: string;
+    };
+}
+export interface AnthropicSseEventContentBlockStop extends AnthropicSseEventBase<'content_block_stop'> {
+    index: number;
+}
+export interface AnthropicSseEventMessageDelta extends AnthropicSseEventBase<'message_delta'> {
+    delta?: {
+        stop_reason?: AnthropicMessageResponse['stop_reason'];
+    };
+}
+export interface AnthropicSseEventMessageStop extends AnthropicSseEventBase<'message_stop'> {
+}
+export type AnthropicSseEvent = AnthropicSseEventMessageStart | AnthropicSseEventContentBlockStart | AnthropicSseEventContentBlockDelta | AnthropicSseEventContentBlockStop | AnthropicSseEventMessageDelta | AnthropicSseEventMessageStop;
+export type AnthropicSseEventStream = AsyncIterable<string> | AsyncIterable<Buffer>;
+export interface AnthropicJsonToSseOptions {
+    requestId: string;
+    model: string;
+    chunkSize?: number;
+}
+export interface SseToAnthropicJsonOptions {
+    requestId: string;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Minimal Anthropic SSE/JSON types for v3 SSE converters
+ * Only covers text and basic tool_use blocks needed for roundtrip.
+ */
+export {};

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

@@ -0,0 +1,308 @@
+/**
+ * Chat协议相关类型定义
+ * 支持OpenAI Chat Completions的JSON↔SSE双向转换
+ */
+import { BaseSseEvent, StreamDirection } from './core-interfaces.js';
+export type ChatSseEventType = 'chat_chunk' | 'chat.done' | 'error' | 'ping';
+export interface ChatSseEvent extends BaseSseEvent {
+    /** 事件类型（SSE标准wire格式） */
+    event: ChatSseEventType;
+    /** 重写type字段以满足BaseSseEvent要求，与event保持一致 */
+    type: string;
+    /** 时间戳 */
+    timestamp: number;
+    /** 事件ID（SSE标准字段） */
+    id?: string;
+    /** 重试间隔（SSE标准字段） */
+    retry?: number;
+    /** 协议标识 */
+    protocol: 'chat';
+    /** 方向标识 */
+    direction: StreamDirection;
+}
+export interface ChatSseEventWithEventField {
+    id?: string;
+    event: ChatSseEventType;
+    data: string;
+    timestamp?: number;
+    retry?: number;
+    sequenceNumber?: number;
+}
+export interface ChatCompletionChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    system_fingerprint?: string;
+    choices: ChatChoiceChunk[];
+    usage?: ChatUsage;
+}
+export interface ChatChoiceChunk {
+    index: number;
+    delta: ChatDelta;
+    finish_reason?: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call' | null;
+    logprobs?: ChatLogProbs;
+}
+export interface ChatDelta {
+    role?: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string | null;
+    function_call?: ChatFunctionCall;
+    tool_calls?: ChatToolCallChunk[];
+}
+export interface ChatFunctionCall {
+    name?: string;
+    arguments?: string;
+}
+export interface ChatToolCallChunk {
+    index: number;
+    id?: string;
+    type?: 'function';
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+}
+export interface ChatLogProbs {
+    content?: ChatTokenLogProb[];
+}
+export interface ChatTokenLogProb {
+    token: string;
+    logprob: number;
+    bytes?: number[];
+    top_logprobs?: ChatTopLogProb[];
+}
+export interface ChatTopLogProb {
+    token: string;
+    logprob: number;
+    bytes?: number[];
+}
+export interface ChatUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export interface ChatCompletionRequest {
+    model: string;
+    messages: ChatMessage[];
+    functions?: ChatFunction[];
+    function_call?: 'auto' | 'none' | {
+        name: string;
+    };
+    tools?: ChatTool[];
+    tool_choice?: 'auto' | 'none' | 'required' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+    temperature?: number;
+    top_p?: number;
+    n?: number;
+    stream?: boolean;
+    stop?: string | string[] | null;
+    max_tokens?: number;
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    logit_bias?: Record<string, number>;
+    user?: string;
+    response_format?: {
+        type: 'text' | 'json_object';
+    };
+    seed?: number;
+}
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string | null;
+    name?: string;
+    function_call?: ChatFunctionCall;
+    tool_calls?: ChatToolCall[];
+    tool_call_id?: string;
+}
+export interface ChatFunction {
+    name: string;
+    description?: string;
+    parameters?: Record<string, any>;
+}
+export interface ChatTool {
+    type: 'function';
+    function: ChatFunction;
+}
+export interface ChatToolCall {
+    id: string;
+    type: 'function';
+    function: ChatFunctionCall;
+}
+export interface ChatCompletionResponse {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    system_fingerprint?: string;
+    choices: ChatChoice[];
+    usage?: ChatUsage;
+}
+export interface ChatChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call';
+    logprobs?: ChatLogProbs;
+}
+export interface ChatJsonToSseContext {
+    requestId: string;
+    model: string;
+    chatRequest: ChatCompletionRequest;
+    options: ChatJsonToSseOptions;
+    startTime: number;
+    sequenceCounter: number;
+    choiceIndexCounter: number;
+    toolCallIndexCounter: number;
+    isStreaming: boolean;
+    currentChunk: Partial<ChatCompletionChunk>;
+    eventStats: ChatEventStats;
+    contentIndexCounter?: Map<string, number>;
+    currentRequest?: any;
+    currentResponse?: any;
+    chatResponse?: ChatCompletionResponse;
+}
+export interface SseToChatJsonContext {
+    requestId: string;
+    model: string;
+    options: SseToChatJsonOptions;
+    startTime: number;
+    aggregatedChunks: ChatCompletionChunk[];
+    currentResponse: Partial<ChatCompletionResponse>;
+    choiceIndexMap: Map<number, ChatChoiceBuilder>;
+    toolCallIndexMap: Map<number, Map<number, ChatToolCallBuilder>>;
+    eventStats: ChatEventStats;
+    isCompleted: boolean;
+}
+export interface ChatChoiceBuilder {
+    index: number;
+    delta: ChatDelta;
+    finishReason?: ChatChoice['finish_reason'];
+    logprobs?: ChatLogProbs;
+    messageBuilder: ChatMessageBuilder;
+    isCompleted: boolean;
+    accumulatedContent: string;
+    toolCallBuilders: Map<number, ChatToolCallBuilder>;
+}
+export interface ChatMessageBuilder {
+    role?: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string;
+    name?: string;
+    functionCall?: ChatFunctionCall;
+    toolCalls?: ChatToolCall[];
+    toolCallId?: string;
+    isCompleted: boolean;
+}
+export interface ChatToolCallBuilder {
+    index: number;
+    id?: string;
+    type?: 'function';
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+    isCompleted: boolean;
+    accumulatedArguments: string;
+}
+export interface ChatJsonToSseOptions {
+    requestId: string;
+    model: string;
+    timeoutMs?: number;
+    enableHeartbeat?: boolean;
+    heartbeatIntervalMs?: number;
+    chunkDelayMs?: number;
+    includeSystemFingerprint?: boolean;
+    includeLogprobs?: boolean;
+    maxTokensPerChunk?: number;
+    validationMode?: 'none' | 'basic' | 'strict';
+    onChunk?: (chunk: ChatCompletionChunk) => void;
+    onError?: (error: Error) => void;
+    onComplete?: () => void;
+}
+export interface SseToChatJsonOptions {
+    requestId: string;
+    model: string;
+    timeoutMs?: number;
+    validateChunks?: boolean;
+    enableSequenceValidation?: boolean;
+    accumulateToolCalls?: boolean;
+    onPartialResponse?: (partial: Partial<ChatCompletionResponse>) => void;
+    onEvent?: (event: ChatSseEvent) => void;
+    onChunk?: (chunk: ChatCompletionChunk) => void;
+    onCompletion?: (final: ChatCompletionResponse) => void;
+    onError?: (error: Error) => void;
+    onTimeout?: () => void;
+}
+export interface ChatEventStats {
+    totalChunks: number;
+    totalTokens: number;
+    totalChoices: number;
+    totalToolCalls: number;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    tokenRate: number;
+    chunkRate: number;
+    errorCount: number;
+    retryCount: number;
+    totalEvents?: number;
+    eventTypes?: Record<string, number>;
+    lastEventTime?: number;
+}
+export interface ChatConversionError extends Error {
+    code: string;
+    requestId: string;
+    chunkId?: string;
+    choiceIndex?: number;
+    toolCallIndex?: number;
+    context?: any;
+}
+export declare const CHAT_CONVERSION_ERROR_CODES: {
+    readonly TIMEOUT: "CHAT_TIMEOUT";
+    readonly INVALID_CHUNK: "CHAT_INVALID_CHUNK";
+    readonly SEQUENCE_ERROR: "CHAT_SEQUENCE_ERROR";
+    readonly TOOL_CALL_ERROR: "CHAT_TOOL_CALL_ERROR";
+    readonly PARSE_ERROR: "CHAT_PARSE_ERROR";
+    readonly VALIDATION_ERROR: "CHAT_VALIDATION_ERROR";
+    readonly STREAM_ERROR: "CHAT_STREAM_ERROR";
+};
+export interface ChatEventValidationRule {
+    eventType: ChatSseEventType;
+    requiredFields: string[];
+    optionalFields: string[];
+    dataValidation?: {
+        schema?: any;
+        customValidator?: (data: any) => boolean;
+    };
+}
+export interface ChatConversionConfig {
+    defaultTimeoutMs: number;
+    heartbeatIntervalMs: number;
+    chunkTimeoutMs: number;
+    defaultChunkDelayMs: number;
+    maxTokensPerChunk: number;
+    maxChunkSize: number;
+    enableChunkValidation: boolean;
+    strictMode: boolean;
+    validateToolCalls: boolean;
+    maxConcurrentChoices: number;
+    maxConcurrentToolCalls: number;
+    eventBufferSize: number;
+    debugMode: boolean;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    enableMetrics: boolean;
+}
+export declare const DEFAULT_CHAT_CONVERSION_CONFIG: ChatConversionConfig;
+export interface ChatSseEventStream extends AsyncIterable<ChatSseEvent> {
+    getStats(): ChatEventStats;
+    getConfig(): ChatConversionConfig;
+    complete(): void;
+    abort(error?: Error): void;
+    on(event: 'error', handler: (error: Error) => void): this;
+    on(event: 'complete', handler: () => void): this;
+    on(event: 'timeout', handler: () => void): this;
+    on(event: 'chunk', handler: (chunk: ChatCompletionChunk) => void): this;
+    on(event: 'stats', handler: (stats: ChatEventStats) => void): this;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Chat协议相关类型定义
+ * 支持OpenAI Chat Completions的JSON↔SSE双向转换
+ */
+// Chat转换错误代码
+export const CHAT_CONVERSION_ERROR_CODES = {
+    TIMEOUT: 'CHAT_TIMEOUT',
+    INVALID_CHUNK: 'CHAT_INVALID_CHUNK',
+    SEQUENCE_ERROR: 'CHAT_SEQUENCE_ERROR',
+    TOOL_CALL_ERROR: 'CHAT_TOOL_CALL_ERROR',
+    PARSE_ERROR: 'CHAT_PARSE_ERROR',
+    VALIDATION_ERROR: 'CHAT_VALIDATION_ERROR',
+    STREAM_ERROR: 'CHAT_STREAM_ERROR'
+};
+// 默认Chat转换配置
+export const DEFAULT_CHAT_CONVERSION_CONFIG = {
+    defaultTimeoutMs: 30000,
+    heartbeatIntervalMs: 15000,
+    chunkTimeoutMs: 5000,
+    defaultChunkDelayMs: 10,
+    maxTokensPerChunk: 100,
+    maxChunkSize: 1024,
+    enableChunkValidation: true,
+    strictMode: false,
+    validateToolCalls: true,
+    maxConcurrentChoices: 10,
+    maxConcurrentToolCalls: 50,
+    eventBufferSize: 1000,
+    debugMode: false,
+    logLevel: 'info',
+    enableMetrics: true
+};