language-models 0.0.1

package/src/models.test.ts

@@ -0,0 +1,392 @@
+/**
+ * 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,
+  type ModelInfo,
+  type ResolvedModel,
+} 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 as readonly string[]).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: readonly string[] = 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: ResolvedModel = 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/src/models.ts

@@ -0,0 +1,174 @@
+/**
+ * Model listing and resolution
+ */
+
+import { createRequire } from 'module'
+import { ALIASES } from './aliases.js'
+
+const require = createRequire(import.meta.url)
+
+/**
+ * Provider endpoint information for direct API access
+ */
+export interface ProviderEndpoint {
+  /** Provider's API base URL (e.g., https://api.anthropic.com/v1) */
+  baseUrl: string
+  /** Provider's model ID (e.g., claude-opus-4-5-20251101) */
+  modelId: string
+}
+
+export interface ModelInfo {
+  id: string
+  name: string
+  description?: string
+  context_length: number
+  pricing: {
+    prompt: string
+    completion: string
+  }
+  architecture?: {
+    modality: string
+    input_modalities: string[]
+    output_modalities: string[]
+  }
+  /** Provider slug (e.g., 'anthropic', 'openai', 'google') */
+  provider?: string
+  /** Provider's native model ID for direct API calls */
+  provider_model_id?: string
+  /** Provider endpoint info for direct routing */
+  endpoint?: ProviderEndpoint
+}
+
+// Load models from JSON
+let modelsCache: ModelInfo[] | null = null
+
+function loadModels(): ModelInfo[] {
+  if (modelsCache) return modelsCache
+  try {
+    modelsCache = require('../data/models.json')
+    return modelsCache!
+  } catch {
+    return []
+  }
+}
+
+/**
+ * List all available models
+ */
+export function list(): ModelInfo[] {
+  return loadModels()
+}
+
+/**
+ * Get a model by exact ID
+ */
+export function get(id: string): ModelInfo | undefined {
+  return loadModels().find(m => m.id === id)
+}
+
+/**
+ * Search models by query string
+ * Searches in id and name fields
+ */
+export function search(query: string): ModelInfo[] {
+  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: string): string {
+  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'] as const
+export type DirectProvider = typeof DIRECT_PROVIDERS[number]
+
+/**
+ * Result of resolving a model with provider routing info
+ */
+export interface ResolvedModel {
+  /** OpenRouter-style model ID (e.g., 'anthropic/claude-opus-4.5') */
+  id: string
+  /** Provider slug (e.g., 'anthropic', 'openai', 'google') */
+  provider: string
+  /** Provider's native model ID (e.g., 'claude-opus-4-5-20251101') */
+  providerModelId?: string
+  /** Whether this provider supports direct SDK routing */
+  supportsDirectRouting: boolean
+  /** Full model info if available */
+  model?: ModelInfo
+}
+
+/**
+ * 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: string): ResolvedModel {
+  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 as readonly string[]).includes(provider)
+
+  return {
+    id,
+    provider,
+    providerModelId: model?.provider_model_id,
+    supportsDirectRouting,
+    model
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

package/vitest.config.ts

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