@codehz/ai 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ai",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "module": "dist/index.mjs",
   "exports": {

package/src/adapters/chat-completions.ts

@@ -21,6 +21,7 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { usageFromChatCompletions } from "../helpers/usage-mapping.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
 
@@ -73,7 +74,13 @@ type ChatChunk = {
   created: number;
   model: string;
   choices: ChatChunkChoice[];
-  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    prompt_tokens_details?: { cached_tokens?: number };
+    completion_tokens_details?: { reasoning_tokens?: number };
+  };
 };
 
 type ChatChunkChoice = {
@@ -485,15 +492,7 @@ export class ChatCompletionsAdapter extends AdapterBase {
 
           // usage 可能在最终 chunk 中
           if (chunk.usage) {
-            auxiliary.recordUsage(
-              {
-                inputTokens: chunk.usage.prompt_tokens,
-                outputTokens: chunk.usage.completion_tokens,
-                totalTokens: chunk.usage.total_tokens,
-              },
-              "final",
-              chunk.usage,
-            );
+            auxiliary.recordUsage(usageFromChatCompletions(chunk.usage), "final", chunk.usage);
           }
 
           for (const choice of chunk.choices) {

package/src/adapters/messages.ts

@@ -24,6 +24,7 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { usageFromAnthropicMessages } from "../helpers/usage-mapping.js";
 
 import { parseSSEEvents } from "../helpers/sse-parser.js";
 
@@ -131,7 +132,12 @@ type MessagesSSEEvent =
       type: "message_delta";
       data: {
         delta: { stop_reason?: string; stop_sequence?: string | null };
-        usage: { input_tokens: number; output_tokens: number };
+        usage: {
+          input_tokens: number;
+          output_tokens: number;
+          cache_creation_input_tokens?: number;
+          cache_read_input_tokens?: number;
+        };
       };
     }
   | { type: "message_stop"; data: Record<string, never> }
@@ -616,15 +622,7 @@ export class MessagesAdapter extends AdapterBase {
               stopSequence = sseEvent.data.delta.stop_sequence;
               const u = sseEvent.data.usage;
               if (u) {
-                auxiliary.recordUsage(
-                  {
-                    inputTokens: u.input_tokens,
-                    outputTokens: u.output_tokens,
-                    totalTokens: u.input_tokens + u.output_tokens,
-                  },
-                  "stream",
-                  u,
-                );
+                auxiliary.recordUsage(usageFromAnthropicMessages(u), "stream", u);
               }
               continue;
             }

package/src/adapters/ollama.ts

@@ -27,6 +27,7 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { usageFromOllama } from "../helpers/usage-mapping.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
 
@@ -478,14 +479,10 @@ export class OllamaAdapter extends AdapterBase {
               (chunk.prompt_eval_count !== undefined || chunk.eval_count !== undefined)
             ) {
               auxiliary.recordUsage(
-                {
-                  inputTokens: chunk.prompt_eval_count,
-                  outputTokens: chunk.eval_count,
-                  totalTokens:
-                    chunk.prompt_eval_count !== undefined && chunk.eval_count !== undefined
-                      ? chunk.prompt_eval_count + chunk.eval_count
-                      : undefined,
-                },
+                usageFromOllama({
+                  prompt_eval_count: chunk.prompt_eval_count,
+                  eval_count: chunk.eval_count,
+                }),
                 "final",
                 {
                   prompt_eval_count: chunk.prompt_eval_count,

package/src/adapters/responses.ts

@@ -22,6 +22,7 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { usageFromOpenAIResponses } from "../helpers/usage-mapping.js";
 
 import { parseSSEEvents } from "../helpers/sse-parser.js";
 
@@ -448,15 +449,7 @@ export class ResponsesAdapter extends AdapterBase {
     if (completedResponse) {
       rawResponseId = completedResponse.id;
       if (completedResponse.usage) {
-        auxiliary.recordUsage(
-          {
-            inputTokens: completedResponse.usage.input_tokens,
-            outputTokens: completedResponse.usage.output_tokens,
-            totalTokens: completedResponse.usage.total_tokens,
-          },
-          "final",
-          completedResponse.usage,
-        );
+        auxiliary.recordUsage(usageFromOpenAIResponses(completedResponse.usage), "final", completedResponse.usage);
       }
     }
 

package/src/helpers/index.ts

@@ -34,3 +34,9 @@ export { syntheticStream } from "./synthetic-stream.js";
 export type { SyntheticStreamOptions } from "./synthetic-stream.js";
 export { AuxiliaryCollector } from "./auxiliary-collector.js";
 export type { UsageSource, BillingSource, LookupResult } from "./auxiliary-collector.js";
+export {
+  usageFromAnthropicMessages,
+  usageFromChatCompletions,
+  usageFromOllama,
+  usageFromOpenAIResponses,
+} from "./usage-mapping.js";

package/src/helpers/usage-mapping.ts

@@ -0,0 +1,150 @@
+/**
+ * Provider usage → canonical Usage 映射
+ *
+ * best-effort 提取 reasoning / cache / billable 等扩展字段。
+ */
+
+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 billableFromOpenAIStyle(
+  inputTokens: number | undefined,
+  outputTokens: number | undefined,
+  cachedInputTokens: number | undefined,
+  reasoningTokens: number | undefined,
+): Pick<Usage, "billableInputTokens" | "billableOutputTokens"> {
+  let billableInputTokens: number | undefined;
+  if (inputTokens !== undefined) {
+    billableInputTokens =
+      cachedInputTokens !== undefined ? Math.max(0, inputTokens - cachedInputTokens) : inputTokens;
+  }
+
+  let billableOutputTokens: number | undefined;
+  if (outputTokens !== undefined) {
+    billableOutputTokens =
+      reasoningTokens !== undefined ? Math.max(0, outputTokens - reasoningTokens) : outputTokens;
+  }
+
+  return record({ billableInputTokens, billableOutputTokens });
+}
+
+/** 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> {
+  const inputTokens = num(raw.prompt_tokens);
+  const outputTokens = num(raw.completion_tokens);
+  const cachedInputTokens = num(raw.prompt_tokens_details?.cached_tokens);
+  const reasoningTokens = num(raw.completion_tokens_details?.reasoning_tokens);
+  const totalTokens =
+    num(raw.total_tokens) ??
+    (inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined);
+
+  return record({
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    cachedInputTokens,
+    reasoningTokens,
+    ...billableFromOpenAIStyle(inputTokens, outputTokens, cachedInputTokens, reasoningTokens),
+  });
+}
+
+/** 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> {
+  const inputTokens = num(raw.input_tokens);
+  const outputTokens = num(raw.output_tokens);
+  const cachedInputTokens = num(raw.input_tokens_details?.cached_tokens);
+  const reasoningTokens = num(raw.output_tokens_details?.reasoning_tokens);
+  const totalTokens =
+    num(raw.total_tokens) ??
+    (inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined);
+
+  return record({
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    cachedInputTokens,
+    reasoningTokens,
+    ...billableFromOpenAIStyle(inputTokens, outputTokens, cachedInputTokens, reasoningTokens),
+  });
+}
+
+/** 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 inputTokens = 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 = [inputTokens, cacheWriteInputTokens, cachedInputTokens].filter(
+    (n): n is number => n !== undefined,
+  );
+  const summedInput = inputParts.length > 0 ? inputParts.reduce((sum, n) => sum + n, 0) : undefined;
+  const totalTokens =
+    summedInput !== undefined && outputTokens !== undefined ? summedInput + outputTokens : undefined;
+
+  let billableInputTokens: number | undefined;
+  if (inputTokens !== undefined || cacheWriteInputTokens !== undefined) {
+    billableInputTokens = (inputTokens ?? 0) + (cacheWriteInputTokens ?? 0);
+  }
+
+  return record({
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    cachedInputTokens,
+    cacheWriteInputTokens,
+    billableInputTokens,
+    billableOutputTokens: outputTokens,
+  });
+}
+
+/** Ollama 流式 chunk（无 cache / reasoning 细分时仅填基础与 billable 镜像） */
+export function usageFromOllama(raw: {
+  prompt_eval_count?: number;
+  eval_count?: number;
+}): Partial<Usage> {
+  const inputTokens = num(raw.prompt_eval_count);
+  const outputTokens = num(raw.eval_count);
+  const totalTokens =
+    inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined;
+
+  return record({
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    billableInputTokens: inputTokens,
+    billableOutputTokens: outputTokens,
+  });
+}

package/src/types/response.ts

@@ -13,13 +13,20 @@ export type StopReason = "end_turn" | "tool_call" | "max_output_tokens" | "conte
 // ── 辅助信息类型 ──────────────────────────────────────────────
 
 export type Usage = {
+  /** Provider prompt / input token count */
   inputTokens?: number;
+  /** Provider completion / output token count */
   outputTokens?: number;
+  /** Reasoning tokens when provider exposes output breakdown (e.g. OpenAI Responses) */
   reasoningTokens?: number;
   totalTokens?: number;
+  /** Tokens read from prompt cache (OpenAI cached_tokens, Anthropic cache_read_input_tokens) */
   cachedInputTokens?: number;
+  /** Tokens written to prompt cache (Anthropic cache_creation_input_tokens) */
   cacheWriteInputTokens?: number;
+  /** Best-effort billable input (full-rate input; excludes discounted cache reads where known) */
   billableInputTokens?: number;
+  /** Best-effort billable output (non-reasoning slice when provider gives reasoning breakdown) */
   billableOutputTokens?: number;
 };