@funkai/models 0.1.0

package/docs/guides/track-costs.md

@@ -0,0 +1,133 @@
+# Track Costs
+
+Calculate and accumulate token costs from model invocations using `calculateCost()`.
+
+## Prerequisites
+
+- `@funkai/models` installed
+- Token usage data from model invocations (e.g. from `@funkai/agents` execution traces)
+
+## Steps
+
+### 1. Import Cost Functions
+
+```ts
+import { calculateCost, model } from "@funkai/models";
+import type { TokenUsage } from "@funkai/models";
+```
+
+### 2. Get Model Pricing
+
+Look up the model definition to access its pricing:
+
+```ts
+const m = model("openai/gpt-4.1");
+if (!m) {
+  throw new Error("Model not found in catalog");
+}
+```
+
+### 3. Calculate Cost for a Single Invocation
+
+```ts
+const usage: TokenUsage = {
+  inputTokens: 1500,
+  outputTokens: 800,
+  totalTokens: 2300,
+  cacheReadTokens: 500,
+  cacheWriteTokens: 0,
+  reasoningTokens: 0,
+};
+
+const cost = calculateCost(usage, m.pricing);
+
+console.log(`Input:  $${cost.input.toFixed(6)}`);
+console.log(`Output: $${cost.output.toFixed(6)}`);
+console.log(`Total:  $${cost.total.toFixed(6)}`);
+```
+
+### 4. Accumulate Costs Across Multiple Calls
+
+```ts
+const totalCost = runs.reduce((sum, run) => {
+  const runModel = model(run.modelId);
+  if (!runModel) return sum;
+  return sum + calculateCost(run.usage, runModel.pricing).total;
+}, 0);
+
+console.log(`Session total: $${totalCost.toFixed(6)}`);
+```
+
+### 5. Compare Model Costs
+
+Estimate the cost of a workload across different models:
+
+```ts
+const usage: TokenUsage = {
+  inputTokens: 10_000,
+  outputTokens: 2_000,
+  totalTokens: 12_000,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+  reasoningTokens: 0,
+};
+
+const candidates = ["openai/gpt-4.1", "anthropic/claude-sonnet-4"] as const;
+
+for (const id of candidates) {
+  const m = model(id);
+  if (!m) continue;
+  const cost = calculateCost(usage, m.pricing);
+  console.log(`${id}: $${cost.total.toFixed(6)}`);
+}
+```
+
+## Verification
+
+Verify cost calculation with known values:
+
+```ts
+const usage: TokenUsage = {
+  inputTokens: 1_000_000,
+  outputTokens: 0,
+  totalTokens: 1_000_000,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+  reasoningTokens: 0,
+};
+
+const m = model("openai/gpt-4.1");
+if (m) {
+  const cost = calculateCost(usage, m.pricing);
+  console.log(`1M input tokens: $${cost.total.toFixed(4)}`);
+}
+```
+
+## Troubleshooting
+
+### Cost is 0 for all fields
+
+**Issue:** Token counts are all zero or the pricing rates are zero.
+
+**Fix:** Verify the `TokenUsage` object has non-zero values and the model exists in the catalog:
+
+```ts
+console.log(usage);
+console.log(m.pricing);
+```
+
+### Cache costs are always 0
+
+**Issue:** The model's pricing does not include `cacheRead` or `cacheWrite` rates.
+
+**Fix:** Not all models support prompt caching. Check whether the model's pricing includes cache fields:
+
+```ts
+console.log(m.pricing.cacheRead);
+console.log(m.pricing.cacheWrite);
+```
+
+## References
+
+- [Cost Calculation](../cost/overview.md)
+- [Model Catalog](../catalog/overview.md)

package/docs/overview.md

@@ -0,0 +1,139 @@
+# Models
+
+`@funkai/models` provides a generated model catalog, configurable provider resolution, and token cost calculations for the funkai AI SDK.
+
+## Architecture
+
+```mermaid
+%%{init: {
+  'theme': 'base',
+  'themeVariables': {
+    'primaryColor': '#313244',
+    'primaryTextColor': '#cdd6f4',
+    'primaryBorderColor': '#6c7086',
+    'lineColor': '#89b4fa',
+    'secondaryColor': '#45475a',
+    'tertiaryColor': '#1e1e2e',
+    'background': '#1e1e2e',
+    'mainBkg': '#313244',
+    'clusterBkg': '#1e1e2e',
+    'clusterBorder': '#45475a'
+  },
+  'flowchart': { 'curve': 'basis', 'padding': 15 }
+}}%%
+
+flowchart LR
+  ModelId["Model ID"]:::external
+
+  subgraph catalog [" "]
+    direction TB
+    MODELS["MODELS catalog"]:::core
+    lookup["model() / models()"]:::core
+    filter["Filter predicates"]:::core
+  end
+
+  subgraph resolver [" "]
+    direction TB
+    createResolver["createModelResolver()"]:::core
+    providers["Provider map"]:::gateway
+    fallback["Fallback (OpenRouter)"]:::gateway
+  end
+
+  subgraph cost [" "]
+    direction TB
+    calcCost["calculateCost()"]:::agent
+    usage["TokenUsage"]:::agent
+    pricing["ModelPricing"]:::agent
+  end
+
+  ModelId --> lookup
+  MODELS --> lookup
+  lookup --> filter
+  ModelId --> createResolver
+  createResolver --> providers
+  createResolver --> fallback
+  providers --> LanguageModel["LanguageModel"]:::external
+  fallback --> LanguageModel
+  usage --> calcCost
+  pricing --> calcCost
+  calcCost --> UsageCost["UsageCost"]:::external
+
+  classDef external fill:#313244,stroke:#f5c2e7,stroke-width:2px,color:#cdd6f4
+  classDef core fill:#313244,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+  classDef gateway fill:#313244,stroke:#fab387,stroke-width:2px,color:#cdd6f4
+  classDef agent fill:#313244,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+
+  style catalog fill:#181825,stroke:#89b4fa,stroke-width:2px
+  style resolver fill:#181825,stroke:#fab387,stroke-width:2px
+  style cost fill:#181825,stroke:#a6e3a1,stroke-width:2px
+```
+
+The package has three domains:
+
+| Domain       | Purpose                                      | Key Exports                           |
+| ------------ | -------------------------------------------- | ------------------------------------- |
+| **Catalog**  | Generated model metadata from models.dev     | `model()`, `models()`, `MODELS`       |
+| **Provider** | Resolve model IDs to AI SDK `LanguageModel`s | `createModelResolver()`, `openrouter` |
+| **Cost**     | Calculate USD costs from token usage         | `calculateCost()`                     |
+
+## Key Concepts
+
+### Model Definitions
+
+Every model in the catalog is a `ModelDefinition` with pricing, capabilities, modalities, and context window metadata. The catalog is auto-generated from [models.dev](https://models.dev) and updated via `pnpm --filter=@funkai/models generate:models`.
+
+### Provider Resolution
+
+`createModelResolver()` maps model ID prefixes (e.g. `"openai"` from `"openai/gpt-4.1"`) to AI SDK provider factories. Unmapped prefixes fall through to an optional fallback (typically OpenRouter).
+
+### Cost Calculation
+
+`calculateCost()` multiplies token counts by per-token pricing rates. Pricing is stored per-token in the catalog (converted from per-million at generation time), so no runtime conversion is needed.
+
+## Usage
+
+### Look Up a Model
+
+```ts
+const m = model("openai/gpt-4.1");
+if (m) {
+  console.log(m.name, m.contextWindow, m.capabilities.reasoning);
+}
+```
+
+### Filter Models
+
+```ts
+const reasoning = models((m) => m.capabilities.reasoning);
+const multimodal = models((m) => m.modalities.input.includes("image"));
+```
+
+### Resolve a Model
+
+```ts
+const resolve = createModelResolver({
+  fallback: openrouter,
+});
+const lm = resolve("openai/gpt-4.1");
+```
+
+### Calculate Cost
+
+```ts
+const cost = calculateCost(usage, m.pricing);
+console.log(`Total: $${cost.total.toFixed(6)}`);
+```
+
+## References
+
+- [Model Catalog](catalog/overview.md)
+- [Filtering](catalog/filtering.md)
+- [Providers](catalog/providers.md)
+- [Provider Resolution](provider/overview.md)
+- [Configuration](provider/configuration.md)
+- [OpenRouter](provider/openrouter.md)
+- [Cost Calculation](cost/overview.md)
+- [Setup Resolver Guide](guides/setup-resolver.md)
+- [Filter Models Guide](guides/filter-models.md)
+- [Track Costs Guide](guides/track-costs.md)
+- [Troubleshooting](troubleshooting.md)

package/docs/provider/configuration.md

@@ -0,0 +1,100 @@
+# Provider Configuration
+
+Configuration options for `createModelResolver()` and how to set up provider mappings.
+
+## Key Concepts
+
+### ModelResolverConfig
+
+| Option      | Type                                 | Default     | Description                               |
+| ----------- | ------------------------------------ | ----------- | ----------------------------------------- |
+| `providers` | `ProviderMap`                        | `{}`        | Direct AI SDK provider mappings by prefix |
+| `fallback`  | `(modelId: string) => LanguageModel` | `undefined` | Fallback factory for unmapped prefixes    |
+
+Both fields are optional. A resolver with no configuration throws on every call.
+
+### ProviderMap
+
+`ProviderMap` is `Readonly<Record<string, ProviderFactory>>`. Keys are provider prefixes that match the portion before `/` in a model ID.
+
+```ts
+const providers: ProviderMap = {
+  openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  anthropic: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+};
+```
+
+### ProviderFactory
+
+`ProviderFactory` is `(modelName: string) => LanguageModel`. AI SDK provider constructors (`createOpenAI`, `createAnthropic`, etc.) return compatible factory functions.
+
+## Configuration Patterns
+
+### Direct Providers Only
+
+Map each provider explicitly. Unmapped prefixes throw an error:
+
+```ts
+const resolve = createModelResolver({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+    anthropic: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+    google: createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_API_KEY }),
+  },
+});
+```
+
+### Direct Providers with OpenRouter Fallback
+
+Map preferred providers directly. Unmapped prefixes route through OpenRouter:
+
+```ts
+const resolve = createModelResolver({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  },
+  fallback: openrouter,
+});
+```
+
+### OpenRouter-Only
+
+Route all models through OpenRouter:
+
+```ts
+const resolve = createModelResolver({
+  fallback: openrouter,
+});
+```
+
+### Custom Fallback
+
+Use any function as a fallback:
+
+```ts
+const resolve = createModelResolver({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  },
+  fallback: (modelId: string) => {
+    const provider = createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
+    return provider(modelId);
+  },
+});
+```
+
+## Error Handling
+
+`createModelResolver()` throws in these cases:
+
+| Condition                    | Error Message                                                                               |
+| ---------------------------- | ------------------------------------------------------------------------------------------- |
+| Empty model ID               | `Cannot resolve model: model ID is empty`                                                   |
+| No prefix, no fallback       | `Cannot resolve model "<id>": no provider prefix and no fallback configured`                |
+| Unmapped prefix, no fallback | `Cannot resolve model "<id>": no provider mapped for "<prefix>" and no fallback configured` |
+
+## References
+
+- [Provider Resolution](overview.md)
+- [OpenRouter](openrouter.md)
+- [Setup Resolver Guide](../guides/setup-resolver.md)

package/docs/provider/openrouter.md

@@ -0,0 +1,105 @@
+# OpenRouter Integration
+
+OpenRouter acts as a model aggregator, routing requests to the underlying provider. `@funkai/models` provides two exports for OpenRouter integration: `openrouter` (cached singleton) and `createOpenRouter` (factory).
+
+## Key Concepts
+
+### API Key Resolution
+
+Both `openrouter` and `createOpenRouter` resolve the API key in this order:
+
+1. Explicit `apiKey` in options (for `createOpenRouter`)
+2. `OPENROUTER_API_KEY` environment variable
+
+If neither is set, an error is thrown at call time.
+
+### Cached Provider
+
+The `openrouter` export is a cached resolver. The underlying provider instance is created once and reused across calls. If `OPENROUTER_API_KEY` changes at runtime, the cache invalidates and a new provider is created.
+
+```ts
+const lm = openrouter("openai/gpt-4.1");
+```
+
+### Provider Factory
+
+`createOpenRouter` creates a new `OpenRouterProvider` instance. Use this when you need multiple providers with different configurations:
+
+```ts
+const provider = createOpenRouter({ apiKey: "sk-..." });
+const lm = provider("openai/gpt-4.1");
+```
+
+## Usage
+
+### As a Fallback
+
+The most common pattern is using `openrouter` as the fallback for `createModelResolver()`:
+
+```ts
+const resolve = createModelResolver({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  },
+  fallback: openrouter,
+});
+```
+
+Models with an `"openai"` prefix route directly. All other prefixes route through OpenRouter.
+
+### As the Only Provider
+
+```ts
+const resolve = createModelResolver({
+  fallback: openrouter,
+});
+
+const lm = resolve("anthropic/claude-sonnet-4");
+```
+
+### Direct Usage
+
+Use `openrouter` directly without a resolver:
+
+```ts
+const lm = openrouter("openai/gpt-4.1");
+```
+
+### Custom Instance
+
+```ts
+const provider = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+const lm = provider("mistral/mistral-large-latest");
+```
+
+## Configuration
+
+`createOpenRouter` accepts all options from `@openrouter/ai-sdk-provider`:
+
+| Option   | Type     | Default                          | Description        |
+| -------- | -------- | -------------------------------- | ------------------ |
+| `apiKey` | `string` | `process.env.OPENROUTER_API_KEY` | OpenRouter API key |
+
+Additional options are forwarded directly to the underlying `@openrouter/ai-sdk-provider`.
+
+## Environment Variables
+
+| Variable             | Required | Description        |
+| -------------------- | -------- | ------------------ |
+| `OPENROUTER_API_KEY` | No\*     | OpenRouter API key |
+
+\*Required when `apiKey` is not provided to `createOpenRouter(...)`.
+
+## Resources
+
+- [OpenRouter Documentation](https://openrouter.ai/docs)
+- [@openrouter/ai-sdk-provider](https://www.npmjs.com/package/@openrouter/ai-sdk-provider)
+
+## References
+
+- [Provider Resolution](overview.md)
+- [Configuration](configuration.md)
+- [Setup Resolver Guide](../guides/setup-resolver.md)

package/docs/provider/overview.md

@@ -0,0 +1,131 @@
+# Provider Resolution
+
+Provider resolution maps model ID strings to AI SDK `LanguageModel` instances. `createModelResolver()` extracts the provider prefix from a model ID and dispatches to the appropriate provider factory.
+
+## Architecture
+
+```mermaid
+%%{init: {
+  'theme': 'base',
+  'themeVariables': {
+    'primaryColor': '#313244',
+    'primaryTextColor': '#cdd6f4',
+    'primaryBorderColor': '#6c7086',
+    'lineColor': '#89b4fa',
+    'secondaryColor': '#45475a',
+    'tertiaryColor': '#1e1e2e',
+    'actorBkg': '#313244',
+    'actorBorder': '#89b4fa',
+    'actorTextColor': '#cdd6f4',
+    'signalColor': '#cdd6f4',
+    'signalTextColor': '#cdd6f4'
+  }
+}}%%
+sequenceDiagram
+  participant C as Caller
+  participant R as ModelResolver
+  participant P as ProviderFactory
+  participant F as Fallback
+
+  C->>R: resolve("openai/gpt-4.1")
+  R->>R: Extract prefix "openai"
+
+  alt Provider mapped
+    R->>P: factory("gpt-4.1")
+    P-->>R: LanguageModel
+  else No match, fallback configured
+    R->>F: fallback("openai/gpt-4.1")
+    F-->>R: LanguageModel
+  else No match, no fallback
+    R-->>C: Error thrown
+  end
+
+  R-->>C: LanguageModel
+```
+
+## Key Concepts
+
+### Resolution Algorithm
+
+When `resolve("openai/gpt-4.1")` is called:
+
+1. The model ID is validated (non-empty)
+2. The prefix before the first `/` is extracted (`"openai"`)
+3. If a provider factory is mapped for that prefix, it receives the model portion (`"gpt-4.1"`)
+4. If no provider matches, the fallback receives the full ID (if configured)
+5. If no fallback exists, an error is thrown
+
+### Model IDs Without a Prefix
+
+Model IDs without a `/` (e.g. `"gpt-4.1"`) skip provider lookup entirely and go directly to the fallback. If no fallback is configured, an error is thrown.
+
+### ProviderFactory
+
+A `ProviderFactory` is a function that takes a model name string and returns a `LanguageModel`. AI SDK provider constructors like `createOpenAI()` return compatible factories:
+
+```ts
+import { createOpenAI } from "@ai-sdk/openai";
+
+const factory: ProviderFactory = createOpenAI({ apiKey: "..." });
+const lm = factory("gpt-4.1");
+```
+
+### ProviderMap
+
+A `ProviderMap` is a readonly record mapping prefix strings to `ProviderFactory` functions:
+
+```ts
+const providers: ProviderMap = {
+  openai: createOpenAI({ apiKey: "..." }),
+  anthropic: createAnthropic({ apiKey: "..." }),
+};
+```
+
+## Usage
+
+### Basic Resolver
+
+```ts
+const resolve = createModelResolver({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  },
+});
+
+const lm = resolve("openai/gpt-4.1");
+```
+
+### Resolver with Fallback
+
+```ts
+const resolve = createModelResolver({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  },
+  fallback: openrouter,
+});
+
+const lm1 = resolve("openai/gpt-4.1");
+const lm2 = resolve("anthropic/claude-sonnet-4");
+```
+
+`lm1` routes through the direct OpenAI provider. `lm2` has no mapped provider for `"anthropic"`, so it falls through to the OpenRouter fallback.
+
+### Fallback-Only Resolver
+
+```ts
+const resolve = createModelResolver({
+  fallback: openrouter,
+});
+
+const lm = resolve("openai/gpt-4.1");
+```
+
+All models route through OpenRouter regardless of prefix.
+
+## References
+
+- [Configuration](configuration.md)
+- [OpenRouter](openrouter.md)
+- [Model Catalog](../catalog/overview.md)
+- [Setup Resolver Guide](../guides/setup-resolver.md)

package/docs/troubleshooting.md

@@ -0,0 +1,100 @@
+# Models Troubleshooting
+
+Common issues and fixes for `@funkai/models`.
+
+## Cannot resolve model: model ID is empty
+
+The model ID passed to the resolver is an empty string or whitespace.
+
+**Fix:** Ensure the model ID is a non-empty string:
+
+```ts
+const lm = resolve("openai/gpt-4.1");
+```
+
+## Cannot resolve model: no provider prefix and no fallback configured
+
+A model ID without a `/` (e.g. `"gpt-4.1"`) was passed to a resolver with no fallback.
+
+**Fix:** Either use the full `"provider/model"` format or configure a fallback:
+
+```ts
+const resolve = createModelResolver({
+  fallback: openrouter,
+});
+```
+
+## Cannot resolve model: no provider mapped for "x" and no fallback configured
+
+The model ID prefix does not match any key in the `providers` map and no `fallback` is configured.
+
+**Fix:** Add the provider to the `providers` map or add a fallback:
+
+```ts
+const resolve = createModelResolver({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  },
+  fallback: openrouter,
+});
+```
+
+## OPENROUTER_API_KEY environment variable is required
+
+`openrouter` or `createOpenRouter()` was called without an API key, and `OPENROUTER_API_KEY` is not set in the environment.
+
+**Fix:** Set the environment variable:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
+```
+
+Or pass the key explicitly:
+
+```ts
+const provider = createOpenRouter({ apiKey: "sk-or-..." });
+```
+
+## model() returns null
+
+The model ID is not in the generated catalog. This can happen with new or custom models.
+
+**Fix:** Check the model ID is correct. Regenerate the catalog to include newly released models:
+
+```bash
+pnpm --filter=@funkai/models generate:models
+```
+
+## models() returns empty array
+
+No models match the filter predicate.
+
+**Fix:** Check available values before filtering:
+
+```ts
+const providers = [...new Set(models().map((m) => m.provider))];
+console.log(providers);
+```
+
+## Module not found: @funkai/models/provider
+
+The subpath import does not match an available export.
+
+**Fix:** Check the `exports` field in `package.json`. Valid subpath imports use the provider slug (e.g. `@funkai/models/openai`, not `@funkai/models/provider/openai`).
+
+## Type error: ModelId is not assignable
+
+`ModelId` uses `LiteralUnion` which accepts both known catalog IDs and arbitrary strings. If you see type errors, ensure you are importing `ModelId` from `@funkai/models`:
+
+```ts
+import type { ModelId } from "@funkai/models";
+
+const id: ModelId = "openai/gpt-4.1";
+```
+
+## References
+
+- [Model Catalog](catalog/overview.md)
+- [Provider Resolution](provider/overview.md)
+- [Cost Calculation](cost/overview.md)
+- [Setup Resolver Guide](guides/setup-resolver.md)