@providerprotocol/ai 0.0.31 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@providerprotocol/ai",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "description": "UPP: Unified Provider Protocol for AI inference",
   "license": "MIT",
   "homepage": "https://providerprotocol.org",
@@ -56,6 +56,11 @@
       "types": "./dist/proxy/index.d.ts",
       "import": "./dist/proxy/index.js",
       "default": "./dist/proxy/index.js"
+    },
+    "./responses": {
+      "types": "./dist/responses/index.d.ts",
+      "import": "./dist/responses/index.js",
+      "default": "./dist/responses/index.js"
     }
   },
   "files": [

package/dist/chunk-73IIE3QT.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/types/stream.ts"],"sourcesContent":["/**\n * @fileoverview Streaming types for real-time LLM responses.\n *\n * Defines the event types and interfaces for streaming LLM inference,\n * including text deltas, tool call deltas, and control events.\n *\n * @module types/stream\n */\n\nimport type { Turn } from './turn.ts';\n\n/**\n * Stream event type constants.\n *\n * Use these constants instead of raw strings for type-safe event handling:\n *\n * @example\n * ```typescript\n * import { StreamEventType } from 'upp';\n *\n * for await (const event of stream) {\n *   if (event.type === StreamEventType.TextDelta) {\n *     process.stdout.write(event.delta.text ?? '');\n *   }\n * }\n * ```\n */\nexport const StreamEventType = {\n  /** Incremental text output */\n  TextDelta: 'text_delta',\n  /** Incremental reasoning/thinking output */\n  ReasoningDelta: 'reasoning_delta',\n  /** Incremental image data */\n  ImageDelta: 'image_delta',\n  /** Incremental audio data */\n  AudioDelta: 'audio_delta',\n  /** Incremental video data */\n  VideoDelta: 'video_delta',\n  /** Incremental tool call data (arguments being streamed) */\n  ToolCallDelta: 'tool_call_delta',\n  /** Tool execution has started (may be emitted after completion in some implementations) */\n  ToolExecutionStart: 'tool_execution_start',\n  /** Tool execution has completed */\n  ToolExecutionEnd: 'tool_execution_end',\n  /** Beginning of a message */\n  MessageStart: 'message_start',\n  /** End of a message */\n  MessageStop: 'message_stop',\n  /** Beginning of a content block */\n  ContentBlockStart: 'content_block_start',\n  /** End of a content block */\n  ContentBlockStop: 'content_block_stop',\n} as const;\n\n/**\n * Stream event type discriminator union.\n *\n * This type is derived from {@link StreamEventType} constants. Use `StreamEventType.TextDelta`\n * for constants or `type MyType = StreamEventType` for type annotations.\n */\nexport type StreamEventType = (typeof StreamEventType)[keyof typeof StreamEventType];\n\n/**\n * Event delta data payload.\n *\n * Contains the type-specific data for a streaming event.\n * Different fields are populated depending on the event type.\n */\nexport interface EventDelta {\n  /** Incremental text content (for text_delta, reasoning_delta) */\n  text?: string;\n\n  /** Incremental binary data (for image_delta, audio_delta, video_delta) */\n  data?: Uint8Array;\n\n  /** Tool call identifier (for tool_call_delta, tool_execution_start/end) */\n  toolCallId?: string;\n\n  /** Tool name (for tool_call_delta, tool_execution_start/end) */\n  toolName?: string;\n\n  /** Incremental JSON arguments string (for tool_call_delta) */\n  argumentsJson?: string;\n\n  /** Tool execution result (for tool_execution_end) */\n  result?: unknown;\n\n  /** Whether tool execution resulted in an error (for tool_execution_end) */\n  isError?: boolean;\n\n  /** Timestamp in milliseconds (for tool_execution_start/end) */\n  timestamp?: number;\n}\n\n/**\n * A single streaming event from the LLM.\n *\n * Events are emitted in order as the model generates output,\n * allowing for real-time display of responses.\n *\n * @example\n * ```typescript\n * import { StreamEventType } from 'upp';\n *\n * for await (const event of stream) {\n *   if (event.type === StreamEventType.TextDelta) {\n *     process.stdout.write(event.delta.text ?? '');\n *   } else if (event.type === StreamEventType.ToolCallDelta) {\n *     console.log('Tool:', event.delta.toolName);\n *   }\n * }\n * ```\n */\nexport interface StreamEvent {\n  /** Event type discriminator */\n  type: StreamEventType;\n\n  /** Index of the content block this event belongs to */\n  index: number;\n\n  /** Event-specific data payload */\n  delta: EventDelta;\n}\n\n/**\n * Stream result - an async iterable that also provides the final turn.\n *\n * Allows consuming streaming events while also awaiting the complete\n * Turn result after streaming finishes.\n *\n * @typeParam TData - Type of the structured output data\n *\n * @example\n * ```typescript\n * import { StreamEventType } from 'upp';\n *\n * const stream = instance.stream('Tell me a story');\n *\n * // Consume streaming events\n * for await (const event of stream) {\n *   if (event.type === StreamEventType.TextDelta) {\n *     process.stdout.write(event.delta.text ?? '');\n *   }\n * }\n *\n * // Get the complete turn after streaming\n * const turn = await stream.turn;\n * console.log('\\n\\nTokens used:', turn.usage.totalTokens);\n * ```\n */\nexport interface StreamResult<TData = unknown>\n  extends AsyncIterable<StreamEvent> {\n  /**\n   * Promise that resolves to the complete Turn after streaming finishes.\n   * Rejects if the stream is aborted or terminated early.\n   */\n  readonly turn: Promise<Turn<TData>>;\n\n  /**\n   * Aborts the stream, stopping further events and cancelling the request.\n   * This will cause {@link StreamResult.turn} to reject.\n   */\n  abort(): void;\n}\n\n/**\n * Creates a StreamResult from an async generator and completion promise.\n *\n * @typeParam TData - Type of the structured output data\n * @param generator - Async generator that yields stream events\n * @param turnPromiseOrFactory - Promise or factory that resolves to the complete Turn\n * @param abortController - Controller for aborting the stream\n * @returns A StreamResult that can be iterated and awaited\n *\n * @example\n * ```typescript\n * const abortController = new AbortController();\n * const stream = createStreamResult(\n *   eventGenerator(),\n *   turnPromise,\n *   abortController\n * );\n * ```\n */\nexport function createStreamResult<TData = unknown>(\n  generator: AsyncGenerator<StreamEvent, void, unknown>,\n  turnPromiseOrFactory: Promise<Turn<TData>> | (() => Promise<Turn<TData>>),\n  abortController: AbortController\n): StreamResult<TData> {\n  let cachedTurn: Promise<Turn<TData>> | null = null;\n\n  const getTurn = (): Promise<Turn<TData>> => {\n    // Lazily build the turn promise to avoid work (or rejections) when unused.\n    if (typeof turnPromiseOrFactory === 'function') {\n      if (!cachedTurn) {\n        cachedTurn = turnPromiseOrFactory();\n      }\n      return cachedTurn;\n    }\n\n    return turnPromiseOrFactory;\n  };\n\n  return {\n    [Symbol.asyncIterator]() {\n      return generator;\n    },\n    get turn() {\n      return getTurn();\n    },\n    abort() {\n      abortController.abort();\n    },\n  };\n}\n\n/**\n * Creates a text delta stream event.\n *\n * @param text - The incremental text content\n * @param index - Content block index (default: 0)\n * @returns A text_delta StreamEvent\n */\nexport function textDelta(text: string, index = 0): StreamEvent {\n  return {\n    type: StreamEventType.TextDelta,\n    index,\n    delta: { text },\n  };\n}\n\n/**\n * Creates a tool call delta stream event.\n *\n * @param toolCallId - Unique identifier for the tool call\n * @param toolName - Name of the tool being called\n * @param argumentsJson - Incremental JSON arguments string\n * @param index - Content block index (default: 0)\n * @returns A tool_call_delta StreamEvent\n */\nexport function toolCallDelta(\n  toolCallId: string,\n  toolName: string,\n  argumentsJson: string,\n  index = 0\n): StreamEvent {\n  return {\n    type: StreamEventType.ToolCallDelta,\n    index,\n    delta: { toolCallId, toolName, argumentsJson },\n  };\n}\n\n/**\n * Creates a message start stream event.\n *\n * @returns A message_start StreamEvent\n */\nexport function messageStart(): StreamEvent {\n  return {\n    type: StreamEventType.MessageStart,\n    index: 0,\n    delta: {},\n  };\n}\n\n/**\n * Creates a message stop stream event.\n *\n * @returns A message_stop StreamEvent\n */\nexport function messageStop(): StreamEvent {\n  return {\n    type: StreamEventType.MessageStop,\n    index: 0,\n    delta: {},\n  };\n}\n\n/**\n * Creates a content block start stream event.\n *\n * @param index - The content block index starting\n * @returns A content_block_start StreamEvent\n */\nexport function contentBlockStart(index: number): StreamEvent {\n  return {\n    type: StreamEventType.ContentBlockStart,\n    index,\n    delta: {},\n  };\n}\n\n/**\n * Creates a content block stop stream event.\n *\n * @param index - The content block index stopping\n * @returns A content_block_stop StreamEvent\n */\nexport function contentBlockStop(index: number): StreamEvent {\n  return {\n    type: StreamEventType.ContentBlockStop,\n    index,\n    delta: {},\n  };\n}\n\n/**\n * Creates a tool execution start stream event.\n *\n * @param toolCallId - Unique identifier for the tool call\n * @param toolName - Name of the tool being executed\n * @param timestamp - Start timestamp in milliseconds\n * @param index - Content block index (default: 0)\n * @returns A tool_execution_start StreamEvent\n */\nexport function toolExecutionStart(\n  toolCallId: string,\n  toolName: string,\n  timestamp: number,\n  index = 0\n): StreamEvent {\n  return {\n    type: StreamEventType.ToolExecutionStart,\n    index,\n    delta: { toolCallId, toolName, timestamp },\n  };\n}\n\n/**\n * Creates a tool execution end stream event.\n *\n * @param toolCallId - Unique identifier for the tool call\n * @param toolName - Name of the tool that was executed\n * @param result - The result from the tool execution\n * @param isError - Whether the execution resulted in an error\n * @param timestamp - End timestamp in milliseconds\n * @param index - Content block index (default: 0)\n * @returns A tool_execution_end StreamEvent\n */\nexport function toolExecutionEnd(\n  toolCallId: string,\n  toolName: string,\n  result: unknown,\n  isError: boolean,\n  timestamp: number,\n  index = 0\n): StreamEvent {\n  return {\n    type: StreamEventType.ToolExecutionEnd,\n    index,\n    delta: { toolCallId, toolName, result, isError, timestamp },\n  };\n}\n"],"mappings":";AA2BO,IAAM,kBAAkB;AAAA;AAAA,EAE7B,WAAW;AAAA;AAAA,EAEX,gBAAgB;AAAA;AAAA,EAEhB,YAAY;AAAA;AAAA,EAEZ,YAAY;AAAA;AAAA,EAEZ,YAAY;AAAA;AAAA,EAEZ,eAAe;AAAA;AAAA,EAEf,oBAAoB;AAAA;AAAA,EAEpB,kBAAkB;AAAA;AAAA,EAElB,cAAc;AAAA;AAAA,EAEd,aAAa;AAAA;AAAA,EAEb,mBAAmB;AAAA;AAAA,EAEnB,kBAAkB;AACpB;AAoIO,SAAS,mBACd,WACA,sBACA,iBACqB;AACrB,MAAI,aAA0C;AAE9C,QAAM,UAAU,MAA4B;AAE1C,QAAI,OAAO,yBAAyB,YAAY;AAC9C,UAAI,CAAC,YAAY;AACf,qBAAa,qBAAqB;AAAA,MACpC;AACA,aAAO;AAAA,IACT;AAEA,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,CAAC,OAAO,aAAa,IAAI;AACvB,aAAO;AAAA,IACT;AAAA,IACA,IAAI,OAAO;AACT,aAAO,QAAQ;AAAA,IACjB;AAAA,IACA,QAAQ;AACN,sBAAgB,MAAM;AAAA,IACxB;AAAA,EACF;AACF;AASO,SAAS,UAAU,MAAc,QAAQ,GAAgB;AAC9D,SAAO;AAAA,IACL,MAAM,gBAAgB;AAAA,IACtB;AAAA,IACA,OAAO,EAAE,KAAK;AAAA,EAChB;AACF;AAWO,SAAS,cACd,YACA,UACA,eACA,QAAQ,GACK;AACb,SAAO;AAAA,IACL,MAAM,gBAAgB;AAAA,IACtB;AAAA,IACA,OAAO,EAAE,YAAY,UAAU,cAAc;AAAA,EAC/C;AACF;AAOO,SAAS,eAA4B;AAC1C,SAAO;AAAA,IACL,MAAM,gBAAgB;AAAA,IACtB,OAAO;AAAA,IACP,OAAO,CAAC;AAAA,EACV;AACF;AAOO,SAAS,cAA2B;AACzC,SAAO;AAAA,IACL,MAAM,gBAAgB;AAAA,IACtB,OAAO;AAAA,IACP,OAAO,CAAC;AAAA,EACV;AACF;AAQO,SAAS,kBAAkB,OAA4B;AAC5D,SAAO;AAAA,IACL,MAAM,gBAAgB;AAAA,IACtB;AAAA,IACA,OAAO,CAAC;AAAA,EACV;AACF;AAQO,SAAS,iBAAiB,OAA4B;AAC3D,SAAO;AAAA,IACL,MAAM,gBAAgB;AAAA,IACtB;AAAA,IACA,OAAO,CAAC;AAAA,EACV;AACF;AAWO,SAAS,mBACd,YACA,UACA,WACA,QAAQ,GACK;AACb,SAAO;AAAA,IACL,MAAM,gBAAgB;AAAA,IACtB;AAAA,IACA,OAAO,EAAE,YAAY,UAAU,UAAU;AAAA,EAC3C;AACF;AAaO,SAAS,iBACd,YACA,UACA,QACA,SACA,WACA,QAAQ,GACK;AACb,SAAO;AAAA,IACL,MAAM,gBAAgB;AAAA,IACtB;AAAA,IACA,OAAO,EAAE,YAAY,UAAU,QAAQ,SAAS,UAAU;AAAA,EAC5D;AACF;","names":[]}