@providerkit/core 0.1.0

package/src/providers/anthropic.ts

@@ -0,0 +1,315 @@
+// Anthropic-shape adapter — SSE from POST /v1/messages.
+import { ProviderError } from "../errors.ts";
+import { streamSse, apiUrl } from "../transport.ts";
+import type {
+  ChatMessage,
+  ContentPart,
+  Effort,
+  FinishReason,
+  Provider,
+  ProviderChunk,
+  StreamOptions,
+  ToolDefinition,
+} from "../types.ts";
+
+export interface AnthropicConfig {
+  apiKey: string;
+  model: string;
+  baseUrl?: string;
+  /** Bound default; a per-call `effort` overrides it. */
+  effort?: Effort;
+  /** Anthropic requires an output ceiling on every request. */
+  maxTokens?: number;
+  version?: string;
+  fetchImpl?: typeof fetch;
+  /** Send the key as a Bearer instead of `x-api-key` — what a subscription
+   *  access token needs. */
+  bearer?: boolean;
+}
+
+const DEFAULT_BASE_URL = "https://api.anthropic.com";
+const DEFAULT_VERSION = "2023-06-01";
+/** Anthropic rejects a request without one, so a default is not optional. */
+const DEFAULT_MAX_TOKENS = 8_192;
+
+/**
+ * Thinking budgets, in output tokens. Thinking and the answer SHARE
+ * `max_tokens`, so a budget is always left below the ceiling — a budget at or
+ * above it leaves no room to answer, and the turn ends mid-thought.
+ */
+const THINKING_BUDGET: Record<Exclude<Effort, "none">, number> = {
+  low: 2_048,
+  medium: 8_192,
+  high: 16_384,
+  max: 32_768,
+};
+
+function mapStopReason(reason: string | undefined): FinishReason | undefined {
+  switch (reason) {
+    case "end_turn":
+    case "stop_sequence":
+      return "stop";
+    case "tool_use":
+      return "tool_calls";
+    case "max_tokens":
+      return "length";
+    case "refusal":
+      return "content_filter";
+    default:
+      return undefined;
+  }
+}
+
+function partsToAnthropic(content: string | ContentPart[]): unknown[] {
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  return content.map((part) =>
+    part.type === "text"
+      ? { type: "text", text: part.text }
+      : {
+          type: "image",
+          source: { type: "base64", media_type: part.mimeType, data: part.data },
+        },
+  );
+}
+
+/**
+ * Anthropic takes `system` at the top level and expects tool RESULTS as user
+ * turns carrying `tool_result` blocks — not as a role of their own. Consecutive
+ * tool results are merged into one user turn, which the API requires.
+ */
+export function toAnthropicMessages(messages: readonly ChatMessage[]): {
+  system?: string;
+  messages: unknown[];
+} {
+  const system = messages
+    .filter((m) => m.role === "system")
+    .map((m) => m.content)
+    .join("\n\n");
+
+  const out: { role: string; content: unknown[] }[] = [];
+  const pushBlocks = (role: string, blocks: unknown[]) => {
+    const last = out[out.length - 1];
+    if (last?.role === role) last.content.push(...blocks);
+    else out.push({ role, content: blocks });
+  };
+
+  for (const message of messages) {
+    if (message.role === "system") continue;
+    if (message.role === "user") {
+      pushBlocks("user", partsToAnthropic(message.content));
+      continue;
+    }
+    if (message.role === "tool") {
+      pushBlocks("user", [
+        {
+          type: "tool_result",
+          tool_use_id: message.toolCallId,
+          content: [
+            { type: "text", text: message.content },
+            ...(message.images ?? []).map((image) => ({
+              type: "image",
+              source: { type: "base64", media_type: image.mimeType, data: image.data },
+            })),
+          ],
+        },
+      ]);
+      continue;
+    }
+    // assistant. Reasoning is deliberately NOT replayed: Anthropic's thinking
+    // blocks carry signatures we never captured, and a block without its
+    // signature is rejected.
+    const blocks: unknown[] = [];
+    if (message.content) blocks.push({ type: "text", text: message.content });
+    for (const call of message.toolCalls ?? []) {
+      blocks.push({
+        type: "tool_use",
+        id: call.id,
+        name: call.name,
+        input: safeParse(call.arguments),
+      });
+    }
+    if (blocks.length > 0) pushBlocks("assistant", blocks);
+  }
+
+  return { ...(system ? { system } : {}), messages: out };
+}
+
+function safeParse(raw: string): unknown {
+  try {
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+interface AnthropicEvent {
+  type?: string;
+  message?: {
+    usage?: {
+      input_tokens?: number;
+      output_tokens?: number;
+      cache_read_input_tokens?: number;
+      cache_creation_input_tokens?: number;
+    };
+  };
+  content_block?: { type?: string; id?: string; name?: string };
+  delta?: {
+    type?: string;
+    text?: string;
+    thinking?: string;
+    partial_json?: string;
+    stop_reason?: string;
+  };
+  usage?: { output_tokens?: number };
+  index?: number;
+  error?: { message?: string; type?: string };
+}
+
+export function createAnthropicProvider(config: AnthropicConfig): Provider {
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+
+  return {
+    id: "anthropic",
+    model: config.model,
+
+    async *createStream(
+      messages: ChatMessage[],
+      tools: ToolDefinition[],
+      opts: StreamOptions = {},
+    ): AsyncIterable<ProviderChunk> {
+      const model = opts.model ?? config.model;
+      const maxTokens = opts.maxTokens ?? config.maxTokens ?? DEFAULT_MAX_TOKENS;
+      const effort = opts.effort ?? config.effort ?? "none";
+      const { system, messages: body } = toAnthropicMessages(messages);
+
+      const request: Record<string, unknown> = {
+        model,
+        max_tokens: maxTokens,
+        messages: body,
+        stream: true,
+      };
+      if (system) request.system = system;
+      if (opts.temperature !== undefined) request.temperature = opts.temperature;
+      if (tools.length > 0) {
+        request.tools = tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          input_schema: tool.inputSchema,
+        }));
+      }
+      if (opts.toolChoice && opts.toolChoice !== "auto") {
+        request.tool_choice =
+          opts.toolChoice === "none"
+            ? { type: "none" }
+            : opts.toolChoice === "required"
+              ? { type: "any" }
+              : { type: "tool", name: opts.toolChoice.name };
+      }
+      if (effort !== "none") {
+        const budget = Math.min(THINKING_BUDGET[effort], Math.floor(maxTokens * 0.8));
+        request.thinking = { type: "enabled", budget_tokens: budget };
+        // Thinking and sampling are mutually exclusive on this shape.
+        delete request.temperature;
+      }
+
+      // Anthropic reports cache reads and writes as fields of their OWN,
+      // EXCLUDED from `input_tokens` — where the OpenAI shapes report a cached
+      // subset already inside the prompt count. Reconciling here is what keeps
+      // one usage record meaningful across both, and a cost figure honest.
+      let inputTokens = 0;
+      let cachedInputTokens = 0;
+      let cacheWriteTokens = 0;
+      let outputTokens = 0;
+      let toolCall: { index: number; id: string; name: string } | null = null;
+      let blockIndex = -1;
+
+      for await (const data of streamSse({
+        url: apiUrl(baseUrl, "/v1/messages"),
+        headers: {
+          "anthropic-version": config.version ?? DEFAULT_VERSION,
+          ...(config.bearer
+            ? { authorization: `Bearer ${config.apiKey}` }
+            : { "x-api-key": config.apiKey }),
+        },
+        body: request,
+        provider: "anthropic",
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+      })) {
+        let event: AnthropicEvent;
+        try {
+          event = JSON.parse(data) as AnthropicEvent;
+        } catch {
+          continue; // a keep-alive or a frame we do not model
+        }
+
+        switch (event.type) {
+          case "error":
+            throw new ProviderError(
+              "anthropic",
+              "overload",
+              event.error?.message ?? "anthropic stream error",
+              { code: event.error?.type },
+            );
+
+          case "message_start": {
+            const usage = event.message?.usage;
+            cachedInputTokens = usage?.cache_read_input_tokens ?? 0;
+            cacheWriteTokens = usage?.cache_creation_input_tokens ?? 0;
+            inputTokens = (usage?.input_tokens ?? 0) + cachedInputTokens + cacheWriteTokens;
+            break;
+          }
+
+          case "content_block_start": {
+            blockIndex += 1;
+            if (event.content_block?.type === "tool_use") {
+              toolCall = {
+                index: blockIndex,
+                id: event.content_block.id ?? "",
+                name: event.content_block.name ?? "",
+              };
+              yield {
+                type: "delta",
+                toolCalls: [{ index: toolCall.index, id: toolCall.id, name: toolCall.name }],
+              };
+            }
+            break;
+          }
+
+          case "content_block_delta": {
+            const delta = event.delta;
+            if (delta?.type === "text_delta" && delta.text) {
+              yield { type: "delta", content: delta.text };
+            } else if (delta?.type === "thinking_delta" && delta.thinking) {
+              yield { type: "delta", reasoning: delta.thinking };
+            } else if (delta?.type === "input_json_delta" && toolCall) {
+              yield {
+                type: "delta",
+                toolCalls: [{ index: toolCall.index, arguments: delta.partial_json ?? "" }],
+              };
+            }
+            break;
+          }
+
+          case "content_block_stop":
+            toolCall = null;
+            break;
+
+          case "message_delta": {
+            outputTokens = event.usage?.output_tokens ?? outputTokens;
+            const finishReason = mapStopReason(event.delta?.stop_reason);
+            if (finishReason) yield { type: "finish", finishReason };
+            break;
+          }
+
+          case "message_stop":
+            yield {
+              type: "usage",
+              usage: { inputTokens, cachedInputTokens, cacheWriteTokens, outputTokens },
+            };
+            break;
+        }
+      }
+    },
+  };
+}

package/src/providers/openai.ts

@@ -0,0 +1,246 @@
+// OpenAI-shape adapter — SSE from POST /v1/chat/completions.
+//
+// This is the dialect most gateways speak, so one adapter serves OpenAI,
+// OpenRouter, DeepSeek, GLM, Kimi, Groq, Together, vLLM, Ollama and LM Studio.
+// Their divergences are small and named where they appear.
+import { streamSse, apiUrl } from "../transport.ts";
+import type {
+  ChatMessage,
+  ContentPart,
+  Effort,
+  FinishReason,
+  Provider,
+  ProviderChunk,
+  StreamOptions,
+  ToolDefinition,
+} from "../types.ts";
+import { toDataUri } from "../types.ts";
+
+export interface OpenAIConfig {
+  apiKey: string;
+  model: string;
+  /** Any OpenAI-compatible endpoint. Defaults to OpenAI itself. */
+  baseUrl?: string;
+  /** Names the provider in errors and logs — "openrouter", "deepseek", … */
+  id?: string;
+  effort?: Effort;
+  maxTokens?: number;
+  fetchImpl?: typeof fetch;
+  headers?: Record<string, string>;
+  /**
+   * Pin OpenRouter to preferred upstream hosts so the PROMPT CACHE stays warm
+   * across rounds. The cache lives on the upstream host's account and default
+   * routing hops between them, and every hop is a cold cache — worse latency
+   * and higher effective input cost. Fallbacks stay on: this is a preference,
+   * not a lock.
+   */
+  providerOrder?: string[];
+}
+
+const DEFAULT_BASE_URL = "https://api.openai.com";
+
+function mapFinishReason(reason: string | null | undefined): FinishReason | undefined {
+  switch (reason) {
+    case "stop":
+      return "stop";
+    case "length":
+      return "length";
+    case "tool_calls":
+    case "function_call":
+      return "tool_calls";
+    case "content_filter":
+      return "content_filter";
+    default:
+      return undefined;
+  }
+}
+
+function partsToOpenAI(content: string | ContentPart[]): unknown {
+  if (typeof content === "string") return content;
+  return content.map((part) =>
+    part.type === "text"
+      ? { type: "text", text: part.text }
+      : { type: "image_url", image_url: { url: toDataUri(part) } },
+  );
+}
+
+/**
+ * Assistant turns carry `reasoning_content` when the history has it — thinking
+ * providers require the prior turn's chain-of-thought replayed on a turn that
+ * made a tool call. A caller running a turn with thinking OFF must strip it
+ * first (`stripReasoning`); the two cannot be mixed.
+ */
+export function toOpenAIMessages(messages: readonly ChatMessage[]): unknown[] {
+  return messages.map((message) => {
+    switch (message.role) {
+      case "system":
+        return { role: "system", content: message.content };
+      case "user":
+        return { role: "user", content: partsToOpenAI(message.content) };
+      case "tool":
+        return { role: "tool", tool_call_id: message.toolCallId, content: message.content };
+      case "assistant": {
+        const out: Record<string, unknown> = {
+          role: "assistant",
+          // Nullable content beside tool_calls is what this shape expects, but
+          // several gateways reject a bare null — "" satisfies both.
+          content: message.content || "",
+        };
+        if (message.reasoning) out.reasoning_content = message.reasoning;
+        if (message.toolCalls?.length) {
+          out.tool_calls = message.toolCalls.map((call) => ({
+            id: call.id,
+            type: "function",
+            function: { name: call.name, arguments: call.arguments },
+          }));
+        }
+        return out;
+      }
+    }
+  });
+}
+
+interface OpenAIChunk {
+  choices?: {
+    delta?: {
+      content?: string | null;
+      reasoning_content?: string | null;
+      reasoning?: string | null;
+      tool_calls?: {
+        index?: number;
+        id?: string;
+        function?: { name?: string; arguments?: string };
+      }[];
+    };
+    finish_reason?: string | null;
+  }[];
+  usage?: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    prompt_tokens_details?: { cached_tokens?: number };
+  } | null;
+}
+
+export function createOpenAIProvider(config: OpenAIConfig): Provider {
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+  const id = config.id ?? "openai";
+
+  return {
+    id,
+    model: config.model,
+
+    async *createStream(
+      messages: ChatMessage[],
+      tools: ToolDefinition[],
+      opts: StreamOptions = {},
+    ): AsyncIterable<ProviderChunk> {
+      const effort = opts.effort ?? config.effort;
+
+      const request: Record<string, unknown> = {
+        model: opts.model ?? config.model,
+        messages: toOpenAIMessages(messages),
+        stream: true,
+        // Without this the usage record never arrives and every call costs
+        // zero — a silent, total loss of the ledger.
+        stream_options: { include_usage: true },
+      };
+      const maxTokens = opts.maxTokens ?? config.maxTokens;
+      if (maxTokens !== undefined) request.max_tokens = maxTokens;
+      if (opts.temperature !== undefined) request.temperature = opts.temperature;
+      if (effort && effort !== "none") request.reasoning_effort = effort;
+      if (tools.length > 0) {
+        request.tools = tools.map((tool) => ({
+          type: "function",
+          function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema,
+          },
+        }));
+      }
+      if (opts.toolChoice && opts.toolChoice !== "auto") {
+        request.tool_choice =
+          typeof opts.toolChoice === "string"
+            ? opts.toolChoice
+            : { type: "function", function: { name: opts.toolChoice.name } };
+      }
+      if (opts.json) {
+        request.response_format = {
+          type: "json_schema",
+          json_schema: { name: opts.json.name, schema: opts.json.schema, strict: true },
+        };
+      }
+      if (config.providerOrder?.length) {
+        request.provider = { order: config.providerOrder, allow_fallbacks: true };
+      }
+
+      for await (const data of streamSse({
+        url: apiUrl(baseUrl, "/v1/chat/completions"),
+        headers: { authorization: `Bearer ${config.apiKey}`, ...config.headers },
+        body: request,
+        provider: id,
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+      })) {
+        let chunk: OpenAIChunk;
+        try {
+          chunk = JSON.parse(data) as OpenAIChunk;
+        } catch {
+          continue;
+        }
+
+        // A usage-only frame carries no choices — this shape sends it last.
+        if (chunk.usage) {
+          const input = chunk.usage.prompt_tokens ?? 0;
+          const cached = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
+          yield {
+            type: "usage",
+            usage: {
+              inputTokens: input,
+              // Already a SUBSET of prompt_tokens on this shape — unlike
+              // Anthropic's, which excludes them. No reconciling to do.
+              cachedInputTokens: cached,
+              outputTokens: chunk.usage.completion_tokens ?? 0,
+            },
+          };
+        }
+
+        const choice = chunk.choices?.[0];
+        if (!choice) continue;
+
+        const delta = choice.delta;
+        if (delta) {
+          const out: ProviderChunk = { type: "delta" };
+          let has = false;
+          if (delta.content) {
+            out.content = delta.content;
+            has = true;
+          }
+          // `reasoning_content` is DeepSeek's field; `reasoning` is
+          // OpenRouter's normalized one. Whichever arrives is the same thing.
+          const reasoning = delta.reasoning_content ?? delta.reasoning;
+          if (reasoning) {
+            out.reasoning = reasoning;
+            has = true;
+          }
+          if (delta.tool_calls?.length) {
+            out.toolCalls = delta.tool_calls.map((call, position) => ({
+              // Some gateways omit `index` entirely on single-tool turns.
+              index: call.index ?? position,
+              ...(call.id ? { id: call.id } : {}),
+              ...(call.function?.name ? { name: call.function.name } : {}),
+              ...(call.function?.arguments !== undefined
+                ? { arguments: call.function.arguments }
+                : {}),
+            }));
+            has = true;
+          }
+          if (has) yield out;
+        }
+
+        const finishReason = mapFinishReason(choice.finish_reason);
+        if (finishReason) yield { type: "finish", finishReason };
+      }
+    },
+  };
+}