@funkai/models 0.3.2 → 0.3.3

package/docs/catalog.md

@@ -0,0 +1,302 @@
+# Model Catalog
+
+The model catalog is an auto-generated, readonly collection of `ModelDefinition` objects sourced from [models.dev](https://models.dev). It provides lookup functions, type-safe IDs with autocomplete, and per-provider subpath exports.
+
+## 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
+  source["models.dev API"]:::external
+
+  subgraph generation [" "]
+    script["generate:models script"]:::core
+    providers["Per-provider .ts files"]:::core
+  end
+
+  subgraph catalog [" "]
+    MODELS["MODELS constant"]:::core
+    modelFn["model(id)"]:::core
+    modelsFn["models(filter?)"]:::core
+  end
+
+  source --> script
+  script --> providers
+  providers --> MODELS
+  MODELS --> modelFn
+  MODELS --> modelsFn
+
+  classDef external fill:#313244,stroke:#f5c2e7,stroke-width:2px,color:#cdd6f4
+  classDef core fill:#313244,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+
+  style generation fill:#181825,stroke:#fab387,stroke-width:2px
+  style catalog fill:#181825,stroke:#89b4fa,stroke-width:2px
+```
+
+## ModelDefinition
+
+Each model has the following fields:
+
+| Field           | Type                | Description                                    |
+| --------------- | ------------------- | ---------------------------------------------- |
+| `id`            | `string`            | Provider-native identifier (e.g. `"gpt-4.1"`)  |
+| `name`          | `string`            | Human-readable display name                    |
+| `provider`      | `string`            | Provider slug (e.g. `"openai"`)                |
+| `family`        | `string`            | Model family (e.g. `"gpt"`, `"claude-sonnet"`) |
+| `pricing`       | `ModelPricing`      | Per-token pricing rates in USD                 |
+| `contextWindow` | `number`            | Maximum context window in tokens               |
+| `maxOutput`     | `number`            | Maximum output tokens                          |
+| `modalities`    | `ModelModalities`   | Supported input/output modalities              |
+| `capabilities`  | `ModelCapabilities` | Boolean capability flags                       |
+
+### ModelPricing
+
+| Field        | Type                  | Description                         |
+| ------------ | --------------------- | ----------------------------------- |
+| `input`      | `number`              | Cost per input token                |
+| `output`     | `number`              | Cost per output token               |
+| `cacheRead`  | `number \| undefined` | Cost per cached input token (read)  |
+| `cacheWrite` | `number \| undefined` | Cost per cached input token (write) |
+
+### ModelCapabilities
+
+| Field              | Type      | Description                      |
+| ------------------ | --------- | -------------------------------- |
+| `reasoning`        | `boolean` | Supports chain-of-thought        |
+| `toolCall`         | `boolean` | Supports tool (function) calling |
+| `attachment`       | `boolean` | Supports file/image attachments  |
+| `structuredOutput` | `boolean` | Supports structured JSON output  |
+
+### ModelModalities
+
+| Field    | Type                | Description                                          |
+| -------- | ------------------- | ---------------------------------------------------- |
+| `input`  | `readonly string[]` | Accepted input modalities (e.g. `"text"`, `"image"`) |
+| `output` | `readonly string[]` | Produced output modalities                           |
+
+## Lookup API
+
+### Look Up a Single Model
+
+`model(id)` returns the matching `ModelDefinition` or `null`:
+
+```ts
+import { model } from "@funkai/models";
+
+const m = model("openai/gpt-4.1");
+if (m) {
+  console.log(m.name);
+  console.log(m.pricing.input);
+  console.log(m.capabilities.reasoning);
+}
+```
+
+### Get All Models
+
+`models()` returns the full catalog. Pass a predicate to filter:
+
+```ts
+import { models } from "@funkai/models";
+
+const all = models();
+const withTools = models((m) => m.capabilities.toolCall);
+```
+
+### Access the Raw Catalog
+
+`MODELS` is the complete readonly array, useful when you need direct iteration:
+
+```ts
+import { MODELS } from "@funkai/models";
+
+const providers = new Set(MODELS.map((m) => m.provider));
+```
+
+## ModelId Type
+
+`ModelId` provides autocomplete for known model IDs while accepting arbitrary strings for new or custom models:
+
+```ts
+import type { ModelId } from "@funkai/models";
+
+const id: ModelId = "openai/gpt-4.1";
+```
+
+## Filtering Patterns
+
+`models()` accepts an optional predicate function `(m: ModelDefinition) => boolean`. When provided, only models where the predicate returns `true` are included.
+
+### Filter by Capability
+
+```ts
+const reasoning = models((m) => m.capabilities.reasoning);
+const withTools = models((m) => m.capabilities.toolCall);
+const structured = models((m) => m.capabilities.structuredOutput);
+```
+
+### Filter by Provider
+
+```ts
+const openai = models((m) => m.provider === "openai");
+const anthropic = models((m) => m.provider === "anthropic");
+```
+
+### Filter by Modality
+
+```ts
+const vision = models((m) => m.modalities.input.includes("image"));
+const audio = models((m) => m.modalities.input.includes("audio"));
+const multimodal = models((m) => m.modalities.input.length > 1);
+```
+
+### Filter by Context Window
+
+```ts
+const largeContext = models((m) => m.contextWindow >= 128_000);
+const longOutput = models((m) => m.maxOutput >= 16_000);
+```
+
+### Filter by Pricing
+
+```ts
+const cheapInput = models((m) => m.pricing.input < 0.000001);
+const withCache = models((m) => m.pricing.cacheRead != null);
+```
+
+### Filter by Family
+
+```ts
+const gpt = models((m) => m.family === "gpt");
+const claude = models((m) => m.family.startsWith("claude"));
+```
+
+### Combine Multiple Conditions
+
+```ts
+const ideal = models(
+  (m) =>
+    m.capabilities.reasoning &&
+    m.capabilities.toolCall &&
+    m.contextWindow >= 128_000 &&
+    m.pricing.input < 0.00001,
+);
+```
+
+### Sort by Price
+
+```ts
+const cheapest = models((m) => m.capabilities.reasoning).toSorted(
+  (a, b) => a.pricing.input - b.pricing.input,
+);
+
+const pick = cheapest[0];
+```
+
+### Extract Unique Values
+
+```ts
+const providers = [...new Set(models().map((m) => m.provider))];
+const families = [...new Set(models().map((m) => m.family))];
+```
+
+### Per-Provider Filtering
+
+Use subpath exports for provider-scoped operations:
+
+```ts
+import { openAIModels } from "@funkai/models/openai";
+
+const reasoningGpt = openAIModels.filter((m) => m.capabilities.reasoning);
+```
+
+## Supported Providers
+
+The model catalog includes models from 21 providers. Each provider has a dedicated subpath export and a prefix used in model IDs.
+
+| Provider       | Prefix           | Subpath Import                  |
+| -------------- | ---------------- | ------------------------------- |
+| OpenAI         | `openai`         | `@funkai/models/openai`         |
+| Anthropic      | `anthropic`      | `@funkai/models/anthropic`      |
+| Google         | `google`         | `@funkai/models/google`         |
+| Google Vertex  | `google-vertex`  | `@funkai/models/google-vertex`  |
+| Mistral        | `mistral`        | `@funkai/models/mistral`        |
+| Amazon Bedrock | `amazon-bedrock` | `@funkai/models/amazon-bedrock` |
+| Groq           | `groq`           | `@funkai/models/groq`           |
+| DeepSeek       | `deepseek`       | `@funkai/models/deepseek`       |
+| xAI            | `xai`            | `@funkai/models/xai`            |
+| Cohere         | `cohere`         | `@funkai/models/cohere`         |
+| Fireworks AI   | `fireworks-ai`   | `@funkai/models/fireworks-ai`   |
+| Together AI    | `togetherai`     | `@funkai/models/togetherai`     |
+| DeepInfra      | `deepinfra`      | `@funkai/models/deepinfra`      |
+| Cerebras       | `cerebras`       | `@funkai/models/cerebras`       |
+| Perplexity     | `perplexity`     | `@funkai/models/perplexity`     |
+| OpenRouter     | `openrouter`     | `@funkai/models/openrouter`     |
+| Llama          | `llama`          | `@funkai/models/llama`          |
+| Alibaba        | `alibaba`        | `@funkai/models/alibaba`        |
+| NVIDIA         | `nvidia`         | `@funkai/models/nvidia`         |
+| Hugging Face   | `huggingface`    | `@funkai/models/huggingface`    |
+| Inception      | `inception`      | `@funkai/models/inception`      |
+
+## Per-Provider Subpath Exports
+
+Each provider subpath exports three members following a consistent naming pattern:
+
+| Export              | Type       | Description                                      |
+| ------------------- | ---------- | ------------------------------------------------ |
+| `<provider>Models`  | `const`    | Readonly array of `ModelDefinition` for provider |
+| `<provider>Model`   | `function` | Look up a model by ID, returns `null` if missing |
+| `<Provider>ModelId` | `type`     | Union type of known model IDs for the provider   |
+
+```ts
+import { anthropicModels, anthropicModel } from "@funkai/models/anthropic";
+import type { AnthropicModelId } from "@funkai/models/anthropic";
+
+const id: AnthropicModelId = "claude-sonnet-4-20250514";
+
+const m = anthropicModel(id);
+if (m) {
+  console.log(m.name, m.pricing.input);
+}
+
+const withReasoning = anthropicModels.filter((m) => m.capabilities.reasoning);
+```
+
+Model IDs in the catalog use the format `<provider-native-id>` (e.g. `"gpt-4.1"`, `"claude-sonnet-4-20250514"`). When used with `createProviderRegistry()`, prefix them with the provider slug: `"openai/gpt-4.1"`, `"anthropic/claude-sonnet-4-20250514"`.
+
+## Updating the Catalog
+
+Regenerate the catalog from models.dev:
+
+```bash
+pnpm --filter=@funkai/models generate:models
+```
+
+Force-regenerate (ignoring staleness cache):
+
+```bash
+pnpm --filter=@funkai/models generate:models --force
+```
+
+This requires `OPENROUTER_API_KEY` to be set in the environment.
+
+## References
+
+- [Provider Resolution](provider-resolution.md)
+- [Cost Tracking](cost-tracking.md)
+- [Troubleshooting](troubleshooting.md)

package/docs/cost-tracking.md

@@ -0,0 +1,144 @@
+# Cost Tracking
+
+`calculateCost()` computes the USD cost of a model invocation by multiplying token counts against per-token pricing rates from the catalog.
+
+## calculateCost() API
+
+```ts
+import { calculateCost, model } from "@funkai/models";
+import type { TokenUsage } from "@funkai/models";
+
+const m = model("openai/gpt-4.1");
+if (m) {
+  const cost = calculateCost(usage, m.pricing);
+}
+```
+
+## Types
+
+### TokenUsage
+
+Token counts from a model invocation:
+
+| Field              | Type     | Description                           |
+| ------------------ | -------- | ------------------------------------- |
+| `inputTokens`      | `number` | Number of input (prompt) tokens       |
+| `outputTokens`     | `number` | Number of output (completion) tokens  |
+| `totalTokens`      | `number` | Total tokens (input + output)         |
+| `cacheReadTokens`  | `number` | Tokens served from prompt cache       |
+| `cacheWriteTokens` | `number` | Tokens written into prompt cache      |
+| `reasoningTokens`  | `number` | Tokens consumed by internal reasoning |
+
+### ModelPricing
+
+Per-token pricing rates from the model catalog:
+
+| Field        | Type                  | Description                       |
+| ------------ | --------------------- | --------------------------------- |
+| `input`      | `number`              | Cost per input token (USD)        |
+| `output`     | `number`              | Cost per output token (USD)       |
+| `cacheRead`  | `number \| undefined` | Cost per cached read token (USD)  |
+| `cacheWrite` | `number \| undefined` | Cost per cached write token (USD) |
+
+Pricing rates are stored per-token in the catalog (converted from per-million at generation time). No runtime conversion is needed.
+
+### UsageCost
+
+The output of `calculateCost()`:
+
+| Field        | Type     | Description                  |
+| ------------ | -------- | ---------------------------- |
+| `input`      | `number` | Cost for input tokens        |
+| `output`     | `number` | Cost for output tokens       |
+| `cacheRead`  | `number` | Cost for cached read tokens  |
+| `cacheWrite` | `number` | Cost for cached write tokens |
+| `total`      | `number` | Sum of all cost fields       |
+
+All fields are non-negative. Fields that don't apply are `0`.
+
+## Basic Usage
+
+```ts
+const m = model("openai/gpt-4.1");
+if (!m) {
+  throw new Error("Model not found in catalog");
+}
+
+const usage: TokenUsage = {
+  inputTokens: 1500,
+  outputTokens: 800,
+  totalTokens: 2300,
+  cacheReadTokens: 500,
+  cacheWriteTokens: 0,
+  reasoningTokens: 0,
+};
+
+const cost = calculateCost(usage, m.pricing);
+console.log(`Total: $${cost.total.toFixed(6)}`);
+```
+
+## Cost Breakdown
+
+```ts
+const cost = calculateCost(usage, m.pricing);
+
+console.log(`Input:       $${cost.input.toFixed(6)}`);
+console.log(`Output:      $${cost.output.toFixed(6)}`);
+console.log(`Cache read:  $${cost.cacheRead.toFixed(6)}`);
+console.log(`Cache write: $${cost.cacheWrite.toFixed(6)}`);
+console.log(`Total:       $${cost.total.toFixed(6)}`);
+```
+
+## Accumulating Costs Across 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)}`);
+```
+
+## Comparing 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 = models((m) => m.capabilities.reasoning);
+
+const costs = candidates.map((m) => ({
+  id: m.id,
+  total: calculateCost(usage, m.pricing).total,
+}));
+
+const sorted = costs.toSorted((a, b) => a.total - b.total);
+```
+
+## Calculation Formula
+
+```text
+input      = inputTokens      * pricing.input
+output     = outputTokens     * pricing.output
+cacheRead  = cacheReadTokens  * (pricing.cacheRead  ?? 0)
+cacheWrite = cacheWriteTokens * (pricing.cacheWrite ?? 0)
+total      = input + output + cacheRead + cacheWrite
+```
+
+Optional pricing fields (`cacheRead`, `cacheWrite`) default to `0` when absent.
+
+## References
+
+- [Model Catalog](catalog.md)
+- [Provider Resolution](provider-resolution.md)
+- [Troubleshooting](troubleshooting.md)

package/docs/guides/setup-resolver.md

@@ -1,12 +1,11 @@
-# Set Up a Model Resolver
+# Set Up a Provider Registry
 
-Configure `createModelResolver()` with multiple providers and an OpenRouter fallback.
+Configure `createProviderRegistry()` with multiple providers.
 
 ## Prerequisites
 
 - `@funkai/models` installed
 - API keys for your providers (OpenAI, Anthropic, etc.)
-- `OPENROUTER_API_KEY` set in the environment (for fallback)
 
 ## Steps
 
@@ -18,55 +17,52 @@ Install the AI SDK providers you want to use directly:
 pnpm add @ai-sdk/openai @ai-sdk/anthropic
 ```
 
-### 2. Create the Resolver
+### 2. Create the Registry
 
 ```ts
-import { createModelResolver, openrouter } from "@funkai/models";
+import { createProviderRegistry } from "@funkai/models";
 import { createOpenAI } from "@ai-sdk/openai";
 import { createAnthropic } from "@ai-sdk/anthropic";
 
-const resolve = createModelResolver({
+const registry = createProviderRegistry({
   providers: {
     openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
     anthropic: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
   },
-  fallback: openrouter,
 });
 ```
 
 ### 3. Resolve Models
 
 ```ts
-const gpt = resolve("openai/gpt-4.1");
-const claude = resolve("anthropic/claude-sonnet-4");
-const mistral = resolve("mistral/mistral-large-latest");
+const gpt = registry("openai/gpt-4.1");
+const claude = registry("anthropic/claude-sonnet-4");
 ```
 
 - `"openai/gpt-4.1"` routes through `@ai-sdk/openai` directly
 - `"anthropic/claude-sonnet-4"` routes through `@ai-sdk/anthropic` directly
-- `"mistral/mistral-large-latest"` has no mapped provider, so it routes through OpenRouter
 
 ### 4. Use with Agents
 
-Pass the resolver to `@funkai/agents` by resolving the model before creating the agent:
+Pass the registry to `@funkai/agents` by resolving the model before creating the agent:
 
 ```ts
 import { agent } from "@funkai/agents";
 
 const summarizer = agent({
   name: "summarizer",
-  model: resolve("openai/gpt-4.1"),
+  model: registry("openai/gpt-4.1"),
   prompt: ({ input }) => `Summarize:\n\n${input.text}`,
 });
 ```
 
 ## Verification
 
-Verify the resolver works by resolving each configured provider:
+Verify the registry works by resolving each configured provider:
 
 ```ts
-const gpt = resolve("openai/gpt-4.1");
-const claude = resolve("anthropic/claude-sonnet-4");
+const gpt = registry("openai/gpt-4.1");
+const claude = registry("anthropic/claude-sonnet-4");
 
 console.log(gpt.modelId);
 console.log(claude.modelId);
@@ -76,29 +72,18 @@ console.log(claude.modelId);
 
 ### Cannot resolve model: no provider mapped
 
-**Issue:** The model ID prefix does not match any key in `providers` and no `fallback` is configured.
+**Issue:** The model ID prefix does not match any key in `providers`.
 
-**Fix:** Add the provider to the `providers` map or configure a `fallback`:
+**Fix:** Add the provider to the `providers` map:
 
 ```ts
-const resolve = createModelResolver({
+const registry = createProviderRegistry({
   providers: {
     openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
   },
-  fallback: openrouter,
 });
 ```
 
-### OPENROUTER_API_KEY environment variable is required
-
-**Issue:** Using `openrouter` as the fallback but `OPENROUTER_API_KEY` is not set.
-
-**Fix:** Set the environment variable:
-
-```bash
-export OPENROUTER_API_KEY=sk-or-...
-```
-
 ## References
 
 - [Provider Resolution](../provider/overview.md)

package/docs/overview.md

@@ -34,9 +34,8 @@ flowchart LR
 
   subgraph resolver [" "]
     direction TB
-    createResolver["createModelResolver()"]:::core
+    createRegistry["createProviderRegistry()"]:::core
     providers["Provider map"]:::gateway
-    fallback["Fallback (OpenRouter)"]:::gateway
   end
 
   subgraph cost [" "]
@@ -49,11 +48,9 @@ flowchart LR
   ModelId --> lookup
   MODELS --> lookup
   lookup --> filter
-  ModelId --> createResolver
-  createResolver --> providers
-  createResolver --> fallback
+  ModelId --> createRegistry
+  createRegistry --> providers
   providers --> LanguageModel["LanguageModel"]:::external
-  fallback --> LanguageModel
   usage --> calcCost
   pricing --> calcCost
   calcCost --> UsageCost["UsageCost"]:::external
@@ -68,72 +65,19 @@ flowchart LR
   style cost fill:#181825,stroke:#a6e3a1,stroke-width:2px
 ```
 
-The package has three domains:
+## 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()`                     |
+| Domain       | Purpose                                      | Key Exports                     |
+| ------------ | -------------------------------------------- | ------------------------------- |
+| **Catalog**  | Generated model metadata from models.dev     | `model()`, `models()`, `MODELS` |
+| **Provider** | Resolve model IDs to AI SDK `LanguageModel`s | `createProviderRegistry()`      |
+| **Cost**     | Calculate USD costs from token usage         | `calculateCost()`               |
 
-## Key Concepts
+## Documentation
 
-### 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)
+| Topic                                         | Description                                                                 |
+| --------------------------------------------- | --------------------------------------------------------------------------- |
+| [Model Catalog](catalog.md)                   | Model definitions, lookup API, filtering patterns, provider subpath exports |
+| [Provider Resolution](provider-resolution.md) | Resolution algorithm, registry configuration, OpenRouter integration        |
+| [Cost Tracking](cost-tracking.md)             | calculateCost() API, types, formula, usage patterns                         |
+| [Troubleshooting](troubleshooting.md)         | Common errors and fixes                                                     |