rax-flow-providers 0.1.0

package/src/host-bridge-adapter.ts

@@ -0,0 +1,189 @@
+import { spawn } from "node:child_process";
+import { IModelProvider, ModelResponse, ProviderCallOptions } from "@rax-flow/core";
+import { parseJsonObjectFromText } from "./utils.js";
+
+type HostBridgeFn = (payload: HostBridgeRequest) => Promise<HostBridgeResponse>;
+
+interface HostBridgeRequest {
+  version: 1;
+  action: "callModel" | "callStructured";
+  prompt: string;
+  schema?: object;
+  options?: ProviderCallOptions;
+}
+
+interface HostBridgeResponse {
+  ok: boolean;
+  output?: unknown;
+  model?: string;
+  latencyMs?: number;
+  error?: string;
+}
+
+interface HostBridgeAdapterOptions {
+  model?: string;
+  mode?: "auto" | "bridge-only" | "mock";
+  command?: string;
+  timeoutMs?: number;
+}
+
+function parseShellCommand(input: string): { command: string; args: string[] } {
+  const parts = input.match(/(?:[^\s"]+|"[^"]*")+/g) ?? [];
+  if (parts.length === 0) {
+    throw new Error("invalid_bridge_command");
+  }
+  const [command, ...rawArgs] = parts;
+  const args = rawArgs.map((arg) => arg.replace(/^"|"$/g, ""));
+  // `command` is defined here because parts.length > 0 is guaranteed above
+  return { command: command!, args };
+}
+
+async function runBridgeCommand(commandSpec: string, payload: HostBridgeRequest, timeoutMs: number): Promise<HostBridgeResponse> {
+  const { command, args } = parseShellCommand(commandSpec);
+  return await new Promise<HostBridgeResponse>((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("host_bridge_timeout"));
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`host_bridge_command_failed:${code}:${stderr}`));
+        return;
+      }
+
+      try {
+        const parsed = JSON.parse(stdout) as HostBridgeResponse;
+        resolve(parsed);
+      } catch {
+        resolve({ ok: true, output: stdout.trim(), model: "host-bridge-command" });
+      }
+    });
+
+    child.stdin.write(JSON.stringify(payload));
+    child.stdin.end();
+  });
+}
+
+function getGlobalBridge(): HostBridgeFn | undefined {
+  const candidate = (globalThis as Record<string, unknown>).__RAX_HOST_BRIDGE__;
+  if (typeof candidate === "function") {
+    return candidate as HostBridgeFn;
+  }
+  return undefined;
+}
+
+export class HostBridgeAdapter implements IModelProvider {
+  private readonly model: string;
+  private readonly mode: "auto" | "bridge-only" | "mock";
+  private readonly command?: string;
+  private readonly timeoutMs: number;
+
+  constructor(options: HostBridgeAdapterOptions = {}) {
+    this.model = options.model ?? "host-managed";
+    this.mode = options.mode ?? "auto";
+    this.command = options.command;
+    this.timeoutMs = options.timeoutMs ?? 20000;
+  }
+
+  private async callBridge(payload: HostBridgeRequest): Promise<HostBridgeResponse> {
+    const bridgeFn = getGlobalBridge();
+    if (bridgeFn) {
+      return await bridgeFn(payload);
+    }
+
+    if (this.command) {
+      return await runBridgeCommand(this.command, payload, this.timeoutMs);
+    }
+
+    if (this.mode === "bridge-only") {
+      throw new Error("host_bridge_missing");
+    }
+
+    return {
+      ok: true,
+      model: this.model,
+      latencyMs: 1,
+      output:
+        payload.action === "callStructured"
+          ? {
+            agent: "HostBridgeMock",
+            success: true,
+            confidence: 0.7,
+            risks: ["latency"],
+            logs: ["host bridge unavailable, using local mock response"],
+            data: {
+              summary: "Mock structured output from host adapter",
+              nextAction: "configure_host_bridge"
+            }
+          }
+          : `host-mock:${payload.prompt.slice(0, 240)}`
+    };
+  }
+
+  async callModel(prompt: string, options?: ProviderCallOptions): Promise<ModelResponse<string>> {
+    const started = Date.now();
+    const res = await this.callBridge({ version: 1, action: "callModel", prompt, options });
+    if (!res.ok) {
+      throw new Error(`host_call_failed:${res.error ?? "unknown"}`);
+    }
+
+    return {
+      provider: "host",
+      model: res.model ?? options?.model ?? this.model,
+      latencyMs: res.latencyMs ?? Date.now() - started,
+      output: typeof res.output === "string" ? res.output : JSON.stringify(res.output ?? "")
+    };
+  }
+
+  async callStructured<T>(prompt: string, schema: object, options?: ProviderCallOptions): Promise<ModelResponse<T>> {
+    const started = Date.now();
+    const res = await this.callBridge({ version: 1, action: "callStructured", prompt, schema, options });
+    if (!res.ok) {
+      throw new Error(`host_structured_failed:${res.error ?? "unknown"}`);
+    }
+
+    let output: T | null = null;
+    if (res.output && typeof res.output === "object") {
+      output = res.output as T;
+    } else if (typeof res.output === "string") {
+      output = parseJsonObjectFromText<T>(res.output);
+    }
+
+    if (!output) {
+      throw new Error("host_structured_parse_failed");
+    }
+
+    return {
+      provider: "host",
+      model: res.model ?? options?.model ?? this.model,
+      latencyMs: res.latencyMs ?? Date.now() - started,
+      output
+    };
+  }
+
+  async healthCheck(): Promise<boolean> {
+    if (this.mode === "mock") return true;
+    if (getGlobalBridge()) return true;
+    if (this.command) return true;
+    return this.mode === "auto";
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./error-mapper.js";
+export * from "./openai-adapter.js";
+export * from "./claude-adapter.js";
+export * from "./gemini-adapter.js";
+export * from "./groq-adapter.js";
+export * from "./mistral-adapter.js";
+export * from "./cohere-adapter.js";
+export * from "./rest-adapter.js";
+export * from "./host-bridge-adapter.js";
+export * from "./strategy.js";
+export * from "./utils.js";

package/src/mistral-adapter.ts

@@ -0,0 +1,262 @@
+/**
+ * @file mistral-adapter.ts
+ * Mistral AI bridge adapter.
+ *
+ * API reference: https://docs.mistral.ai/api/
+ *
+ * • callModel      → POST /v1/chat/completions  (standard)
+ * • callStructured → same endpoint with `response_format: { type: "json_object" }`
+ *                    Mistral supports native JSON mode since 2024-02 on all
+ *                    large models.  For smaller models we fall back to
+ *                    system-prompt enforcement.
+ *
+ * Supported models: mistral-large-latest, mistral-small-latest,
+ *                   open-mixtral-8x22b, codestral-latest, etc.
+ */
+
+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";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Wire shapes
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface MistralMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+
+interface MistralChatRequest {
+    model: string;
+    messages: MistralMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    response_format?: { type: "text" | "json_object" };
+    safe_prompt?: boolean;
+}
+
+interface MistralChatResponse {
+    id?: string;
+    choices?: Array<{
+        message?: { content?: string };
+        finish_reason?: string;
+    }>;
+    usage?: { total_tokens?: number; prompt_tokens?: number; completion_tokens?: number };
+    // Error body when status is non-2xx
+    message?: string;
+    detail?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+const VENDOR = "mistral";
+const DEFAULT_MODEL = "mistral-large-latest";
+const BASE_URL = "https://api.mistral.ai";
+
+/** Models known to support native json_object response_format. */
+const JSON_MODE_MODELS = new Set([
+    "mistral-large-latest",
+    "mistral-small-latest",
+    "codestral-latest",
+    "open-mixtral-8x22b",
+    "open-mistral-nemo",
+]);
+
+export interface MistralAdapterOptions {
+    apiKey: string;
+    baseUrl?: string;
+    defaultModel?: string;
+    timeoutMs?: number;
+    /** Disable Mistral safe-prompt for structured tasks (default: false). */
+    safePrompt?: boolean;
+}
+
+export class MistralAdapter implements IModelProvider {
+    private readonly apiKey: string;
+    private readonly baseUrl: string;
+    private readonly defaultModel: string;
+    private readonly timeoutMs: number;
+    private readonly safePrompt: boolean;
+
+    constructor(options: MistralAdapterOptions) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl ?? BASE_URL;
+        this.defaultModel = options.defaultModel ?? DEFAULT_MODEL;
+        this.timeoutMs = options.timeoutMs ?? 25_000;
+        this.safePrompt = options.safePrompt ?? false;
+    }
+
+    // ── private helpers ────────────────────────────────────────────────────────
+
+    private supportsJsonMode(model: string): boolean {
+        return JSON_MODE_MODELS.has(model);
+    }
+
+    private async post(
+        body: MistralChatRequest,
+        context: "callModel" | "callStructured"
+    ): Promise<MistralChatResponse> {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+        let res: Response;
+        try {
+            res = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+                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 MistralChatResponse;
+
+        // Mistral can signal content policy stop
+        const finishReason = payload.choices?.[0]?.finish_reason;
+        if (finishReason === "content_filter") {
+            throw new RaxProviderError(
+                VENDOR,
+                "content_filtered",
+                "Mistral content policy rejection",
+                { raw: payload }
+            );
+        }
+
+        return payload;
+    }
+
+    private extractText(payload: MistralChatResponse): string {
+        return payload.choices?.[0]?.message?.content ?? "";
+    }
+
+    // ── 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,
+                safe_prompt: this.safePrompt,
+                messages: [{ role: "user", content: prompt }],
+            },
+            "callModel"
+        );
+
+        const usage = payload.usage
+            ? {
+                promptTokens: payload.usage.prompt_tokens ?? 0,
+                completionTokens: payload.usage.completion_tokens ?? 0,
+                totalTokens: payload.usage.total_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;
+
+        const messages: MistralMessage[] = [];
+
+        if (this.supportsJsonMode(model)) {
+            // Native JSON mode — schema hint via system prompt
+            messages.push({
+                role: "system",
+                content: `Respond with ONLY a valid JSON object that matches this schema:\n${JSON.stringify(schema, null, 2)}`,
+            });
+            messages.push({ role: "user", content: prompt });
+        } else {
+            // Fallback for non-json-mode models: inline schema in user message
+            messages.push({
+                role: "user",
+                content: `${prompt}\n\nRespond ONLY with a JSON object matching this schema:\n${JSON.stringify(schema)}`,
+            });
+        }
+
+        const requestBody: MistralChatRequest = {
+            model,
+            temperature: options?.temperature ?? 0,
+            max_tokens: options?.maxTokens ?? 1400,
+            safe_prompt: false, // disable safe rewrites on structured tasks
+            messages,
+        };
+
+        if (this.supportsJsonMode(model)) {
+            requestBody.response_format = { type: "json_object" };
+        }
+
+        const payload = await this.post(requestBody, "callStructured");
+        const text = this.extractText(payload);
+        const parsed = parseJsonObjectFromText<T>(text);
+
+        if (!parsed) {
+            throw mapParseError(VENDOR, "callStructured", text);
+        }
+
+        const usage = payload.usage
+            ? {
+                promptTokens: payload.usage.prompt_tokens ?? 0,
+                completionTokens: payload.usage.completion_tokens ?? 0,
+                totalTokens: payload.usage.total_tokens ?? 0,
+            }
+            : 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);
+    }
+}

package/src/openai-adapter.ts

@@ -0,0 +1,240 @@
+/**
+ * @file openai-adapter.ts
+ * OpenAI bridge adapter.
+ *
+ * API reference: https://platform.openai.com/docs/api-reference/chat
+ */
+
+import { IModelProvider, IEmbeddingProvider, ModelResponse, ProviderCallOptions, EmbeddingResponse } from "@rax-flow/core";
+import { asString, parseJsonObjectFromText } from "./utils.js";
+import { calculateCost } from "./pricing.js";
+import {
+  RaxProviderError,
+  mapHttpError,
+  mapNetworkError,
+  mapParseError,
+} from "./error-mapper.js";
+
+type ContentPart = { type: string; text?: string };
+
+interface OpenAIMessage {
+  role: "system" | "user" | "assistant";
+  content: string | ContentPart[];
+}
+
+interface OpenAIChatRequest {
+  model: string;
+  messages: OpenAIMessage[];
+  temperature?: number;
+  max_tokens?: number;
+  response_format?:
+  | { type: "text" }
+  | { type: "json_object" }
+  | {
+    type: "json_schema";
+    json_schema: { name: string; strict: boolean; schema: object };
+  };
+}
+
+interface OpenAIChatResponse {
+  id?: string;
+  choices?: Array<{
+    message?: { content?: string | ContentPart[] };
+    finish_reason?: string;
+  }>;
+  usage?: { total_tokens?: number; prompt_tokens?: number; completion_tokens?: number };
+  error?: { message?: string; type?: string; code?: string };
+}
+
+const VENDOR = "openai";
+const DEFAULT_MODEL = "gpt-4.1-mini";
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+
+const STRICT_JSON_SCHEMA_MODELS = new Set([
+  "gpt-4o",
+  "gpt-4o-mini",
+  "gpt-4.1",
+  "gpt-4.1-mini",
+  "gpt-4.1-nano",
+  "gpt-4-turbo",
+  "o1",
+  "o1-mini",
+  "o3-mini",
+]);
+
+export interface OpenAIAdapterOptions {
+  apiKey: string;
+  baseUrl?: string;
+  defaultModel?: string;
+  timeoutMs?: number;
+}
+
+export class OpenAIAdapter implements IModelProvider, IEmbeddingProvider {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly defaultModel: string;
+  private readonly timeoutMs: number;
+
+  constructor(options: OpenAIAdapterOptions);
+  /** @deprecated Pass an options object instead of positional args. */
+  constructor(apiKey: string, baseUrl?: string);
+  constructor(
+    optionsOrApiKey: OpenAIAdapterOptions | 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 supportsStrictJsonSchema(model: string): boolean {
+    for (const known of STRICT_JSON_SCHEMA_MODELS) {
+      if (model === known || model.startsWith(`${known}-`)) return true;
+    }
+    return false;
+  }
+
+  private async post(
+    body: OpenAIChatRequest,
+    context: "callModel" | "callStructured"
+  ): Promise<OpenAIChatResponse> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "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 OpenAIChatResponse;
+    if (payload.error) {
+      const errMsg = payload.error.message ?? "unknown openai error";
+      const isRefusal = payload.error.type === "invalid_request_error" && /content_policy|moderat|filter/i.test(errMsg);
+      throw new RaxProviderError(VENDOR, isRefusal ? "content_filtered" : "invalid_request", errMsg, { raw: payload });
+    }
+
+    const finishReason = payload.choices?.[0]?.finish_reason;
+    if (finishReason === "content_filter") {
+      throw new RaxProviderError(VENDOR, "content_filtered", "OpenAI content policy rejection", { raw: payload });
+    }
+    return payload;
+  }
+
+  private extractText(payload: OpenAIChatResponse): string {
+    const content = payload.choices?.[0]?.message?.content;
+    if (Array.isArray(content)) return content.map((c) => c.text ?? "").join("\n");
+    return content ?? "";
+  }
+
+  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 usage = payload.usage ? {
+      promptTokens: payload.usage.prompt_tokens ?? 0,
+      completionTokens: payload.usage.completion_tokens ?? 0,
+      totalTokens: payload.usage.total_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;
+
+    const body: OpenAIChatRequest = {
+      model, temperature: options?.temperature ?? 0, max_tokens: options?.maxTokens ?? 1400,
+      messages: [{ role: "user", content: prompt }],
+    };
+
+    if (this.supportsStrictJsonSchema(model)) {
+      body.response_format = { type: "json_schema", json_schema: { name: "rax_flow_output", strict: true, schema } };
+    } else {
+      body.response_format = { type: "json_object" };
+      body.messages = [
+        { role: "system", content: `Respond ONLY with a valid JSON object matching this schema:\n${JSON.stringify(schema, null, 2)}` },
+        { role: "user", content: prompt },
+      ];
+    }
+
+    const payload = await this.post(body, "callStructured");
+    const text = asString(this.extractText(payload) || "{}");
+    const parsed = parseJsonObjectFromText<T>(text);
+    if (!parsed) throw mapParseError(VENDOR, "callStructured", text);
+
+    const usage = payload.usage ? {
+      promptTokens: payload.usage.prompt_tokens ?? 0,
+      completionTokens: payload.usage.completion_tokens ?? 0,
+      totalTokens: payload.usage.total_tokens ?? 0,
+    } : undefined;
+
+    return {
+      provider: VENDOR, model, latencyMs: Date.now() - started, costUsd: calculateCost(model, usage), usage,
+      output: parsed, raw: payload,
+    };
+  }
+
+  async embed(texts: string[]): Promise<EmbeddingResponse> {
+    const res = await fetch(`${this.baseUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        input: texts,
+        model: "text-embedding-3-small",
+      }),
+    });
+
+    if (!res.ok) {
+      const raw = await res.json().catch(() => ({}));
+      throw mapHttpError(VENDOR, res.status, raw, "embed" as any);
+    }
+
+    const payload = (await res.json()) as { data: Array<{ embedding: number[] }>; model: string; usage: { total_tokens: number } };
+    return {
+      vectors: payload.data.map((d) => d.embedding),
+      model: payload.model,
+      usage: { totalTokens: payload.usage.total_tokens }
+    };
+  }
+
+  async healthCheck(): Promise<boolean> {
+    return Boolean(this.apiKey && this.baseUrl);
+  }
+}