@aeye/openai 0.3.9 → 0.4.0

package/aeye-openai.md

@@ -1,178 +1,189 @@
-# @aeye/openai
-
-One-line purpose: OpenAI provider for the `@aeye/ai` framework — chat, vision, reasoning, tools, structured output, image generation/edit, transcription, speech, and embeddings via the official `openai` SDK. Also the base class for any OpenAI-compatible provider.
-
-## When to use
-
-- You want to call OpenAI (GPT-4o, GPT-4, o-series, DALL-E, gpt-image, Whisper, TTS, text-embedding-3-*) through `@aeye/ai`.
-- You need a base class to build an OpenAI-compatible provider (Azure OpenAI, OpenRouter, local OpenAI-shaped endpoints). `@aeye/openrouter` is built this way.
-
-## Install / import
-
-```bash
-npm install @aeye/openai openai
-```
-
-```typescript
-import {
-  OpenAIProvider,
-  type OpenAIConfig,
-  type OpenAIHooks,
-  // error classes (from @aeye/openai)
-  ProviderError,
-  ProviderAuthError,
-  RateLimitError,
-  ProviderRateLimitError,
-  ProviderQuotaError,
-  ContextWindowError,
-} from '@aeye/openai';
-```
-
-`@aeye/ai` and `@aeye/core` are peer/runtime dependencies (they ship as `dependencies`). The `openai` SDK and `zod` are also dependencies.
-
-## Register with an `@aeye/ai` instance
-
-A provider is registered by passing it into `AI.with().providers({...})`. The key you give it is the provider's local name in the registry.
-
-```typescript
-import { AI } from '@aeye/ai';
-import { OpenAIProvider } from '@aeye/openai';
-
-const openai = new OpenAIProvider({
-  apiKey: process.env.OPENAI_API_KEY!,
-});
-
-const ai = AI.with()
-  .providers({ openai })
-  .create({ /* AI config: modelSources, hooks, defaultContext, ... */ });
-
-// Chat
-const response = await ai.chat.get({
-  messages: [{ role: 'user', content: 'Hello!' }],
-});
-console.log(response.content);
-
-// Explicit model selection is done via metadata, not the provider
-const r2 = await ai.chat.get(
-  { messages: [{ role: 'user', content: 'Hi' }] },
-  { metadata: { model: 'openai/gpt-4o' } }
-);
-```
-
-You can also use the provider directly without the `AI` facade:
-
-```typescript
-const executor = openai.createExecutor();
-const res = await executor(
-  { messages: [{ role: 'user', content: 'Hello!' }] },
-  {},                 // AIContext
-  { model: 'gpt-4o' } // AIMetadata
-);
-```
-
-## Authentication / credentials
-
-- `apiKey` is **required** on `OpenAIConfig` (typed `string`). Conventionally supply `process.env.OPENAI_API_KEY`.
-- `organization` and `project` map to the OpenAI SDK's `organization` / `project` options.
-- `baseURL` lets you point at an OpenAI-compatible endpoint (e.g. Azure). There is no special env var handling in this package — credentials come from the config object you pass.
-
-## Configuration (`OpenAIConfig`)
-
-| Field | Type | Notes |
-|-------|------|-------|
-| `apiKey` | `string` (required) | OpenAI API key |
-| `baseURL` | `string` | Custom/compatible endpoint |
-| `organization` | `string` | Org ID |
-| `project` | `string` | Project ID |
-| `store` | `boolean` | Allow OpenAI to store call contents. Defaults to `false` |
-| `retry` | `RetryConfig` | Per-provider retry (maxRetries, initialDelay, retryableStatuses, etc.) |
-| `retryEvents` | `RetryEvents` | Retry lifecycle callbacks (e.g. `onRetry`) |
-| `hooks` | `OpenAIHooks` | Per-operation `beforeRequest` / `afterRequest` / `onError` |
-| `defaultModels` | object | Fallback model per capability: `chat`, `imageGenerate`, `imageEdit`, `imageAnalyze`, `transcription`, `speech`, `embedding` |
-
-Retry config can also be overridden per request via `request.extra.retry` / `request.extra.retryEvents`.
-
-### Hooks
-
-`OpenAIHooks` has a block per operation: `chat`, `imageGenerate`, `imageEdit`, `imageAnalyze`, `transcribe`, `speech`, `embed`. Each block may define `beforeRequest(request, params, ctx, metadata)`, `afterRequest(request, params, response, ctx, metadata)`, and `onError(request, params, error, ctx, metadata)`. The `params` argument is the raw OpenAI SDK params, so you can inspect/mutate the exact wire payload.
-
-## Supported capabilities
-
-| Capability | API surface | Models |
-|-----------|-------------|--------|
-| Chat (+ streaming) | `ai.chat.get` / `ai.chat.stream` | GPT-4o, GPT-4, GPT-3.5, o-series |
-| Vision | `ai.chat` with `image` content | GPT-4o / GPT-4V |
-| Reasoning | `ai.chat` with `request.reason.effort` → `reasoning_effort` | o1, o3-mini, etc. |
-| Tools / function calling | `ai.chat` with `tools` | GPT-4o, GPT-4 |
-| Structured output | `ai.chat` with a schema `responseFormat` | GPT-4o (strict json_schema) |
-| Image generation | `ai.image.generate` | `dall-e-2`, `dall-e-3`, `gpt-image-*` |
-| Image edit | `ai.image.edit` | `dall-e-2`, `gpt-image-*` |
-| Transcription (+ stream) | `ai.transcribe` | `whisper-1`, gpt-4o transcribe |
-| Speech / TTS | `ai.speech` | `tts-1`, `tts-1-hd`, gpt-4o-mini-tts |
-| Embeddings | `ai.embed` | `text-embedding-3-small` / `-large` |
-
-### Strict / structured output
-
-The provider only emits OpenAI-shaped strict schemas (`supportedStrictFamilies = {'openai'}`). Strict mode for a tool or structured output engages only when the resolved model's strict format is `openai` **and** the model declares the `toolsStrict` / `structured` capability; otherwise it silently falls back to a lenient (non-strict) schema. A shared `SchemaBudget` is used so tools and the response format cooperate on per-request limits.
-
-## Usage examples
-
-```typescript
-// Vision
-await ai.chat.get({
-  messages: [{
-    role: 'user',
-    content: [
-      { type: 'text', content: 'Describe this image' },
-      { type: 'image', content: 'https://example.com/cat.png' },
-    ],
-  }],
-});
-
-// Tools
-import { z } from 'zod';
-await ai.chat.get({
-  messages: [{ role: 'user', content: 'Weather in SF?' }],
-  tools: [{
-    name: 'get_weather',
-    description: 'Get current weather',
-    parameters: z.object({ location: z.string() }),
-  }],
-  toolChoice: 'auto',
-});
-
-// Image generation
-await ai.image.generate.get({ prompt: 'A sunset over mountains', size: '1024x1024' });
-
-// Embeddings
-await ai.embed.get({ texts: ['Hello world'] });
-```
-
-## Extending for OpenAI-compatible providers
-
-`OpenAIProvider<TConfig>` is designed for subclassing. Override:
-
-- `createClient(config)` — point at a different `baseURL` / set custom headers.
-- `convertModel(model)` — enrich `ModelInfo`.
-- `listModels(config)` — custom model discovery.
-- `augmentChatRequest` / `augmentChatMessage` / `augmentChatContent` / `augmentChatChunk` / `augmentChatResponse` — inject provider-specific params and parse extra response fields.
-- `augmentImageGenerateRequest`, `augmentImageEditRequest`, `augmentTranscriptionRequest`, `augmentSpeechRequest`, `augmentEmbeddingRequest`.
-- `supportedStrictFamilies` — widen accepted strict descriptor families.
-
-```typescript
-class AzureProvider extends OpenAIProvider {
-  readonly name = 'azure';
-  protected createClient(config: OpenAIConfig) {
-    return new OpenAI({ apiKey: config.apiKey, baseURL: 'https://my.openai.azure.com/v1' });
-  }
-}
-```
-
-## Gotchas
-
-- `apiKey` is required by the type; this package does not auto-read `OPENAI_API_KEY` for you (you pass it in).
-- Model is required at request time — supply it via `request.model`, `ctx.metadata.model`, request metadata, or `defaultModels`. Missing model throws `ProviderError`.
-- `store` defaults to `false`; set it explicitly if you rely on OpenAI storing calls.
-- Context-window overflow is not thrown on the chat path — the executor/streamer returns a `Response` with `finishReason: 'length'` instead.
-- Streaming chat always sends `stream_options.include_usage: true` so usage arrives in trailing chunks.
-- Retry types (`RetryConfig`, `RetryEvents`) are accepted structurally via `OpenAIConfig` but are not re-exported from the package entry point.
+# @aeye/openai
+
+One-line purpose: OpenAI provider for the `@aeye/ai` framework — chat (Chat Completions or the Responses API), vision, reasoning, tools, hosted tools, structured output, audio output, image generation/edit, transcription, speech, and embeddings via the official `openai` SDK. Also the base class for any OpenAI-compatible provider.
+
+## When to use
+
+- You want to call OpenAI (GPT-5.x, GPT-6, GPT-4.1, gpt-audio, GPT Image, gpt-transcribe, TTS, text-embedding-3-*) through `@aeye/ai`.
+- You need a base class to build an OpenAI-compatible provider (Azure OpenAI, OpenRouter, local OpenAI-shaped endpoints). `@aeye/openrouter` is built this way.
+
+## Install / import
+
+```bash
+npm install @aeye/openai openai
+```
+
+```typescript
+import {
+  OpenAIProvider,
+  type OpenAIConfig,
+  type OpenAIHooks,
+  // error classes (from @aeye/openai)
+  ProviderError,
+  ProviderAuthError,
+  RateLimitError,
+  ProviderRateLimitError,
+  ProviderQuotaError,
+  ContextWindowError,
+} from '@aeye/openai';
+```
+
+`@aeye/ai` and `@aeye/core` are peer/runtime dependencies (they ship as `dependencies`). The `openai` SDK (v7) and `zod` are also dependencies. Requires Node >= 22.
+
+## Register with an `@aeye/ai` instance
+
+A provider is registered by passing it into `AI.with().providers({...})`. The key you give it is the provider's local name in the registry.
+
+```typescript
+import { AI } from '@aeye/ai';
+import { OpenAIProvider } from '@aeye/openai';
+
+const openai = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+});
+
+const ai = AI.with()
+  .providers({ openai })
+  .create({ /* AI config: modelSources, hooks, defaultContext, ... */ });
+
+// Chat
+const response = await ai.chat.get({
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+console.log(response.content);
+
+// Explicit model selection is done via metadata, not the provider
+const r2 = await ai.chat.get(
+  { messages: [{ role: 'user', content: 'Hi' }] },
+  { metadata: { model: 'openai/gpt-5.4-mini' } }
+);
+```
+
+You can also use the provider directly without the `AI` facade:
+
+```typescript
+const executor = openai.createExecutor();
+const res = await executor(
+  { messages: [{ role: 'user', content: 'Hello!' }] },
+  {},                 // AIContext
+  { model: 'gpt-5.4-mini' } // AIMetadata
+);
+```
+
+## Authentication / credentials
+
+- `apiKey` is **required** on `OpenAIConfig` (typed `string`). Conventionally supply `process.env.OPENAI_API_KEY`.
+- `organization` and `project` map to the OpenAI SDK's `organization` / `project` options.
+- `baseURL` lets you point at an OpenAI-compatible endpoint (e.g. Azure). There is no special env var handling in this package — credentials come from the config object you pass.
+
+## Configuration (`OpenAIConfig`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `apiKey` | `string` (required) | OpenAI API key |
+| `baseURL` | `string` | Custom/compatible endpoint |
+| `organization` | `string` | Org ID |
+| `project` | `string` | Project ID |
+| `store` | `boolean` | Allow OpenAI to store call contents. Defaults to `false` |
+| `api` | `'auto' \| 'chat' \| 'responses'` | Which API chat uses. `auto` (default) picks Responses for Responses-only models (registry `metadata.responsesOnly`, else by id: codex, pre-5.6 pro, deep-research, computer-use), `hostedTools`, or `reason.mode`/`summary`/`context` |
+| `retry` | `RetryConfig` | Per-provider retry (maxRetries, initialDelay, retryableStatuses, etc.) |
+| `retryEvents` | `RetryEvents` | Retry lifecycle callbacks (e.g. `onRetry`) |
+| `hooks` | `OpenAIHooks` | Per-operation `beforeRequest` / `afterRequest` / `onError` |
+| `defaultModels` | object | Fallback model per capability: `chat`, `imageGenerate`, `imageEdit`, `imageAnalyze`, `transcription`, `speech`, `embedding`. Built-in defaults (the protected `defaults` property, overridable by subclasses): `gpt-image-2`, `gpt-5.4-mini` (image analysis), `gpt-transcribe`, `gpt-4o-mini-tts`, `text-embedding-3-small`; no chat default |
+
+Retry config can also be overridden per request via `request.extra.retry` / `request.extra.retryEvents`.
+
+### Hooks
+
+`OpenAIHooks` has a block per operation in `OpenAIOperations`: `chat`, `responses`, `imageGenerate`, `imageEdit`, `transcribe`, `speech`, `embed`. Image analysis runs as chat and reports through the `chat` (or `responses`) hooks. Each block may define `beforeRequest(request, params, ctx, metadata)`, `afterRequest(request, params, response, ctx, metadata)`, and `onError(request, params, error, ctx, metadata)`. The `params` argument is the raw OpenAI SDK params, so you can inspect/mutate the exact wire payload.
+
+## Supported capabilities
+
+| Capability | API surface | Models |
+|-----------|-------------|--------|
+| Chat (+ streaming) | `ai.chat.get` / `ai.chat.stream` | GPT-5.x, GPT-6, GPT-4.1, o3 |
+| Vision / files | `ai.chat` with `image` / `file` content (`detail`, `name`) | GPT-5.x, GPT-6, GPT-4.1 |
+| Reasoning | `ai.chat` with `request.reason` — `effort` (`none`..`max`, clamped to the model's `reasoningEfforts`) → `reasoning_effort`; `summary`/`mode`/`context` use Responses | GPT-5.x, GPT-6, o3 |
+| Tools / function calling | `ai.chat` with `tools` | GPT-5.x, GPT-6, GPT-4.1 |
+| Hosted tools | `ai.chat` with `hostedTools` (Responses): `web_search` (allowedDomains only), `file_search`, `code_interpreter`, `image_generation`, `mcp`; `web_fetch` rejected | Responses models |
+| Structured output | `ai.chat` with a schema `responseFormat` | GPT-5.x, GPT-6, GPT-4.1 (strict json_schema) |
+| Audio output | `ai.chat` with `modalities: ['text', 'audio']` + `audio: { voice, format }` | `gpt-audio-1.5` |
+| Image generation (+ stream) | `ai.image.generate` | GPT Image (`gpt-image-2`) |
+| Image edit (+ stream) | `ai.image.edit` (`image` + `references`, `mask`, `inputFidelity`) | GPT Image (`gpt-image-2`) |
+| Transcription (+ stream) | `ai.transcribe` (incl. `diarized_json` + `knownSpeakers`) | `gpt-transcribe`, `gpt-4o-transcribe-diarize`, `whisper-1` |
+| Speech / TTS | `ai.speech` (any voice, incl. custom voice ids) | `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd` |
+| Embeddings | `ai.embed` | `text-embedding-3-small` / `-large` |
+
+Other request fields passed through: `seed`, `verbosity`, `serviceTier`, `metadata` (Chat Completions sends it only when `store` is on), `moderate` (inline `omni-moderation-latest`), `cacheBreakpoint` on content. Responses carry `citations`, `images`, `audio`, `moderation`, `serviceTier`; `usage` counts cache writes, audio, reasoning, and hosted tool calls once each.
+
+Through Responses, reasoning comes back encrypted (`include: reasoning.encrypted_content`, unless `store` is on) as `openai-responses-v1` reasoning details and is replayed from the assistant message's `reasoning` on later turns.
+
+### Strict / structured output
+
+The provider only emits OpenAI-shaped strict schemas (`supportedStrictFamilies = {'openai'}`). Strict mode for a tool or structured output engages only when the resolved model's strict format is `openai` **and** the model declares the `toolsStrict` / `structured` capability; otherwise it silently falls back to the family's non-strict descriptor. When selection supplies only a model id (no `ModelInfo`), the family is still resolved from the id, so the family's non-strict dialect is kept; strict needs the `ModelInfo` capabilities. A shared `SchemaBudget` is used so tools and the response format cooperate on per-request limits.
+
+That default is correct for api.openai.com, which speaks exactly one dialect. **A subclass that fronts other providers' models must widen it** — `supportedStrictFamilies` is the gate on the whole family resolution, so leaving it at `{'openai'}` sends every other family's tool schemas out as LENIENT no matter what the model declares. `OpenRouterProvider` sets `{'openai', 'anthropic', 'google', 'xai'}` for this reason; `AWSProvider` sets `{'openai', 'anthropic', 'google'}`.
+
+## Usage examples
+
+```typescript
+// Vision
+await ai.chat.get({
+  messages: [{
+    role: 'user',
+    content: [
+      { type: 'text', content: 'Describe this image' },
+      { type: 'image', content: 'https://example.com/cat.png' },
+    ],
+  }],
+});
+
+// Tools
+import { z } from 'zod';
+await ai.chat.get({
+  messages: [{ role: 'user', content: 'Weather in SF?' }],
+  tools: [{
+    name: 'get_weather',
+    description: 'Get current weather',
+    parameters: z.object({ location: z.string() }),
+  }],
+  toolChoice: 'auto',
+});
+
+// Image generation
+await ai.image.generate.get({ prompt: 'A sunset over mountains', size: '1024x1024' });
+
+// Embeddings
+await ai.embed.get({ texts: ['Hello world'] });
+```
+
+## Extending for OpenAI-compatible providers
+
+`OpenAIProvider<TConfig>` is designed for subclassing. Override:
+
+- `createClient(config)` — point at a different `baseURL` / set custom headers.
+- `convertModel(model)` — enrich `ModelInfo`.
+- `listModels(config)` — custom model discovery.
+- `augmentChatRequest` / `augmentChatMessage` / `augmentChatContent` / `augmentChatChunk` / `augmentChatResponse` — inject provider-specific params and parse extra response fields.
+- `augmentImageGenerateRequest`, `augmentImageEditRequest`, `augmentTranscriptionRequest`, `augmentSpeechRequest`, `augmentEmbeddingRequest`.
+- `supportedStrictFamilies` — widen accepted strict descriptor families.
+- `usesResponses(request, modelId, config, model?)` — decide when chat goes to the Responses API.
+- `defaults` — the built-in default model id per operation.
+
+```typescript
+class AzureProvider extends OpenAIProvider {
+  readonly name = 'azure';
+  protected createClient(config: OpenAIConfig) {
+    return new OpenAI({ apiKey: config.apiKey, baseURL: 'https://my.openai.azure.com/v1' });
+  }
+}
+```
+
+## Gotchas
+
+- `apiKey` is required by the type; this package does not auto-read `OPENAI_API_KEY` for you (you pass it in).
+- Model is required at request time — supply it via `request.model`, `ctx.metadata.model`, request metadata, or `defaultModels`. Missing model throws `ProviderError`.
+- `store` defaults to `false`; set it explicitly if you rely on OpenAI storing calls.
+- Context-window overflow is not thrown on the chat path — the executor/streamer returns a `Response` with `finishReason: 'length'` instead.
+- Streaming chat always sends `stream_options.include_usage: true` so usage arrives in trailing chunks.
+- Retry types (`RetryConfig`, `RetryEvents`) are accepted structurally via `OpenAIConfig` but are not re-exported from the package entry point.

package/dist/convert.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Conversions from OpenAI wire shapes to @aeye shapes, shared by the Chat
+ * Completions, Responses, and media endpoints.
+ */
+import type { AudioFormat, Citation, Moderation, ServiceTier, Usage } from '@aeye/core';
+import OpenAI from 'openai';
+/**
+ * Token totals as an endpoint reports them, before splitting into Usage
+ * categories. Detail counts are subsets of their total.
+ */
+export interface TokenCounts {
+    input?: number;
+    output?: number;
+    cached?: number;
+    cacheWrite?: number;
+    audioInput?: number;
+    reasoning?: number;
+    audioOutput?: number;
+}
+/**
+ * Splits token totals into Usage categories so each token is counted once:
+ * cache reads and writes and audio come out of the input total; reasoning
+ * and audio output come out of the output total.
+ */
+export declare function toUsage(counts: TokenCounts): Usage;
+/**
+ * Usage reported by Chat Completions (and OpenAI-compatible endpoints).
+ */
+export declare function chatUsage(usage: OpenAI.CompletionUsage): Usage;
+/**
+ * Usage reported by the Responses API.
+ */
+export declare function responsesUsage(usage: OpenAI.Responses.ResponseUsage): Usage;
+/**
+ * Usage reported by transcription: tokens for token-billed models, seconds
+ * for duration-billed ones (OpenAI-compatible routers may omit `type`).
+ */
+export declare function transcriptionUsage(usage: OpenAI.Audio.Transcription.Tokens | OpenAI.Audio.Transcription.Duration): Usage;
+/**
+ * The tier a response reports it ran on.
+ */
+export declare function toServiceTier(tier: string | null | undefined): ServiceTier | undefined;
+/**
+ * A URL citation, as both Chat Completions and Responses report them.
+ */
+export declare function toCitation(citation: {
+    url: string;
+    title?: string;
+    start_index?: number;
+    end_index?: number;
+}): Citation;
+/**
+ * One side of a moderation verdict, as both Chat Completions and Responses
+ * report it: results, or an error when moderation itself failed.
+ */
+interface WireModerationSide {
+    type: string;
+    results?: Array<{
+        flagged: boolean;
+        categories: {
+            [category: string]: boolean;
+        };
+    }>;
+}
+/**
+ * Moderation verdicts for the input and the output.
+ */
+export declare function toModeration(moderation: {
+    input: WireModerationSide;
+    output: WireModerationSide;
+}): Moderation;
+/**
+ * The model OpenAI runs moderation with when a request asks for it.
+ */
+export declare const MODERATION_MODEL = "omni-moderation-latest";
+/**
+ * Chat Completions names 16-bit PCM `pcm16`.
+ */
+export declare function toChatAudioFormat(format: AudioFormat): OpenAI.Chat.ChatCompletionAudioParam['format'];
+export {};
+//# sourceMappingURL=convert.d.ts.map

package/dist/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAoB,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC1G,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAoBlD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,eAAe,GAAG,KAAK,CAU9D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,aAAa,GAAG,KAAK,CAQ3E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,QAAQ,GAAG,KAAK,CAIxH;AAcD;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAEtF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAExH;AAED;;;GAGG;AACH,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE;YAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CACpF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAAG,UAAU,CAM9G;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,2BAA2B,CAAC;AAEzD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAErG"}

package/dist/convert.js

@@ -0,0 +1,108 @@
+/**
+ * Conversions from OpenAI wire shapes to @aeye shapes, shared by the Chat
+ * Completions, Responses, and media endpoints.
+ */
+/**
+ * Splits token totals into Usage categories so each token is counted once:
+ * cache reads and writes and audio come out of the input total; reasoning
+ * and audio output come out of the output total.
+ */
+export function toUsage(counts) {
+    const nonZero = (n = 0) => n > 0 ? n : undefined;
+    const usage = {};
+    const text = {
+        input: nonZero((counts.input ?? 0) - (counts.cached ?? 0) - (counts.cacheWrite ?? 0) - (counts.audioInput ?? 0)),
+        output: nonZero((counts.output ?? 0) - (counts.reasoning ?? 0) - (counts.audioOutput ?? 0)),
+        cached: nonZero(counts.cached),
+        cacheWrite: nonZero(counts.cacheWrite),
+    };
+    if (text.input || text.output || text.cached || text.cacheWrite) {
+        usage.text = text;
+    }
+    if (counts.reasoning) {
+        usage.reasoning = { output: counts.reasoning };
+    }
+    if (counts.audioInput || counts.audioOutput) {
+        usage.audio = { input: nonZero(counts.audioInput), output: nonZero(counts.audioOutput) };
+    }
+    return usage;
+}
+/**
+ * Usage reported by Chat Completions (and OpenAI-compatible endpoints).
+ */
+export function chatUsage(usage) {
+    return toUsage({
+        input: usage.prompt_tokens,
+        output: usage.completion_tokens,
+        cached: usage.prompt_tokens_details?.cached_tokens,
+        cacheWrite: usage.prompt_tokens_details?.cache_write_tokens,
+        audioInput: usage.prompt_tokens_details?.audio_tokens,
+        reasoning: usage.completion_tokens_details?.reasoning_tokens,
+        audioOutput: usage.completion_tokens_details?.audio_tokens,
+    });
+}
+/**
+ * Usage reported by the Responses API.
+ */
+export function responsesUsage(usage) {
+    return toUsage({
+        input: usage.input_tokens,
+        output: usage.output_tokens,
+        cached: usage.input_tokens_details.cached_tokens,
+        cacheWrite: usage.input_tokens_details.cache_write_tokens,
+        reasoning: usage.output_tokens_details.reasoning_tokens,
+    });
+}
+/**
+ * Usage reported by transcription: tokens for token-billed models, seconds
+ * for duration-billed ones (OpenAI-compatible routers may omit `type`).
+ */
+export function transcriptionUsage(usage) {
+    return 'seconds' in usage
+        ? { audio: { seconds: usage.seconds } }
+        : toUsage({ input: usage.input_tokens, output: usage.output_tokens, audioInput: usage.input_token_details?.audio_tokens });
+}
+/**
+ * Wire tiers to @aeye tiers. `priority` is the older name for `fast`.
+ */
+const SERVICE_TIERS = {
+    auto: 'auto',
+    default: 'default',
+    flex: 'flex',
+    fast: 'fast',
+    priority: 'fast',
+    scale: 'scale',
+};
+/**
+ * The tier a response reports it ran on.
+ */
+export function toServiceTier(tier) {
+    return tier ? SERVICE_TIERS[tier] : undefined;
+}
+/**
+ * A URL citation, as both Chat Completions and Responses report them.
+ */
+export function toCitation(citation) {
+    return { url: citation.url, title: citation.title, start: citation.start_index, end: citation.end_index };
+}
+/**
+ * Moderation verdicts for the input and the output.
+ */
+export function toModeration(moderation) {
+    const side = ({ results }) => results && {
+        flagged: results.some(result => result.flagged),
+        categories: [...new Set(results.flatMap(result => Object.keys(result.categories).filter(category => result.categories[category])))],
+    };
+    return { input: side(moderation.input), output: side(moderation.output) };
+}
+/**
+ * The model OpenAI runs moderation with when a request asks for it.
+ */
+export const MODERATION_MODEL = 'omni-moderation-latest';
+/**
+ * Chat Completions names 16-bit PCM `pcm16`.
+ */
+export function toChatAudioFormat(format) {
+    return format === 'pcm' ? 'pcm16' : format;
+}
+//# sourceMappingURL=convert.js.map

package/dist/convert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.js","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"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"}