@funkai/models 0.1.0

package/src/cost/calculate.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest";
+
+import { calculateCost } from "./calculate.js";
+import type { ModelPricing } from "@/catalog/types.js";
+import type { TokenUsage } from "@/provider/types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const ZERO_USAGE: TokenUsage = {
+  inputTokens: 0,
+  outputTokens: 0,
+  totalTokens: 0,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+  reasoningTokens: 0,
+};
+
+const BASIC_PRICING: ModelPricing = {
+  input: 0.000002,
+  output: 0.000008,
+};
+
+const FULL_PRICING: ModelPricing = {
+  input: 0.000002,
+  output: 0.000008,
+  cacheRead: 0.0000005,
+  cacheWrite: 0.000001,
+};
+
+const REASONING_PRICING: ModelPricing = {
+  input: 0.000002,
+  output: 0.000008,
+  cacheRead: 0.0000005,
+  cacheWrite: 0.000001,
+  reasoning: 0.000012,
+};
+
+// ---------------------------------------------------------------------------
+// calculateCost()
+// ---------------------------------------------------------------------------
+
+describe("calculateCost()", () => {
+  it("returns all zeros for zero usage", () => {
+    const result = calculateCost(ZERO_USAGE, FULL_PRICING);
+
+    expect(result.input).toBe(0);
+    expect(result.output).toBe(0);
+    expect(result.cacheRead).toBe(0);
+    expect(result.cacheWrite).toBe(0);
+    expect(result.reasoning).toBe(0);
+    expect(result.total).toBe(0);
+  });
+
+  it("calculates input and output costs", () => {
+    const usage: TokenUsage = {
+      ...ZERO_USAGE,
+      inputTokens: 1000,
+      outputTokens: 500,
+      totalTokens: 1500,
+    };
+
+    const result = calculateCost(usage, BASIC_PRICING);
+
+    expect(result.input).toBeCloseTo(0.002);
+    expect(result.output).toBeCloseTo(0.004);
+    expect(result.total).toBeCloseTo(0.006);
+  });
+
+  it("handles pricing without optional fields", () => {
+    const usage: TokenUsage = {
+      inputTokens: 1000,
+      outputTokens: 500,
+      totalTokens: 1500,
+      cacheReadTokens: 200,
+      cacheWriteTokens: 100,
+      reasoningTokens: 50,
+    };
+
+    const result = calculateCost(usage, BASIC_PRICING);
+
+    // Optional pricing fields default to 0, so cache and reasoning cost nothing
+    expect(result.cacheRead).toBe(0);
+    expect(result.cacheWrite).toBe(0);
+    expect(result.reasoning).toBe(0);
+    expect(result.total).toBeCloseTo(0.006);
+  });
+
+  it("calculates full cost breakdown with all pricing fields", () => {
+    const usage: TokenUsage = {
+      inputTokens: 1000,
+      outputTokens: 500,
+      totalTokens: 1500,
+      cacheReadTokens: 200,
+      cacheWriteTokens: 100,
+      reasoningTokens: 300,
+    };
+
+    const result = calculateCost(usage, FULL_PRICING);
+
+    expect(result.input).toBeCloseTo(0.002);
+    expect(result.output).toBeCloseTo(0.004);
+    expect(result.cacheRead).toBeCloseTo(0.0001);
+    expect(result.cacheWrite).toBeCloseTo(0.0001);
+    expect(result.total).toBeCloseTo(0.0062);
+  });
+
+  it("calculates reasoning token costs when pricing is provided", () => {
+    const usage: TokenUsage = {
+      inputTokens: 1000,
+      outputTokens: 500,
+      totalTokens: 1500,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      reasoningTokens: 800,
+    };
+
+    const result = calculateCost(usage, REASONING_PRICING);
+
+    expect(result.reasoning).toBeCloseTo(0.0096);
+    expect(result.total).toBeCloseTo(0.002 + 0.004 + 0.0096);
+  });
+
+  it("defaults reasoning cost to zero when pricing omits reasoning", () => {
+    const usage: TokenUsage = {
+      inputTokens: 1000,
+      outputTokens: 500,
+      totalTokens: 1500,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      reasoningTokens: 800,
+    };
+
+    const result = calculateCost(usage, BASIC_PRICING);
+
+    expect(result.reasoning).toBe(0);
+    expect(result.total).toBeCloseTo(0.006);
+  });
+
+  it("total equals sum of all fields", () => {
+    const usage: TokenUsage = {
+      inputTokens: 500,
+      outputTokens: 250,
+      totalTokens: 750,
+      cacheReadTokens: 100,
+      cacheWriteTokens: 50,
+      reasoningTokens: 150,
+    };
+
+    const result = calculateCost(usage, FULL_PRICING);
+    const expectedTotal =
+      result.input + result.output + result.cacheRead + result.cacheWrite + result.reasoning;
+
+    expect(result.total).toBeCloseTo(expectedTotal);
+  });
+});

package/src/cost/calculate.ts

@@ -0,0 +1,43 @@
+import type { UsageCost } from "./types.js";
+import type { ModelPricing } from "@/catalog/types.js";
+import type { TokenUsage } from "@/provider/types.js";
+
+/**
+ * Calculate the dollar cost from token usage and model pricing.
+ *
+ * Multiplies each token count by the corresponding per-token pricing rate.
+ * Optional pricing fields (cache) default to `0` when absent.
+ *
+ * @param usage - Token counts from a model invocation.
+ * @param pricing - Per-token pricing rates for the model.
+ * @returns A {@link UsageCost} with per-field and total costs in USD.
+ *
+ * @example
+ * ```typescript
+ * import { calculateCost, model } from '@funkai/models'
+ *
+ * const usage: TokenUsage = {
+ *   inputTokens: 1000,
+ *   outputTokens: 500,
+ *   totalTokens: 1500,
+ *   cacheReadTokens: 200,
+ *   cacheWriteTokens: 0,
+ *   reasoningTokens: 0,
+ * }
+ * const m = model('gpt-4.1')
+ * if (m) {
+ *   const cost = calculateCost(usage, m.pricing)
+ *   console.log(cost.total) // 0.006
+ * }
+ * ```
+ */
+export function calculateCost(usage: TokenUsage, pricing: ModelPricing): UsageCost {
+  const input = usage.inputTokens * pricing.input;
+  const output = usage.outputTokens * pricing.output;
+  const cacheRead = usage.cacheReadTokens * (pricing.cacheRead ?? 0);
+  const cacheWrite = usage.cacheWriteTokens * (pricing.cacheWrite ?? 0);
+  const reasoning = usage.reasoningTokens * (pricing.reasoning ?? 0);
+  const total = input + output + cacheRead + cacheWrite + reasoning;
+
+  return { input, output, cacheRead, cacheWrite, reasoning, total };
+}

package/src/cost/index.ts

@@ -0,0 +1,2 @@
+export { calculateCost } from "./calculate.js";
+export type { UsageCost } from "./types.js";

package/src/cost/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Breakdown of cost in USD from a model invocation.
+ *
+ * Each field is the dollar cost for that token category.
+ * All fields are non-negative numbers. Fields that don't apply are `0`.
+ */
+export interface UsageCost {
+  /** Cost for input tokens. */
+  readonly input: number;
+
+  /** Cost for output tokens. */
+  readonly output: number;
+
+  /** Cost for cached input tokens (read). */
+  readonly cacheRead: number;
+
+  /** Cost for cached input tokens (write). */
+  readonly cacheWrite: number;
+
+  /** Cost for reasoning tokens. */
+  readonly reasoning: number;
+
+  /** Total cost (sum of all fields). */
+  readonly total: number;
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+// Catalog
+export { model, models, MODELS } from "@/catalog/index.js";
+export type {
+  KnownModelId,
+  ModelId,
+  ModelCapabilities,
+  ModelModalities,
+  ModelPricing,
+  ModelDefinition,
+} from "@/catalog/index.js";
+
+// Provider
+export { createOpenRouter, openrouter } from "@/provider/openrouter.js";
+export { createModelResolver } from "@/provider/resolver.js";
+export type {
+  ProviderFactory,
+  ProviderMap,
+  ModelResolverConfig,
+  ModelResolver,
+} from "@/provider/resolver.js";
+export type { LanguageModel, TokenUsage } from "@/provider/types.js";
+
+// Cost
+export { calculateCost } from "@/cost/calculate.js";
+export type { UsageCost } from "@/cost/types.js";

package/src/provider/index.ts

@@ -0,0 +1,9 @@
+export { createOpenRouter, openrouter } from "./openrouter.js";
+export { createModelResolver } from "./resolver.js";
+export type {
+  ProviderFactory,
+  ProviderMap,
+  ModelResolverConfig,
+  ModelResolver,
+} from "./resolver.js";
+export type { LanguageModel, TokenUsage } from "./types.js";

package/src/provider/openrouter.test.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock the external provider before importing the module under test
+const mockBaseCreateOpenRouter = vi.fn();
+const mockProviderInstance = vi.fn();
+
+vi.mock("@openrouter/ai-sdk-provider", () => ({
+  createOpenRouter: mockBaseCreateOpenRouter,
+}));
+
+// Must import after mocking
+const { createOpenRouter, openrouter } = await import("@/provider/openrouter.js");
+
+// ---------------------------------------------------------------------------
+// createOpenRouter()
+// ---------------------------------------------------------------------------
+
+describe("createOpenRouter()", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockBaseCreateOpenRouter.mockReturnValue(mockProviderInstance);
+    vi.stubEnv("OPENROUTER_API_KEY", "env-key-123");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("uses explicit apiKey when provided in options", () => {
+    createOpenRouter({ apiKey: "explicit-key" });
+
+    expect(mockBaseCreateOpenRouter).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: "explicit-key" }),
+    );
+  });
+
+  it("falls back to OPENROUTER_API_KEY env var when no apiKey in options", () => {
+    createOpenRouter();
+
+    expect(mockBaseCreateOpenRouter).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: "env-key-123" }),
+    );
+  });
+
+  it("falls back to env var when options are provided without apiKey", () => {
+    createOpenRouter({});
+
+    expect(mockBaseCreateOpenRouter).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: "env-key-123" }),
+    );
+  });
+
+  it("throws when no apiKey provided and env var is not set", () => {
+    vi.stubEnv("OPENROUTER_API_KEY", undefined as unknown as string);
+
+    expect(() => createOpenRouter()).toThrow("OPENROUTER_API_KEY environment variable is required");
+  });
+
+  it("forwards additional options to the base provider", () => {
+    createOpenRouter({ apiKey: "key", baseURL: "https://custom.api" } as Record<string, unknown>);
+
+    expect(mockBaseCreateOpenRouter).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiKey: "key",
+        baseURL: "https://custom.api",
+      }),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// openrouter() — cached model factory
+// ---------------------------------------------------------------------------
+
+describe("openrouter()", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockProviderInstance.mockReturnValue({ modelId: "mock-model" });
+    mockBaseCreateOpenRouter.mockReturnValue(mockProviderInstance);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("creates a provider and returns a language model", () => {
+    vi.stubEnv("OPENROUTER_API_KEY", "key-test-create");
+
+    const result = openrouter("openai/gpt-5.2-codex");
+
+    expect(mockBaseCreateOpenRouter).toHaveBeenCalledWith({ apiKey: "key-test-create" });
+    expect(mockProviderInstance).toHaveBeenCalledWith("openai/gpt-5.2-codex");
+    expect(result).toEqual({ modelId: "mock-model" });
+  });
+
+  it("reuses cached provider on subsequent calls with same api key", () => {
+    vi.stubEnv("OPENROUTER_API_KEY", "key-test-reuse");
+
+    openrouter("openai/gpt-5.2-codex");
+    openrouter("openai/gpt-5.2");
+
+    // Provider should only be created once since key is the same
+    expect(mockBaseCreateOpenRouter).toHaveBeenCalledTimes(1);
+    expect(mockProviderInstance).toHaveBeenCalledTimes(2);
+  });
+
+  it("creates new provider when api key changes", () => {
+    vi.stubEnv("OPENROUTER_API_KEY", "key-test-change-1");
+    openrouter("openai/gpt-5.2-codex");
+
+    vi.stubEnv("OPENROUTER_API_KEY", "key-test-change-2");
+    openrouter("openai/gpt-5.2");
+
+    expect(mockBaseCreateOpenRouter).toHaveBeenCalledTimes(2);
+    expect(mockBaseCreateOpenRouter).toHaveBeenLastCalledWith({ apiKey: "key-test-change-2" });
+  });
+
+  it("throws when OPENROUTER_API_KEY is not set", () => {
+    vi.stubEnv("OPENROUTER_API_KEY", undefined as unknown as string);
+
+    expect(() => openrouter("openai/gpt-5.2-codex")).toThrow(
+      "OPENROUTER_API_KEY environment variable is required",
+    );
+  });
+});

package/src/provider/openrouter.ts

@@ -0,0 +1,110 @@
+import {
+  createOpenRouter as baseCreateOpenRouter,
+  type OpenRouterProvider,
+  type OpenRouterProviderSettings,
+} from "@openrouter/ai-sdk-provider";
+
+import type { ModelId } from "@/catalog/index.js";
+import type { LanguageModel } from "@/provider/types.js";
+
+/**
+ * Create an OpenRouter provider instance with automatic API key resolution.
+ *
+ * Falls back to the `OPENROUTER_API_KEY` environment variable when
+ * no explicit `apiKey` is provided in the options.
+ *
+ * @param options - Provider settings forwarded to `@openrouter/ai-sdk-provider`.
+ * @returns A configured {@link OpenRouterProvider} instance.
+ *
+ * @example
+ * ```typescript
+ * const openrouter = createOpenRouter({ apiKey: 'sk-...' })
+ * const m = openrouter('openai/gpt-5.2-codex')
+ * ```
+ */
+export function createOpenRouter(options?: OpenRouterProviderSettings): OpenRouterProvider {
+  const apiKey = resolveApiKey(options);
+  return baseCreateOpenRouter({
+    ...options,
+    apiKey,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * @private
+ */
+function resolveApiKey(options: OpenRouterProviderSettings | undefined): string {
+  if (options != null && options.apiKey != null) {
+    return options.apiKey;
+  }
+  return getOpenRouterApiKey();
+}
+
+/**
+ * Create a cached OpenRouter model resolver.
+ *
+ * The returned function caches the underlying provider and invalidates
+ * when the API key changes at runtime.
+ *
+ * @returns A function that resolves a model ID to a {@link LanguageModel}.
+ *
+ * @private
+ */
+// Cache mutation is safe: JS is single-threaded and baseCreateOpenRouter is synchronous.
+// If this were refactored to async initialization, a lock or re-architecture would be needed.
+function createCachedOpenRouter(): (modelId: ModelId) => LanguageModel {
+  const cache: { provider: OpenRouterProvider | undefined; apiKey: string | undefined } = {
+    provider: undefined,
+    apiKey: undefined,
+  };
+  return (modelId: ModelId): LanguageModel => {
+    const apiKey = getOpenRouterApiKey();
+    if (!cache.provider || cache.apiKey !== apiKey) {
+      cache.provider = baseCreateOpenRouter({ apiKey });
+      cache.apiKey = apiKey;
+    }
+    return cache.provider(modelId);
+  };
+}
+
+/**
+ * Shorthand for creating a single OpenRouter language model.
+ *
+ * Resolves the API key from the environment and returns a ready-to-use
+ * {@link LanguageModel} that can be passed directly to AI SDK functions.
+ *
+ * The provider instance is cached at module scope and reused across
+ * calls. If `OPENROUTER_API_KEY` changes at runtime, the cache is
+ * invalidated and a new provider is created.
+ *
+ * @param modelId - A model identifier (e.g. `"openai/gpt-5.2-codex"`).
+ * @returns A configured {@link LanguageModel} instance.
+ *
+ * @example
+ * ```typescript
+ * const m = openrouter('openai/gpt-5.2-codex')
+ * ```
+ */
+export const openrouter: (modelId: ModelId) => LanguageModel = createCachedOpenRouter();
+
+/**
+ * Read the OpenRouter API key from the environment.
+ *
+ * @throws {Error} If `OPENROUTER_API_KEY` is not set.
+ *
+ * @private
+ */
+function getOpenRouterApiKey(): string {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "OPENROUTER_API_KEY environment variable is required. " +
+        "Set it in your .env file or environment.",
+    );
+  }
+  return apiKey;
+}

package/src/provider/resolver.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createModelResolver } from "@/provider/resolver.js";
+import type { LanguageModel } from "@/provider/types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function fakeModel(id: string): LanguageModel {
+  return { modelId: id } as unknown as LanguageModel;
+}
+
+function fakeFactory(prefix: string): (modelName: string) => LanguageModel {
+  return (modelName: string) => fakeModel(`${prefix}/${modelName}`);
+}
+
+// ---------------------------------------------------------------------------
+// createModelResolver()
+// ---------------------------------------------------------------------------
+
+describe("createModelResolver()", () => {
+  it("throws when no providers or fallback are configured for prefixed ID", () => {
+    const resolve = createModelResolver();
+
+    expect(() => resolve("openai/gpt-4.1")).toThrow(
+      'Cannot resolve model "openai/gpt-4.1": no provider mapped for "openai" and no fallback configured',
+    );
+  });
+
+  it("throws when no providers or fallback are configured for unprefixed ID", () => {
+    const resolve = createModelResolver();
+
+    expect(() => resolve("gpt-4.1")).toThrow(
+      'Cannot resolve model "gpt-4.1": no provider prefix and no fallback configured',
+    );
+  });
+
+  it("uses a mapped provider when prefix matches", () => {
+    const openaiFactory = vi.fn(fakeFactory("openai"));
+    const resolve = createModelResolver({
+      providers: { openai: openaiFactory },
+    });
+
+    const result = resolve("openai/gpt-4.1");
+
+    expect(openaiFactory).toHaveBeenCalledWith("gpt-4.1");
+    expect(result).toEqual(fakeModel("openai/gpt-4.1"));
+  });
+
+  it("falls back to fallback for unmapped prefixes", () => {
+    const fallback = vi.fn((id: string) => fakeModel(id));
+    const resolve = createModelResolver({
+      providers: { openai: fakeFactory("openai") },
+      fallback,
+    });
+
+    resolve("anthropic/claude-sonnet-4-20250514");
+
+    expect(fallback).toHaveBeenCalledWith("anthropic/claude-sonnet-4-20250514");
+  });
+
+  it("handles model IDs without a slash via fallback", () => {
+    const fallback = vi.fn((id: string) => fakeModel(id));
+    const resolve = createModelResolver({ fallback });
+
+    resolve("gpt-4.1");
+
+    expect(fallback).toHaveBeenCalledWith("gpt-4.1");
+  });
+
+  it("throws for unmapped prefixes when no fallback is configured", () => {
+    const resolve = createModelResolver({
+      providers: { openai: fakeFactory("openai") },
+    });
+
+    expect(() => resolve("anthropic/claude-sonnet-4-20250514")).toThrow(
+      'Cannot resolve model "anthropic/claude-sonnet-4-20250514": no provider mapped for "anthropic" and no fallback configured',
+    );
+  });
+
+  it("supports multiple mapped providers", () => {
+    const openaiFactory = vi.fn(fakeFactory("openai"));
+    const anthropicFactory = vi.fn(fakeFactory("anthropic"));
+
+    const resolve = createModelResolver({
+      providers: {
+        openai: openaiFactory,
+        anthropic: anthropicFactory,
+      },
+    });
+
+    resolve("openai/gpt-4.1");
+    resolve("anthropic/claude-sonnet-4-20250514");
+
+    expect(openaiFactory).toHaveBeenCalledWith("gpt-4.1");
+    expect(anthropicFactory).toHaveBeenCalledWith("claude-sonnet-4-20250514");
+  });
+
+  it("handles model IDs with multiple slashes correctly", () => {
+    const resolve = createModelResolver({
+      providers: { "meta-llama": fakeFactory("meta-llama") },
+    });
+
+    resolve("meta-llama/llama-4-scout/extended");
+
+    expect(resolve("meta-llama/llama-4-scout/extended")).toEqual(
+      fakeModel("meta-llama/llama-4-scout/extended"),
+    );
+  });
+
+  it("throws for empty model ID", () => {
+    const resolve = createModelResolver();
+
+    expect(() => resolve("")).toThrow("Cannot resolve model: model ID is empty");
+  });
+
+  it("throws for whitespace-only model ID", () => {
+    const resolve = createModelResolver();
+
+    expect(() => resolve("   ")).toThrow("Cannot resolve model: model ID is empty");
+  });
+
+  it("prefers mapped provider over fallback", () => {
+    const openaiFactory = vi.fn(fakeFactory("openai"));
+    const fallback = vi.fn((id: string) => fakeModel(id));
+
+    const resolve = createModelResolver({
+      providers: { openai: openaiFactory },
+      fallback,
+    });
+
+    resolve("openai/gpt-4.1");
+
+    expect(openaiFactory).toHaveBeenCalledWith("gpt-4.1");
+    expect(fallback).not.toHaveBeenCalled();
+  });
+});