language-models 2.0.2 → 2.1.3

package/.turbo/turbo-build.log

@@ -1,5 +1,4 @@
-
-
-> language-models@2.0.1 build /Users/nathanclevenger/projects/primitives.org.ai/packages/language-models
-> tsc -p tsconfig.json && cp -r data dist/
-
+
+> language-models@2.1.3 build /Users/nathanclevenger/projects/primitives.org.ai/packages/language-models
+> tsc -p tsconfig.json && cp -r data dist/
+

package/.turbo/turbo-test.log

@@ -0,0 +1,18 @@
+
+> language-models@2.1.1 test /Users/nathanclevenger/projects/primitives.org.ai/packages/language-models
+> vitest
+
+
+ DEV  v2.1.9 /Users/nathanclevenger/projects/primitives.org.ai/packages/language-models
+
+ ✓ src/aliases.test.ts (48 tests) 8ms
+ ✓ src/models.test.ts (41 tests) 8ms
+ ✓ src/index.test.ts (39 tests) 11ms
+
+ Test Files  3 passed (3)
+      Tests  128 passed (128)
+   Start at  06:45:30
+   Duration  356ms (transform 238ms, setup 0ms, collect 326ms, tests 28ms, environment 0ms, prepare 112ms)
+
+ PASS  Waiting for file changes...
+       press h to show help, press q to quit

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # language-models
 
+## 2.1.3
+
+### Patch Changes
+
+- Documentation and testing improvements
+  - Add deterministic AI testing suite with self-validating patterns
+  - Apply StoryBrand narrative to all package READMEs
+  - Update TESTING.md with four principles of deterministic AI testing
+  - Fix duplicate examples package name conflict
+
+## 2.1.1
+
+## 2.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - rpc.do@0.2.0
+
 ## 2.0.2
 
 ## 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 .org.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,79 +1,140 @@
 # language-models
 
-Model listing and resolution for LLM providers. Fetches models from OpenRouter and resolves aliases to full model IDs.
+**Stop memorizing model IDs. Start shipping.**
+
+You're building AI-powered applications, but every provider has different naming conventions. Is it `claude-opus-4-5-20251101` or `anthropic/claude-opus-4.5`? Was it `gpt-4o` or `openai/gpt-4o`? You shouldn't have to care.
+
+## The Problem
+
+```typescript
+// Without language-models: fragile, provider-specific, constantly breaking
+const model = 'anthropic/claude-3-opus-20240229' // Wait, is this still current?
+const model = 'claude-opus-4-5-20251101'         // Or was it this format?
+const model = 'anthropic/claude-opus-4.5'        // Which one does OpenRouter want?
+```
+
+## The Solution
+
+```typescript
+// With language-models: simple, memorable, always resolves correctly
+import { resolve } from 'language-models'
+
+resolve('opus')   // 'anthropic/claude-opus-4.5'
+resolve('sonnet') // 'anthropic/claude-sonnet-4.5'
+resolve('gpt')    // 'openai/gpt-4o'
+resolve('llama')  // 'meta-llama/llama-4-maverick'
+```
 
 ## Quick Start
 
+**1. Install**
+```bash
+npm install language-models
+```
+
+**2. Import**
 ```typescript
 import { resolve, list, search } from 'language-models'
+```
 
-// Resolve aliases to full model IDs
-resolve('opus')        // 'anthropic/claude-opus-4.5'
-resolve('gpt-4o')      // 'openai/gpt-4o'
-resolve('llama-70b')   // 'meta-llama/llama-3.3-70b-instruct'
-resolve('mistral')     // 'mistralai/mistral-large-2411'
-
-// List all available models
-const models = list()
+**3. Use**
+```typescript
+// Resolve human-friendly aliases to full model IDs
+const modelId = resolve('opus')
 
-// Search models
+// Search across 200+ models
 const claudeModels = search('claude')
+
+// Get full model catalog with pricing and context info
+const allModels = list()
 ```
 
-## API
+## API Reference
 
 ### `resolve(input: string): string`
 
-Resolve an alias or partial name to a full model ID.
+Resolve an alias or partial name to a full OpenRouter model ID.
 
 ```typescript
 resolve('opus')                      // 'anthropic/claude-opus-4.5'
 resolve('sonnet')                    // 'anthropic/claude-sonnet-4.5'
 resolve('gpt')                       // 'openai/gpt-4o'
 resolve('llama')                     // 'meta-llama/llama-4-maverick'
-resolve('anthropic/claude-opus-4.5') // 'anthropic/claude-opus-4.5' (pass-through)
+resolve('anthropic/claude-opus-4.5') // Pass-through for full IDs
+```
+
+### `resolveWithProvider(input: string): ResolvedModel`
+
+Get full routing information including provider details for direct SDK access.
+
+```typescript
+const info = resolveWithProvider('opus')
+// {
+//   id: 'anthropic/claude-opus-4.5',
+//   provider: 'anthropic',
+//   providerModelId: 'claude-opus-4-5-20251101',
+//   supportsDirectRouting: true,
+//   model: { name, pricing, context_length, ... }
+// }
 ```
 
 ### `list(): ModelInfo[]`
 
-List all available models from OpenRouter.
+Get the complete model catalog with pricing, context lengths, and capabilities.
 
 ### `get(id: string): ModelInfo | undefined`
 
-Get a model by exact ID.
+Fetch a specific model by exact ID.
 
 ### `search(query: string): ModelInfo[]`
 
-Search models by ID or name.
-
-## Available Aliases
-
-| Alias | Model ID |
-|-------|----------|
-| `opus` | anthropic/claude-opus-4.5 |
-| `sonnet` | anthropic/claude-sonnet-4.5 |
-| `haiku` | anthropic/claude-haiku-4.5 |
-| `claude` | anthropic/claude-sonnet-4.5 |
-| `gpt`, `gpt-4o`, `4o` | openai/gpt-4o |
-| `o1`, `o3`, `o3-mini` | openai/o1, openai/o3, openai/o3-mini |
-| `gemini`, `flash` | google/gemini-2.5-flash |
-| `gemini-pro` | google/gemini-2.5-pro |
-| `llama`, `llama-4` | meta-llama/llama-4-maverick |
-| `llama-70b` | meta-llama/llama-3.3-70b-instruct |
-| `mistral` | mistralai/mistral-large-2411 |
-| `codestral` | mistralai/codestral-2501 |
-| `deepseek` | deepseek/deepseek-chat |
-| `r1` | deepseek/deepseek-r1 |
-| `qwen` | qwen/qwen3-235b-a22b |
-| `grok` | x-ai/grok-3 |
-| `sonar` | perplexity/sonar-pro |
-
-## Updating Models
-
-Fetch the latest models from OpenRouter:
+Find models matching a search query across IDs and names.
+
+## Supported Aliases
+
+| You type | You get |
+|----------|---------|
+| `opus` | `anthropic/claude-opus-4.5` |
+| `sonnet` | `anthropic/claude-sonnet-4.5` |
+| `haiku` | `anthropic/claude-haiku-4.5` |
+| `gpt`, `gpt-4o`, `4o` | `openai/gpt-4o` |
+| `o1`, `o3`, `o3-mini` | `openai/o1`, `openai/o3`, `openai/o3-mini` |
+| `gemini`, `flash` | `google/gemini-2.5-flash` |
+| `gemini-pro` | `google/gemini-2.5-pro` |
+| `llama`, `llama-4` | `meta-llama/llama-4-maverick` |
+| `llama-70b` | `meta-llama/llama-3.3-70b-instruct` |
+| `mistral` | `mistralai/mistral-large-2411` |
+| `codestral` | `mistralai/codestral-2501` |
+| `deepseek` | `deepseek/deepseek-chat` |
+| `r1` | `deepseek/deepseek-r1` |
+| `qwen` | `qwen/qwen3-235b-a22b` |
+| `grok` | `x-ai/grok-3` |
+| `sonar` | `perplexity/sonar-pro` |
+
+## Direct Provider Routing
+
+For providers that support direct SDK access (Anthropic, OpenAI, Google), use `resolveWithProvider` to get the native model ID:
+
+```typescript
+import { resolveWithProvider, DIRECT_PROVIDERS } from 'language-models'
+
+const { provider, providerModelId, supportsDirectRouting } = resolveWithProvider('opus')
+
+if (supportsDirectRouting) {
+  // Use native SDK with providerModelId
+} else {
+  // Route through OpenRouter
+}
+```
+
+## Updating the Model Catalog
 
 ```bash
 pnpm fetch-models
 ```
 
-This updates `data/models.json` with all available models.
+Fetches the latest models from OpenRouter and updates `data/models.json`.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "language-models",
-  "version": "2.0.2",
+  "version": "2.1.3",
   "description": "Model listing and resolution for LLM providers",
   "type": "module",
   "main": "dist/index.js",
@@ -11,15 +11,6 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json && cp -r data dist/",
-    "dev": "tsc -p tsconfig.json --watch",
-    "test": "vitest",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "clean": "rm -rf dist",
-    "fetch-models": "npx tsx scripts/fetch-models.ts"
-  },
   "keywords": [
     "ai",
     "llm",
@@ -28,7 +19,14 @@
     "primitives"
   ],
   "license": "MIT",
-  "dependencies": {
-    "rpc.do": "^0.1.0"
+  "dependencies": {},
+  "scripts": {
+    "build": "tsc -p tsconfig.json && cp -r data dist/",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "clean": "rm -rf dist",
+    "fetch-models": "npx tsx scripts/fetch-models.ts"
   }
-}
+}

package/scripts/fetch-models.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env npx tsx
+/**
+ * Fetch models from OpenRouter API and save to data/models.json
+ *
+ * Fetches from both:
+ * - /api/v1/models - Basic model info
+ * - /api/frontend/models - Provider routing info (provider_model_id, endpoint)
+ *
+ * Usage: npx tsx scripts/fetch-models.ts
+ */
+import { writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const OUTPUT_PATH = join(__dirname, '..', 'data', 'models.json');
+async function fetchModels() {
+    console.log('Fetching models from OpenRouter API...');
+    // Fetch basic model info
+    const modelsResponse = await fetch('https://openrouter.ai/api/v1/models');
+    if (!modelsResponse.ok) {
+        throw new Error(`Failed to fetch models: ${modelsResponse.status} ${modelsResponse.statusText}`);
+    }
+    const modelsData = await modelsResponse.json();
+    const models = modelsData.data || modelsData;
+    console.log(`Found ${models.length} models from v1 API`);
+    // Fetch frontend models for provider routing info
+    console.log('Fetching provider routing info from frontend API...');
+    let frontendModels = [];
+    try {
+        const frontendResponse = await fetch('https://openrouter.ai/api/frontend/models');
+        if (frontendResponse.ok) {
+            const frontendData = await frontendResponse.json();
+            frontendModels = Array.isArray(frontendData) ? frontendData : (frontendData.data || []);
+            console.log(`Found ${frontendModels.length} models from frontend API`);
+        }
+    }
+    catch (err) {
+        console.warn('Could not fetch frontend models, continuing without provider routing info');
+    }
+    // Create a map of frontend models by slug for quick lookup
+    const frontendMap = new Map();
+    for (const fm of frontendModels) {
+        if (fm.slug) {
+            frontendMap.set(fm.slug, fm);
+        }
+    }
+    // Merge frontend data into models
+    let enrichedCount = 0;
+    for (const model of models) {
+        const frontend = frontendMap.get(model.id);
+        if (frontend?.endpoint) {
+            // Add provider routing info from nested endpoint
+            if (frontend.endpoint.provider_model_id) {
+                model.provider_model_id = frontend.endpoint.provider_model_id;
+            }
+            if (frontend.endpoint.provider_slug) {
+                model.provider = frontend.endpoint.provider_slug;
+            }
+            if (frontend.endpoint.provider_info?.baseUrl) {
+                model.endpoint = {
+                    baseUrl: frontend.endpoint.provider_info.baseUrl,
+                    modelId: frontend.endpoint.provider_model_id || model.id.split('/')[1]
+                };
+            }
+            enrichedCount++;
+        }
+        else {
+            // Extract provider from ID as fallback
+            const slashIndex = model.id.indexOf('/');
+            if (slashIndex > 0) {
+                model.provider = model.id.substring(0, slashIndex);
+            }
+        }
+    }
+    console.log(`Enriched ${enrichedCount} models with provider routing info`);
+    // Sort by created date (newest first)
+    models.sort((a, b) => (b.created || 0) - (a.created || 0));
+    writeFileSync(OUTPUT_PATH, JSON.stringify(models, null, 2));
+    console.log(`Saved to ${OUTPUT_PATH}`);
+    // Print some stats
+    const providers = new Set(models.map((m) => m.id.split('/')[0]));
+    console.log(`\nProviders: ${[...providers].join(', ')}`);
+    // Show which direct providers have routing info
+    const directProviders = ['openai', 'anthropic', 'google'];
+    for (const provider of directProviders) {
+        const withRouting = models.filter((m) => m.id.startsWith(`${provider}/`) && m.provider_model_id);
+        console.log(`${provider}: ${withRouting.length} models with provider_model_id`);
+    }
+}
+fetchModels().catch(console.error);

package/src/aliases.js

@@ -0,0 +1,40 @@
+/**
+ * Model aliases - map simple names to full model IDs
+ */
+export const ALIASES = {
+    // Claude (Anthropic)
+    'opus': 'anthropic/claude-opus-4.5',
+    'sonnet': 'anthropic/claude-sonnet-4.5',
+    'haiku': 'anthropic/claude-haiku-4.5',
+    'claude': 'anthropic/claude-sonnet-4.5',
+    // GPT (OpenAI)
+    'gpt': 'openai/gpt-4o',
+    'gpt-4o': 'openai/gpt-4o',
+    'gpt-4o-mini': 'openai/gpt-4o-mini',
+    '4o': 'openai/gpt-4o',
+    'o1': 'openai/o1',
+    'o3': 'openai/o3',
+    'o3-mini': 'openai/o3-mini',
+    'o4-mini': 'openai/o4-mini',
+    // Gemini (Google)
+    'gemini': 'google/gemini-2.5-flash',
+    'flash': 'google/gemini-2.5-flash',
+    'gemini-flash': 'google/gemini-2.5-flash',
+    'gemini-pro': 'google/gemini-2.5-pro',
+    // Llama (Meta)
+    'llama': 'meta-llama/llama-4-maverick',
+    'llama-4': 'meta-llama/llama-4-maverick',
+    'llama-70b': 'meta-llama/llama-3.3-70b-instruct',
+    // DeepSeek
+    'deepseek': 'deepseek/deepseek-chat',
+    'r1': 'deepseek/deepseek-r1',
+    // Mistral
+    'mistral': 'mistralai/mistral-large-2411',
+    'codestral': 'mistralai/codestral-2501',
+    // Qwen
+    'qwen': 'qwen/qwen3-235b-a22b',
+    // Grok
+    'grok': 'x-ai/grok-3',
+    // Perplexity
+    'sonar': 'perplexity/sonar-pro',
+};