@intx/inference-discovery-anthropic 0.1.2

package/README.md

@@ -0,0 +1,69 @@
+# @intx/inference-discovery-anthropic
+
+Anthropic provider plug-in for the discovery rig. Captures Claude
+wire responses across streaming and non-streaming variants of each
+capability and writes them into the shared fixture corpus.
+
+See [`@intx/inference-discovery`](../inference-discovery/README.md)
+for the runtime, the plug-in contract, and the `discover` CLI.
+
+## Models
+
+- `claude-sonnet-4-5-20250929`
+- `claude-opus-4-1-20250805`
+- `claude-haiku-4-5-20251001`
+
+The full per-capability list is in `SUPPORT_MATRIX` in
+`@intx/inference-discovery/catalog`.
+
+## Usage
+
+```ts
+import { createAnthropicPlugin } from "@intx/inference-discovery-anthropic";
+
+const plugin = createAnthropicPlugin({ apiKey: process.env.ANTHROPIC_API_KEY });
+// Hand off to runCapture from @intx/inference-discovery.
+```
+
+In practice the `bin/discover.ts` CLI does this wiring for you;
+construct the plug-in directly only when writing tests or one-off
+scripts.
+
+## Environment
+
+| Variable            | Purpose                         |
+| ------------------- | ------------------------------- |
+| `ANTHROPIC_API_KEY` | Sent as the `x-api-key` header. |
+
+The key is redacted in captured fixtures.
+
+## Multi-step capabilities
+
+Three capability families drive multi-step exchanges before the
+runner writes the bundle:
+
+- **Files API** (`files-api-reference`,
+  `files-api-reference-streaming`) — the plug-in first uploads the
+  intent's media asset to the Anthropic files endpoint, then uses
+  the returned file id to construct the messages body for the
+  second step. Each step writes its own `upload/` and `generate/`
+  subdirectory under the run root.
+- **Multi-turn function calling**
+  (`function-calling-multi-turn`,
+  `function-calling-multi-turn-streaming`,
+  `function-calling-with-thinking`,
+  `function-calling-with-thinking-streaming`) — turn 1 is sent as
+  usual; the plug-in extracts the model's content blocks from the
+  parsed response and sends a turn-2 body that echoes the
+  assistant turn verbatim and appends the tool result. Each turn
+  writes its own `turn-1/` and `turn-2/` subdirectory.
+- **Redacted thinking**
+  (`redacted-thinking`, `redacted-thinking-streaming`) — turn 1
+  produces a redacted thinking block that turn 2 must echo back
+  verbatim; the plug-in extracts the redacted block from the
+  response and assembles the turn-2 body around it.
+
+The Files API and code-execution capabilities additionally set
+per-step beta-flag headers (`files-api-2025-04-14`,
+`code-execution-2025-05-22`). All other capabilities are
+single-step.

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@intx/inference-discovery-anthropic",
+  "version": "0.1.2",
+  "license": "LGPL-2.1-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@intx/inference-discovery": "0.0.0",
+    "arktype": "^2.1.29"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,17 @@
+// API version pin recommended by Anthropic for first-party clients. New
+// versions opt in to wire-shape changes; we pin so captures stay stable
+// across upstream rollouts and only move under a deliberate bump here.
+export const ANTHROPIC_VERSION = "2023-06-01";
+
+export const API_KEY_HEADER = "x-api-key";
+export const VERSION_HEADER = "anthropic-version";
+
+export function buildAuthHeaders(apiKey: string): Record<string, string> {
+  if (apiKey.length === 0) {
+    throw new Error("anthropic: apiKey must be a non-empty string");
+  }
+  return {
+    [API_KEY_HEADER]: apiKey,
+    [VERSION_HEADER]: ANTHROPIC_VERSION,
+  };
+}

package/src/endpoint.ts

@@ -0,0 +1,19 @@
+import type { Capability } from "@intx/inference-discovery/catalog";
+
+export const ANTHROPIC_BASE = "https://api.anthropic.com";
+export const MESSAGES_PATH = "/v1/messages";
+export const FILES_PATH = "/v1/files";
+
+// Both streaming and non-streaming requests target /v1/messages; the
+// `stream: true` field in the request body is what distinguishes them.
+export function buildMessagesURL(): string {
+  return `${ANTHROPIC_BASE}${MESSAGES_PATH}`;
+}
+
+export function buildFilesURL(): string {
+  return `${ANTHROPIC_BASE}${FILES_PATH}`;
+}
+
+export function isStreamingCapability(capability: Capability): boolean {
+  return capability.endsWith("-streaming");
+}

package/src/index.ts

@@ -0,0 +1,308 @@
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import {
+  resolveMediaPath,
+  type Capability,
+  type CapabilityIntent,
+} from "@intx/inference-discovery/catalog";
+import type {
+  CaptureStep,
+  CapturedResponse,
+  IterateCaptureStepsOpts,
+  ProviderPlugin,
+} from "@intx/inference-discovery";
+import { buildAuthHeaders } from "./auth";
+import {
+  buildFilesURL,
+  buildMessagesURL,
+  isStreamingCapability,
+} from "./endpoint";
+import { mediaTypeFor } from "./media";
+import {
+  buildFilesApiGenerateBody,
+  buildFunctionCallingTurn2Body,
+  buildRedactedThinkingTurn2Body,
+  buildRequestBody,
+} from "./request-body";
+import { extractReasoningTrace } from "./reasoning";
+import { extractContentBlocksFromSSE } from "./sse";
+
+const PROVIDER_NAME = "anthropic";
+
+const MODELS = [
+  "claude-sonnet-4-5-20250929",
+  "claude-opus-4-1-20250805",
+  "claude-haiku-4-5-20251001",
+] as const;
+
+const REDACT_REQUEST_HEADERS = ["x-api-key"] as const;
+const REDACT_RESPONSE_HEADERS: readonly string[] = [];
+
+// Beta-flag header markers Anthropic requires for opt-in features.
+// These live on per-step headers (not in buildAuthHeaders) because they
+// apply per-request, not per-plug-in; auth headers are plug-in-wide.
+const FILES_API_BETA = "files-api-2025-04-14";
+const CODE_EXECUTION_BETA = "code-execution-2025-05-22";
+
+const FUNCTION_CALLING_MULTI_TURN_CAPABILITIES: ReadonlySet<Capability> =
+  new Set<Capability>([
+    "function-calling-multi-turn",
+    "function-calling-multi-turn-streaming",
+    "function-calling-with-thinking",
+    "function-calling-with-thinking-streaming",
+  ]);
+
+const REDACTED_THINKING_CAPABILITIES: ReadonlySet<Capability> =
+  new Set<Capability>(["redacted-thinking", "redacted-thinking-streaming"]);
+
+const FILES_API_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
+  "files-api-reference",
+  "files-api-reference-streaming",
+]);
+
+const CODE_EXECUTION_CAPABILITIES: ReadonlySet<Capability> =
+  new Set<Capability>(["code-execution", "code-execution-streaming"]);
+
+export interface AnthropicPluginOptions {
+  apiKey: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function basename(p: string): string {
+  const slash = p.lastIndexOf("/");
+  return slash < 0 ? p : p.slice(slash + 1);
+}
+
+function perCapabilityHeaders(
+  capability: Capability,
+): Record<string, string> | undefined {
+  if (FILES_API_CAPABILITIES.has(capability)) {
+    return { "anthropic-beta": FILES_API_BETA };
+  }
+  if (CODE_EXECUTION_CAPABILITIES.has(capability)) {
+    return { "anthropic-beta": CODE_EXECUTION_BETA };
+  }
+  return undefined;
+}
+
+function withPerCapabilityHeaders(
+  capability: Capability,
+  step: CaptureStep,
+): CaptureStep {
+  const extra = perCapabilityHeaders(capability);
+  if (extra === undefined) return step;
+  return { ...step, headers: { ...(step.headers ?? {}), ...extra } };
+}
+
+interface MultipartUpload {
+  contentType: string;
+  body: Uint8Array;
+}
+
+function buildMultipartUpload(opts: {
+  fieldName: string;
+  filename: string;
+  contentType: string;
+  bytes: Uint8Array;
+}): MultipartUpload {
+  // Boundary is regenerated on every call, which means a captured
+  // request-headers.json carries a run-specific Content-Type header.
+  // Byte-diffing regenerated fixtures against committed ones will
+  // always differ on the boundary; structural comparison is the right
+  // tool for files-api fixture equivalence.
+  const boundary = `----intx-anthropic-${randomUUID().replace(/-/g, "")}`;
+  const encoder = new TextEncoder();
+  const preamble = encoder.encode(
+    `--${boundary}\r\n` +
+      `Content-Disposition: form-data; name="${opts.fieldName}"; filename="${opts.filename}"\r\n` +
+      `Content-Type: ${opts.contentType}\r\n\r\n`,
+  );
+  const epilogue = encoder.encode(`\r\n--${boundary}--\r\n`);
+  const body = new Uint8Array(
+    preamble.length + opts.bytes.length + epilogue.length,
+  );
+  body.set(preamble, 0);
+  body.set(opts.bytes, preamble.length);
+  body.set(epilogue, preamble.length + opts.bytes.length);
+  return {
+    contentType: `multipart/form-data; boundary=${boundary}`,
+    body,
+  };
+}
+
+function buildFilesUploadStep(intent: CapabilityIntent): {
+  step: CaptureStep;
+  filename: string;
+  mediaType: string;
+} {
+  const media = intent.media?.[0];
+  if (media === undefined) {
+    throw new Error(
+      "anthropic files-api: intent.media[0] is required; the catalog's " +
+        "files-api-reference intent must declare the document to upload.",
+    );
+  }
+  const buf = readFileSync(resolveMediaPath(media));
+  const bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  const filename = basename(media.path);
+  const mediaType = mediaTypeFor(media);
+  const multipart = buildMultipartUpload({
+    fieldName: "file",
+    filename,
+    contentType: mediaType,
+    bytes,
+  });
+  return {
+    step: {
+      kind: "raw",
+      subdir: "upload",
+      url: buildFilesURL(),
+      method: "POST",
+      contentType: multipart.contentType,
+      headers: { "anthropic-beta": FILES_API_BETA },
+      body: multipart.body,
+    },
+    filename,
+    mediaType,
+  };
+}
+
+function extractFileId(parsed: unknown): string {
+  if (!isRecord(parsed)) {
+    throw new Error(
+      "anthropic files-api: upload response is not a JSON object",
+    );
+  }
+  const id = parsed.id;
+  if (typeof id !== "string" || id.length === 0) {
+    throw new Error(
+      "anthropic files-api: upload response has no string 'id' field",
+    );
+  }
+  return id;
+}
+
+function makeJsonStep(opts: {
+  capability: Capability;
+  subdir: string | null;
+  body: unknown;
+}): CaptureStep {
+  return withPerCapabilityHeaders(opts.capability, {
+    kind: "json",
+    subdir: opts.subdir,
+    url: buildMessagesURL(),
+    body: opts.body,
+  });
+}
+
+// Reconstructs the assistant content blocks from turn-1's CapturedResponse.
+// For JSON turn-1, that is the parsed message body. For SSE turn-1, the
+// runner returns bytes and we parse them through the SSE event stream.
+// Both paths surface the blocks in the shape buildFunctionCallingTurn2Body
+// and buildRedactedThinkingTurn2Body expect.
+function turn1AssistantResponse(turn1: CapturedResponse): unknown {
+  if (turn1.parsed !== null) return turn1.parsed;
+  if (turn1.bytes === null) {
+    throw new Error(
+      "anthropic multi-turn: turn-1 CapturedResponse had neither parsed body nor SSE bytes",
+    );
+  }
+  const blocks = extractContentBlocksFromSSE(turn1.bytes);
+  return { content: blocks };
+}
+
+export function* iterateCaptureSteps(
+  opts: IterateCaptureStepsOpts,
+): Generator<CaptureStep, void, CapturedResponse> {
+  const { model, capability, intent } = opts;
+
+  if (FILES_API_CAPABILITIES.has(capability)) {
+    const upload = buildFilesUploadStep(intent);
+    const uploadResponse = yield upload.step;
+    const fileId = extractFileId(uploadResponse.parsed);
+    const generateBody = buildFilesApiGenerateBody({
+      model,
+      fileId,
+      intent,
+      stream: isStreamingCapability(capability),
+    });
+    yield makeJsonStep({
+      capability,
+      subdir: "generate",
+      body: generateBody,
+    });
+    return;
+  }
+
+  if (FUNCTION_CALLING_MULTI_TURN_CAPABILITIES.has(capability)) {
+    const turn1Body = buildRequestBody({ model, capability, intent });
+    const turn1Response = yield makeJsonStep({
+      capability,
+      subdir: "turn-1",
+      body: turn1Body,
+    });
+    const turn2Body = buildFunctionCallingTurn2Body({
+      model,
+      capability,
+      intent,
+      turn1Body,
+      turn1Response: turn1AssistantResponse(turn1Response),
+    });
+    yield makeJsonStep({
+      capability,
+      subdir: "turn-2",
+      body: turn2Body,
+    });
+    return;
+  }
+
+  if (REDACTED_THINKING_CAPABILITIES.has(capability)) {
+    // Turn-1 carries the canary prompt and thinking enabled; Anthropic
+    // returns either thinking or redacted_thinking blocks depending on
+    // whether the safety classifier fires. Turn-2 echoes the assistant
+    // content blocks verbatim and prompts a brief follow-up so the
+    // round-trip is exercised on the wire.
+    const turn1Body = buildRequestBody({ model, capability, intent });
+    const turn1Response = yield makeJsonStep({
+      capability,
+      subdir: "turn-1",
+      body: turn1Body,
+    });
+    const turn2Body = buildRedactedThinkingTurn2Body({
+      model,
+      intent,
+      turn1Body,
+      turn1Response: turn1AssistantResponse(turn1Response),
+    });
+    yield makeJsonStep({
+      capability,
+      subdir: "turn-2",
+      body: turn2Body,
+    });
+    return;
+  }
+
+  yield makeJsonStep({
+    capability,
+    subdir: null,
+    body: buildRequestBody({ model, capability, intent }),
+  });
+}
+
+export function createAnthropicPlugin(
+  opts: AnthropicPluginOptions,
+): ProviderPlugin {
+  const apiKey = opts.apiKey;
+  return {
+    name: PROVIDER_NAME,
+    models: MODELS,
+    redactRequestHeaders: REDACT_REQUEST_HEADERS,
+    redactResponseHeaders: REDACT_RESPONSE_HEADERS,
+    buildAuthHeaders: () => buildAuthHeaders(apiKey),
+    extractReasoningTrace,
+    iterateCaptureSteps,
+  };
+}

package/src/media.ts

@@ -0,0 +1,35 @@
+import type { MediaRef } from "@intx/inference-discovery/catalog";
+
+// Single source of truth for the extension → MIME type mapping used by
+// both the inline media path (vision-input, document-input) and the
+// Files API upload path. Adding a new extension here is the only place
+// it needs to land for both call sites to pick it up.
+const EXTENSION_TO_MEDIA_TYPE: Readonly<Record<string, string>> = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  pdf: "application/pdf",
+};
+
+export function extensionFor(path: string): string {
+  const dot = path.lastIndexOf(".");
+  if (dot < 0 || dot === path.length - 1) {
+    throw new Error(
+      `anthropic: cannot infer media type, no extension in path: ${path}`,
+    );
+  }
+  return path.slice(dot + 1).toLowerCase();
+}
+
+export function mediaTypeFor(ref: MediaRef): string {
+  const ext = extensionFor(ref.path);
+  const mime = EXTENSION_TO_MEDIA_TYPE[ext];
+  if (mime === undefined) {
+    throw new Error(
+      `anthropic: no media-type mapping for extension .${ext} (path ${ref.path})`,
+    );
+  }
+  return mime;
+}