@sembl/provider-anthropic 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -0,0 +1,221 @@
+"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, {
+  AnthropicProvider: () => AnthropicProvider,
+  AnthropicProviderError: () => AnthropicProviderError,
+  DEFAULT_MAX_RETRIES: () => DEFAULT_MAX_RETRIES,
+  DEFAULT_MAX_TOKENS: () => DEFAULT_MAX_TOKENS,
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  toInputSchema: () => toInputSchema,
+  toToolName: () => toToolName
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/anthropic-provider.ts
+var import_sdk2 = __toESM(require("@anthropic-ai/sdk"), 1);
+
+// src/anthropic-config.ts
+var DEFAULT_MAX_TOKENS = 4096;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_TIMEOUT_MS = 12e4;
+
+// src/errors.ts
+var import_sdk = require("@anthropic-ai/sdk");
+var AnthropicProviderError = 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;
+  /** Anthropic's `stop_reason`, when the call returned a message we rejected. */
+  stopReason;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "AnthropicProviderError";
+    this.kind = options.kind;
+    this.retryable = options.retryable;
+    this.status = options.status;
+    this.stopReason = options.stopReason;
+  }
+};
+function toProviderError(error) {
+  if (error instanceof import_sdk.APIError) {
+    const status = error.status;
+    const retryable = error instanceof import_sdk.APIConnectionError || status === void 0 || status === 408 || status === 409 || status === 429 || status >= 500;
+    return new AnthropicProviderError(
+      `Anthropic request failed${status ? ` (${status})` : ""}: ${error.message}`,
+      { kind: "api", retryable, status, cause: error }
+    );
+  }
+  return new AnthropicProviderError(
+    `Anthropic 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 toToolName(schemaId) {
+  const cleaned = schemaId.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 57);
+  return `extract_${cleaned || "schema"}`.slice(0, 64);
+}
+function toInputSchema(schema, bundle, resolvedEnums) {
+  return (0, import_core.runtimeSchemaToJsonSchema)(schema, bundle, {
+    dialect: "standard",
+    resolvedEnums
+  });
+}
+
+// src/anthropic-provider.ts
+var AnthropicProvider = class {
+  client;
+  config;
+  callOptions;
+  constructor(config) {
+    this.config = config;
+    if (config.client) {
+      this.client = config.client;
+      this.callOptions = config.maxRetries === void 0 && config.timeoutMs === void 0 ? void 0 : { maxRetries: config.maxRetries, timeout: config.timeoutMs };
+    } else {
+      this.client = new import_sdk2.default({
+        apiKey: config.apiKey,
+        baseURL: config.baseURL,
+        maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+        timeout: config.timeoutMs ?? DEFAULT_TIMEOUT_MS
+      });
+      this.callOptions = void 0;
+    }
+  }
+  async complete(request) {
+    const toolName = this.config.toolName ?? toToolName(request.schema.id);
+    const maxTokens = this.config.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const inputSchema = toInputSchema(
+      request.schema,
+      request.bundle,
+      request.resolvedEnums
+    );
+    const message = await this.send(
+      {
+        model: this.config.model,
+        max_tokens: maxTokens,
+        temperature: this.config.temperature ?? 0,
+        system: this.buildSystem(request.systemPrompt),
+        messages: [{ role: "user", content: request.userInput }],
+        tools: [
+          {
+            name: toolName,
+            description: request.schema.description,
+            input_schema: inputSchema
+          }
+        ],
+        tool_choice: { type: "tool", name: toolName }
+      },
+      this.callOptions
+    );
+    const toolUse = message.content.find(
+      (block) => block.type === "tool_use" && block.name === toolName
+    );
+    if (!toolUse) {
+      if (message.stop_reason === "max_tokens") {
+        throw new AnthropicProviderError(
+          `Anthropic hit the ${maxTokens}-token output cap before completing the "${toolName}" call. Raise maxTokens, or coerce into a smaller schema.`,
+          { kind: "truncated", retryable: false, stopReason: "max_tokens" }
+        );
+      }
+      throw new AnthropicProviderError(
+        `Anthropic returned no "${toolName}" tool call (stop_reason: ${message.stop_reason ?? "unknown"})`,
+        {
+          kind: "no_output",
+          retryable: false,
+          stopReason: message.stop_reason ?? void 0
+        }
+      );
+    }
+    return {
+      data: toolUse.input,
+      usage: {
+        promptTokens: message.usage.input_tokens,
+        completionTokens: message.usage.output_tokens,
+        totalTokens: message.usage.input_tokens + message.usage.output_tokens,
+        ...message.usage.cache_read_input_tokens != null && {
+          cacheReadTokens: message.usage.cache_read_input_tokens
+        },
+        ...message.usage.cache_creation_input_tokens != null && {
+          cacheWriteTokens: message.usage.cache_creation_input_tokens
+        }
+      }
+    };
+  }
+  /**
+   * The system prompt, marked as a cache breakpoint when caching is on.
+   *
+   * One breakpoint is enough: the API renders `tools` before `system`, so a
+   * marker on the trailing system block covers the tool definition too — and
+   * the user input, the only part that changes between calls, sits after it
+   * in `messages` where it invalidates nothing.
+   */
+  buildSystem(systemPrompt) {
+    if (!this.config.cachePrompt) return systemPrompt;
+    return [
+      {
+        type: "text",
+        text: systemPrompt,
+        cache_control: { type: "ephemeral", ttl: this.config.cacheTtl ?? "5m" }
+      }
+    ];
+  }
+  /** Issue the call, translating SDK failures into typed provider errors. */
+  async send(body, options) {
+    try {
+      return await this.client.messages.create(body, options);
+    } catch (error) {
+      throw toProviderError(error);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AnthropicProvider,
+  AnthropicProviderError,
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_MAX_TOKENS,
+  DEFAULT_TIMEOUT_MS,
+  toInputSchema,
+  toToolName
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/anthropic-provider.ts","../src/anthropic-config.ts","../src/errors.ts","../src/schema-converter.ts"],"sourcesContent":["export { AnthropicProvider } from \"./anthropic-provider.js\";\nexport type { AnthropicProviderConfig } from \"./anthropic-config.js\";\nexport {\n  DEFAULT_MAX_TOKENS,\n  DEFAULT_MAX_RETRIES,\n  DEFAULT_TIMEOUT_MS,\n} from \"./anthropic-config.js\";\nexport { AnthropicProviderError } from \"./errors.js\";\nexport type { ProviderErrorKind } from \"./errors.js\";\nexport { toInputSchema, toToolName } from \"./schema-converter.js\";\n","import Anthropic from \"@anthropic-ai/sdk\";\nimport type { Provider, ProviderRequest, ProviderResponse } from \"@sembl/core\";\nimport type { AnthropicProviderConfig } from \"./anthropic-config.js\";\nimport {\n  DEFAULT_MAX_RETRIES,\n  DEFAULT_MAX_TOKENS,\n  DEFAULT_TIMEOUT_MS,\n} from \"./anthropic-config.js\";\nimport { AnthropicProviderError, toProviderError } from \"./errors.js\";\nimport { toInputSchema, toToolName } from \"./schema-converter.js\";\n\n/** Per-call overrides handed to the SDK alongside the request body. */\ninterface CallOptions {\n  maxRetries?: number;\n  timeout?: number;\n}\n\n/**\n * Anthropic provider implementation.\n *\n * Structured output is obtained by declaring the target schema as a single\n * tool and forcing the model to call it (`tool_choice: { type: \"tool\" }`), so\n * the arguments come back already parsed and shape-checked by the API — no\n * JSON scraped out of prose.\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 AnthropicProviderError}.\n */\nexport class AnthropicProvider implements Provider {\n  private client: Pick<Anthropic, \"messages\">;\n  private config: AnthropicProviderConfig;\n  private callOptions: CallOptions | undefined;\n\n  constructor(config: AnthropicProviderConfig) {\n    this.config = config;\n\n    if (config.client) {\n      // The host owns this client's transport policy, so only override it\n      // per-call where the caller asked for something specific.\n      this.client = config.client;\n      this.callOptions =\n        config.maxRetries === undefined && config.timeoutMs === undefined\n          ? undefined\n          : { maxRetries: config.maxRetries, timeout: config.timeoutMs };\n    } else {\n      this.client = new Anthropic({\n        apiKey: config.apiKey,\n        baseURL: config.baseURL,\n        maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,\n        timeout: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n      });\n      this.callOptions = undefined;\n    }\n  }\n\n  async complete(request: ProviderRequest): Promise<ProviderResponse> {\n    const toolName = this.config.toolName ?? toToolName(request.schema.id);\n    const maxTokens = this.config.maxTokens ?? DEFAULT_MAX_TOKENS;\n    const inputSchema = toInputSchema(\n      request.schema,\n      request.bundle,\n      request.resolvedEnums,\n    );\n\n    const message = await this.send(\n      {\n        model: this.config.model,\n        max_tokens: maxTokens,\n        temperature: this.config.temperature ?? 0,\n        system: this.buildSystem(request.systemPrompt),\n        messages: [{ role: \"user\", content: request.userInput }],\n        tools: [\n          {\n            name: toolName,\n            description: request.schema.description,\n            input_schema: inputSchema as Anthropic.Tool[\"input_schema\"],\n          },\n        ],\n        tool_choice: { type: \"tool\", name: toolName },\n      },\n      this.callOptions,\n    );\n\n    const toolUse = message.content.find(\n      (block): block is Anthropic.ToolUseBlock =>\n        block.type === \"tool_use\" && block.name === toolName,\n    );\n\n    if (!toolUse) {\n      if (message.stop_reason === \"max_tokens\") {\n        throw new AnthropicProviderError(\n          `Anthropic hit the ${maxTokens}-token output cap before completing the \"${toolName}\" call. ` +\n            \"Raise maxTokens, or coerce into a smaller schema.\",\n          { kind: \"truncated\", retryable: false, stopReason: \"max_tokens\" },\n        );\n      }\n      throw new AnthropicProviderError(\n        `Anthropic returned no \"${toolName}\" tool call (stop_reason: ${message.stop_reason ?? \"unknown\"})`,\n        {\n          kind: \"no_output\",\n          retryable: false,\n          stopReason: message.stop_reason ?? undefined,\n        },\n      );\n    }\n\n    return {\n      data: toolUse.input as Record<string, unknown>,\n      usage: {\n        promptTokens: message.usage.input_tokens,\n        completionTokens: message.usage.output_tokens,\n        totalTokens: message.usage.input_tokens + message.usage.output_tokens,\n        ...(message.usage.cache_read_input_tokens != null && {\n          cacheReadTokens: message.usage.cache_read_input_tokens,\n        }),\n        ...(message.usage.cache_creation_input_tokens != null && {\n          cacheWriteTokens: message.usage.cache_creation_input_tokens,\n        }),\n      },\n    };\n  }\n\n  /**\n   * The system prompt, marked as a cache breakpoint when caching is on.\n   *\n   * One breakpoint is enough: the API renders `tools` before `system`, so a\n   * marker on the trailing system block covers the tool definition too — and\n   * the user input, the only part that changes between calls, sits after it\n   * in `messages` where it invalidates nothing.\n   */\n  private buildSystem(\n    systemPrompt: string,\n  ): string | Anthropic.TextBlockParam[] {\n    if (!this.config.cachePrompt) return systemPrompt;\n\n    return [\n      {\n        type: \"text\",\n        text: systemPrompt,\n        cache_control: { type: \"ephemeral\", ttl: this.config.cacheTtl ?? \"5m\" },\n      },\n    ];\n  }\n\n  /** Issue the call, translating SDK failures into typed provider errors. */\n  private async send(\n    body: Anthropic.MessageCreateParamsNonStreaming,\n    options: CallOptions | undefined,\n  ): Promise<Anthropic.Message> {\n    try {\n      return await this.client.messages.create(body, options);\n    } catch (error) {\n      throw toProviderError(error);\n    }\n  }\n}\n","import type Anthropic from \"@anthropic-ai/sdk\";\nimport type { ProviderConfig } from \"@sembl/core\";\n\n/**\n * Configuration specific to the Anthropic provider.\n *\n * Supply either `client` or `apiKey`. Prefer `client` when the host app\n * already resolves credentials its own way (Secret Manager, Vault, Bedrock,\n * a Vertex client) — the provider will reuse that client as-is rather than\n * constructing its own.\n */\nexport interface AnthropicProviderConfig extends ProviderConfig {\n  /**\n   * A pre-built Anthropic client. Takes precedence over `apiKey`/`baseURL`.\n   * Also accepts an `AnthropicBedrock` / `AnthropicVertex` client — anything\n   * exposing a compatible `messages.create`.\n   */\n  client?: Pick<Anthropic, \"messages\">;\n  /** Anthropic API key. Ignored when `client` is supplied. */\n  apiKey?: string;\n  /** Base URL override. Ignored when `client` is supplied. */\n  baseURL?: string;\n  /**\n   * Name given to the extraction tool the model is forced to call.\n   * Defaults to a sanitized form of the schema id. Only override this if a\n   * name shows up somewhere you care about (logs, prompt-cache keys).\n   */\n  toolName?: string;\n  /**\n   * Mark the stable prefix of the request — the tool definition and the\n   * system prompt — as cacheable, so a run of calls against the same schema\n   * pays to process it once instead of once per call.\n   *\n   * Off by default: a cache write costs more than an ordinary read of the\n   * same tokens, so a single call, or a prefix below the model's minimum\n   * cacheable length, comes out slightly behind. Turn it on for batches.\n   * `ProviderResponse.usage.cacheReadTokens` says whether it is paying off.\n   */\n  cachePrompt?: boolean;\n  /**\n   * Lifetime of the cached prefix. Ignored unless `cachePrompt` is set.\n   *\n   * `\"5m\"` (the default) is refreshed by every read, so back-to-back calls\n   * keep it alive indefinitely and it is the cheaper write. Choose `\"1h\"`\n   * only for traffic with gaps longer than five minutes between calls — it\n   * survives the gap, but the write costs roughly twice as much.\n   */\n  cacheTtl?: \"5m\" | \"1h\";\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}. When a `client` is supplied,\n   * leaving this unset keeps that client's own policy.\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}. When a `client` is supplied,\n   * leaving this unset keeps that client's own policy.\n   */\n  timeoutMs?: number;\n}\n\n/** Anthropic requires an explicit output budget; this is used when none is set. */\nexport const DEFAULT_MAX_TOKENS = 4096;\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 listing when the retry is cheap.\n */\nexport const DEFAULT_TIMEOUT_MS = 120_000;\n","import { APIConnectionError, APIError } from \"@anthropic-ai/sdk\";\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 listing's content — retrying it changes nothing.\n *\n * The same three kinds are used by `@sembl/provider-openai`, so a caller that\n * 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 Anthropic provider.\n *\n * Branch on `kind` rather than matching the message — messages stay\n * diagnostic and are free to change.\n */\nexport class AnthropicProviderError 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  /** Anthropic's `stop_reason`, when the call returned a message we rejected. */\n  public readonly stopReason?: string;\n\n  constructor(\n    message: string,\n    options: {\n      kind: ProviderErrorKind;\n      retryable: boolean;\n      status?: number;\n      stopReason?: string;\n      cause?: unknown;\n    },\n  ) {\n    super(message, { cause: options.cause });\n    this.name = \"AnthropicProviderError\";\n    this.kind = options.kind;\n    this.retryable = options.retryable;\n    this.status = options.status;\n    this.stopReason = options.stopReason;\n  }\n}\n\n/**\n * Wrap an SDK-level failure as an `AnthropicProviderError`.\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): AnthropicProviderError {\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 AnthropicProviderError(\n      `Anthropic request failed${status ? ` (${status})` : \"\"}: ${error.message}`,\n      { kind: \"api\", retryable, status, cause: error },\n    );\n  }\n\n  // Anything else (an AbortError, a bug in a caller-supplied client) is\n  // surfaced with the same shape so callers only need one catch.\n  return new AnthropicProviderError(\n    `Anthropic request failed: ${error instanceof Error ? error.message : String(error)}`,\n    { kind: \"api\", retryable: false, cause: error },\n  );\n}\n","import type { RuntimeSchema, ResolvedEnums, SchemaBundle } from \"@sembl/core\";\nimport { runtimeSchemaToJsonSchema } from \"@sembl/core\";\n\n/** Anthropic tool names must match `^[a-zA-Z0-9_-]{1,64}$`. */\nexport function toToolName(schemaId: string): string {\n  const cleaned = schemaId.replace(/[^a-zA-Z0-9_-]/g, \"_\").slice(0, 57);\n  return `extract_${cleaned || \"schema\"}`.slice(0, 64);\n}\n\n/**\n * Convert a RuntimeSchema to an Anthropic tool `input_schema`.\n *\n * Unlike OpenAI structured outputs, Anthropic takes ordinary JSON Schema, so\n * optional fields are left out of `required` instead of being made nullable.\n * That keeps the model from inventing explicit `null`s for fields the source\n * text simply never mentioned — which matters for partial coercion, where an\n * absent field and a null field mean different things to the caller.\n */\nexport function toInputSchema(\n  schema: RuntimeSchema,\n  bundle?: SchemaBundle,\n  resolvedEnums?: ResolvedEnums,\n): Record<string, unknown> {\n  return runtimeSchemaToJsonSchema(schema, bundle, {\n    dialect: \"standard\",\n    resolvedEnums,\n  });\n}\n"],"mappings":"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","names":["import_sdk","Anthropic"]}

package/dist/index.d.cts

@@ -0,0 +1,162 @@
+import { ProviderConfig, Provider, ProviderRequest, ProviderResponse, RuntimeSchema, SchemaBundle, ResolvedEnums } from '@sembl/core';
+import Anthropic from '@anthropic-ai/sdk';
+
+/**
+ * Configuration specific to the Anthropic provider.
+ *
+ * Supply either `client` or `apiKey`. Prefer `client` when the host app
+ * already resolves credentials its own way (Secret Manager, Vault, Bedrock,
+ * a Vertex client) — the provider will reuse that client as-is rather than
+ * constructing its own.
+ */
+interface AnthropicProviderConfig extends ProviderConfig {
+    /**
+     * A pre-built Anthropic client. Takes precedence over `apiKey`/`baseURL`.
+     * Also accepts an `AnthropicBedrock` / `AnthropicVertex` client — anything
+     * exposing a compatible `messages.create`.
+     */
+    client?: Pick<Anthropic, "messages">;
+    /** Anthropic API key. Ignored when `client` is supplied. */
+    apiKey?: string;
+    /** Base URL override. Ignored when `client` is supplied. */
+    baseURL?: string;
+    /**
+     * Name given to the extraction tool the model is forced to call.
+     * Defaults to a sanitized form of the schema id. Only override this if a
+     * name shows up somewhere you care about (logs, prompt-cache keys).
+     */
+    toolName?: string;
+    /**
+     * Mark the stable prefix of the request — the tool definition and the
+     * system prompt — as cacheable, so a run of calls against the same schema
+     * pays to process it once instead of once per call.
+     *
+     * Off by default: a cache write costs more than an ordinary read of the
+     * same tokens, so a single call, or a prefix below the model's minimum
+     * cacheable length, comes out slightly behind. Turn it on for batches.
+     * `ProviderResponse.usage.cacheReadTokens` says whether it is paying off.
+     */
+    cachePrompt?: boolean;
+    /**
+     * Lifetime of the cached prefix. Ignored unless `cachePrompt` is set.
+     *
+     * `"5m"` (the default) is refreshed by every read, so back-to-back calls
+     * keep it alive indefinitely and it is the cheaper write. Choose `"1h"`
+     * only for traffic with gaps longer than five minutes between calls — it
+     * survives the gap, but the write costs roughly twice as much.
+     */
+    cacheTtl?: "5m" | "1h";
+    /**
+     * 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}. When a `client` is supplied,
+     * leaving this unset keeps that client's own policy.
+     */
+    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}. When a `client` is supplied,
+     * leaving this unset keeps that client's own policy.
+     */
+    timeoutMs?: number;
+}
+/** Anthropic requires an explicit output budget; this is used when none is set. */
+declare const DEFAULT_MAX_TOKENS = 4096;
+/** 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 listing when the retry is cheap.
+ */
+declare const DEFAULT_TIMEOUT_MS = 120000;
+
+/**
+ * Anthropic provider implementation.
+ *
+ * Structured output is obtained by declaring the target schema as a single
+ * tool and forcing the model to call it (`tool_choice: { type: "tool" }`), so
+ * the arguments come back already parsed and shape-checked by the API — no
+ * JSON scraped out of prose.
+ *
+ * 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 AnthropicProviderError}.
+ */
+declare class AnthropicProvider implements Provider {
+    private client;
+    private config;
+    private callOptions;
+    constructor(config: AnthropicProviderConfig);
+    complete(request: ProviderRequest): Promise<ProviderResponse>;
+    /**
+     * The system prompt, marked as a cache breakpoint when caching is on.
+     *
+     * One breakpoint is enough: the API renders `tools` before `system`, so a
+     * marker on the trailing system block covers the tool definition too — and
+     * the user input, the only part that changes between calls, sits after it
+     * in `messages` where it invalidates nothing.
+     */
+    private buildSystem;
+    /** Issue the call, translating SDK failures into typed provider errors. */
+    private send;
+}
+
+/**
+ * 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 listing's content — retrying it changes nothing.
+ *
+ * The same three kinds are used by `@sembl/provider-openai`, so a caller that
+ * branches on `kind` keeps working when the provider is swapped.
+ */
+type ProviderErrorKind = "api" | "truncated" | "no_output";
+/**
+ * Error thrown by the Anthropic provider.
+ *
+ * Branch on `kind` rather than matching the message — messages stay
+ * diagnostic and are free to change.
+ */
+declare class AnthropicProviderError 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;
+    /** Anthropic's `stop_reason`, when the call returned a message we rejected. */
+    readonly stopReason?: string;
+    constructor(message: string, options: {
+        kind: ProviderErrorKind;
+        retryable: boolean;
+        status?: number;
+        stopReason?: string;
+        cause?: unknown;
+    });
+}
+
+/** Anthropic tool names must match `^[a-zA-Z0-9_-]{1,64}$`. */
+declare function toToolName(schemaId: string): string;
+/**
+ * Convert a RuntimeSchema to an Anthropic tool `input_schema`.
+ *
+ * Unlike OpenAI structured outputs, Anthropic takes ordinary JSON Schema, so
+ * optional fields are left out of `required` instead of being made nullable.
+ * That keeps the model from inventing explicit `null`s for fields the source
+ * text simply never mentioned — which matters for partial coercion, where an
+ * absent field and a null field mean different things to the caller.
+ */
+declare function toInputSchema(schema: RuntimeSchema, bundle?: SchemaBundle, resolvedEnums?: ResolvedEnums): Record<string, unknown>;
+
+export { AnthropicProvider, type AnthropicProviderConfig, AnthropicProviderError, DEFAULT_MAX_RETRIES, DEFAULT_MAX_TOKENS, DEFAULT_TIMEOUT_MS, type ProviderErrorKind, toInputSchema, toToolName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sembl/provider-anthropic",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Anthropic provider for SEMBL, using forced tool calls for structured output.",
   "keywords": [
     "llm",
@@ -22,13 +22,21 @@
     "directory": "packages/provider-anthropic"
   },
   "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",
@@ -44,7 +52,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sembl/core": "0.1.0"
+    "@sembl/core": "0.2.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.30.0"