language-models 2.0.1 → 2.1.1

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

package/CHANGELOG.md

@@ -1,3 +1,14 @@
 # language-models
 
+## 2.1.1
+
+## 2.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - rpc.do@0.2.0
+
+## 2.0.2
+
 ## 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "language-models",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "Model listing and resolution for LLM providers",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,5 @@
     "primitives"
   ],
   "license": "MIT",
-  "dependencies": {
-    "rpc.do": "^0.1.0"
-  }
+  "dependencies": {}
 }

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',
+};

package/src/aliases.test.js

@@ -0,0 +1,264 @@
+/**
+ * Tests for model aliases
+ *
+ * These tests verify the alias mapping and ensure all documented
+ * aliases are present and correctly mapped.
+ */
+import { describe, it, expect } from 'vitest';
+import { ALIASES } from './aliases.js';
+describe('ALIASES', () => {
+    it('is an object', () => {
+        expect(typeof ALIASES).toBe('object');
+        expect(ALIASES).not.toBeNull();
+    });
+    it('has string keys and values', () => {
+        for (const [key, value] of Object.entries(ALIASES)) {
+            expect(typeof key).toBe('string');
+            expect(typeof value).toBe('string');
+        }
+    });
+    it('has no empty keys or values', () => {
+        for (const [key, value] of Object.entries(ALIASES)) {
+            expect(key.length).toBeGreaterThan(0);
+            expect(value.length).toBeGreaterThan(0);
+        }
+    });
+    it('all values are valid model IDs with provider prefix', () => {
+        for (const [key, value] of Object.entries(ALIASES)) {
+            expect(value).toContain('/');
+            const [provider, modelName] = value.split('/');
+            expect(provider.length).toBeGreaterThan(0);
+            expect(modelName.length).toBeGreaterThan(0);
+        }
+    });
+    describe('Claude (Anthropic) aliases', () => {
+        it('has opus alias', () => {
+            expect(ALIASES['opus']).toBe('anthropic/claude-opus-4.5');
+        });
+        it('has sonnet alias', () => {
+            expect(ALIASES['sonnet']).toBe('anthropic/claude-sonnet-4.5');
+        });
+        it('has haiku alias', () => {
+            expect(ALIASES['haiku']).toBe('anthropic/claude-haiku-4.5');
+        });
+        it('has claude default alias', () => {
+            expect(ALIASES['claude']).toBe('anthropic/claude-sonnet-4.5');
+        });
+        it('claude aliases point to anthropic provider', () => {
+            expect(ALIASES['opus']).toContain('anthropic/');
+            expect(ALIASES['sonnet']).toContain('anthropic/');
+            expect(ALIASES['haiku']).toContain('anthropic/');
+            expect(ALIASES['claude']).toContain('anthropic/');
+        });
+    });
+    describe('GPT (OpenAI) aliases', () => {
+        it('has gpt alias', () => {
+            expect(ALIASES['gpt']).toBe('openai/gpt-4o');
+        });
+        it('has gpt-4o alias', () => {
+            expect(ALIASES['gpt-4o']).toBe('openai/gpt-4o');
+        });
+        it('has gpt-4o-mini alias', () => {
+            expect(ALIASES['gpt-4o-mini']).toBe('openai/gpt-4o-mini');
+        });
+        it('has 4o shorthand', () => {
+            expect(ALIASES['4o']).toBe('openai/gpt-4o');
+        });
+        it('has o1 alias', () => {
+            expect(ALIASES['o1']).toBe('openai/o1');
+        });
+        it('has o3 alias', () => {
+            expect(ALIASES['o3']).toBe('openai/o3');
+        });
+        it('has o3-mini alias', () => {
+            expect(ALIASES['o3-mini']).toBe('openai/o3-mini');
+        });
+        it('has o4-mini alias', () => {
+            expect(ALIASES['o4-mini']).toBe('openai/o4-mini');
+        });
+        it('openai aliases point to openai provider', () => {
+            expect(ALIASES['gpt']).toContain('openai/');
+            expect(ALIASES['gpt-4o']).toContain('openai/');
+            expect(ALIASES['4o']).toContain('openai/');
+            expect(ALIASES['o1']).toContain('openai/');
+            expect(ALIASES['o3']).toContain('openai/');
+        });
+    });
+    describe('Gemini (Google) aliases', () => {
+        it('has gemini alias', () => {
+            expect(ALIASES['gemini']).toBe('google/gemini-2.5-flash');
+        });
+        it('has flash alias', () => {
+            expect(ALIASES['flash']).toBe('google/gemini-2.5-flash');
+        });
+        it('has gemini-flash alias', () => {
+            expect(ALIASES['gemini-flash']).toBe('google/gemini-2.5-flash');
+        });
+        it('has gemini-pro alias', () => {
+            expect(ALIASES['gemini-pro']).toBe('google/gemini-2.5-pro');
+        });
+        it('google aliases point to google provider', () => {
+            expect(ALIASES['gemini']).toContain('google/');
+            expect(ALIASES['flash']).toContain('google/');
+            expect(ALIASES['gemini-flash']).toContain('google/');
+            expect(ALIASES['gemini-pro']).toContain('google/');
+        });
+    });
+    describe('Llama (Meta) aliases', () => {
+        it('has llama alias', () => {
+            expect(ALIASES['llama']).toBe('meta-llama/llama-4-maverick');
+        });
+        it('has llama-4 alias', () => {
+            expect(ALIASES['llama-4']).toBe('meta-llama/llama-4-maverick');
+        });
+        it('has llama-70b alias', () => {
+            expect(ALIASES['llama-70b']).toBe('meta-llama/llama-3.3-70b-instruct');
+        });
+        it('llama aliases point to meta-llama provider', () => {
+            expect(ALIASES['llama']).toContain('meta-llama/');
+            expect(ALIASES['llama-4']).toContain('meta-llama/');
+            expect(ALIASES['llama-70b']).toContain('meta-llama/');
+        });
+    });
+    describe('DeepSeek aliases', () => {
+        it('has deepseek alias', () => {
+            expect(ALIASES['deepseek']).toBe('deepseek/deepseek-chat');
+        });
+        it('has r1 alias', () => {
+            expect(ALIASES['r1']).toBe('deepseek/deepseek-r1');
+        });
+        it('deepseek aliases point to deepseek provider', () => {
+            expect(ALIASES['deepseek']).toContain('deepseek/');
+            expect(ALIASES['r1']).toContain('deepseek/');
+        });
+    });
+    describe('Mistral aliases', () => {
+        it('has mistral alias', () => {
+            expect(ALIASES['mistral']).toBe('mistralai/mistral-large-2411');
+        });
+        it('has codestral alias', () => {
+            expect(ALIASES['codestral']).toBe('mistralai/codestral-2501');
+        });
+        it('mistral aliases point to mistralai provider', () => {
+            expect(ALIASES['mistral']).toContain('mistralai/');
+            expect(ALIASES['codestral']).toContain('mistralai/');
+        });
+    });
+    describe('Qwen aliases', () => {
+        it('has qwen alias', () => {
+            expect(ALIASES['qwen']).toBe('qwen/qwen3-235b-a22b');
+        });
+        it('qwen alias points to qwen provider', () => {
+            expect(ALIASES['qwen']).toContain('qwen/');
+        });
+    });
+    describe('Grok (X.AI) aliases', () => {
+        it('has grok alias', () => {
+            expect(ALIASES['grok']).toBe('x-ai/grok-3');
+        });
+        it('grok alias points to x-ai provider', () => {
+            expect(ALIASES['grok']).toContain('x-ai/');
+        });
+    });
+    describe('Perplexity aliases', () => {
+        it('has sonar alias', () => {
+            expect(ALIASES['sonar']).toBe('perplexity/sonar-pro');
+        });
+        it('sonar alias points to perplexity provider', () => {
+            expect(ALIASES['sonar']).toContain('perplexity/');
+        });
+    });
+    describe('alias uniqueness', () => {
+        it('has no duplicate keys', () => {
+            const keys = Object.keys(ALIASES);
+            const uniqueKeys = new Set(keys);
+            expect(keys.length).toBe(uniqueKeys.size);
+        });
+        it('has unique lowercase keys', () => {
+            const lowerKeys = Object.keys(ALIASES).map(k => k.toLowerCase());
+            const uniqueLowerKeys = new Set(lowerKeys);
+            expect(lowerKeys.length).toBe(uniqueLowerKeys.size);
+        });
+    });
+    describe('alias conventions', () => {
+        it('uses lowercase keys', () => {
+            for (const key of Object.keys(ALIASES)) {
+                expect(key).toBe(key.toLowerCase());
+            }
+        });
+        it('uses lowercase provider names in values', () => {
+            for (const value of Object.values(ALIASES)) {
+                const provider = value.split('/')[0];
+                expect(provider).toBe(provider.toLowerCase());
+            }
+        });
+        it('uses kebab-case or lowercase for model names', () => {
+            for (const value of Object.values(ALIASES)) {
+                const modelName = value.split('/')[1];
+                // Model names should not have uppercase letters or spaces
+                expect(modelName).not.toMatch(/[A-Z]/);
+                expect(modelName).not.toContain(' ');
+            }
+        });
+    });
+    describe('provider coverage', () => {
+        it('covers major AI providers', () => {
+            const providers = new Set(Object.values(ALIASES).map(v => v.split('/')[0]));
+            expect(providers.has('anthropic')).toBe(true);
+            expect(providers.has('openai')).toBe(true);
+            expect(providers.has('google')).toBe(true);
+            expect(providers.has('meta-llama')).toBe(true);
+        });
+        it('has multiple aliases per major provider', () => {
+            const providerCounts = {};
+            for (const value of Object.values(ALIASES)) {
+                const provider = value.split('/')[0];
+                providerCounts[provider] = (providerCounts[provider] || 0) + 1;
+            }
+            // Major providers should have multiple aliases
+            expect(providerCounts['anthropic']).toBeGreaterThanOrEqual(3);
+            expect(providerCounts['openai']).toBeGreaterThanOrEqual(5);
+            expect(providerCounts['google']).toBeGreaterThanOrEqual(3);
+        });
+    });
+    describe('README documentation alignment', () => {
+        it('matches all aliases documented in README', () => {
+            // These are the aliases listed in the README.md table
+            const documentedAliases = {
+                '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-4o',
+                'gpt-4o': 'openai/gpt-4o',
+                '4o': 'openai/gpt-4o',
+                'o1': 'openai/o1',
+                'o3': 'openai/o3',
+                'o3-mini': 'openai/o3-mini',
+                'gemini': 'google/gemini-2.5-flash',
+                'flash': 'google/gemini-2.5-flash',
+                'gemini-pro': 'google/gemini-2.5-pro',
+                'llama': 'meta-llama/llama-4-maverick',
+                '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',
+            };
+            for (const [alias, expectedId] of Object.entries(documentedAliases)) {
+                expect(ALIASES[alias]).toBe(expectedId);
+            }
+        });
+    });
+    describe('alias count', () => {
+        it('has reasonable number of aliases', () => {
+            const count = Object.keys(ALIASES).length;
+            expect(count).toBeGreaterThanOrEqual(20);
+            expect(count).toBeLessThanOrEqual(100);
+        });
+    });
+});

package/src/index.js

@@ -0,0 +1,9 @@
+/**
+ * language-models - Model listing and resolution
+ *
+ * Lists all available models and resolves aliases to full model IDs.
+ *
+ * @packageDocumentation
+ */
+export { resolve, resolveWithProvider, list, get, search, DIRECT_PROVIDERS } from './models.js';
+export { ALIASES } from './aliases.js';

package/src/index.test.js

@@ -0,0 +1,320 @@
+/**
+ * Integration tests for the language-models package
+ *
+ * These tests verify the public API exports and end-to-end functionality.
+ */
+import { describe, it, expect } from 'vitest';
+import { resolve, resolveWithProvider, list, get, search, DIRECT_PROVIDERS, ALIASES, } from './index.js';
+describe('package exports', () => {
+    it('exports resolve function', () => {
+        expect(typeof resolve).toBe('function');
+    });
+    it('exports resolveWithProvider function', () => {
+        expect(typeof resolveWithProvider).toBe('function');
+    });
+    it('exports list function', () => {
+        expect(typeof list).toBe('function');
+    });
+    it('exports get function', () => {
+        expect(typeof get).toBe('function');
+    });
+    it('exports search function', () => {
+        expect(typeof search).toBe('function');
+    });
+    it('exports DIRECT_PROVIDERS constant', () => {
+        expect(DIRECT_PROVIDERS).toBeDefined();
+        expect(Array.isArray(DIRECT_PROVIDERS)).toBe(true);
+    });
+    it('exports ALIASES constant', () => {
+        expect(ALIASES).toBeDefined();
+        expect(typeof ALIASES).toBe('object');
+    });
+});
+describe('type exports', () => {
+    it('ModelInfo type is available', () => {
+        // Type check - if this compiles, the type is exported correctly
+        const model = {
+            id: 'test/model',
+            name: 'Test Model',
+            context_length: 8192,
+            pricing: {
+                prompt: '0',
+                completion: '0',
+            },
+        };
+        expect(model).toBeDefined();
+    });
+    it('ProviderEndpoint type is available', () => {
+        const endpoint = {
+            baseUrl: 'https://api.example.com',
+            modelId: 'test-model-id',
+        };
+        expect(endpoint).toBeDefined();
+    });
+    it('ResolvedModel type is available', () => {
+        const resolved = {
+            id: 'test/model',
+            provider: 'test',
+            supportsDirectRouting: false,
+        };
+        expect(resolved).toBeDefined();
+    });
+    it('DirectProvider type is available', () => {
+        const provider = 'anthropic';
+        expect(provider).toBeDefined();
+    });
+});
+describe('end-to-end workflows', () => {
+    describe('simple alias resolution', () => {
+        it('resolves opus and gets model info', () => {
+            const modelId = resolve('opus');
+            expect(modelId).toBe('anthropic/claude-opus-4.5');
+            const model = get(modelId);
+            if (model) {
+                expect(model.id).toBe(modelId);
+                expect(model.name).toContain('Claude');
+            }
+        });
+        it('resolves gpt and gets model info', () => {
+            const modelId = resolve('gpt');
+            expect(modelId).toBe('openai/gpt-4o');
+            const model = get(modelId);
+            if (model) {
+                expect(model.id).toBe(modelId);
+                expect(model.name).toContain('GPT');
+            }
+        });
+    });
+    describe('advanced resolution with provider info', () => {
+        it('resolves opus with full provider details', () => {
+            const resolved = resolveWithProvider('opus');
+            expect(resolved.id).toBe('anthropic/claude-opus-4.5');
+            expect(resolved.provider).toBe('anthropic');
+            expect(resolved.supportsDirectRouting).toBe(true);
+            if (resolved.model) {
+                expect(resolved.model.name).toBeTruthy();
+                expect(resolved.model.context_length).toBeGreaterThan(0);
+            }
+        });
+        it('resolves with provider model ID if available', () => {
+            const resolved = resolveWithProvider('opus');
+            if (resolved.model?.provider_model_id) {
+                expect(resolved.providerModelId).toBe(resolved.model.provider_model_id);
+            }
+        });
+    });
+    describe('search and select workflow', () => {
+        it('searches for claude models and selects one', () => {
+            const matches = search('claude');
+            expect(matches.length).toBeGreaterThan(0);
+            const first = matches[0];
+            expect(first.id).toContain('/');
+            expect(first.name).toBeTruthy();
+            const retrieved = get(first.id);
+            expect(retrieved).toBeDefined();
+            expect(retrieved?.id).toBe(first.id);
+        });
+        it('searches for openai models', () => {
+            const matches = search('openai');
+            expect(matches.length).toBeGreaterThan(0);
+            for (const model of matches) {
+                expect(model.id).toContain('openai/');
+            }
+        });
+    });
+    describe('listing and filtering', () => {
+        it('lists all models and filters by provider', () => {
+            const allModels = list();
+            expect(allModels.length).toBeGreaterThanOrEqual(0);
+            if (allModels.length > 0) {
+                const anthropicModels = allModels.filter(m => m.id.startsWith('anthropic/'));
+                const openaiModels = allModels.filter(m => m.id.startsWith('openai/'));
+                if (anthropicModels.length > 0) {
+                    expect(anthropicModels[0].id).toContain('anthropic/');
+                }
+                if (openaiModels.length > 0) {
+                    expect(openaiModels[0].id).toContain('openai/');
+                }
+            }
+        });
+        it('lists models and checks for direct routing', () => {
+            const allModels = list();
+            if (allModels.length > 0) {
+                const directModels = allModels.filter(m => {
+                    const provider = m.id.split('/')[0];
+                    return DIRECT_PROVIDERS.includes(provider);
+                });
+                for (const model of directModels) {
+                    const resolved = resolveWithProvider(model.id);
+                    expect(resolved.supportsDirectRouting).toBe(true);
+                }
+            }
+        });
+    });
+    describe('case insensitivity', () => {
+        it('resolves aliases case-insensitively', () => {
+            const lower = resolve('opus');
+            const upper = resolve('OPUS');
+            const mixed = resolve('OpUs');
+            expect(lower).toBe(upper);
+            expect(lower).toBe(mixed);
+        });
+        it('searches case-insensitively', () => {
+            const lower = search('claude');
+            const upper = search('CLAUDE');
+            expect(lower).toEqual(upper);
+        });
+    });
+    describe('unknown inputs', () => {
+        it('handles unknown alias gracefully', () => {
+            const result = resolve('unknown-alias-xyz');
+            expect(result).toBe('unknown-alias-xyz');
+        });
+        it('handles unknown model ID gracefully', () => {
+            const model = get('unknown/model-id');
+            expect(model).toBeUndefined();
+        });
+        it('handles unknown search gracefully', () => {
+            const results = search('this-should-not-exist-xyz123');
+            expect(results).toEqual([]);
+        });
+        it('resolves unknown with provider info', () => {
+            const resolved = resolveWithProvider('unknown/model');
+            expect(resolved.id).toBe('unknown/model');
+            expect(resolved.provider).toBe('unknown');
+            expect(resolved.model).toBeUndefined();
+        });
+    });
+    describe('README examples', () => {
+        it('works with README quick start examples', () => {
+            // Examples from README.md Quick Start section
+            const opus = resolve('opus');
+            expect(opus).toBe('anthropic/claude-opus-4.5');
+            const gpt4o = resolve('gpt-4o');
+            expect(gpt4o).toBe('openai/gpt-4o');
+            const llama70b = resolve('llama-70b');
+            expect(llama70b).toBe('meta-llama/llama-3.3-70b-instruct');
+            const mistral = resolve('mistral');
+            expect(mistral).toBe('mistralai/mistral-large-2411');
+        });
+        it('works with README API examples', () => {
+            // Examples from README.md API section
+            const opus = resolve('opus');
+            expect(opus).toBe('anthropic/claude-opus-4.5');
+            const sonnet = resolve('sonnet');
+            expect(sonnet).toBe('anthropic/claude-sonnet-4.5');
+            const gpt = resolve('gpt');
+            expect(gpt).toBe('openai/gpt-4o');
+            const llama = resolve('llama');
+            expect(llama).toBe('meta-llama/llama-4-maverick');
+            // Pass-through example
+            const fullId = resolve('anthropic/claude-opus-4.5');
+            expect(fullId).toBe('anthropic/claude-opus-4.5');
+        });
+        it('list returns array as shown in README', () => {
+            const models = list();
+            expect(Array.isArray(models)).toBe(true);
+        });
+        it('search returns matching models as shown in README', () => {
+            const claudeModels = search('claude');
+            expect(Array.isArray(claudeModels)).toBe(true);
+            if (claudeModels.length > 0) {
+                expect(claudeModels.some(m => m.id.includes('claude') || m.name.toLowerCase().includes('claude'))).toBe(true);
+            }
+        });
+    });
+    describe('data directory integration', () => {
+        it('loads models from data/models.json', () => {
+            const models = list();
+            // Should load from data directory, even if empty
+            expect(Array.isArray(models)).toBe(true);
+        });
+        it('handles missing data file gracefully', () => {
+            // Even without data/models.json, functions should not throw
+            expect(() => list()).not.toThrow();
+            expect(() => get('test/model')).not.toThrow();
+            expect(() => search('test')).not.toThrow();
+        });
+    });
+    describe('model metadata completeness', () => {
+        it('models have pricing information', () => {
+            const models = list();
+            if (models.length > 0) {
+                const model = models[0];
+                expect(model.pricing).toBeDefined();
+                expect(model.pricing.prompt).toBeDefined();
+                expect(model.pricing.completion).toBeDefined();
+            }
+        });
+        it('models have context length', () => {
+            const models = list();
+            if (models.length > 0) {
+                for (const model of models.slice(0, 5)) {
+                    expect(typeof model.context_length).toBe('number');
+                    expect(model.context_length).toBeGreaterThan(0);
+                }
+            }
+        });
+        it('models may have architecture info', () => {
+            const models = list();
+            if (models.length > 0) {
+                const modelWithArch = models.find(m => m.architecture);
+                if (modelWithArch?.architecture) {
+                    expect(modelWithArch.architecture.modality).toBeDefined();
+                    expect(Array.isArray(modelWithArch.architecture.input_modalities)).toBe(true);
+                    expect(Array.isArray(modelWithArch.architecture.output_modalities)).toBe(true);
+                }
+            }
+        });
+    });
+    describe('provider routing', () => {
+        it('correctly identifies direct routing providers', () => {
+            const directProviders = ['anthropic', 'openai', 'google'];
+            for (const provider of directProviders) {
+                const models = list().filter(m => m.id.startsWith(`${provider}/`));
+                if (models.length > 0) {
+                    const resolved = resolveWithProvider(models[0].id);
+                    expect(resolved.supportsDirectRouting).toBe(true);
+                    expect(resolved.provider).toBe(provider);
+                }
+            }
+        });
+        it('identifies non-direct routing providers', () => {
+            const models = list();
+            const nonDirectModel = models.find(m => {
+                const provider = m.id.split('/')[0];
+                return !DIRECT_PROVIDERS.includes(provider);
+            });
+            if (nonDirectModel) {
+                const resolved = resolveWithProvider(nonDirectModel.id);
+                expect(resolved.supportsDirectRouting).toBe(false);
+            }
+        });
+    });
+});
+describe('consistency checks', () => {
+    it('all aliases resolve to valid format', () => {
+        for (const [alias, modelId] of Object.entries(ALIASES)) {
+            expect(modelId).toContain('/');
+            const [provider, model] = modelId.split('/');
+            expect(provider.length).toBeGreaterThan(0);
+            expect(model.length).toBeGreaterThan(0);
+        }
+    });
+    it('resolve and resolveWithProvider are consistent', () => {
+        const testCases = ['opus', 'gpt', 'gemini', 'llama'];
+        for (const alias of testCases) {
+            const simpleResolve = resolve(alias);
+            const fullResolve = resolveWithProvider(alias);
+            expect(fullResolve.id).toBe(simpleResolve);
+        }
+    });
+    it('search results are all valid models', () => {
+        const results = search('claude');
+        for (const model of results) {
+            const retrieved = get(model.id);
+            // All search results should be retrievable
+            expect(retrieved?.id).toBe(model.id);
+        }
+    });
+});

package/src/models.js

@@ -0,0 +1,108 @@
+/**
+ * Model listing and resolution
+ */
+import { createRequire } from 'module';
+import { ALIASES } from './aliases.js';
+const require = createRequire(import.meta.url);
+// Load models from JSON
+let modelsCache = null;
+function loadModels() {
+    if (modelsCache)
+        return modelsCache;
+    try {
+        modelsCache = require('../data/models.json');
+        return modelsCache;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * List all available models
+ */
+export function list() {
+    return loadModels();
+}
+/**
+ * Get a model by exact ID
+ */
+export function get(id) {
+    return loadModels().find(m => m.id === id);
+}
+/**
+ * Search models by query string
+ * Searches in id and name fields
+ */
+export function search(query) {
+    const q = query.toLowerCase();
+    return loadModels().filter(m => m.id.toLowerCase().includes(q) ||
+        m.name.toLowerCase().includes(q));
+}
+/**
+ * Resolve a model alias or partial name to a full model ID
+ *
+ * Resolution order:
+ * 1. Check aliases (e.g., 'opus' -> 'anthropic/claude-opus-4.5')
+ * 2. Check if it's already a full ID (contains '/')
+ * 3. Search for first matching model
+ *
+ * @example
+ * resolve('opus')           // 'anthropic/claude-opus-4.5'
+ * resolve('gpt-4o')         // 'openai/gpt-4o'
+ * resolve('claude-sonnet')  // 'anthropic/claude-sonnet-4.5'
+ * resolve('llama-70b')      // 'meta-llama/llama-3.3-70b-instruct'
+ */
+export function resolve(input) {
+    const normalized = input.toLowerCase().trim();
+    // Check aliases first
+    if (ALIASES[normalized]) {
+        return ALIASES[normalized];
+    }
+    // Already a full ID with provider prefix
+    if (input.includes('/')) {
+        // Verify it exists or return as-is
+        const model = get(input);
+        return model?.id || input;
+    }
+    // Search for matching model
+    const matches = search(normalized);
+    const firstMatch = matches[0];
+    if (firstMatch) {
+        return firstMatch.id;
+    }
+    // Return as-is if nothing found
+    return input;
+}
+/**
+ * Providers that support direct SDK access (not via OpenRouter)
+ * These providers have special capabilities like MCP, extended thinking, etc.
+ */
+export const DIRECT_PROVIDERS = ['openai', 'anthropic', 'google'];
+/**
+ * Resolve a model alias and get full routing information
+ *
+ * @example
+ * const info = resolveWithProvider('opus')
+ * // {
+ * //   id: 'anthropic/claude-opus-4.5',
+ * //   provider: 'anthropic',
+ * //   providerModelId: 'claude-opus-4-5-20251101',
+ * //   supportsDirectRouting: true,
+ * //   model: { ... }
+ * // }
+ */
+export function resolveWithProvider(input) {
+    const id = resolve(input);
+    const model = get(id);
+    // Extract provider from ID (e.g., 'anthropic' from 'anthropic/claude-opus-4.5')
+    const slashIndex = id.indexOf('/');
+    const provider = slashIndex > 0 ? id.substring(0, slashIndex) : 'unknown';
+    const supportsDirectRouting = DIRECT_PROVIDERS.includes(provider);
+    return {
+        id,
+        provider,
+        providerModelId: model?.provider_model_id,
+        supportsDirectRouting,
+        model
+    };
+}

package/src/models.test.js

@@ -0,0 +1,335 @@
+/**
+ * Tests for model listing, resolution, and search
+ *
+ * These are pure unit tests - no external API calls needed.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { list, get, search, resolve, resolveWithProvider, DIRECT_PROVIDERS, } from './models.js';
+import { ALIASES } from './aliases.js';
+describe('list', () => {
+    it('returns an array of models', () => {
+        const models = list();
+        expect(Array.isArray(models)).toBe(true);
+    });
+    it('returns models with required properties', () => {
+        const models = list();
+        if (models.length > 0) {
+            const model = models[0];
+            expect(model).toHaveProperty('id');
+            expect(model).toHaveProperty('name');
+            expect(model).toHaveProperty('context_length');
+            expect(model).toHaveProperty('pricing');
+            expect(model.pricing).toHaveProperty('prompt');
+            expect(model.pricing).toHaveProperty('completion');
+        }
+    });
+    it('caches results on subsequent calls', () => {
+        const models1 = list();
+        const models2 = list();
+        expect(models1).toBe(models2); // Same reference
+    });
+    it('returns empty array if models.json does not exist', () => {
+        // This test verifies graceful handling of missing data file
+        const models = list();
+        expect(Array.isArray(models)).toBe(true);
+    });
+});
+describe('get', () => {
+    it('returns undefined for non-existent model', () => {
+        const model = get('non-existent/model-id');
+        expect(model).toBeUndefined();
+    });
+    it('returns model info for valid model ID', () => {
+        const models = list();
+        if (models.length > 0) {
+            const firstModel = models[0];
+            const retrieved = get(firstModel.id);
+            expect(retrieved).toBeDefined();
+            expect(retrieved?.id).toBe(firstModel.id);
+            expect(retrieved?.name).toBe(firstModel.name);
+        }
+    });
+    it('performs exact match only', () => {
+        const models = list();
+        if (models.length > 0) {
+            const model = models[0];
+            const partialId = model.id.split('/')[0]; // Just the provider
+            const result = get(partialId);
+            // Should not match partial ID
+            if (result) {
+                expect(result.id).toBe(partialId); // Only matches if there's an exact model with this ID
+            }
+        }
+    });
+});
+describe('search', () => {
+    it('returns empty array for no matches', () => {
+        const results = search('this-should-not-match-anything-12345');
+        expect(results).toEqual([]);
+    });
+    it('searches by model ID', () => {
+        const models = list();
+        if (models.length > 0) {
+            const model = models[0];
+            const idPart = model.id.split('/')[0]; // Provider name
+            const results = search(idPart);
+            expect(results.length).toBeGreaterThan(0);
+            expect(results.some(m => m.id.includes(idPart))).toBe(true);
+        }
+    });
+    it('searches by model name', () => {
+        const models = list();
+        if (models.length > 0) {
+            const model = models[0];
+            const namePart = model.name.split(' ')[0].toLowerCase();
+            const results = search(namePart);
+            expect(results.length).toBeGreaterThan(0);
+        }
+    });
+    it('is case-insensitive', () => {
+        const models = list();
+        if (models.length > 0) {
+            const model = models[0];
+            const idLower = model.id.toLowerCase();
+            const idUpper = model.id.toUpperCase();
+            const resultsLower = search(idLower);
+            const resultsUpper = search(idUpper);
+            expect(resultsLower).toEqual(resultsUpper);
+        }
+    });
+    it('searches in both id and name fields', () => {
+        const models = list();
+        if (models.length > 0) {
+            // Find a model and search for part of its name
+            const model = models.find(m => m.name.includes(' '));
+            if (model) {
+                const namePart = model.name.split(' ')[0].toLowerCase();
+                const results = search(namePart);
+                expect(results.some(m => m.id === model.id || m.name.toLowerCase().includes(namePart))).toBe(true);
+            }
+        }
+    });
+    it('returns multiple matches', () => {
+        const models = list();
+        if (models.length > 1) {
+            // Search for a common term that should match multiple models
+            const commonProviders = ['anthropic', 'openai', 'google', 'meta'];
+            for (const provider of commonProviders) {
+                const results = search(provider);
+                if (results.length > 1) {
+                    expect(results.length).toBeGreaterThan(1);
+                    break;
+                }
+            }
+        }
+    });
+});
+describe('resolve', () => {
+    beforeEach(() => {
+        // Ensure we have fresh data
+        list();
+    });
+    describe('alias resolution', () => {
+        it('resolves known aliases', () => {
+            const result = resolve('opus');
+            expect(result).toBe(ALIASES['opus']);
+        });
+        it('resolves claude alias', () => {
+            const result = resolve('claude');
+            expect(result).toBe(ALIASES['claude']);
+        });
+        it('resolves gpt alias', () => {
+            const result = resolve('gpt');
+            expect(result).toBe(ALIASES['gpt']);
+        });
+        it('resolves llama alias', () => {
+            const result = resolve('llama');
+            expect(result).toBe(ALIASES['llama']);
+        });
+        it('is case-insensitive for aliases', () => {
+            const lower = resolve('opus');
+            const upper = resolve('OPUS');
+            const mixed = resolve('Opus');
+            expect(lower).toBe(upper);
+            expect(lower).toBe(mixed);
+        });
+        it('handles whitespace in input', () => {
+            const result = resolve('  opus  ');
+            expect(result).toBe(ALIASES['opus']);
+        });
+        it('resolves all documented aliases', () => {
+            // Test key aliases from the README
+            const aliasesToTest = [
+                ['opus', 'anthropic/claude-opus-4.5'],
+                ['sonnet', 'anthropic/claude-sonnet-4.5'],
+                ['haiku', 'anthropic/claude-haiku-4.5'],
+                ['gpt-4o', 'openai/gpt-4o'],
+                ['gemini', 'google/gemini-2.5-flash'],
+                ['llama-70b', 'meta-llama/llama-3.3-70b-instruct'],
+                ['mistral', 'mistralai/mistral-large-2411'],
+            ];
+            for (const [alias, expected] of aliasesToTest) {
+                const result = resolve(alias);
+                expect(result).toBe(expected);
+            }
+        });
+    });
+    describe('full ID passthrough', () => {
+        it('returns full ID as-is if it exists', () => {
+            const models = list();
+            if (models.length > 0) {
+                const model = models[0];
+                const result = resolve(model.id);
+                expect(result).toBe(model.id);
+            }
+        });
+        it('returns unknown full ID as-is', () => {
+            const unknownId = 'unknown-provider/unknown-model';
+            const result = resolve(unknownId);
+            expect(result).toBe(unknownId);
+        });
+        it('detects full ID by slash character', () => {
+            const result = resolve('custom/model-name');
+            expect(result).toBe('custom/model-name');
+        });
+    });
+    describe('partial name search', () => {
+        it('finds model by partial name', () => {
+            const models = list();
+            if (models.length > 0) {
+                const model = models[0];
+                const provider = model.id.split('/')[0];
+                const result = resolve(provider);
+                // Should find a model from that provider
+                expect(result).toContain('/');
+            }
+        });
+        it('returns first match for partial search', () => {
+            const result = resolve('claude');
+            // Should return an alias if it exists, or search result
+            expect(result).toBeTruthy();
+            expect(typeof result).toBe('string');
+        });
+        it('returns input as-is if no matches found', () => {
+            const input = 'unknown-model-xyz';
+            const result = resolve(input);
+            expect(result).toBe(input);
+        });
+    });
+    describe('resolution priority', () => {
+        it('prioritizes aliases over search', () => {
+            // 'opus' is an alias, so it should resolve to the alias target
+            // even if there are other models containing 'opus'
+            const result = resolve('opus');
+            expect(result).toBe(ALIASES['opus']);
+        });
+        it('checks full ID before partial search', () => {
+            const models = list();
+            if (models.length > 0) {
+                const model = models[0];
+                const result = resolve(model.id);
+                expect(result).toBe(model.id);
+            }
+        });
+    });
+});
+describe('resolveWithProvider', () => {
+    it('extracts provider from model ID', () => {
+        const result = resolveWithProvider('opus');
+        expect(result.provider).toBe('anthropic');
+    });
+    it('includes resolved model ID', () => {
+        const result = resolveWithProvider('opus');
+        expect(result.id).toBe(ALIASES['opus']);
+    });
+    it('identifies direct routing support', () => {
+        const anthropic = resolveWithProvider('opus');
+        expect(anthropic.supportsDirectRouting).toBe(true);
+        const openai = resolveWithProvider('gpt');
+        expect(openai.supportsDirectRouting).toBe(true);
+        const google = resolveWithProvider('gemini');
+        expect(google.supportsDirectRouting).toBe(true);
+    });
+    it('identifies non-direct providers', () => {
+        // Use a model from a provider not in DIRECT_PROVIDERS
+        const models = list();
+        const nonDirectModel = models.find(m => {
+            const provider = m.id.split('/')[0];
+            return !DIRECT_PROVIDERS.includes(provider);
+        });
+        if (nonDirectModel) {
+            const result = resolveWithProvider(nonDirectModel.id);
+            expect(result.supportsDirectRouting).toBe(false);
+        }
+    });
+    it('includes full model info if available', () => {
+        const result = resolveWithProvider('opus');
+        if (result.model) {
+            expect(result.model).toHaveProperty('id');
+            expect(result.model).toHaveProperty('name');
+            expect(result.model).toHaveProperty('pricing');
+        }
+    });
+    it('includes provider model ID if available', () => {
+        const result = resolveWithProvider('opus');
+        if (result.model?.provider_model_id) {
+            expect(result.providerModelId).toBeDefined();
+            expect(typeof result.providerModelId).toBe('string');
+        }
+    });
+    it('handles unknown models gracefully', () => {
+        const result = resolveWithProvider('unknown/model');
+        expect(result.id).toBe('unknown/model');
+        expect(result.provider).toBe('unknown');
+        expect(result.model).toBeUndefined();
+    });
+    it('handles models without provider prefix', () => {
+        const result = resolveWithProvider('opus');
+        expect(result.provider).toBeTruthy();
+        expect(result.id).toContain('/');
+    });
+});
+describe('DIRECT_PROVIDERS', () => {
+    it('contains expected providers', () => {
+        expect(DIRECT_PROVIDERS).toContain('anthropic');
+        expect(DIRECT_PROVIDERS).toContain('openai');
+        expect(DIRECT_PROVIDERS).toContain('google');
+    });
+    it('has exactly 3 providers', () => {
+        expect(DIRECT_PROVIDERS.length).toBe(3);
+    });
+    it('is readonly', () => {
+        // Type check - this should compile
+        const providers = DIRECT_PROVIDERS;
+        expect(providers).toBeDefined();
+    });
+});
+describe('ModelInfo type', () => {
+    it('models have correct structure', () => {
+        const models = list();
+        if (models.length > 0) {
+            const model = models[0];
+            expect(typeof model.id).toBe('string');
+            expect(typeof model.name).toBe('string');
+            expect(typeof model.context_length).toBe('number');
+            expect(typeof model.pricing.prompt).toBe('string');
+            expect(typeof model.pricing.completion).toBe('string');
+            if (model.architecture) {
+                expect(typeof model.architecture.modality).toBe('string');
+                expect(Array.isArray(model.architecture.input_modalities)).toBe(true);
+                expect(Array.isArray(model.architecture.output_modalities)).toBe(true);
+            }
+        }
+    });
+});
+describe('ResolvedModel type', () => {
+    it('returns complete resolution info', () => {
+        const result = resolveWithProvider('opus');
+        expect(result).toHaveProperty('id');
+        expect(result).toHaveProperty('provider');
+        expect(result).toHaveProperty('supportsDirectRouting');
+        expect(typeof result.id).toBe('string');
+        expect(typeof result.provider).toBe('string');
+        expect(typeof result.supportsDirectRouting).toBe('boolean');
+    });
+});

package/vitest.config.js

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        globals: false,
+        environment: 'node',
+        include: ['src/**/*.test.ts'],
+        testTimeout: 10000,
+        hookTimeout: 10000,
+    },
+});