@cogitator-ai/models 1.1.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @cogitator-ai/models
 
-Dynamic model registry with pricing information for Cogitator. Fetches up-to-date model data from LiteLLM.
+Dynamic model registry with pricing information for Cogitator. Fetches up-to-date model data from LiteLLM and provides built-in fallbacks for major providers.
 
 ## Installation
 
@@ -8,51 +8,504 @@ Dynamic model registry with pricing information for Cogitator. Fetches up-to-dat
 pnpm add @cogitator-ai/models
 ```
 
-## Usage
+## Features
 
-### Get Model Information
+- **Dynamic Data** - Fetches latest model info from LiteLLM
+- **Pricing Information** - Input/output costs per million tokens
+- **Capability Tracking** - Vision, tools, streaming, JSON mode support
+- **Multi-Provider** - OpenAI, Anthropic, Google, Ollama, Azure, AWS, and more
+- **Caching** - Memory or file-based cache with configurable TTL
+- **Fallback** - Built-in models when external data unavailable
+- **Filtering** - Query models by provider, capabilities, price
+
+---
+
+## Quick Start
 
 ```typescript
-import { getModel, getPrice, listModels } from '@cogitator-ai/models';
+import { initializeModels, getModel, getPrice, listModels } from '@cogitator-ai/models';
+
+await initializeModels();
 
-// Get model details
-const model = await getModel('gpt-4o');
-console.log(model.contextWindow); // 128000
+const model = getModel('gpt-4o');
+console.log(model?.contextWindow);
+console.log(model?.capabilities?.supportsVision);
 
-// Get pricing
-const price = await getPrice('claude-sonnet-4-20250514');
-console.log(price.inputPerMillion); // $3.00
-console.log(price.outputPerMillion); // $15.00
+const price = getPrice('claude-sonnet-4-20250514');
+console.log(`Input: $${price?.input}/M tokens`);
+console.log(`Output: $${price?.output}/M tokens`);
 
-// List all models
-const models = await listModels({
+const toolModels = listModels({
+  supportsTools: true,
   provider: 'openai',
-  hasToolCalling: true,
 });
 ```
 
-### Built-in Providers
+---
 
-- **OpenAI**: GPT-4o, GPT-4o Mini, o1, o3-mini
-- **Anthropic**: Claude Sonnet 4, Claude 3.5 Sonnet/Haiku, Claude 3 Opus
-- **Google**: Gemini 2.5 Pro/Flash, Gemini 2.0 Flash, Gemini 1.5 Pro/Flash
+## Model Registry
 
-### Caching
+The `ModelRegistry` class manages model data with caching and auto-refresh.
 
-Model data is cached for 24 hours with automatic refresh:
+### Initialization
 
 ```typescript
 import { ModelRegistry } from '@cogitator-ai/models';
 
 const registry = new ModelRegistry({
-  cacheTtl: 3600 * 1000, // 1 hour
-  cacheDir: './cache',
+  cache: {
+    ttl: 24 * 60 * 60 * 1000,
+    storage: 'file',
+    filePath: './cache/models.json',
+  },
+  autoRefresh: true,
+  refreshInterval: 24 * 60 * 60 * 1000,
+  fallbackToBuiltin: true,
+});
+
+await registry.initialize();
+```
+
+### Configuration Options
+
+```typescript
+interface RegistryOptions {
+  cache?: CacheOptions;
+  autoRefresh?: boolean;
+  refreshInterval?: number;
+  fallbackToBuiltin?: boolean;
+}
+
+interface CacheOptions {
+  ttl: number;
+  storage: 'memory' | 'file';
+  filePath?: string;
+}
+```
+
+| Option              | Default    | Description                          |
+| ------------------- | ---------- | ------------------------------------ |
+| `cache.ttl`         | 24 hours   | Cache time-to-live in milliseconds   |
+| `cache.storage`     | `'memory'` | Storage backend                      |
+| `cache.filePath`    | -          | File path for file-based cache       |
+| `autoRefresh`       | `false`    | Enable automatic background refresh  |
+| `refreshInterval`   | 24 hours   | Refresh interval in milliseconds     |
+| `fallbackToBuiltin` | `true`     | Use built-in models on fetch failure |
+
+### Registry Methods
+
+```typescript
+await registry.initialize();
+
+const model = registry.getModel('gpt-4o');
+
+const price = registry.getPrice('claude-3-5-sonnet-20241022');
+
+const models = registry.listModels({
+  provider: 'anthropic',
+  supportsVision: true,
+});
+
+const providers = registry.listProviders();
+
+const provider = registry.getProvider('openai');
+
+console.log(registry.getModelCount());
+console.log(registry.isInitialized());
+
+await registry.refresh();
+
+registry.shutdown();
+```
+
+---
+
+## Global Functions
+
+For convenience, the package provides global functions that use a default registry:
+
+```typescript
+import {
+  initializeModels,
+  getModel,
+  getPrice,
+  listModels,
+  getModelRegistry,
+  shutdownModels,
+} from '@cogitator-ai/models';
+
+await initializeModels();
+
+const model = getModel('gpt-4o-mini');
+const price = getPrice('gpt-4o-mini');
+const allModels = listModels();
+
+const registry = getModelRegistry();
+const count = registry.getModelCount();
+
+shutdownModels();
+```
+
+---
+
+## Model Information
+
+### ModelInfo Type
+
+```typescript
+interface ModelInfo {
+  id: string;
+  provider: string;
+  displayName: string;
+  pricing: ModelPricing;
+  contextWindow: number;
+  maxOutputTokens?: number;
+  capabilities?: ModelCapabilities;
+  deprecated?: boolean;
+  aliases?: string[];
+}
+
+interface ModelPricing {
+  input: number;
+  output: number;
+  inputCached?: number;
+  outputCached?: number;
+}
+
+interface ModelCapabilities {
+  supportsVision?: boolean;
+  supportsTools?: boolean;
+  supportsFunctions?: boolean;
+  supportsStreaming?: boolean;
+  supportsJson?: boolean;
+}
+```
+
+### Example Model
+
+```typescript
+const model = getModel('gpt-4o');
+// {
+//   id: 'gpt-4o',
+//   provider: 'openai',
+//   displayName: 'GPT-4o',
+//   pricing: { input: 2.5, output: 10 },
+//   contextWindow: 128000,
+//   maxOutputTokens: 16384,
+//   capabilities: {
+//     supportsVision: true,
+//     supportsTools: true,
+//     supportsStreaming: true,
+//     supportsJson: true,
+//   }
+// }
+```
+
+---
+
+## Filtering Models
+
+Use `ModelFilter` to query specific models:
+
+```typescript
+interface ModelFilter {
+  provider?: string;
+  supportsTools?: boolean;
+  supportsVision?: boolean;
+  minContextWindow?: number;
+  maxPricePerMillion?: number;
+  excludeDeprecated?: boolean;
+}
+```
+
+### Filter Examples
+
+```typescript
+const openaiModels = listModels({
+  provider: 'openai',
+});
+
+const visionModels = listModels({
+  supportsVision: true,
+});
+
+const toolModels = listModels({
+  supportsTools: true,
+  excludeDeprecated: true,
+});
+
+const largeContext = listModels({
+  minContextWindow: 100000,
+});
+
+const cheapModels = listModels({
+  maxPricePerMillion: 1.0,
+});
+
+const anthropicVision = listModels({
+  provider: 'anthropic',
+  supportsVision: true,
+  supportsTools: true,
+});
+```
+
+---
+
+## Providers
+
+### Built-in Providers
+
+```typescript
+import { BUILTIN_PROVIDERS } from '@cogitator-ai/models';
+```
+
+| Provider     | Website                |
+| ------------ | ---------------------- |
+| OpenAI       | openai.com             |
+| Anthropic    | anthropic.com          |
+| Google       | ai.google.dev          |
+| Ollama       | ollama.com             |
+| Azure OpenAI | azure.microsoft.com    |
+| AWS Bedrock  | aws.amazon.com/bedrock |
+| Mistral AI   | mistral.ai             |
+| Cohere       | cohere.com             |
+| Groq         | groq.com               |
+| Together AI  | together.ai            |
+| Fireworks AI | fireworks.ai           |
+| DeepInfra    | deepinfra.com          |
+| Perplexity   | perplexity.ai          |
+| Replicate    | replicate.com          |
+| xAI          | x.ai                   |
+
+### Provider Information
+
+```typescript
+interface ProviderInfo {
+  id: string;
+  name: string;
+  website?: string;
+  models: string[];
+}
+
+const providers = registry.listProviders();
+const openai = registry.getProvider('openai');
+console.log(openai?.models.length);
+```
+
+---
+
+## Built-in Models
+
+Fallback models are available when LiteLLM data cannot be fetched:
+
+```typescript
+import {
+  BUILTIN_MODELS,
+  OPENAI_MODELS,
+  ANTHROPIC_MODELS,
+  GOOGLE_MODELS,
+} from '@cogitator-ai/models';
+```
+
+### OpenAI Models
+
+- gpt-4o
+- gpt-4o-mini
+- o1
+- o1-mini
+- o3-mini
+
+### Anthropic Models
+
+- claude-sonnet-4-20250514
+- claude-3-5-sonnet-20241022
+- claude-3-5-haiku-20241022
+- claude-3-opus-20240229
+
+### Google Models
+
+- gemini-2.5-pro
+- gemini-2.5-flash
+- gemini-2.0-flash
+- gemini-1.5-pro
+- gemini-1.5-flash
+
+---
+
+## Caching
+
+### Memory Cache
+
+```typescript
+const registry = new ModelRegistry({
+  cache: {
+    ttl: 60 * 60 * 1000,
+    storage: 'memory',
+  },
+});
+```
+
+### File Cache
+
+```typescript
+const registry = new ModelRegistry({
+  cache: {
+    ttl: 24 * 60 * 60 * 1000,
+    storage: 'file',
+    filePath: './cache/models.json',
+  },
+});
+```
+
+### ModelCache Class
+
+```typescript
+import { ModelCache } from '@cogitator-ai/models';
+
+const cache = new ModelCache({
+  ttl: 3600000,
+  storage: 'file',
+  filePath: './models-cache.json',
+});
+
+const models = await cache.get();
+
+await cache.set(models);
+
+const staleData = await cache.getStale();
+```
+
+---
+
+## Data Fetching
+
+### LiteLLM Integration
+
+```typescript
+import { fetchLiteLLMData, transformLiteLLMData } from '@cogitator-ai/models';
+
+const rawData = await fetchLiteLLMData();
+
+const models = transformLiteLLMData(rawData);
+```
+
+### LiteLLM Data Structure
+
+```typescript
+interface LiteLLMModelEntry {
+  max_tokens?: number;
+  max_input_tokens?: number;
+  max_output_tokens?: number;
+  input_cost_per_token?: number;
+  output_cost_per_token?: number;
+  litellm_provider?: string;
+  supports_function_calling?: boolean;
+  supports_vision?: boolean;
+  deprecation_date?: string;
+}
+```
+
+---
+
+## Examples
+
+### Cost Calculator
+
+```typescript
+import { getPrice } from '@cogitator-ai/models';
+
+function calculateCost(modelId: string, inputTokens: number, outputTokens: number): number | null {
+  const price = getPrice(modelId);
+  if (!price) return null;
+
+  const inputCost = (inputTokens / 1_000_000) * price.input;
+  const outputCost = (outputTokens / 1_000_000) * price.output;
+
+  return inputCost + outputCost;
+}
+
+const cost = calculateCost('gpt-4o', 10000, 2000);
+console.log(`Cost: $${cost?.toFixed(4)}`);
+```
+
+### Model Selector
+
+```typescript
+import { listModels } from '@cogitator-ai/models';
+
+function selectBestModel(options: {
+  needsVision?: boolean;
+  needsTools?: boolean;
+  maxCost?: number;
+  minContext?: number;
+}): string | null {
+  const models = listModels({
+    supportsVision: options.needsVision,
+    supportsTools: options.needsTools,
+    maxPricePerMillion: options.maxCost,
+    minContextWindow: options.minContext,
+    excludeDeprecated: true,
+  });
+
+  if (models.length === 0) return null;
+
+  models.sort((a, b) => {
+    const aPrice = (a.pricing.input + a.pricing.output) / 2;
+    const bPrice = (b.pricing.input + b.pricing.output) / 2;
+    return aPrice - bPrice;
+  });
+
+  return models[0].id;
+}
+
+const cheapTool = selectBestModel({
+  needsTools: true,
+  maxCost: 2.0,
 });
 ```
 
-## Documentation
+### Provider Dashboard
+
+```typescript
+import { getModelRegistry, initializeModels } from '@cogitator-ai/models';
+
+async function showDashboard() {
+  await initializeModels();
+  const registry = getModelRegistry();
+
+  console.log(`Total models: ${registry.getModelCount()}`);
+  console.log();
+
+  for (const provider of registry.listProviders()) {
+    const models = registry.listModels({ provider: provider.id });
+    console.log(`${provider.name}: ${models.length} models`);
+
+    const avgPrice =
+      models.reduce((sum, m) => sum + (m.pricing.input + m.pricing.output) / 2, 0) / models.length;
+    console.log(`  Avg price: $${avgPrice.toFixed(2)}/M tokens`);
+  }
+}
+```
+
+---
+
+## Type Reference
+
+```typescript
+import type {
+  ModelInfo,
+  ModelPricing,
+  ModelCapabilities,
+  ModelFilter,
+  ProviderInfo,
+  CacheOptions,
+  RegistryOptions,
+  LiteLLMModelEntry,
+  LiteLLMModelData,
+} from '@cogitator-ai/models';
+```
 
-See the [Cogitator documentation](https://github.com/eL1fe/cogitator) for full API reference.
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogitator-ai/models",
-  "version": "1.1.0",
+  "version": "3.0.0",
   "description": "Dynamic model registry with pricing for Cogitator",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@cogitator-ai/types": "0.3.1"
+    "@cogitator-ai/types": "0.5.0"
   },
   "repository": {
     "type": "git",