language-models 2.1.1 → 2.1.3

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> language-models@2.0.3 build /Users/nathanclevenger/projects/primitives.org.ai/packages/language-models
+> 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

@@ -1,7 +1,18 @@
 
-> language-models@2.0.3 test /Users/nathanclevenger/projects/primitives.org.ai/packages/language-models
-> vitest "--run"
+> language-models@2.1.1 test /Users/nathanclevenger/projects/primitives.org.ai/packages/language-models
+> vitest
 
 
- RUN  v2.1.9 /Users/nathanclevenger/projects/primitives.org.ai/packages/language-models
+ 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,15 @@
 # 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

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.1.1",
+  "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,5 +19,14 @@
     "primitives"
   ],
   "license": "MIT",
-  "dependencies": {}
-}
+  "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"
+  }
+}