@sembl/provider-openai 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -0,0 +1,192 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_MAX_RETRIES: () => DEFAULT_MAX_RETRIES,
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  OpenAIProvider: () => OpenAIProvider,
+  OpenAIProviderError: () => OpenAIProviderError,
+  toResponseFormat: () => toResponseFormat
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/openai-provider.ts
+var import_openai2 = __toESM(require("openai"), 1);
+
+// src/openai-config.ts
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_TIMEOUT_MS = 12e4;
+
+// src/errors.ts
+var import_openai = require("openai");
+var OpenAIProviderError = class extends Error {
+  /** What class of failure this is. */
+  kind;
+  /**
+   * Whether another attempt could plausibly succeed. The SDK has already
+   * retried retryable transport failures (see `maxRetries`); this says only
+   * that the failure was transient in nature, so a caller running a queue can
+   * re-enqueue the item rather than dead-letter it.
+   */
+  retryable;
+  /** HTTP status, when the failure came back as an API error. */
+  status;
+  /** OpenAI's `finish_reason`, when the call returned a choice we rejected. */
+  finishReason;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "OpenAIProviderError";
+    this.kind = options.kind;
+    this.retryable = options.retryable;
+    this.status = options.status;
+    this.finishReason = options.finishReason;
+  }
+};
+function toProviderError(error) {
+  if (error instanceof import_openai.APIError) {
+    const status = error.status;
+    const retryable = error instanceof import_openai.APIConnectionError || status === void 0 || status === 408 || status === 409 || status === 429 || status >= 500;
+    return new OpenAIProviderError(
+      `OpenAI request failed${status ? ` (${status})` : ""}: ${error.message}`,
+      { kind: "api", retryable, status, cause: error }
+    );
+  }
+  return new OpenAIProviderError(
+    `OpenAI request failed: ${error instanceof Error ? error.message : String(error)}`,
+    { kind: "api", retryable: false, cause: error }
+  );
+}
+
+// src/schema-converter.ts
+var import_core = require("@sembl/core");
+function toResponseFormat(schema, bundle) {
+  const jsonSchema = (0, import_core.toOpenAIJsonSchema)(schema, bundle);
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: schema.id,
+      strict: true,
+      schema: jsonSchema.schema
+    }
+  };
+}
+
+// src/openai-provider.ts
+var OpenAIProvider = class {
+  client;
+  config;
+  constructor(config) {
+    this.config = config;
+    this.client = new import_openai2.default({
+      apiKey: config.apiKey,
+      baseURL: config.baseURL,
+      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+      timeout: config.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    });
+  }
+  async complete(request) {
+    const responseFormat = toResponseFormat(request.schema, request.bundle);
+    let completion;
+    try {
+      completion = await this.client.chat.completions.create({
+        model: this.config.model,
+        temperature: this.config.temperature ?? 0,
+        max_tokens: this.config.maxTokens,
+        messages: [
+          { role: "system", content: request.systemPrompt },
+          { role: "user", content: request.userInput }
+        ],
+        response_format: responseFormat
+      });
+    } catch (error) {
+      throw toProviderError(error);
+    }
+    const choice = completion.choices[0];
+    if (choice?.finish_reason === "length") {
+      const cap = this.config.maxTokens ? `the ${this.config.maxTokens}-token output cap` : "the model's default output cap";
+      throw new OpenAIProviderError(
+        `OpenAI hit ${cap} before completing the "${request.schema.id}" object. Raise maxTokens, or coerce into a smaller schema.`,
+        { kind: "truncated", retryable: false, finishReason: "length" }
+      );
+    }
+    if (choice?.message?.refusal) {
+      throw new OpenAIProviderError(
+        `OpenAI declined to extract "${request.schema.id}": ${choice.message.refusal}`,
+        {
+          kind: "no_output",
+          retryable: false,
+          finishReason: choice.finish_reason
+        }
+      );
+    }
+    if (!choice?.message?.content) {
+      throw new OpenAIProviderError(
+        `OpenAI returned no content in response (finish_reason: ${choice?.finish_reason ?? "unknown"})`,
+        {
+          kind: "no_output",
+          retryable: false,
+          finishReason: choice?.finish_reason
+        }
+      );
+    }
+    let data;
+    try {
+      data = JSON.parse(choice.message.content);
+    } catch (error) {
+      throw new OpenAIProviderError(
+        `OpenAI returned content that is not valid JSON for "${request.schema.id}"`,
+        { kind: "no_output", retryable: false, cause: error }
+      );
+    }
+    return {
+      data,
+      usage: completion.usage ? {
+        promptTokens: completion.usage.prompt_tokens,
+        completionTokens: completion.usage.completion_tokens,
+        totalTokens: completion.usage.total_tokens,
+        // OpenAI caches long prefixes automatically and reports only what
+        // it served from cache — there is no write to account for.
+        ...completion.usage.prompt_tokens_details?.cached_tokens != null && {
+          cacheReadTokens: completion.usage.prompt_tokens_details.cached_tokens
+        }
+      } : void 0
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_TIMEOUT_MS,
+  OpenAIProvider,
+  OpenAIProviderError,
+  toResponseFormat
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/openai-provider.ts","../src/openai-config.ts","../src/errors.ts","../src/schema-converter.ts"],"sourcesContent":["export { OpenAIProvider } from \"./openai-provider.js\";\nexport type { OpenAIProviderConfig } from \"./openai-config.js\";\nexport { DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS } from \"./openai-config.js\";\nexport { OpenAIProviderError } from \"./errors.js\";\nexport type { ProviderErrorKind } from \"./errors.js\";\nexport { toResponseFormat } from \"./schema-converter.js\";\n","import OpenAI from \"openai\";\nimport type { Provider, ProviderRequest, ProviderResponse } from \"@sembl/core\";\nimport type { OpenAIProviderConfig } from \"./openai-config.js\";\nimport { DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS } from \"./openai-config.js\";\nimport { OpenAIProviderError, toProviderError } from \"./errors.js\";\nimport { toResponseFormat } from \"./schema-converter.js\";\n\n/**\n * OpenAI provider implementation using structured outputs (json_schema response_format).\n *\n * Retries and timeouts are the SDK's (exponential backoff, `retry-after`\n * aware); this class only chooses the numbers and translates whatever comes\n * back out into an {@link OpenAIProviderError}.\n */\nexport class OpenAIProvider implements Provider {\n  private client: OpenAI;\n  private config: OpenAIProviderConfig;\n\n  constructor(config: OpenAIProviderConfig) {\n    this.config = config;\n    this.client = new OpenAI({\n      apiKey: config.apiKey,\n      baseURL: config.baseURL,\n      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,\n      timeout: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    });\n  }\n\n  async complete(request: ProviderRequest): Promise<ProviderResponse> {\n    const responseFormat = toResponseFormat(request.schema, request.bundle);\n\n    let completion;\n    try {\n      completion = await this.client.chat.completions.create({\n        model: this.config.model,\n        temperature: this.config.temperature ?? 0,\n        max_tokens: this.config.maxTokens,\n        messages: [\n          { role: \"system\", content: request.systemPrompt },\n          { role: \"user\", content: request.userInput },\n        ],\n        response_format: responseFormat,\n      });\n    } catch (error) {\n      throw toProviderError(error);\n    }\n\n    const choice = completion.choices[0];\n\n    // A truncated response is a budget problem, not a content one: the JSON is\n    // cut mid-object, so it would only fail to parse a step later.\n    if (choice?.finish_reason === \"length\") {\n      const cap = this.config.maxTokens\n        ? `the ${this.config.maxTokens}-token output cap`\n        : \"the model's default output cap\";\n      throw new OpenAIProviderError(\n        `OpenAI hit ${cap} before completing the \"${request.schema.id}\" object. ` +\n          \"Raise maxTokens, or coerce into a smaller schema.\",\n        { kind: \"truncated\", retryable: false, finishReason: \"length\" },\n      );\n    }\n\n    if (choice?.message?.refusal) {\n      throw new OpenAIProviderError(\n        `OpenAI declined to extract \"${request.schema.id}\": ${choice.message.refusal}`,\n        {\n          kind: \"no_output\",\n          retryable: false,\n          finishReason: choice.finish_reason,\n        },\n      );\n    }\n\n    if (!choice?.message?.content) {\n      throw new OpenAIProviderError(\n        `OpenAI returned no content in response (finish_reason: ${choice?.finish_reason ?? \"unknown\"})`,\n        {\n          kind: \"no_output\",\n          retryable: false,\n          finishReason: choice?.finish_reason,\n        },\n      );\n    }\n\n    let data: Record<string, unknown>;\n    try {\n      data = JSON.parse(choice.message.content) as Record<string, unknown>;\n    } catch (error) {\n      throw new OpenAIProviderError(\n        `OpenAI returned content that is not valid JSON for \"${request.schema.id}\"`,\n        { kind: \"no_output\", retryable: false, cause: error },\n      );\n    }\n\n    return {\n      data,\n      usage: completion.usage\n        ? {\n            promptTokens: completion.usage.prompt_tokens,\n            completionTokens: completion.usage.completion_tokens,\n            totalTokens: completion.usage.total_tokens,\n            // OpenAI caches long prefixes automatically and reports only what\n            // it served from cache — there is no write to account for.\n            ...(completion.usage.prompt_tokens_details?.cached_tokens !=\n              null && {\n              cacheReadTokens:\n                completion.usage.prompt_tokens_details.cached_tokens,\n            }),\n          }\n        : undefined,\n    };\n  }\n}\n","import type { ProviderConfig } from \"@sembl/core\";\n\n/**\n * Configuration specific to the OpenAI provider.\n */\nexport interface OpenAIProviderConfig extends ProviderConfig {\n  /** OpenAI API key. Defaults to OPENAI_API_KEY env var. */\n  apiKey?: string;\n  /** Base URL for the OpenAI API. Defaults to OpenAI's production endpoint. */\n  baseURL?: string;\n  /**\n   * How many times the SDK retries a failed call before giving up. The SDK\n   * retries connection errors, 408/409/429 and 5xx with exponential backoff\n   * and honours `retry-after`, so there is nothing to hand-roll here.\n   *\n   * Defaults to {@link DEFAULT_MAX_RETRIES}.\n   */\n  maxRetries?: number;\n  /**\n   * Timeout for a single attempt, in milliseconds. Retries each get their\n   * own attempt, so the worst-case wall clock is roughly\n   * `timeoutMs * (maxRetries + 1)` plus backoff.\n   *\n   * Defaults to {@link DEFAULT_TIMEOUT_MS}.\n   */\n  timeoutMs?: number;\n}\n\n/** Matches the SDK's own default; stated here so it survives an SDK change. */\nexport const DEFAULT_MAX_RETRIES = 2;\n\n/**\n * Two minutes per attempt. The SDK's own default is ten, which is a long time\n * for a backend import to sit on one record when the retry is cheap.\n */\nexport const DEFAULT_TIMEOUT_MS = 120_000;\n","import { APIConnectionError, APIError } from \"openai\";\n\n/**\n * Why a provider call failed, in the terms a caller can act on.\n *\n * A batch import wants to route these differently: `\"api\"` failures are worth\n * re-queueing, `\"truncated\"` needs a bigger output budget, and `\"no_output\"`\n * is a property of that one input's content — retrying it changes nothing.\n *\n * The same three kinds are used by `@sembl/provider-anthropic`, so a caller\n * that branches on `kind` keeps working when the provider is swapped.\n */\nexport type ProviderErrorKind = \"api\" | \"truncated\" | \"no_output\";\n\n/**\n * Error thrown by the OpenAI provider.\n *\n * Branch on `kind` rather than matching the message — messages stay\n * diagnostic and are free to change.\n */\nexport class OpenAIProviderError extends Error {\n  /** What class of failure this is. */\n  public readonly kind: ProviderErrorKind;\n  /**\n   * Whether another attempt could plausibly succeed. The SDK has already\n   * retried retryable transport failures (see `maxRetries`); this says only\n   * that the failure was transient in nature, so a caller running a queue can\n   * re-enqueue the item rather than dead-letter it.\n   */\n  public readonly retryable: boolean;\n  /** HTTP status, when the failure came back as an API error. */\n  public readonly status?: number;\n  /** OpenAI's `finish_reason`, when the call returned a choice we rejected. */\n  public readonly finishReason?: string;\n\n  constructor(\n    message: string,\n    options: {\n      kind: ProviderErrorKind;\n      retryable: boolean;\n      status?: number;\n      finishReason?: string;\n      cause?: unknown;\n    },\n  ) {\n    super(message, { cause: options.cause });\n    this.name = \"OpenAIProviderError\";\n    this.kind = options.kind;\n    this.retryable = options.retryable;\n    this.status = options.status;\n    this.finishReason = options.finishReason;\n  }\n}\n\n/**\n * Wrap an SDK-level failure as an `OpenAIProviderError`.\n *\n * Retryability is read off the SDK's own error classes rather than the\n * message: connection failures and timeouts are transient by construction,\n * and of the status codes only 408/409/429 and 5xx are worth another attempt —\n * the same set the SDK itself retries internally.\n */\nexport function toProviderError(error: unknown): OpenAIProviderError {\n  if (error instanceof APIError) {\n    const status = error.status;\n    const retryable =\n      error instanceof APIConnectionError ||\n      status === undefined ||\n      status === 408 ||\n      status === 409 ||\n      status === 429 ||\n      status >= 500;\n\n    return new OpenAIProviderError(\n      `OpenAI request failed${status ? ` (${status})` : \"\"}: ${error.message}`,\n      { kind: \"api\", retryable, status, cause: error },\n    );\n  }\n\n  // Anything else (an AbortError, a bug in the transport) is surfaced with the\n  // same shape so callers only need one catch.\n  return new OpenAIProviderError(\n    `OpenAI request failed: ${error instanceof Error ? error.message : String(error)}`,\n    { kind: \"api\", retryable: false, cause: error },\n  );\n}\n","import type { RuntimeSchema, SchemaBundle } from \"@sembl/core\";\nimport { toOpenAIJsonSchema } from \"@sembl/core\";\nimport type OpenAI from \"openai\";\n\ntype ResponseFormatJSONSchema =\n  OpenAI.ChatCompletionCreateParams[\"response_format\"] & { type: \"json_schema\" };\n\n/**\n * Convert a RuntimeSchema to an OpenAI-compatible response_format parameter.\n * Applies OpenAI strict mode constraints:\n * - All properties in `required` array\n * - Optional fields use anyOf: [type, { type: \"null\" }]\n * - additionalProperties: false on every object\n * - Everything inlined (no $ref)\n */\nexport function toResponseFormat(\n  schema: RuntimeSchema,\n  bundle?: SchemaBundle,\n): ResponseFormatJSONSchema {\n  const jsonSchema = toOpenAIJsonSchema(schema, bundle);\n\n  return {\n    type: \"json_schema\",\n    json_schema: {\n      name: schema.id,\n      strict: true,\n      schema: jsonSchema.schema as Record<string, unknown>,\n    },\n  } as ResponseFormatJSONSchema;\n}\n"],"mappings":"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","names":["import_openai","OpenAI"]}

package/dist/index.d.cts

@@ -0,0 +1,104 @@
+import { ProviderConfig, Provider, ProviderRequest, ProviderResponse, RuntimeSchema, SchemaBundle } from '@sembl/core';
+import OpenAI from 'openai';
+
+/**
+ * Configuration specific to the OpenAI provider.
+ */
+interface OpenAIProviderConfig extends ProviderConfig {
+    /** OpenAI API key. Defaults to OPENAI_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL for the OpenAI API. Defaults to OpenAI's production endpoint. */
+    baseURL?: string;
+    /**
+     * How many times the SDK retries a failed call before giving up. The SDK
+     * retries connection errors, 408/409/429 and 5xx with exponential backoff
+     * and honours `retry-after`, so there is nothing to hand-roll here.
+     *
+     * Defaults to {@link DEFAULT_MAX_RETRIES}.
+     */
+    maxRetries?: number;
+    /**
+     * Timeout for a single attempt, in milliseconds. Retries each get their
+     * own attempt, so the worst-case wall clock is roughly
+     * `timeoutMs * (maxRetries + 1)` plus backoff.
+     *
+     * Defaults to {@link DEFAULT_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
+}
+/** Matches the SDK's own default; stated here so it survives an SDK change. */
+declare const DEFAULT_MAX_RETRIES = 2;
+/**
+ * Two minutes per attempt. The SDK's own default is ten, which is a long time
+ * for a backend import to sit on one record when the retry is cheap.
+ */
+declare const DEFAULT_TIMEOUT_MS = 120000;
+
+/**
+ * OpenAI provider implementation using structured outputs (json_schema response_format).
+ *
+ * Retries and timeouts are the SDK's (exponential backoff, `retry-after`
+ * aware); this class only chooses the numbers and translates whatever comes
+ * back out into an {@link OpenAIProviderError}.
+ */
+declare class OpenAIProvider implements Provider {
+    private client;
+    private config;
+    constructor(config: OpenAIProviderConfig);
+    complete(request: ProviderRequest): Promise<ProviderResponse>;
+}
+
+/**
+ * Why a provider call failed, in the terms a caller can act on.
+ *
+ * A batch import wants to route these differently: `"api"` failures are worth
+ * re-queueing, `"truncated"` needs a bigger output budget, and `"no_output"`
+ * is a property of that one input's content — retrying it changes nothing.
+ *
+ * The same three kinds are used by `@sembl/provider-anthropic`, so a caller
+ * that branches on `kind` keeps working when the provider is swapped.
+ */
+type ProviderErrorKind = "api" | "truncated" | "no_output";
+/**
+ * Error thrown by the OpenAI provider.
+ *
+ * Branch on `kind` rather than matching the message — messages stay
+ * diagnostic and are free to change.
+ */
+declare class OpenAIProviderError extends Error {
+    /** What class of failure this is. */
+    readonly kind: ProviderErrorKind;
+    /**
+     * Whether another attempt could plausibly succeed. The SDK has already
+     * retried retryable transport failures (see `maxRetries`); this says only
+     * that the failure was transient in nature, so a caller running a queue can
+     * re-enqueue the item rather than dead-letter it.
+     */
+    readonly retryable: boolean;
+    /** HTTP status, when the failure came back as an API error. */
+    readonly status?: number;
+    /** OpenAI's `finish_reason`, when the call returned a choice we rejected. */
+    readonly finishReason?: string;
+    constructor(message: string, options: {
+        kind: ProviderErrorKind;
+        retryable: boolean;
+        status?: number;
+        finishReason?: string;
+        cause?: unknown;
+    });
+}
+
+type ResponseFormatJSONSchema = OpenAI.ChatCompletionCreateParams["response_format"] & {
+    type: "json_schema";
+};
+/**
+ * Convert a RuntimeSchema to an OpenAI-compatible response_format parameter.
+ * Applies OpenAI strict mode constraints:
+ * - All properties in `required` array
+ * - Optional fields use anyOf: [type, { type: "null" }]
+ * - additionalProperties: false on every object
+ * - Everything inlined (no $ref)
+ */
+declare function toResponseFormat(schema: RuntimeSchema, bundle?: SchemaBundle): ResponseFormatJSONSchema;
+
+export { DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, OpenAIProvider, type OpenAIProviderConfig, OpenAIProviderError, type ProviderErrorKind, toResponseFormat };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sembl/provider-openai",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenAI provider for SEMBL, using structured outputs.",
   "keywords": [
     "llm",
@@ -21,13 +21,21 @@
     "directory": "packages/provider-openai"
   },
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -43,7 +51,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sembl/core": "0.1.0"
+    "@sembl/core": "0.2.0"
   },
   "devDependencies": {
     "openai": "^4.0.0",