@codehz/ai 0.4.6 → 0.7.0

package/src/helpers/request-mapper.ts

@@ -1,94 +0,0 @@
-import { AIRequestError } from "../core/errors.js";
-import { contentBlocksToText } from "./mapping.js";
-
-import type { ContentBlock, InstructionBlock, ToolCallItem, ToolChoice, ToolDefinition } from "../types/index.js";
-
-export class NormalizedRequestMapper {
-  constructor(readonly kind: string) {}
-
-  mapInstructions(instructions: string | InstructionBlock[]): string {
-    return typeof instructions === "string"
-      ? instructions
-      : contentBlocksToText(this.ensureTextBlocks(instructions, "instructions"));
-  }
-
-  ensureTextBlocks(blocks: ContentBlock[], field: string): ContentBlock[] {
-    return this.ensureBlocks(blocks, field, ["text", "json"], "only text/json blocks are supported");
-  }
-
-  ensureReasoningBlocks(blocks: ContentBlock[], field: string): Array<Extract<ContentBlock, { type: "text" }>> {
-    return this.ensureBlocks(blocks, field, ["text"], "reasoning only supports text blocks") as Array<
-      Extract<ContentBlock, { type: "text" }>
-    >;
-  }
-
-  /** ensureTextBlocks + contentBlocksToText 的常见组合。 */
-  textFromBlocks(blocks: ContentBlock[], field: string): string {
-    return contentBlocksToText(this.ensureTextBlocks(blocks, field));
-  }
-
-  parseToolArguments(item: ToolCallItem): Record<string, unknown> {
-    try {
-      const parsed: unknown = JSON.parse(item.argumentsText);
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-        return parsed as Record<string, unknown>;
-      }
-    } catch {
-      // handled below
-    }
-
-    throw new AIRequestError(
-      `${this.kind} requires tool_call argumentsText to be a valid JSON object`,
-      "TOOL_CALL_ARGUMENTS_INVALID",
-    );
-  }
-
-  rollbackTrailingAssistantMessages<T extends { role: string }>(messages: T[]): void {
-    while (messages.length > 0 && messages[messages.length - 1]?.role === "assistant") {
-      messages.pop();
-    }
-  }
-
-  mapToolsIfPresent<T>(tools: ToolDefinition[] | undefined, map: (tool: ToolDefinition) => T): T[] | undefined {
-    if (!tools || tools.length === 0) return undefined;
-    return tools.map(map);
-  }
-
-  /**
-   * 将 canonical toolChoice 映射为 provider 形状。
-   * 返回 undefined 表示调用方无需写入 body 字段。
-   */
-  mapToolChoice<T>(
-    toolChoice: ToolChoice | undefined,
-    mappers: {
-      auto: T;
-      none: T;
-      tool: (name: string) => T;
-    },
-  ): T | undefined {
-    if (!toolChoice) return undefined;
-    if (toolChoice === "auto") return mappers.auto;
-    if (toolChoice === "none") return mappers.none;
-    if (toolChoice.type === "tool") return mappers.tool(toolChoice.name);
-    return undefined;
-  }
-
-  private ensureBlocks(
-    blocks: ContentBlock[],
-    field: string,
-    supportedTypes: ReadonlyArray<ContentBlock["type"]>,
-    description: string,
-  ): ContentBlock[] {
-    for (let i = 0; i < blocks.length; i++) {
-      const block = blocks[i];
-      if (block && !supportedTypes.includes(block.type)) {
-        throw new AIRequestError(
-          `${this.kind} does not support ${field}[${i}] of type "${block.type}"; ${description}`,
-          "UNSUPPORTED_CONTENT_BLOCK",
-        );
-      }
-    }
-
-    return blocks;
-  }
-}

package/src/helpers/synthetic-stream.ts

@@ -1,188 +0,0 @@
-/**
- * 模拟流式 (Synthetic Streaming)
- *
- * 将一组已解析的 canonical OutputItem 包装为规范事件流。
- * 适用于非原生流式后端：adapter 拿到完整响应后，调用此函数
- * 即可产出一致的事件序列，无需自己逐事件组装。
- *
- * 约束：
- * - 每个 item 只发一块完整 delta（不模拟逐 token）
- * - 保持 item 边界
- * - 保持后端原始顺序
- * - 不发明 reasoning
- * - 不改写工具参数
- */
-
-import { createEventFactory } from "../core/event-factory.js";
-import { replayFromOutput } from "./mapping.js";
-
-import type {
-  OutputItem,
-  ReplayItem,
-  StopReason,
-  Usage,
-  BillingInfo,
-  AIStreamEvent,
-  MessageItem,
-  ReasoningItem,
-  ToolCallItem,
-  OpaqueItem,
-} from "../types/index.js";
-
-// ── 输入参数 ──────────────────────────────────────────────────
-
-export type SyntheticStreamOptions = {
-  model: string;
-  responseId: string;
-  backend: {
-    kind: "chat-completions" | "messages" | "responses" | "mock";
-    /** syntheticStream 强制设为 true */
-  };
-  output: OutputItem[];
-  replay?: ReplayItem[];
-  stopReason?: StopReason;
-  usage?: Usage;
-  billing?: BillingInfo;
-  providerMetadata?: Record<string, unknown>;
-  rawResponseId?: string;
-  warnings?: string[];
-};
-
-// ── Synthetic Stream ──────────────────────────────────────────
-
-/**
- * 将已解析的 output items 包装为完整规范事件流。
- *
- * 用法示例（在 adapter 的 runStream 中）：
- * ```ts
- * const result = parseNonStreamingResponse(data);
- * yield* syntheticStream({
- *   model: request.model,
- *   responseId: request.requestId,
- *   backend: { kind: "chat-completions" },
- *   output: result.output,
- *   stopReason: result.stopReason,
- *   usage: result.usage,
- * });
- * ```
- */
-export async function* syntheticStream(options: SyntheticStreamOptions): AsyncIterable<AIStreamEvent> {
-  const {
-    model,
-    responseId,
-    backend,
-    output,
-    replay,
-    stopReason,
-    usage,
-    billing,
-    providerMetadata,
-    rawResponseId,
-    warnings: extraWarnings,
-  } = options;
-
-  const factory = createEventFactory({
-    responseId,
-    backend: { kind: backend.kind, isSynthetic: true },
-  });
-
-  // 1. 响应开始
-  yield factory.responseStarted(model);
-
-  // 2. item 级事件 — 每个 item 只发一块完整 delta
-  for (const item of output) {
-    yield* emitItemEvents(item, factory);
-  }
-
-  // 3. auxiliary 事件（如有）
-  if (usage || billing) {
-    yield factory.responseAuxiliary({ usage, billing });
-  }
-
-  // 4. 构建最终 completion 并发射
-  const finalReplay = replay ?? replayFromOutput(output);
-
-  // 收集警告
-  const allWarnings: string[] = [];
-  allWarnings.push("Response is synthetically streamed; delta granularity may differ from native streaming");
-  if (extraWarnings) allWarnings.push(...extraWarnings);
-
-  yield factory.responseCompleted({
-    replay: finalReplay,
-    stopReason,
-    usage,
-    billing,
-    auxiliary: providerMetadata ? { providerMetadata } : undefined,
-    opaqueOutput: output.filter((item): item is OpaqueItem => item.type === "opaque"),
-    warnings: allWarnings.length > 0 ? allWarnings : undefined,
-    trace: {
-      requestId: responseId,
-      rawResponseId,
-      adapter: backend.kind,
-      isSyntheticStream: true,
-      warnings: allWarnings.length > 0 ? allWarnings : undefined,
-    },
-  });
-}
-
-// ── Item 事件发射 ─────────────────────────────────────────────
-
-function* emitItemEvents(item: OutputItem, factory: ReturnType<typeof createEventFactory>): Generator<AIStreamEvent> {
-  switch (item.type) {
-    case "message":
-      yield* emitMessageEvents(item, factory);
-      break;
-    case "reasoning":
-      yield* emitReasoningEvents(item, factory);
-      break;
-    case "tool_call":
-      yield* emitToolCallEvents(item, factory);
-      break;
-    case "opaque":
-      // Opaque items in output have no streaming events
-      break;
-  }
-}
-
-function* emitMessageEvents(
-  item: MessageItem,
-  factory: ReturnType<typeof createEventFactory>,
-): Generator<AIStreamEvent> {
-  const id = item.id ?? `syn-msg-${crypto.randomUUID()}`;
-  yield factory.messageStarted(id);
-
-  for (const block of item.content) {
-    yield factory.messageDelta(id, block);
-  }
-
-  yield factory.messageCompleted(id);
-}
-
-function* emitReasoningEvents(
-  item: ReasoningItem,
-  factory: ReturnType<typeof createEventFactory>,
-): Generator<AIStreamEvent> {
-  const id = item.id ?? `syn-reason-${crypto.randomUUID()}`;
-  yield factory.reasoningStarted(id, item.visibility);
-
-  for (const block of item.content) {
-    yield factory.reasoningDelta(id, block);
-  }
-
-  yield factory.reasoningCompleted(id);
-}
-
-function* emitToolCallEvents(
-  item: ToolCallItem,
-  factory: ReturnType<typeof createEventFactory>,
-): Generator<AIStreamEvent> {
-  yield factory.toolCallStarted(item.id, item.name);
-
-  if (item.argumentsText) {
-    yield factory.toolCallDelta(item.id, { argumentsText: item.argumentsText });
-  }
-
-  yield factory.toolCallCompleted(item.id);
-}
-
-// ── Helper ────────────────────────────────────────────────────

package/src/helpers/usage-mapping.ts

@@ -1,110 +0,0 @@
-/**
- * Provider usage → canonical Usage 映射
- *
- * best-effort 提取 reasoning / cache 等扩展字段。
- */
-
-import type { Usage } from "../types/index.js";
-
-function num(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}
-
-function record(obj: Record<string, number | undefined>): Partial<Usage> {
-  const out: Partial<Usage> = {};
-  for (const [key, value] of Object.entries(obj)) {
-    if (value !== undefined) {
-      (out as Record<string, number>)[key] = value;
-    }
-  }
-  return out;
-}
-
-function withDerivedTotal(usage: {
-  inputTokens?: number;
-  outputTokens?: number;
-  totalTokens?: number;
-  cachedInputTokens?: number;
-  reasoningTokens?: number;
-  cacheWriteInputTokens?: number;
-}): Partial<Usage> {
-  const { inputTokens, outputTokens, totalTokens, cachedInputTokens, reasoningTokens, cacheWriteInputTokens } = usage;
-  return record({
-    inputTokens,
-    outputTokens,
-    totalTokens:
-      totalTokens ?? (inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined),
-    cachedInputTokens,
-    reasoningTokens,
-    cacheWriteInputTokens,
-  });
-}
-
-/** OpenAI Chat Completions `usage` */
-export function usageFromChatCompletions(raw: {
-  prompt_tokens?: number;
-  completion_tokens?: number;
-  total_tokens?: number;
-  prompt_tokens_details?: { cached_tokens?: number; [key: string]: unknown };
-  completion_tokens_details?: { reasoning_tokens?: number; [key: string]: unknown };
-}): Partial<Usage> {
-  return withDerivedTotal({
-    inputTokens: num(raw.prompt_tokens),
-    outputTokens: num(raw.completion_tokens),
-    totalTokens: num(raw.total_tokens),
-    cachedInputTokens: num(raw.prompt_tokens_details?.cached_tokens),
-    reasoningTokens: num(raw.completion_tokens_details?.reasoning_tokens),
-  });
-}
-
-/** OpenAI Responses API `usage` */
-export function usageFromOpenAIResponses(raw: {
-  input_tokens?: number;
-  output_tokens?: number;
-  total_tokens?: number;
-  input_tokens_details?: { cached_tokens?: number; [key: string]: unknown };
-  output_tokens_details?: { reasoning_tokens?: number; [key: string]: unknown };
-  [key: string]: unknown;
-}): Partial<Usage> {
-  return withDerivedTotal({
-    inputTokens: num(raw.input_tokens),
-    outputTokens: num(raw.output_tokens),
-    totalTokens: num(raw.total_tokens),
-    cachedInputTokens: num(raw.input_tokens_details?.cached_tokens),
-    reasoningTokens: num(raw.output_tokens_details?.reasoning_tokens),
-  });
-}
-
-/** Anthropic Messages `usage`（message_start / message_delta） */
-export function usageFromAnthropicMessages(raw: {
-  input_tokens?: number;
-  output_tokens?: number;
-  cache_creation_input_tokens?: number;
-  cache_read_input_tokens?: number;
-  [key: string]: unknown;
-}): Partial<Usage> {
-  const uncachedInputTokens = num(raw.input_tokens);
-  const outputTokens = num(raw.output_tokens);
-  const cacheWriteInputTokens = num(raw.cache_creation_input_tokens);
-  const cachedInputTokens = num(raw.cache_read_input_tokens);
-
-  const inputParts = [uncachedInputTokens, cacheWriteInputTokens, cachedInputTokens].filter(
-    (n): n is number => n !== undefined,
-  );
-  const inputTokens = inputParts.length > 0 ? inputParts.reduce((sum, n) => sum + n, 0) : undefined;
-
-  return withDerivedTotal({
-    inputTokens,
-    outputTokens,
-    cachedInputTokens,
-    cacheWriteInputTokens,
-  });
-}
-
-/** Ollama 流式 chunk */
-export function usageFromOllama(raw: { prompt_eval_count?: number; eval_count?: number }): Partial<Usage> {
-  return withDerivedTotal({
-    inputTokens: num(raw.prompt_eval_count),
-    outputTokens: num(raw.eval_count),
-  });
-}

package/src/index.ts

@@ -1,17 +0,0 @@
-/**
- * @codehz/ai — 统一流式 AI 客户端
- *
- * 对外只暴露一个 canonical 主入口：client.stream()
- */
-
-// Re-export all canonical types
-export * from "./types/index.js";
-
-// Re-export core client API
-export * from "./core/index.js";
-
-// Re-export adapters
-export * from "./adapters/index.js";
-
-// Re-export helpers
-export * from "./helpers/index.js";

package/src/types/adapter.ts

@@ -1,42 +0,0 @@
-/**
- * BackendAdapter — adapter 内部协议和 client 公开类型
- *
- * adapter 对前台只暴露一个统一适配点。
- */
-
-import type { AIRequest } from "./request.js";
-import type { AIStreamEvent } from "./events.js";
-
-// ── 公共工具类型 ──────────────────────────────────────────────
-
-/** HTTP fetch 函数签名，用于注入自定义请求实现（测试／代理） */
-export type FetchFn = (url: string, init: RequestInit) => Promise<Response>;
-
-// ── 归一化请求 ────────────────────────────────────────────────
-
-export type NormalizedRequest = AIRequest & {
-  model: string;
-  requestId: string;
-};
-
-// ── Adapter 接口 ──────────────────────────────────────────────
-
-export interface BackendAdapter {
-  readonly kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
-  readonly isSyntheticStream: boolean;
-  stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
-}
-
-// ── Client 公开类型 ───────────────────────────────────────────
-
-export type CreateAIClientOptions = {
-  adapter: BackendAdapter;
-  model: string;
-  defaults?: Partial<AIRequest>;
-  /** 全局默认 AbortSignal，当 request.signal 未设置时生效。 */
-  signal?: AbortSignal;
-};
-
-export interface AIClient {
-  stream(request: AIRequest): AsyncIterable<AIStreamEvent>;
-}

package/src/types/content.ts

@@ -1,15 +0,0 @@
-/**
- * ContentBlock — 统一内容块类型
- *
- * 覆盖文本、JSON、图片、二进制引用和后端私有内容。
- */
-
-export type TextContentBlock = { type: "text"; text: string };
-export type JsonContentBlock = { type: "json"; json: unknown };
-export type InstructionBlock = TextContentBlock | JsonContentBlock;
-
-export type ContentBlock =
-  | InstructionBlock
-  | { type: "image"; imageUrl: string }
-  | { type: "binary_ref"; ref: string }
-  | { type: "opaque"; payload: unknown };

package/src/types/events.ts

@@ -1,138 +0,0 @@
-/**
- * AIStreamEvent — 统一流事件模型
- *
- * 所有 adapter 都必须产出 AsyncIterable<AIStreamEvent>。
- * 无论后端是否支持原生流式，调用方看到的事件语义都一致：
- *   响应级开始 → item 级开始/增量/完成 → 响应级完成
- */
-
-import type { ContentBlock } from "./content.js";
-import type { Usage, BillingInfo, AuxiliaryInfo, BackendTrace, StopReason } from "./response.js";
-import type { OpaqueItem, ReplayItem } from "./items.js";
-
-// ── 事件基类 ──────────────────────────────────────────────────
-
-export type StreamEventBase = {
-  type: string;
-  responseId?: string;
-  sequence: number;
-  timestamp: string;
-  backend: {
-    kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
-    isSynthetic: boolean;
-  };
-};
-
-// ── 响应级事件 ────────────────────────────────────────────────
-
-export type ResponseStartedEvent = StreamEventBase & {
-  type: "response.started";
-  model: string;
-};
-
-export type ResponseWarningEvent = StreamEventBase & {
-  type: "response.warning";
-  message: string;
-  code?: string;
-};
-
-export type ResponseAuxiliaryEvent = StreamEventBase & {
-  type: "response.auxiliary";
-  usage?: Usage;
-  billing?: BillingInfo;
-  auxiliary?: Partial<AuxiliaryInfo>;
-};
-
-export type ResponseCompletedEvent = StreamEventBase & {
-  type: "response.completed";
-  replay: ReplayItem[];
-  stopReason?: StopReason;
-  usage?: Usage;
-  billing?: BillingInfo;
-  auxiliary?: AuxiliaryInfo;
-  warnings?: string[];
-  opaqueOutput?: OpaqueItem[];
-  trace?: Partial<BackendTrace>;
-};
-
-// ── 消息流事件 ────────────────────────────────────────────────
-
-export type MessageStartedEvent = StreamEventBase & {
-  type: "message.started";
-  item: {
-    id: string;
-    role: "assistant";
-  };
-};
-
-export type MessageDeltaEvent = StreamEventBase & {
-  type: "message.delta";
-  itemId: string;
-  delta: ContentBlock;
-};
-
-export type MessageCompletedEvent = StreamEventBase & {
-  type: "message.completed";
-  itemId: string;
-};
-
-// ── 思维链流事件 ──────────────────────────────────────────────
-
-export type ReasoningStartedEvent = StreamEventBase & {
-  type: "reasoning.started";
-  item: {
-    id: string;
-    visibility: "full" | "summary" | "redacted" | "opaque";
-  };
-};
-
-export type ReasoningDeltaEvent = StreamEventBase & {
-  type: "reasoning.delta";
-  itemId: string;
-  delta: ContentBlock;
-};
-
-export type ReasoningCompletedEvent = StreamEventBase & {
-  type: "reasoning.completed";
-  itemId: string;
-};
-
-// ── 工具调用流事件 ────────────────────────────────────────────
-
-export type ToolCallStartedEvent = StreamEventBase & {
-  type: "tool_call.started";
-  item: {
-    id: string;
-    name: string;
-  };
-};
-
-export type ToolCallDeltaEvent = StreamEventBase & {
-  type: "tool_call.delta";
-  itemId: string;
-  delta: {
-    argumentsText?: string;
-  };
-};
-
-export type ToolCallCompletedEvent = StreamEventBase & {
-  type: "tool_call.completed";
-  itemId: string;
-};
-
-// ── 统一事件联合 ──────────────────────────────────────────────
-
-export type AIStreamEvent =
-  | ResponseStartedEvent
-  | ResponseWarningEvent
-  | ResponseAuxiliaryEvent
-  | MessageStartedEvent
-  | MessageDeltaEvent
-  | MessageCompletedEvent
-  | ReasoningStartedEvent
-  | ReasoningDeltaEvent
-  | ReasoningCompletedEvent
-  | ToolCallStartedEvent
-  | ToolCallDeltaEvent
-  | ToolCallCompletedEvent
-  | ResponseCompletedEvent;

package/src/types/index.ts

@@ -1,49 +0,0 @@
-/**
- * Canonical 类型系统
- *
- * 模块边界：统一请求、事件、响应模型的核心类型定义。
- * 所有公开类型最终从这里导出。
- */
-
-// 基础内容块
-export type { TextContentBlock, JsonContentBlock, InstructionBlock, ContentBlock } from "./content.js";
-
-// Item 类型体系
-export type {
-  MessageItem,
-  ReasoningItem,
-  ToolCallItem,
-  ToolResultItem,
-  OpaqueItem,
-  InputItem,
-  OutputItem,
-  ReplayItem,
-} from "./items.js";
-
-// 请求模型
-export type { AIRequest, ToolDefinition, ToolChoice, IncludeSettings, ReasoningLevel } from "./request.js";
-
-// 响应模型
-export type { AIResponse, StopReason, Usage, BillingInfo, AuxiliaryInfo, BackendTrace } from "./response.js";
-
-// 流事件模型
-export type {
-  AIStreamEvent,
-  StreamEventBase,
-  ResponseStartedEvent,
-  ResponseWarningEvent,
-  ResponseAuxiliaryEvent,
-  ResponseCompletedEvent,
-  MessageStartedEvent,
-  MessageDeltaEvent,
-  MessageCompletedEvent,
-  ReasoningStartedEvent,
-  ReasoningDeltaEvent,
-  ReasoningCompletedEvent,
-  ToolCallStartedEvent,
-  ToolCallDeltaEvent,
-  ToolCallCompletedEvent,
-} from "./events.js";
-
-// Adapter 协议和 client 类型
-export type { BackendAdapter, FetchFn, NormalizedRequest, CreateAIClientOptions, AIClient } from "./adapter.js";