@jsonstudio/llms 0.4.2

package/dist/conversion/conversion-v3/sse/types/utility-types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * 工具类型定义
+ * 提供JSON↔SSE双向转换中常用的工具类型和辅助函数
+ */
+export type ProtocolType = 'chat' | 'responses';
+export type ConversionDirection = 'json_to_sse' | 'sse_to_json';
+export interface EventTypeMap {
+    chat: {
+        SSE_EVENT: 'chat_chunk' | 'chat.done' | 'error' | 'ping';
+        JSON_TYPE: 'ChatCompletionChunk' | 'ChatCompletionResponse';
+    };
+    responses: {
+        SSE_EVENT: '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';
+        JSON_TYPE: 'ResponsesResponse' | 'ResponsesRequest';
+    };
+}
+export interface GenericConverter<TProtocol extends ProtocolType, TDirection extends ConversionDirection> {
+    protocol: TProtocol;
+    direction: TDirection;
+    convert(input: any, options: any): Promise<any>;
+    validate?(input: any): boolean;
+    getStats?(): any;
+}
+export interface UnifiedConversionOptions {
+    requestId: string;
+    model: string;
+    protocol: ProtocolType;
+    direction: ConversionDirection;
+    timeoutMs?: number;
+    enableHeartbeat?: boolean;
+    heartbeatIntervalMs?: number;
+    validationMode?: 'none' | 'basic' | 'strict';
+    debugMode?: boolean;
+    onError?: (error: Error) => void;
+    onComplete?: () => void;
+}
+export interface UnifiedEventStream extends AsyncIterable<any> {
+    protocol: ProtocolType;
+    direction: ConversionDirection;
+    requestId: string;
+    getStats(): any;
+    getConfig(): any;
+    pause?(): void;
+    resume?(): void;
+    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: 'stats', handler: (stats: any) => void): this;
+}
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type RequireKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;
+export type JsonType<TProtocol extends ProtocolType> = TProtocol extends 'chat' ? ChatJsonType : TProtocol extends 'responses' ? ResponsesJsonType : never;
+export type SseEventType<TProtocol extends ProtocolType> = TProtocol extends 'chat' ? ChatSseEventType : TProtocol extends 'responses' ? ResponsesSseEventType : never;
+export interface ChatJsonType {
+    id: string;
+    object: 'chat.completion' | 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: any[];
+    usage?: any;
+}
+export type ChatSseEventType = 'chat_chunk' | 'chat.done' | 'error' | 'ping';
+export interface ResponsesJsonType {
+    id: string;
+    object: 'response';
+    created_at: number;
+    model: string;
+    status: string;
+    output: any[];
+    usage?: any;
+}
+export type ResponsesSseEventType = '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 ConversionResult<TSuccess = any, TError = Error> {
+    success: boolean;
+    data?: TSuccess;
+    error?: TError;
+    metadata?: {
+        duration: number;
+        eventsProcessed: number;
+        bytesProcessed: number;
+        protocol: ProtocolType;
+        direction: ConversionDirection;
+    };
+}
+export type AsyncConversionResult<TSuccess = any, TError = Error> = Promise<ConversionResult<TSuccess, TError>>;
+export interface ConverterFactory {
+    createJsonToSseConverter<TProtocol extends ProtocolType>(protocol: TProtocol, options: UnifiedConversionOptions): GenericConverter<TProtocol, 'json_to_sse'>;
+    createSseToJsonConverter<TProtocol extends ProtocolType>(protocol: TProtocol, options: UnifiedConversionOptions): GenericConverter<TProtocol, 'sse_to_json'>;
+}
+export interface ConverterRegistry {
+    register<TProtocol extends ProtocolType, TDirection extends ConversionDirection>(protocol: TProtocol, direction: TDirection, converter: GenericConverter<TProtocol, TDirection>): void;
+    get<TProtocol extends ProtocolType, TDirection extends ConversionDirection>(protocol: TProtocol, direction: TDirection): GenericConverter<TProtocol, TDirection> | undefined;
+    list(): Array<{
+        protocol: ProtocolType;
+        direction: ConversionDirection;
+        converter: GenericConverter<any, any>;
+    }>;
+}
+export interface Validator<T> {
+    validate(input: T): ValidationResult;
+    isValid(input: T): boolean;
+    getErrors(input: T): string[];
+}
+export interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+export interface ValidationError {
+    code: string;
+    message: string;
+    path: string;
+    value?: any;
+}
+export interface ValidationWarning {
+    code: string;
+    message: string;
+    path: string;
+    value?: any;
+}
+export interface Serializer<T> {
+    serialize(input: T): string;
+    deserialize(input: string): T;
+    isValid(input: string): boolean;
+}
+export interface Cache<K, V> {
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    size: number;
+}
+export interface MetricsCollector {
+    incrementCounter(name: string, tags?: Record<string, string>): void;
+    recordHistogram(name: string, value: number, tags?: Record<string, string>): void;
+    setGauge(name: string, value: number, tags?: Record<string, string>): void;
+    recordTimer(name: string, duration: number, tags?: Record<string, string>): void;
+    getMetrics(): Record<string, any>;
+}
+export interface Logger {
+    debug(message: string, meta?: any): void;
+    info(message: string, meta?: any): void;
+    warn(message: string, meta?: any): void;
+    error(message: string, error?: Error, meta?: any): void;
+    child(meta: any): Logger;
+}
+export interface RetryConfig {
+    maxAttempts: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+    jitter: boolean;
+    retryableErrors: string[];
+}
+export interface CircuitBreakerConfig {
+    failureThreshold: number;
+    recoveryTimeoutMs: number;
+    monitoringPeriodMs: number;
+    expectedRecoveryTimeMs: number;
+}
+export interface RateLimitConfig {
+    windowMs: number;
+    maxRequests: number;
+    burstSize?: number;
+    strategy: 'sliding_window' | 'fixed_window' | 'token_bucket';
+}
+export interface HealthCheck {
+    isHealthy(): Promise<boolean>;
+    getStatus(): HealthStatus;
+    onHealthChange(callback: (status: HealthStatus) => void): void;
+}
+export interface HealthStatus {
+    healthy: boolean;
+    timestamp: number;
+    details?: Record<string, any>;
+}
+export interface LifecycleHooks {
+    beforeConversion?: (context: any) => Promise<void>;
+    afterConversion?: (context: any, result: any) => Promise<void>;
+    onError?: (context: any, error: Error) => Promise<void>;
+    onTimeout?: (context: any) => Promise<void>;
+    onRetry?: (context: any, attempt: number) => Promise<void>;
+}
+export interface Middleware {
+    name: string;
+    priority: number;
+    beforeConversion?: (context: any) => Promise<void>;
+    afterConversion?: (context: any, result: any) => Promise<void>;
+    onError?: (context: any, error: Error) => Promise<void>;
+}
+export interface Plugin {
+    name: string;
+    version: string;
+    initialize(context: any): Promise<void>;
+    destroy(): Promise<void>;
+    getMiddlewares(): Middleware[];
+    getHooks(): LifecycleHooks;
+}
+export interface ConfigMerger {
+    merge<T>(base: T, override: Partial<T>): T;
+    validate<T>(config: T): ValidationResult;
+    normalize<T>(config: T): T;
+}
+export interface EnvironmentParser {
+    getString(key: string, defaultValue?: string): string;
+    getNumber(key: string, defaultValue?: number): number;
+    getBoolean(key: string, defaultValue?: boolean): boolean;
+    getArray(key: string, delimiter?: string): string[];
+    getObject(key: string): any;
+}
+export declare const TypeGuards: {
+    isString: (value: any) => value is string;
+    isNumber: (value: any) => value is number;
+    isBoolean: (value: any) => value is boolean;
+    isObject: (value: any) => value is object;
+    isArray: (value: any) => value is any[];
+    isFunction: (value: any) => value is Function;
+    isDate: (value: any) => value is Date;
+    isNull: (value: any) => value is null;
+    isUndefined: (value: any) => value is undefined;
+    isNullOrUndefined: (value: any) => value is null | undefined;
+};
+export declare const AsyncUtils: {
+    delay: (ms: number) => Promise<void>;
+    timeout: <T>(promise: Promise<T>, ms: number) => Promise<T>;
+    retry: <T>(fn: () => Promise<T>, config: RetryConfig) => Promise<T>;
+};

package/dist/conversion/conversion-v3/sse/types/utility-types.js

@@ -0,0 +1,49 @@
+/**
+ * 工具类型定义
+ * 提供JSON↔SSE双向转换中常用的工具类型和辅助函数
+ */
+// 类型守卫工具函数
+export const TypeGuards = {
+    isString: (value) => typeof value === 'string',
+    isNumber: (value) => typeof value === 'number' && !isNaN(value),
+    isBoolean: (value) => typeof value === 'boolean',
+    isObject: (value) => value !== null && typeof value === 'object',
+    isArray: (value) => Array.isArray(value),
+    isFunction: (value) => typeof value === 'function',
+    isDate: (value) => value instanceof Date,
+    isNull: (value) => value === null,
+    isUndefined: (value) => value === undefined,
+    isNullOrUndefined: (value) => value == null
+};
+// 异步工具函数
+export const AsyncUtils = {
+    delay: (ms) => new Promise(resolve => setTimeout(resolve, ms)),
+    timeout: (promise, ms) => {
+        return Promise.race([
+            promise,
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Operation timed out after ${ms}ms`)), ms))
+        ]);
+    },
+    retry: async (fn, config) => {
+        let lastError;
+        for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                if (!config.retryableErrors.includes(error.name) || attempt === config.maxAttempts) {
+                    throw error;
+                }
+                const delay = Math.min(config.initialDelayMs * Math.pow(config.backoffMultiplier, attempt - 1), config.maxDelayMs);
+                if (config.jitter) {
+                    await AsyncUtils.delay(delay + Math.random() * delay * 0.1);
+                }
+                else {
+                    await AsyncUtils.delay(delay);
+                }
+            }
+        }
+        throw lastError;
+    }
+};

package/dist/conversion/conversion-v3/standards/context-adapter.d.ts

@@ -0,0 +1,146 @@
+import { type PipelineContext } from './pipeline-context.js';
+import type { PipelineErrorCallbacks } from './errors.js';
+import type { NodeConfig, NodeContext, NodeResult } from '../types/index.js';
+/**
+ * Phase 1b: Context Adapter + Hybrid streaming support
+ *
+ * 将 V3 NodeContext 与标准 PipelineContext 做双向适配，
+ * 并在调试信息中追踪 JSON / SSE / Hybrid 三种流式模式。
+ */
+/**
+ * 混合流式载荷
+ */
+export interface HybridStreamPayload<TStream = unknown> {
+    mode: 'sse' | 'json' | 'hybrid';
+    stream?: TStream | null;
+    snapshot?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 从 NodeContext 转换 PipelineContext 时的附加选项
+ */
+export interface ContextAdapterOptions {
+    hookPhase?: PipelineContext['metadata']['hookPhase'];
+    providerProtocol?: string;
+    routeName?: string;
+    pipelineId?: string;
+    lifecycleMetadata?: Record<string, unknown>;
+}
+/**
+ * 将 PipelineContext 还原为 NodeContext 时使用的种子数据
+ */
+export interface NodeContextSeed {
+    request: NodeContext['request'];
+    pipeline: NodeContext['pipeline'];
+    nodeConfig: NodeConfig;
+    data?: Record<string, unknown>;
+    callbacks?: PipelineErrorCallbacks | null;
+}
+/**
+ * mergeNodeResult 的附加配置
+ */
+export interface MergeOptions {
+    hookPhase?: PipelineContext['metadata']['hookPhase'];
+}
+export declare class ContextAdapter {
+    /**
+     * 将 V3 NodeContext 适配为标准 PipelineContext
+     */
+    static fromNodeContext(nodeContext: NodeContext, options?: ContextAdapterOptions): PipelineContext;
+    /**
+     * 将 PipelineContext 还原为 V3 NodeContext
+     */
+    static toNodeContext(pipelineContext: PipelineContext, seed?: NodeContextSeed): NodeContext;
+    /**
+     * 在 PipelineContext 上合并 NodeResult
+     */
+    static mergeNodeResult(pipelineContext: PipelineContext, nodeContext: NodeContext, result: NodeResult, options?: MergeOptions): PipelineContext;
+    /**
+     * 构造 PipelineContext.metadata
+     */
+    private static buildMetadata;
+    /**
+     * 构造调试上下文
+     */
+    private static buildDebugContext;
+    /**
+     * 构造节点契约
+     */
+    private static buildNodeContracts;
+    /**
+     * 推断 providerProtocol
+     */
+    private static resolveProviderProtocol;
+    /**
+     * 解析请求附加 metadata
+     */
+    private static getRequestMetadata;
+    /**
+     * 解析入口端点
+     */
+    private static resolveEntryEndpoint;
+    /**
+     * 解析流式偏好
+     */
+    private static resolveStreamingPreference;
+    /**
+     * 判断请求是否包含流式语义
+     */
+    private static hasStreamingIntent;
+    /**
+     * 构建 StreamingContext
+     */
+    private static buildStreamingContext;
+    /**
+     * 根据端点 + 流式意图推断模式
+     */
+    private static resolveStreamingMode;
+    /**
+     * 更新 StreamingContext（基于节点输出）
+     */
+    private static updateStreamingContext;
+    /**
+     * 提取标准化请求
+     */
+    private static extractStandardizedRequest;
+    /**
+     * 提取标准化响应
+     */
+    private static extractStandardizedResponse;
+    /**
+     * 从 NodeResult 中提取响应
+     */
+    private static extractResponseFromResult;
+    /**
+     * 记录 NodeContext 快照以供 round-trip
+     */
+    private static createNodeContextSnapshot;
+    /**
+     * 从 PipelineContext.extra 获取快照
+     */
+    private static getSnapshotFromContext;
+    /**
+     * 合并请求快照和 PipelineContext 元数据
+     */
+    private static mergeRequestSnapshot;
+    /**
+     * 合并 pipelineState
+     */
+    private static mergePipelineState;
+    /**
+     * 合并 nodeContext data
+     */
+    private static mergeNodeData;
+    /**
+     * 判断对象是否是 Readable
+     */
+    private static isReadable;
+    /**
+     * 提取 HybridStreamPayload
+     */
+    static extractHybridPayload(source?: Record<string, unknown> | unknown): HybridStreamPayload | null;
+    /**
+     * 构建错误上下文
+     */
+    private static buildErrorContext;
+}