rax-flow-providers 0.1.0

package/src/pricing.ts

@@ -0,0 +1,77 @@
+/**
+ * @file pricing.ts
+ * Token pricing catalog and cost calculation.
+ *
+ * Prices are in USD per 1M tokens unless specified.
+ * Updated: 2026-02 (simulated current date)
+ */
+
+interface ModelPrice {
+    input: number;  // $ per 1M tokens
+    output: number; // $ per 1M tokens
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Official Pricing Catalog (approximate / standard rates)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const PRICING_CATALOG: Record<string, ModelPrice> = {
+    // OpenAI
+    "gpt-4o": { input: 2.50, output: 10.00 },
+    "gpt-4o-2024-05-13": { input: 2.50, output: 10.00 },
+    "gpt-4o-mini": { input: 0.15, output: 0.60 },
+    "gpt-4.5-preview": { input: 75.00, output: 150.00 }, // hypothetical high-end
+    "o1": { input: 15.00, output: 60.00 },
+    "o3-mini": { input: 1.10, output: 4.40 },
+
+    // Anthropic
+    "claude-3-5-sonnet-latest": { input: 3.00, output: 15.00 },
+    "claude-3-5-haiku-latest": { input: 0.25, output: 1.25 },
+    "claude-3-opus-20240229": { input: 15.00, output: 75.00 },
+
+    // Google (Gemini 1.5 / 2.0)
+    "gemini-2.0-flash": { input: 0.10, output: 0.40 },
+    "gemini-1.5-flash": { input: 0.075, output: 0.30 },
+    "gemini-1.5-pro": { input: 1.25, output: 5.00 },
+
+    // Mistral
+    "mistral-large-latest": { input: 2.00, output: 6.00 },
+    "mistral-small-latest": { input: 0.20, output: 0.60 },
+    "codestral-latest": { input: 1.00, output: 3.00 },
+    "open-mixtral-8x22b": { input: 2.00, output: 6.00 },
+
+    // Groq (Llama 3 hosted)
+    "llama-3.3-70b-versatile": { input: 0.59, output: 0.79 },
+    "llama3-8b-8192": { input: 0.05, output: 0.08 },
+    "mixtral-8x7b-32768": { input: 0.24, output: 0.24 },
+
+    // Cohere
+    "command-r-plus-08-2024": { input: 2.50, output: 10.00 },
+    "command-r-08-2024": { input: 0.15, output: 0.60 },
+};
+
+// Default fallback price (cheap generic model assumption)
+const DEFAULT_PRICE: ModelPrice = { input: 0.50, output: 1.50 };
+
+/** Returns the price config for a given model ID (with fuzzy matching). */
+function getPriceConfig(model: string): ModelPrice {
+    if (PRICING_CATALOG[model]) return PRICING_CATALOG[model];
+
+    // Fuzzy match for versioned models (e.g. gpt-4o-2024-08-06 -> gpt-4o)
+    const base = Object.keys(PRICING_CATALOG).find((k) => model.startsWith(k));
+    return base ? PRICING_CATALOG[base] : DEFAULT_PRICE;
+}
+
+/**
+ * Calculates the estimated cost in USD for a given usage.
+ */
+export function calculateCost(
+    model: string,
+    usage?: { promptTokens: number; completionTokens: number }
+): number {
+    if (!usage) return 0;
+    const price = getPriceConfig(model);
+    const inputCost = (usage.promptTokens / 1_000_000) * price.input;
+    const outputCost = (usage.completionTokens / 1_000_000) * price.output;
+    return inputCost + outputCost;
+}

package/src/rest-adapter.ts

@@ -0,0 +1,181 @@
+/**
+ * @file rest-adapter.ts
+ * Generic REST bridge adapter.
+ *
+ * Targets any OpenAI-compatible or custom LLM endpoint that accepts a simple
+ * JSON body with { model, prompt, temperature, maxTokens } and returns
+ * { output | content | text }.
+ *
+ * Useful for: LM Studio, local Ollama proxy, custom inference servers, etc.
+ */
+
+import { IModelProvider, ModelResponse, ProviderCallOptions } from "@rax-flow/core";
+import { parseJsonObjectFromText } from "./utils.js";
+import { mapHttpError, mapNetworkError, mapParseError } from "./error-mapper.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Wire shapes
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface RestResponse {
+  output?: unknown;
+  content?: string;
+  text?: string;
+  error?: unknown;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+const VENDOR = "rest";
+
+export interface GenericRestAdapterOptions {
+  endpoint: string;
+  token?: string;
+  defaultModel?: string;
+  timeoutMs?: number;
+}
+
+export class GenericRestAdapter implements IModelProvider {
+  private readonly endpoint: string;
+  private readonly token?: string;
+  private readonly defaultModel: string;
+  private readonly timeoutMs: number;
+
+  constructor(options: GenericRestAdapterOptions);
+  /** @deprecated Prefer the options-object constructor. */
+  constructor(endpoint: string, token?: string);
+  constructor(
+    optionsOrEndpoint: GenericRestAdapterOptions | string,
+    legacyToken?: string
+  ) {
+    if (typeof optionsOrEndpoint === "string") {
+      this.endpoint = optionsOrEndpoint;
+      this.token = legacyToken;
+      this.defaultModel = "generic-llm";
+      this.timeoutMs = 30_000;
+    } else {
+      this.endpoint = optionsOrEndpoint.endpoint;
+      this.token = optionsOrEndpoint.token;
+      this.defaultModel = optionsOrEndpoint.defaultModel ?? "generic-llm";
+      this.timeoutMs = optionsOrEndpoint.timeoutMs ?? 30_000;
+    }
+  }
+
+  // ── private helpers ────────────────────────────────────────────────────────
+
+  private async post(
+    body: Record<string, unknown>,
+    context: "callModel" | "callStructured"
+  ): Promise<RestResponse> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    let res: Response;
+    try {
+      res = await fetch(this.endpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
+        },
+        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);
+    }
+
+    return raw as RestResponse;
+  }
+
+  private extractText(payload: RestResponse): string {
+    if (typeof payload.output === "string") return payload.output;
+    if (payload.content) return payload.content;
+    if (payload.text) return payload.text;
+    return JSON.stringify(payload.output ?? payload);
+  }
+
+  // ── 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,
+        prompt,
+        temperature: options?.temperature ?? 0.2,
+        maxTokens: options?.maxTokens ?? 1200,
+      },
+      "callModel"
+    );
+
+    return {
+      provider: VENDOR,
+      model,
+      latencyMs: Date.now() - started,
+      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 augmentedPrompt = [
+      prompt,
+      "",
+      "Return ONLY valid JSON matching this schema:",
+      JSON.stringify(schema),
+    ].join("\n");
+
+    const payload = await this.post(
+      {
+        model,
+        prompt: augmentedPrompt,
+        temperature: 0,
+        maxTokens: options?.maxTokens ?? 1400,
+      },
+      "callStructured"
+    );
+
+    const text = this.extractText(payload);
+    const parsed = parseJsonObjectFromText<T>(text);
+
+    if (!parsed) {
+      throw mapParseError(VENDOR, "callStructured", text);
+    }
+
+    return {
+      provider: VENDOR,
+      model,
+      latencyMs: Date.now() - started,
+      output: parsed,
+      raw: payload,
+    };
+  }
+
+  async healthCheck(): Promise<boolean> {
+    return Boolean(this.endpoint);
+  }
+}

package/src/strategy.ts

@@ -0,0 +1,166 @@
+/**
+ * @file strategy.ts
+ * Provider selection strategies: smart fallback, retries, aggregation.
+ *
+ * Uses `RaxProviderError` codes to decide whether to retry the same provider
+ * or immediately move to the next one in the fallback chain.
+ */
+
+import { IModelProvider, ModelResponse, ProviderCallOptions } from "@rax-flow/core";
+import { RaxProviderError, RETRYABLE_CODES } from "./error-mapper.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FallbackCallOptions {
+  /** How many times to retry a retryable error on the SAME provider before moving on. */
+  maxRetriesPerProvider?: number;
+  /** Delay in ms between retries (simple linear backoff). */
+  retryDelayMs?: number;
+  /** Per-call options forwarded to each provider. */
+  callOptions?: ProviderCallOptions;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Smart fallback
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Tries each provider in order.
+ * - If a `RaxProviderError` with `isRetryable=true` is thrown, retries up to
+ *   `maxRetriesPerProvider` times (with linear back-off) before moving on.
+ * - If a `RaxProviderError` with `shouldFallback=true` is thrown, skips to
+ *   the next provider immediately.
+ * - Any other error is also treated as a skip trigger.
+ */
+export async function fallbackCall(
+  providers: IModelProvider[],
+  prompt: string,
+  options: FallbackCallOptions = {}
+): Promise<ModelResponse<string>> {
+  const { maxRetriesPerProvider = 1, retryDelayMs = 500, callOptions } = options;
+
+  const errors: string[] = [];
+
+  for (const provider of providers) {
+    const healthy = await provider.healthCheck().catch(() => false);
+    if (!healthy) continue;
+
+    let attempt = 0;
+    let lastError: unknown;
+
+    while (attempt <= maxRetriesPerProvider) {
+      try {
+        return await provider.callModel(prompt, callOptions);
+      } catch (err) {
+        lastError = err;
+
+        if (err instanceof RaxProviderError) {
+          if (err.isRetryable && attempt < maxRetriesPerProvider) {
+            // Retry this provider after a delay
+            await sleep(retryDelayMs * (attempt + 1));
+            attempt++;
+            continue;
+          }
+          // Non-retryable or retries exhausted → next provider
+          errors.push(err.message);
+          break;
+        }
+
+        // Unknown error → move on immediately
+        errors.push(err instanceof Error ? err.message : String(err));
+        break;
+      }
+    }
+
+    if (lastError) {
+      // Log for observability but continue to next provider
+      continue;
+    }
+  }
+
+  throw new Error(`fallback_chain_exhausted: all providers failed.\n${errors.join("\n")}`);
+}
+
+/**
+ * Structured-output variant of the fallback chain.
+ */
+export async function fallbackCallStructured<T>(
+  providers: IModelProvider[],
+  prompt: string,
+  schema: object,
+  options: FallbackCallOptions = {}
+): Promise<ModelResponse<T>> {
+  const { maxRetriesPerProvider = 1, retryDelayMs = 500, callOptions } = options;
+
+  const errors: string[] = [];
+
+  for (const provider of providers) {
+    const healthy = await provider.healthCheck().catch(() => false);
+    if (!healthy) continue;
+
+    let attempt = 0;
+
+    while (attempt <= maxRetriesPerProvider) {
+      try {
+        return await provider.callStructured<T>(prompt, schema, callOptions);
+      } catch (err) {
+        if (err instanceof RaxProviderError && err.isRetryable && attempt < maxRetriesPerProvider) {
+          await sleep(retryDelayMs * (attempt + 1));
+          attempt++;
+          continue;
+        }
+        errors.push(err instanceof Error ? err.message : String(err));
+        break;
+      }
+    }
+  }
+
+  throw new Error(
+    `fallback_structured_chain_exhausted: all providers failed.\n${errors.join("\n")}`
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Aggregate / consensus
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Calls all providers in parallel and picks the longest non-empty output
+ * as a simple consensus heuristic.  Useful for ensemble verification.
+ */
+export async function aggregateCalls(
+  providers: IModelProvider[],
+  prompt: string,
+  callOptions?: ProviderCallOptions
+): Promise<{ outputs: ModelResponse<string>[]; consensus: string }> {
+  const outputs = await Promise.all(
+    providers.map(async (p) => {
+      try {
+        return await p.callModel(prompt, callOptions);
+      } catch {
+        return {
+          provider: "unknown",
+          model: "failed",
+          latencyMs: 0,
+          output: "",
+        } as ModelResponse<string>;
+      }
+    })
+  );
+
+  const nonEmpty = outputs.filter((o: ModelResponse<string>) => o.output.length > 0);
+  const consensus =
+    nonEmpty.sort((a: ModelResponse<string>, b: ModelResponse<string>) => b.output.length - a.output.length)[0]?.output ?? "";
+
+  return { outputs, consensus };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/utils.ts

@@ -0,0 +1,18 @@
+export function parseJsonObjectFromText<T>(text: string): T | null {
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    const match = text.match(/\{[\s\S]*\}/);
+    if (!match) return null;
+    try {
+      return JSON.parse(match[0]) as T;
+    } catch {
+      return null;
+    }
+  }
+}
+
+export function asString(value: unknown): string {
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "references": [
+    {
+      "path": "../core"
+    }
+  ]
+}