@sembl/provider-anthropic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sembl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @sembl/provider-anthropic
+
+Anthropic provider for SEMBL. Structured output is obtained by declaring the
+target schema as a single tool and forcing the model to call it, so arguments
+come back parsed and shape-checked by the API.
+
+## Install
+
+```sh
+pnpm add @sembl/core @sembl/provider-anthropic @anthropic-ai/sdk
+```
+
+`@anthropic-ai/sdk` is a peer dependency: the host app owns the version and,
+usually, the client instance.
+
+## Usage
+
+```ts
+import { sembl, SemblConfig } from "@sembl/core";
+import { AnthropicProvider } from "@sembl/provider-anthropic";
+
+SemblConfig.configure({
+  provider: new AnthropicProvider({ model: "claude-sonnet-5", apiKey }),
+  bundle,
+});
+
+const draft = await sembl(listingHtml).partialCoerceTo(StayDetailsSchema);
+```
+
+### Bring your own client
+
+When the host app already resolves credentials its own way — Secret Manager,
+Vault, Bedrock, Vertex — pass the client instead of an API key. Anything with a
+compatible `messages.create` works, including `AnthropicBedrock` and
+`AnthropicVertex`.
+
+```ts
+const provider = new AnthropicProvider({
+  model: "claude-sonnet-5",
+  client: await getAnthropic(), // your cached, secret-managed client
+});
+```
+
+### Per-call model selection
+
+`Provider` is cheap to construct and holds no connection state, so a service
+that lets callers pick a model can build one per request over a shared client:
+
+```ts
+const provider = new AnthropicProvider({ model: req.model, client });
+await coerce(input, { provider, schema, bundle });
+```
+
+## Options
+
+| Option        | Default              | Notes                                                        |
+| ------------- | -------------------- | ------------------------------------------------------------ |
+| `model`       | —                    | Required.                                                     |
+| `client`      | —                    | Pre-built SDK client. Takes precedence over `apiKey`/`baseURL`. |
+| `apiKey`      | `ANTHROPIC_API_KEY`  | Falls back to the SDK's own env lookup.                       |
+| `baseURL`     | Anthropic production | Ignored when `client` is set.                                 |
+| `temperature` | `0`                  |                                                               |
+| `maxTokens`   | `4096`               | Anthropic requires an explicit output budget.                 |
+| `toolName`    | `extract_<SchemaId>` | Sanitized to Anthropic's `^[a-zA-Z0-9_-]{1,64}$`.             |
+| `cachePrompt` | `false`              | Cache the stable prefix — tool definition plus system prompt. |
+| `cacheTtl`    | `"5m"`               | `"5m"` or `"1h"`. Ignored unless `cachePrompt` is set.        |
+| `maxRetries`  | `2`                  | Retries per call, handled by the SDK.                         |
+| `timeoutMs`   | `120000`             | Per-attempt timeout.                                          |
+
+## Prompt caching
+
+Every call against the same schema sends the same tool definition and the same
+system prompt; only the user input differs. `cachePrompt: true` marks that
+prefix so the API processes it once and serves it from cache afterwards:
+
+```ts
+const provider = new AnthropicProvider({
+  model: "claude-sonnet-5",
+  apiKey,
+  cachePrompt: true,
+});
+```
+
+One breakpoint does the whole job. The API renders `tools` before `system`, so
+marking the trailing system block covers the tool definition too, and the user
+input — the only part that varies — sits after it in `messages`, where it
+invalidates nothing.
+
+**When it pays.** Cache reads cost about a tenth of an ordinary input token,
+but a write costs about a quarter more than one. Two calls sharing a prefix
+already break even on the 5-minute TTL; a single one-off call is slightly worse
+off than leaving caching alone. Bulk imports — hundreds of listings through one
+schema — are the case this exists for.
+
+**When it does nothing.** A prefix shorter than the model's minimum cacheable
+length is silently not cached (no error, no write): the minimum is
+model-dependent and ranges from 512 to 4096 tokens, so a handful of fields with
+short descriptions may never reach it. Caches are also scoped per model and per
+workspace, so splitting a batch across models writes a separate entry for each.
+
+**Choosing the TTL.** A read refreshes the entry, so with calls less than five
+minutes apart the default `"5m"` stays warm indefinitely and is the cheaper
+write. `"1h"` is for traffic with longer gaps — it survives them, but the write
+costs roughly twice as much, so it needs three or so calls to pay for itself.
+
+**Check that it is working.** `ProviderResponse.usage` reports it:
+
+```ts
+const { usage } = await provider.complete(request);
+usage?.cacheWriteTokens; // prefix written to cache — expect this on call one
+usage?.cacheReadTokens;  // prefix served from cache — expect this after that
+```
+
+A write on every call means something upstream is changing the prefix between
+calls: a schema description built with a timestamp in it, non-deterministic
+ordering of the enum values in a `dynamicEnum` field, a per-request tool name.
+Note that Anthropic reports these *alongside* `promptTokens` rather than inside
+it, so the prompt actually processed is the sum of the three.
+
+## Resilience
+
+Retries and timeouts are the SDK's, not a layer on top of it. It already
+retries connection errors, 408, 409, 429 and 5xx with exponential backoff and
+jitter, and honours `retry-after`. This provider only picks the numbers:
+`maxRetries` (2, the SDK's own default) and `timeoutMs` (2 minutes, down from
+the SDK's 10 — a long time for one listing to hold up an import queue).
+
+Each retry gets its own timeout, so the worst-case wall clock for a call is
+roughly `timeoutMs * (maxRetries + 1)` plus backoff. Size it accordingly.
+
+When you supply your own `client`, that client's transport policy is left
+alone unless you set `maxRetries` or `timeoutMs` explicitly — in which case
+they are applied per call, overriding the client for SEMBL's requests only.
+
+## Errors
+
+Failures arrive as `AnthropicProviderError` with a `kind` you can branch on
+instead of matching messages:
+
+| `kind`        | Means                                          | `retryable` |
+| ------------- | ---------------------------------------------- | ----------- |
+| `"api"`       | Transport or API failure — rate limit, overload, timeout, bad request | `true` when transient |
+| `"truncated"` | Output hit the token cap mid-tool-call         | `false`     |
+| `"no_output"` | The model answered without calling the extraction tool | `false` |
+
+```ts
+try {
+  await coerce(listingHtml, { provider, schema, bundle });
+} catch (error) {
+  if (error instanceof AnthropicProviderError && error.retryable) {
+    return requeue(listing); // rate limited or overloaded
+  }
+  throw error;
+}
+```
+
+`retryable` says the failure was transient in nature — the SDK has already
+retried it `maxRetries` times, so this is about whether the item is worth
+re-queueing rather than whether to loop immediately. The originating SDK error
+is kept on `cause`, and `status` / `stopReason` carry the API's own account of
+what happened. `@sembl/provider-openai` throws the same three `kind`s, so
+caller code that branches on them survives a provider swap.
+
+## Schema dialect
+
+Anthropic takes ordinary JSON Schema, so this provider emits the `"standard"`
+dialect: optional fields are omitted from `required` rather than being made
+nullable the way OpenAI structured outputs demand. That keeps the model from
+inventing explicit `null`s for fields the source never mentioned — which
+matters for `partialCoerce`, where an absent field and a null field mean
+different things to the caller.

package/dist/index.d.ts

@@ -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/dist/index.js

@@ -0,0 +1,178 @@
+// src/anthropic-provider.ts
+import Anthropic from "@anthropic-ai/sdk";
+
+// src/anthropic-config.ts
+var DEFAULT_MAX_TOKENS = 4096;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_TIMEOUT_MS = 12e4;
+
+// src/errors.ts
+import { APIConnectionError, APIError } from "@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 APIError) {
+    const status = error.status;
+    const retryable = error instanceof 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
+import { runtimeSchemaToJsonSchema } from "@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 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 Anthropic({
+        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);
+    }
+  }
+};
+export {
+  AnthropicProvider,
+  AnthropicProviderError,
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_MAX_TOKENS,
+  DEFAULT_TIMEOUT_MS,
+  toInputSchema,
+  toToolName
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/anthropic-provider.ts","../src/anthropic-config.ts","../src/errors.ts","../src/schema-converter.ts"],"sourcesContent":["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":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@sembl/provider-anthropic",
+  "version": "0.1.0",
+  "description": "Anthropic provider for SEMBL, using forced tool calls for structured output.",
+  "keywords": [
+    "llm",
+    "structured-output",
+    "anthropic",
+    "claude",
+    "tool-use",
+    "extraction"
+  ],
+  "license": "MIT",
+  "author": "Sembl contributors",
+  "homepage": "https://github.com/nickrunner/sembl#readme",
+  "bugs": {
+    "url": "https://github.com/nickrunner/sembl/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nickrunner/sembl.git",
+    "directory": "packages/provider-anthropic"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@sembl/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.30.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.65.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}