@funkai/models 0.3.1 → 0.3.3

package/docs/provider/configuration.md

@@ -1,17 +1,16 @@
 # Provider Configuration
 
-Configuration options for `createModelResolver()` and how to set up provider mappings.
+Configuration options for `createProviderRegistry()` and how to set up provider mappings.
 
 ## Key Concepts
 
-### ModelResolverConfig
+### ProviderRegistryConfig
 
-| Option      | Type                                 | Default     | Description                               |
-| ----------- | ------------------------------------ | ----------- | ----------------------------------------- |
-| `providers` | `ProviderMap`                        | `{}`        | Direct AI SDK provider mappings by prefix |
-| `fallback`  | `(modelId: string) => LanguageModel` | `undefined` | Fallback factory for unmapped prefixes    |
+| Option      | Type          | Default | Description                               |
+| ----------- | ------------- | ------- | ----------------------------------------- |
+| `providers` | `ProviderMap` | `{}`    | Direct AI SDK provider mappings by prefix |
 
-Both fields are optional. A resolver with no configuration throws on every call.
+A registry with no providers throws on every call.
 
 ### ProviderMap
 
@@ -35,7 +34,7 @@ const providers: ProviderMap = {
 Map each provider explicitly. Unmapped prefixes throw an error:
 
 ```ts
-const resolve = createModelResolver({
+const resolve = createProviderRegistry({
   providers: {
     openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
     anthropic: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
@@ -44,54 +43,32 @@ const resolve = createModelResolver({
 });
 ```
 
-### Direct Providers with OpenRouter Fallback
+### With OpenRouter
 
-Map preferred providers directly. Unmapped prefixes route through OpenRouter:
+Include OpenRouter as a provider using `@openrouter/ai-sdk-provider`:
 
 ```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
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 
-Use any function as a fallback:
-
-```ts
-const resolve = createModelResolver({
+const registry = createProviderRegistry({
   providers: {
     openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
-  },
-  fallback: (modelId: string) => {
-    const provider = createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
-    return provider(modelId);
+    openrouter: createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY }),
   },
 });
+
+const lm = registry("openrouter/anthropic/claude-sonnet-4");
 ```
 
 ## Error Handling
 
-`createModelResolver()` throws in these cases:
+`createProviderRegistry()` 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` |
+| Condition       | Error Message                                                    |
+| --------------- | ---------------------------------------------------------------- |
+| Empty model ID  | `Cannot resolve model: model ID is empty`                        |
+| No prefix       | `Cannot resolve model "<id>": no provider prefix`                |
+| Unmapped prefix | `Cannot resolve model "<id>": no provider mapped for "<prefix>"` |
 
 ## References
 

package/docs/provider/openrouter.md

@@ -1,83 +1,64 @@
 # 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).
+OpenRouter acts as a model aggregator, routing requests to the underlying provider. Use the `@openrouter/ai-sdk-provider` package directly to create an OpenRouter provider instance.
 
 ## Key Concepts
 
 ### API Key Resolution
 
-Both `openrouter` and `createOpenRouter` resolve the API key in this order:
+`createOpenRouter` from `@openrouter/ai-sdk-provider` resolves the API key in this order:
 
-1. Explicit `apiKey` in options (for `createOpenRouter`)
+1. Explicit `apiKey` in options
 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:
+`createOpenRouter` from `@openrouter/ai-sdk-provider` creates a provider instance:
 
 ```ts
-const provider = createOpenRouter({ apiKey: "sk-..." });
-const lm = provider("openai/gpt-4.1");
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+
+const openrouter = createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
+const lm = openrouter("openai/gpt-4.1");
 ```
 
 ## Usage
 
-### As a Fallback
+### As a Provider in the Registry
 
-The most common pattern is using `openrouter` as the fallback for `createModelResolver()`:
+The most common pattern is registering OpenRouter as a provider in `createProviderRegistry()`:
 
 ```ts
-const resolve = createModelResolver({
+import { createProviderRegistry } from "@funkai/models";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+
+const registry = createProviderRegistry({
   providers: {
     openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+    openrouter: createOpenRouter({ apiKey: process.env.OPENROUTER_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");
-```
+Models with an `"openai"` prefix route through `@ai-sdk/openai`. Models with an `"openrouter"` prefix route through OpenRouter.
 
 ### Direct Usage
 
-Use `openrouter` directly without a resolver:
+Use `createOpenRouter` directly without a registry:
 
 ```ts
-const lm = openrouter("openai/gpt-4.1");
-```
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 
-### Custom Instance
-
-```ts
-const provider = createOpenRouter({
-  apiKey: process.env.OPENROUTER_API_KEY,
-});
-
-const lm = provider("mistral/mistral-large-latest");
+const openrouter = createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
+const lm = openrouter("openai/gpt-4.1");
 ```
 
 ## Configuration
 
-`createOpenRouter` accepts all options from `@openrouter/ai-sdk-provider`:
+`createOpenRouter` from `@openrouter/ai-sdk-provider` accepts:
 
 | Option   | Type     | Default                          | Description        |
 | -------- | -------- | -------------------------------- | ------------------ |

package/docs/provider/overview.md

@@ -1,6 +1,6 @@
 # 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.
+Provider resolution maps model ID strings to AI SDK `LanguageModel` instances. `createProviderRegistry()` extracts the provider prefix from a model ID and dispatches to the appropriate provider factory.
 
 ## Architecture
 
@@ -23,20 +23,16 @@ Provider resolution maps model ID strings to AI SDK `LanguageModel` instances. `
 }}%%
 sequenceDiagram
   participant C as Caller
-  participant R as ModelResolver
+  participant R as ProviderRegistry
   participant P as ProviderFactory
-  participant F as Fallback
 
-  C->>R: resolve("openai/gpt-4.1")
+  C->>R: registry("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
+  else No match
     R-->>C: Error thrown
   end
 
@@ -47,17 +43,16 @@ sequenceDiagram
 
 ### Resolution Algorithm
 
-When `resolve("openai/gpt-4.1")` is called:
+When `registry("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
+4. If no provider matches, 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.
+Model IDs without a `/` (e.g. `"gpt-4.1"`) have no prefix to match, so an error is thrown. Always use the full `"provider/model"` format.
 
 ### ProviderFactory
 
@@ -83,45 +78,36 @@ const providers: ProviderMap = {
 
 ## Usage
 
-### Basic Resolver
+### Basic Registry
 
 ```ts
-const resolve = createModelResolver({
+const registry = createProviderRegistry({
   providers: {
     openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
   },
 });
 
-const lm = resolve("openai/gpt-4.1");
+const lm = registry("openai/gpt-4.1");
 ```
 
-### Resolver with Fallback
+### Multi-Provider Registry
 
 ```ts
-const resolve = createModelResolver({
+import { createOpenAI } from "@ai-sdk/openai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+
+const registry = createProviderRegistry({
   providers: {
     openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+    anthropic: createAnthropic({ apiKey: process.env.ANTHROPIC_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");
+const lm1 = registry("openai/gpt-4.1");
+const lm2 = registry("anthropic/claude-sonnet-4");
 ```
 
-All models route through OpenRouter regardless of prefix.
+`lm1` routes through `@ai-sdk/openai`. `lm2` routes through `@ai-sdk/anthropic`.
 
 ## References
 

package/docs/provider-resolution.md

@@ -0,0 +1,210 @@
+# Provider Resolution
+
+Provider resolution maps model ID strings to AI SDK `LanguageModel` instances. `createProviderRegistry()` extracts the provider prefix from a model ID and dispatches to the appropriate provider factory.
+
+## How It Works
+
+```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 ProviderRegistry
+  participant P as ProviderFactory
+
+  C->>R: registry("openai/gpt-4.1")
+  R->>R: Extract prefix "openai"
+
+  alt Provider mapped
+    R->>P: factory("gpt-4.1")
+    P-->>R: LanguageModel
+  else No match
+    R-->>C: Error thrown
+  end
+
+  R-->>C: LanguageModel
+```
+
+When `registry("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, an error is thrown
+
+Model IDs without a `/` (e.g. `"gpt-4.1"`) have no prefix to match, so an error is thrown. Always use the full `"provider/model"` format.
+
+## createProviderRegistry() API
+
+### ProviderRegistryConfig
+
+| Option      | Type          | Default | Description                               |
+| ----------- | ------------- | ------- | ----------------------------------------- |
+| `providers` | `ProviderMap` | `{}`    | Direct AI SDK provider mappings by prefix |
+
+A registry with no providers 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.
+
+```ts
+import { createOpenAI } from "@ai-sdk/openai";
+
+const factory: ProviderFactory = createOpenAI({ apiKey: "..." });
+const lm = factory("gpt-4.1");
+```
+
+## Setting Up Providers
+
+### Install Provider SDKs
+
+Install the AI SDK providers you want to use:
+
+```bash
+pnpm add @ai-sdk/openai @ai-sdk/anthropic
+```
+
+### Basic Registry
+
+```ts
+import { createProviderRegistry } from "@funkai/models";
+import { createOpenAI } from "@ai-sdk/openai";
+
+const registry = createProviderRegistry({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  },
+});
+
+const lm = registry("openai/gpt-4.1");
+```
+
+### Multi-Provider Registry
+
+```ts
+import { createProviderRegistry } from "@funkai/models";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+
+const registry = createProviderRegistry({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+    anthropic: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+  },
+});
+
+const gpt = registry("openai/gpt-4.1");
+const claude = registry("anthropic/claude-sonnet-4");
+```
+
+### Use with Agents
+
+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: registry("openai/gpt-4.1"),
+  prompt: ({ input }) => `Summarize:\n\n${input.text}`,
+});
+```
+
+## OpenRouter Integration
+
+OpenRouter acts as a model aggregator, routing requests to the underlying provider. Use the `@openrouter/ai-sdk-provider` package to create an OpenRouter provider instance.
+
+### API Key Resolution
+
+`createOpenRouter` resolves the API key in this order:
+
+1. Explicit `apiKey` in options
+2. `OPENROUTER_API_KEY` environment variable
+
+If neither is set, an error is thrown at call time.
+
+### Configuration
+
+| 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`.
+
+### As a Registry Provider
+
+```ts
+import { createProviderRegistry } from "@funkai/models";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+
+const registry = createProviderRegistry({
+  providers: {
+    openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+    openrouter: createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY }),
+  },
+});
+
+const lm = registry("openrouter/anthropic/claude-sonnet-4");
+```
+
+Models with an `"openai"` prefix route through `@ai-sdk/openai`. Models with an `"openrouter"` prefix route through OpenRouter.
+
+### Direct Usage
+
+Use `createOpenRouter` directly without a registry:
+
+```ts
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+
+const openrouter = createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
+const lm = openrouter("openai/gpt-4.1");
+```
+
+### Resources
+
+- [OpenRouter Documentation](https://openrouter.ai/docs)
+- [@openrouter/ai-sdk-provider](https://www.npmjs.com/package/@openrouter/ai-sdk-provider)
+
+## Error Handling
+
+`createProviderRegistry()` throws in these cases:
+
+| Condition       | Error Message                                                    |
+| --------------- | ---------------------------------------------------------------- |
+| Empty model ID  | `Cannot resolve model: model ID is empty`                        |
+| No prefix       | `Cannot resolve model "<id>": no provider prefix`                |
+| Unmapped prefix | `Cannot resolve model "<id>": no provider mapped for "<prefix>"` |
+
+## References
+
+- [Model Catalog](catalog.md)
+- [Cost Tracking](cost-tracking.md)
+- [Troubleshooting](troubleshooting.md)

package/docs/troubleshooting.md

@@ -4,7 +4,7 @@ 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.
+The model ID passed to the registry is an empty string or whitespace.
 
 **Fix:** Ensure the model ID is a non-empty string:
 
@@ -12,30 +12,27 @@ The model ID passed to the resolver is an empty string or whitespace.
 const lm = resolve("openai/gpt-4.1");
 ```
 
-## Cannot resolve model: no provider prefix and no fallback configured
+## Cannot resolve model: no provider prefix
 
-A model ID without a `/` (e.g. `"gpt-4.1"`) was passed to a resolver with no fallback.
+A model ID without a `/` (e.g. `"gpt-4.1"`) was passed to the registry.
 
-**Fix:** Either use the full `"provider/model"` format or configure a fallback:
+**Fix:** Use the full `"provider/model"` format:
 
 ```ts
-const resolve = createModelResolver({
-  fallback: openrouter,
-});
+const lm = registry("openai/gpt-4.1");
 ```
 
-## Cannot resolve model: no provider mapped for "x" and no fallback configured
+## Cannot resolve model: no provider mapped for "x"
 
-The model ID prefix does not match any key in the `providers` map and no `fallback` is configured.
+The model ID prefix does not match any key in the `providers` map.
 
-**Fix:** Add the provider to the `providers` map or add 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,
 });
 ```
 
@@ -94,7 +91,6 @@ 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)
+- [Model Catalog](catalog.md)
+- [Provider Resolution](provider-resolution.md)
+- [Cost Tracking](cost-tracking.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funkai/models",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "private": false,
   "description": "Model catalog, provider resolution, and cost calculations for the funkai AI SDK",
   "keywords": [
@@ -117,7 +117,7 @@
     "access": "public"
   },
   "dependencies": {
-    "ai": "^6.0.116",
+    "ai": "^6.0.136",
     "type-fest": "^5.5.0"
   },
   "devDependencies": {