@funkai/models 0.1.0

package/docs/catalog/filtering.md

@@ -0,0 +1,102 @@
+# Filtering Models
+
+Advanced patterns for filtering the model catalog using `models()` predicates.
+
+## Key Concepts
+
+### Predicate-Based Filtering
+
+`models()` accepts an optional predicate function `(m: ModelDefinition) => boolean`. When provided, only models where the predicate returns `true` are included. When omitted, the full catalog is returned.
+
+```ts
+const filtered = models((m) => m.capabilities.reasoning);
+```
+
+## Usage
+
+### 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,
+);
+```
+
+### Chain Filters with Array Methods
+
+Since `models()` returns `readonly ModelDefinition[]`, standard array methods work:
+
+```ts
+const sorted = models((m) => m.capabilities.reasoning).toSorted(
+  (a, b) => a.pricing.input - b.pricing.input,
+);
+
+const cheapest = sorted[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);
+```
+
+## References
+
+- [Model Catalog](overview.md)
+- [Providers](providers.md)
+- [Filter Models Guide](../guides/filter-models.md)

package/docs/catalog/overview.md

@@ -0,0 +1,168 @@
+# 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
+```
+
+## Key Concepts
+
+### 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                           |
+
+## Usage
+
+### Look Up a Single Model
+
+`model(id)` returns the matching `ModelDefinition` or `null`:
+
+```ts
+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
+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
+const providers = new Set(MODELS.map((m) => m.provider));
+```
+
+### Type-Safe Model IDs
+
+`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";
+```
+
+### Per-Provider Subpath Exports
+
+Each provider has a dedicated subpath with a filtered model list, lookup function, and typed ID:
+
+```ts
+import { openAIModels, openAIModel } from "@funkai/models/openai";
+
+const m = openAIModel("gpt-4o-2024-11-20");
+```
+
+## 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
+
+- [Filtering](filtering.md)
+- [Providers](providers.md)
+- [Provider Resolution](../provider/overview.md)
+- [Cost Calculation](../cost/overview.md)

package/docs/catalog/providers.md

@@ -0,0 +1,73 @@
+# 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 List
+
+| 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`      |
+
+## Subpath Export API
+
+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   |
+
+### Example
+
+```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 ID Format
+
+Model IDs in the catalog use the format `<provider-native-id>` (e.g. `"gpt-4.1"`, `"claude-sonnet-4-20250514"`). When used with `createModelResolver()`, prefix them with the provider slug: `"openai/gpt-4.1"`, `"anthropic/claude-sonnet-4-20250514"`.
+
+## Data Source
+
+All provider data is auto-generated from [models.dev](https://models.dev) via the `generate:models` script. To update:
+
+```bash
+pnpm --filter=@funkai/models generate:models
+```
+
+## References
+
+- [Model Catalog](overview.md)
+- [Filtering](filtering.md)
+- [Provider Resolution](../provider/overview.md)

package/docs/cost/overview.md

@@ -0,0 +1,125 @@
+# Cost Calculation
+
+`calculateCost()` computes the USD cost of a model invocation by multiplying token counts against per-token pricing rates from the catalog.
+
+## Key Concepts
+
+### 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`.
+
+## Usage
+
+### Basic Cost Calculation
+
+```ts
+const m = model("openai/gpt-4.1");
+if (m) {
+  const usage: TokenUsage = {
+    inputTokens: 1000,
+    outputTokens: 500,
+    totalTokens: 1500,
+    cacheReadTokens: 200,
+    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)}`);
+```
+
+### Compare Costs Across Models
+
+```ts
+const candidates = models((m) => m.capabilities.reasoning);
+
+const usage: TokenUsage = {
+  inputTokens: 10_000,
+  outputTokens: 2_000,
+  totalTokens: 12_000,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+  reasoningTokens: 0,
+};
+
+const costs = candidates.map((m) => ({
+  id: m.id,
+  total: calculateCost(usage, m.pricing).total,
+}));
+
+const sorted = costs.toSorted((a, b) => a.total - b.total);
+```
+
+### Accumulate Costs
+
+```ts
+const totalCost = runs.reduce((sum, run) => {
+  const cost = calculateCost(run.usage, run.model.pricing);
+  return sum + cost.total;
+}, 0);
+```
+
+## 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/overview.md)
+- [Track Costs Guide](../guides/track-costs.md)

package/docs/guides/filter-models.md

@@ -0,0 +1,113 @@
+# Filter Models
+
+Common patterns for finding the right model from the catalog using `models()` predicates.
+
+## Prerequisites
+
+- `@funkai/models` installed
+
+## Steps
+
+### 1. Import the Catalog Functions
+
+```ts
+import { models, model } from "@funkai/models";
+```
+
+### 2. Filter by Capability
+
+Find models with specific capabilities:
+
+```ts
+const reasoning = models((m) => m.capabilities.reasoning);
+const withTools = models((m) => m.capabilities.toolCall);
+const structured = models((m) => m.capabilities.structuredOutput);
+```
+
+### 3. Filter by Provider
+
+Narrow to a specific provider:
+
+```ts
+const openai = models((m) => m.provider === "openai");
+```
+
+Or use the subpath export:
+
+```ts
+import { openAIModels } from "@funkai/models/openai";
+```
+
+### 4. Combine Conditions
+
+Chain multiple requirements:
+
+```ts
+const ideal = models(
+  (m) =>
+    m.capabilities.reasoning &&
+    m.capabilities.toolCall &&
+    m.contextWindow >= 128_000 &&
+    m.pricing.input < 0.00001,
+);
+```
+
+### 5. Sort by Price
+
+Find the cheapest model matching your criteria:
+
+```ts
+const cheapest = models((m) => m.capabilities.reasoning).toSorted(
+  (a, b) => a.pricing.input - b.pricing.input,
+);
+
+const pick = cheapest[0];
+```
+
+### 6. Find Multimodal Models
+
+```ts
+const vision = models((m) => m.modalities.input.includes("image"));
+const audio = models((m) => m.modalities.input.includes("audio"));
+```
+
+## Verification
+
+Verify your filter returns expected results:
+
+```ts
+const results = models((m) => m.capabilities.reasoning && m.provider === "openai");
+
+for (const m of results) {
+  console.log(m.id, m.name, m.pricing.input);
+}
+```
+
+## Troubleshooting
+
+### Filter returns empty array
+
+**Issue:** No models match your predicate.
+
+**Fix:** Relax your filter conditions. Check which values exist in the catalog:
+
+```ts
+const providers = [...new Set(models().map((m) => m.provider))];
+console.log(providers);
+```
+
+### Model not found in catalog
+
+**Issue:** `model(id)` returns `null` for a model you expect to exist.
+
+**Fix:** The catalog is generated periodically. Regenerate it to include new models:
+
+```bash
+pnpm --filter=@funkai/models generate:models
+```
+
+## References
+
+- [Model Catalog](../catalog/overview.md)
+- [Filtering](../catalog/filtering.md)
+- [Providers](../catalog/providers.md)

package/docs/guides/setup-resolver.md

@@ -0,0 +1,106 @@
+# Set Up a Model Resolver
+
+Configure `createModelResolver()` with multiple providers and an OpenRouter fallback.
+
+## Prerequisites
+
+- `@funkai/models` installed
+- API keys for your providers (OpenAI, Anthropic, etc.)
+- `OPENROUTER_API_KEY` set in the environment (for fallback)
+
+## Steps
+
+### 1. Install Provider SDKs
+
+Install the AI SDK providers you want to use directly:
+
+```bash
+pnpm add @ai-sdk/openai @ai-sdk/anthropic
+```
+
+### 2. Create the Resolver
+
+```ts
+import { createModelResolver, openrouter } from "@funkai/models";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+
+const resolve = createModelResolver({
+  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");
+```
+
+- `"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:
+
+```ts
+import { agent } from "@funkai/agents";
+
+const summarizer = agent({
+  name: "summarizer",
+  model: resolve("openai/gpt-4.1"),
+  prompt: ({ input }) => `Summarize:\n\n${input.text}`,
+});
+```
+
+## Verification
+
+Verify the resolver works by resolving each configured provider:
+
+```ts
+const gpt = resolve("openai/gpt-4.1");
+const claude = resolve("anthropic/claude-sonnet-4");
+
+console.log(gpt.modelId);
+console.log(claude.modelId);
+```
+
+## Troubleshooting
+
+### Cannot resolve model: no provider mapped
+
+**Issue:** The model ID prefix does not match any key in `providers` and no `fallback` is configured.
+
+**Fix:** Add the provider to the `providers` map or configure a `fallback`:
+
+```ts
+const resolve = createModelResolver({
+  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)
+- [Configuration](../provider/configuration.md)
+- [OpenRouter](../provider/openrouter.md)