rax-flow-providers 0.1.0

package/src/claude-adapter.ts

@@ -0,0 +1,350 @@
+/**
+ * @file claude-adapter.ts
+ * Anthropic Claude bridge adapter.
+ *
+ * API reference: https://docs.anthropic.com/en/api/messages
+ *
+ * • callModel      → POST /v1/messages  (plain text, streaming=false)
+ * • callStructured → same endpoint using Claude's tool_use mechanism
+ *                    (the structured extraction tool), which is the most
+ *                    reliable way to get valid JSON from Claude without
+ *                    prompt-hacking.  Falls back to prompt-only for
+ *                    claude-3-haiku which may not have tool_use.
+ *
+ * Supported models: claude-opus-4-5, claude-sonnet-4-5,
+ *                   claude-3-7-sonnet-latest, claude-3-5-sonnet-latest,
+ *                   claude-3-5-haiku-latest, claude-3-haiku-20240307
+ */
+
+import { IModelProvider, ModelResponse, ProviderCallOptions } from "@rax-flow/core";
+import { asString, parseJsonObjectFromText } from "./utils.js";
+import {
+  RaxProviderError,
+  mapHttpError,
+  mapNetworkError,
+  mapParseError,
+} from "./error-mapper.js";
+import { calculateCost } from "./pricing.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Wire shapes
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface ClaudeMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+interface ClaudeTool {
+  name: string;
+  description: string;
+  input_schema: object;
+}
+
+interface ClaudeRequest {
+  model: string;
+  max_tokens: number;
+  temperature?: number;
+  messages: ClaudeMessage[];
+  tools?: ClaudeTool[];
+  tool_choice?: { type: "auto" | "any" | "tool"; name?: string };
+}
+
+type ClaudeContentBlock =
+  | { type: "text"; text: string }
+  | { type: "tool_use"; id: string; name: string; input: unknown };
+
+interface ClaudeResponse {
+  id?: string;
+  content?: ClaudeContentBlock[];
+  stop_reason?: string;
+  usage?: { input_tokens?: number; output_tokens?: number };
+  // Error shapes
+  type?: string;
+  error?: { type?: string; message?: string };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+const VENDOR = "claude";
+const DEFAULT_MODEL = "claude-3-5-sonnet-latest";
+const DEFAULT_BASE_URL = "https://api.anthropic.com";
+const ANTHROPIC_VERSION = "2023-06-01";
+
+/** Models that reliably support tool_use for structured output extraction. */
+const TOOL_USE_MODELS = new Set([
+  "claude-opus-4-5",
+  "claude-sonnet-4-5",
+  "claude-3-7-sonnet-latest",
+  "claude-3-5-sonnet-latest",
+  "claude-3-5-haiku-latest",
+  "claude-3-opus-20240229",
+  "claude-3-sonnet-20240229",
+]);
+
+export interface ClaudeAdapterOptions {
+  apiKey: string;
+  baseUrl?: string;
+  defaultModel?: string;
+  timeoutMs?: number;
+}
+
+export class ClaudeAdapter implements IModelProvider {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly defaultModel: string;
+  private readonly timeoutMs: number;
+
+  constructor(options: ClaudeAdapterOptions);
+  /** @deprecated Pass an options object instead. */
+  constructor(apiKey: string, baseUrl?: string);
+  constructor(
+    optionsOrApiKey: ClaudeAdapterOptions | string,
+    legacyBaseUrl?: string
+  ) {
+    if (typeof optionsOrApiKey === "string") {
+      this.apiKey = optionsOrApiKey;
+      this.baseUrl = legacyBaseUrl ?? DEFAULT_BASE_URL;
+      this.defaultModel = DEFAULT_MODEL;
+      this.timeoutMs = 30_000;
+    } else {
+      this.apiKey = optionsOrApiKey.apiKey;
+      this.baseUrl = optionsOrApiKey.baseUrl ?? DEFAULT_BASE_URL;
+      this.defaultModel = optionsOrApiKey.defaultModel ?? DEFAULT_MODEL;
+      this.timeoutMs = optionsOrApiKey.timeoutMs ?? 30_000;
+    }
+  }
+
+  // ── private helpers ────────────────────────────────────────────────────────
+
+  private supportsToolUse(model: string): boolean {
+    for (const known of TOOL_USE_MODELS) {
+      if (model === known || model.startsWith(`${known}-`) || model.startsWith("claude-3-5") || model.startsWith("claude-3-7") || model.startsWith("claude-opus") || model.startsWith("claude-sonnet")) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private async post(
+    body: ClaudeRequest,
+    context: "callModel" | "callStructured"
+  ): Promise<ClaudeResponse> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}/v1/messages`, {
+        method: "POST",
+        headers: {
+          "x-api-key": this.apiKey,
+          "anthropic-version": ANTHROPIC_VERSION,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      throw mapNetworkError(VENDOR, err);
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const raw = await res.json().catch(() => ({}));
+
+    if (!res.ok) {
+      throw mapHttpError(VENDOR, res.status, raw, context);
+    }
+
+    const payload = raw as ClaudeResponse;
+
+    // Anthropic embeds errors inside 200 (type: "error")
+    if (payload.type === "error" && payload.error) {
+      const errType = payload.error.type ?? "";
+      const errMsg = payload.error.message ?? "unknown claude error";
+      const code =
+        errType === "overloaded_error" ? "server_error" :
+          errType === "rate_limit_error" ? "auth_quota_exceeded" :
+            errType === "authentication_error" ? "auth_invalid" :
+              (errType.includes("content") || errType.includes("safety")) ? "content_filtered" :
+                "unknown";
+      throw new RaxProviderError(VENDOR, code, errMsg, { raw: payload });
+    }
+
+    return payload;
+  }
+
+  private extractText(payload: ClaudeResponse): string {
+    return (
+      payload.content
+        ?.filter((c): c is { type: "text"; text: string } => c.type === "text")
+        .map((c) => c.text)
+        .join("\n") ?? ""
+    );
+  }
+
+  private extractToolInput(payload: ClaudeResponse): unknown | null {
+    const toolBlock = payload.content?.find(
+      (c): c is { type: "tool_use"; id: string; name: string; input: unknown } =>
+        c.type === "tool_use"
+    );
+    return toolBlock?.input ?? null;
+  }
+
+  // ── IModelProvider ─────────────────────────────────────────────────────────
+
+  async callModel(
+    prompt: string,
+    options?: ProviderCallOptions
+  ): Promise<ModelResponse<string>> {
+    const started = Date.now();
+    const model = options?.model ?? this.defaultModel;
+
+    const payload = await this.post(
+      {
+        model,
+        max_tokens: options?.maxTokens ?? 1200,
+        temperature: options?.temperature ?? 0.2,
+        messages: [{ role: "user", content: prompt }],
+      },
+      "callModel"
+    );
+
+    const usage = payload.usage
+      ? {
+        promptTokens: payload.usage.input_tokens ?? 0,
+        completionTokens: payload.usage.output_tokens ?? 0,
+        totalTokens: (payload.usage.input_tokens ?? 0) + (payload.usage.output_tokens ?? 0),
+      }
+      : undefined;
+
+    return {
+      provider: VENDOR,
+      model,
+      latencyMs: Date.now() - started,
+      costUsd: calculateCost(model, usage),
+      usage,
+      output: this.extractText(payload),
+      raw: payload,
+    };
+  }
+
+  async callStructured<T>(
+    prompt: string,
+    schema: object,
+    options?: ProviderCallOptions
+  ): Promise<ModelResponse<T>> {
+    const started = Date.now();
+    const model = options?.model ?? this.defaultModel;
+
+    if (this.supportsToolUse(model)) {
+      // ── Tool-use path (most reliable for structured output) ────────────────
+      const extractionTool: ClaudeTool = {
+        name: "structured_output",
+        description: "Extract the required structured data and return it as JSON.",
+        input_schema: schema,
+      };
+
+      const payload = await this.post(
+        {
+          model,
+          max_tokens: options?.maxTokens ?? 1400,
+          temperature: options?.temperature ?? 0,
+          messages: [{ role: "user", content: prompt }],
+          tools: [extractionTool],
+          tool_choice: { type: "tool", name: "structured_output" },
+        },
+        "callStructured"
+      );
+
+      const usage = payload.usage
+        ? {
+          promptTokens: payload.usage.input_tokens ?? 0,
+          completionTokens: payload.usage.output_tokens ?? 0,
+          totalTokens: (payload.usage.input_tokens ?? 0) + (payload.usage.output_tokens ?? 0),
+        }
+        : undefined;
+
+      const toolInput = this.extractToolInput(payload);
+      if (toolInput && typeof toolInput === "object") {
+        return {
+          provider: VENDOR,
+          model,
+          latencyMs: Date.now() - started,
+          costUsd: calculateCost(model, usage),
+          usage,
+          output: toolInput as T,
+          raw: payload,
+        };
+      }
+
+      // If tool_use block missing, fall through to text parsing
+      const textFallback = this.extractText(payload);
+      const parsed = parseJsonObjectFromText<T>(textFallback);
+      if (parsed) {
+        return {
+          provider: VENDOR,
+          model,
+          latencyMs: Date.now() - started,
+          costUsd: calculateCost(model, usage),
+          usage,
+          output: parsed,
+          raw: payload,
+        };
+      }
+
+      throw mapParseError(VENDOR, "callStructured", textFallback);
+    }
+
+    // ── Prompt-only path (claude-3-haiku and legacy models) ─────────────────
+    const strictPrompt = [
+      prompt,
+      "",
+      "Return ONLY valid JSON matching this schema (no other text):",
+      JSON.stringify(schema, null, 2),
+    ].join("\n");
+
+    const payload = await this.post(
+      {
+        model,
+        max_tokens: options?.maxTokens ?? 1400,
+        temperature: 0,
+        messages: [{ role: "user", content: strictPrompt }],
+      },
+      "callStructured"
+    );
+
+    const usage = payload.usage
+      ? {
+        promptTokens: payload.usage.input_tokens ?? 0,
+        completionTokens: payload.usage.output_tokens ?? 0,
+        totalTokens: (payload.usage.input_tokens ?? 0) + (payload.usage.output_tokens ?? 0),
+      }
+      : undefined;
+
+    const text = this.extractText(payload);
+    const parsed = parseJsonObjectFromText<T>(asString(text));
+
+    if (!parsed) {
+      throw mapParseError(VENDOR, "callStructured", text);
+    }
+
+    return {
+      provider: VENDOR,
+      model,
+      latencyMs: Date.now() - started,
+      costUsd: calculateCost(model, usage),
+      usage,
+      output: parsed,
+      raw: payload,
+    };
+  }
+
+  async healthCheck(): Promise<boolean> {
+    return Boolean(this.apiKey && this.baseUrl);
+  }
+}

package/src/cohere-adapter.ts

@@ -0,0 +1,262 @@
+/**
+ * @file cohere-adapter.ts
+ * Cohere bridge adapter (Command R / Command R+).
+ *
+ * API reference: https://docs.cohere.com/reference/chat
+ *
+ * • callModel      → POST /v2/chat  (v2 chat API — streaming=false)
+ * • callStructured → same endpoint with response_format="json_object"
+ *                    and a JSON schema injected via system_prompt
+ *
+ * Supported models: command-r-plus-08-2024, command-r-08-2024,
+ *                   command-r7b-12-2024, command-a-03-2025, etc.
+ *
+ * Notes:
+ * - Cohere v2 uses "message" field not "messages" for single-turn.
+ * - Structured JSON is supported via response_format + preamble (system).
+ */
+
+import { IModelProvider, ModelResponse, ProviderCallOptions } from "@rax-flow/core";
+import { parseJsonObjectFromText } from "./utils.js";
+import {
+    RaxProviderError,
+    mapHttpError,
+    mapNetworkError,
+    mapParseError,
+} from "./error-mapper.js";
+import { calculateCost } from "./pricing.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cohere v2 wire shapes
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface CohereMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+
+interface CohereChatRequestV2 {
+    model: string;
+    messages: CohereMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    response_format?: {
+        type: "text" | "json_object";
+        json_schema?: object;
+    };
+}
+
+interface CohereContent {
+    type: string;
+    text?: string;
+}
+
+interface CohereChatResponseV2 {
+    id?: string;
+    message?: {
+        role?: string;
+        content?: CohereContent[];
+    };
+    finish_reason?: string;
+    usage?: {
+        billed_units?: { input_tokens?: number; output_tokens?: number };
+    };
+    // Error body
+    message_str?: string; // top-level error message field in v2 errors
+    error?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+const VENDOR = "cohere";
+const DEFAULT_MODEL = "command-r-plus-08-2024";
+const BASE_URL = "https://api.cohere.com";
+
+export interface CohereAdapterOptions {
+    apiKey: string;
+    baseUrl?: string;
+    defaultModel?: string;
+    timeoutMs?: number;
+}
+
+export class CohereAdapter implements IModelProvider {
+    private readonly apiKey: string;
+    private readonly baseUrl: string;
+    private readonly defaultModel: string;
+    private readonly timeoutMs: number;
+
+    constructor(options: CohereAdapterOptions) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl ?? BASE_URL;
+        this.defaultModel = options.defaultModel ?? DEFAULT_MODEL;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+    }
+
+    // ── private helpers ────────────────────────────────────────────────────────
+
+    private async post(
+        body: CohereChatRequestV2,
+        context: "callModel" | "callStructured"
+    ): Promise<CohereChatResponseV2> {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+        let res: Response;
+        try {
+            res = await fetch(`${this.baseUrl}/v2/chat`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        } catch (err) {
+            clearTimeout(timer);
+            throw mapNetworkError(VENDOR, err);
+        } finally {
+            clearTimeout(timer);
+        }
+
+        const raw = await res.json().catch(() => ({}));
+
+        if (!res.ok) {
+            throw mapHttpError(VENDOR, res.status, raw, context);
+        }
+
+        const payload = raw as CohereChatResponseV2;
+
+        // Cohere finish reasons that signal a safety block
+        if (
+            payload.finish_reason === "MAX_TOKENS" &&
+            !payload.message?.content?.length
+        ) {
+            throw new RaxProviderError(
+                VENDOR,
+                "content_filtered",
+                "Cohere response truncated without content — possible safety block",
+                { raw: payload }
+            );
+        }
+
+        return payload;
+    }
+
+    private extractText(payload: CohereChatResponseV2): string {
+        return (
+            payload.message?.content
+                ?.filter((c) => c.type === "text")
+                .map((c) => c.text ?? "")
+                .join("\n") ?? ""
+        );
+    }
+
+    // ── IModelProvider ─────────────────────────────────────────────────────────
+
+    async callModel(
+        prompt: string,
+        options?: ProviderCallOptions
+    ): Promise<ModelResponse<string>> {
+        const started = Date.now();
+        const model = options?.model ?? this.defaultModel;
+
+        const payload = await this.post(
+            {
+                model,
+                temperature: options?.temperature ?? 0.2,
+                max_tokens: options?.maxTokens ?? 1200,
+                messages: [{ role: "user", content: prompt }],
+            },
+            "callModel"
+        );
+
+        const inputTokens = payload.usage?.billed_units?.input_tokens ?? 0;
+        const outputTokens = payload.usage?.billed_units?.output_tokens ?? 0;
+        const usage = payload.usage?.billed_units
+            ? {
+                promptTokens: inputTokens,
+                completionTokens: outputTokens,
+                totalTokens: inputTokens + outputTokens,
+            }
+            : undefined;
+
+        return {
+            provider: VENDOR,
+            model,
+            latencyMs: Date.now() - started,
+            costUsd: calculateCost(model, usage),
+            usage,
+            output: this.extractText(payload),
+            raw: payload,
+        };
+    }
+
+    async callStructured<T>(
+        prompt: string,
+        schema: object,
+        options?: ProviderCallOptions
+    ): Promise<ModelResponse<T>> {
+        const started = Date.now();
+        const model = options?.model ?? this.defaultModel;
+
+        // Cohere json_object mode with schema embedded in system message
+        const systemContent = [
+            "You are a JSON generation assistant.",
+            "ALWAYS respond with ONLY a valid JSON object.",
+            "The JSON must strictly follow this schema:",
+            JSON.stringify(schema, null, 2),
+        ].join("\n");
+
+        const payload = await this.post(
+            {
+                model,
+                temperature: options?.temperature ?? 0,
+                max_tokens: options?.maxTokens ?? 1400,
+                response_format: {
+                    type: "json_object",
+                    json_schema: schema,
+                },
+                messages: [
+                    { role: "system", content: systemContent },
+                    { role: "user", content: prompt },
+                ],
+            },
+            "callStructured"
+        );
+
+        const text = this.extractText(payload);
+        const parsed = parseJsonObjectFromText<T>(text);
+
+        if (!parsed) {
+            throw mapParseError(VENDOR, "callStructured", text);
+        }
+
+        const inputTokens = payload.usage?.billed_units?.input_tokens ?? 0;
+        const outputTokens = payload.usage?.billed_units?.output_tokens ?? 0;
+        const usage = payload.usage?.billed_units
+            ? {
+                promptTokens: inputTokens,
+                completionTokens: outputTokens,
+                totalTokens: inputTokens + outputTokens,
+            }
+            : undefined;
+
+        return {
+            provider: VENDOR,
+            model,
+            latencyMs: Date.now() - started,
+            costUsd: calculateCost(model, usage),
+            usage,
+            output: parsed,
+            raw: payload,
+        };
+    }
+
+    async healthCheck(): Promise<boolean> {
+        return Boolean(this.apiKey && this.baseUrl);
+    }
+}