aimodels 0.3.12 → 0.4.1

package/README.md

@@ -1,6 +1,15 @@
-# AIModels
+# aimodels
 
-A collection of AI model specifications across different providers. This package provides normalized data about AI models, including their capabilities, context windows, and pricing information.
+A collection of AI model specifications across different providers. This universal JavaScript package provides normalized data about AI models, including their capabilities, context windows, and pricing information. Works in any JavaScript runtime (Node.js, browsers, Deno).
+
+## Use cases
+
+aimodels is useful when you need to programmatically access info about AI models and their capabilities. It's ideal for frameworks or applications that interact with different models, need to run inference across various providers or show info about models in the UI.
+
+aimodels powers: 
+- [aimodels.dev](https://aimodels.dev) - a website about AI models
+- [aiwrapper](https://github.com/mitkury/aiwrapper) - an AI wrapper for running AI models ([aiwrapper.dev](https://aiwrapper.dev))
+- [Supa](https://github.com/supaorg/supa) - an open alternative to ChatGPT ([supa.cloud](https://supa.cloud))
 
 ## Installation
 
@@ -13,48 +22,120 @@ npm install aimodels
 ```typescript
 import { models } from 'aimodels';
 
-// Find models by capability using fluent API
+// 1. Get all models that support chat functionality
 const chatModels = models.canChat();
-const visionModels = models.canSee();
-const reasoningModels = models.canReason();
-
-// Chain methods for more specific filtering
-const smartVisionModels = models.canChat().canReason().canSee();
-const multimodalAssistants = models.canChat().canSee().canHear();
-const fullStackModels = models.canChat().canCallFunctions().canOutputJSON();
-
-// Audio capabilities
-const speechModels = models.canHear().canSpeak();
-
-// Text processing
-const textProcessors = models.canRead().canWrite();
-
-// Available fluent API methods:
-// - canChat() - models with chat capability
-// - canReason() - models with reasoning capability
-// - canRead() - models that can process text input
-// - canWrite() - models that can output text
-// - canSee() - models that understand images
-// - canGenerateImages() - models that can create images
-// - canHear() - models that understand audio
-// - canSpeak() - models that can generate speech
-// - canOutputJSON() - models that provide structured JSON output
-// - canCallFunctions() - models with function calling capability
-// - canGenerateEmbeddings() - models that output vector embeddings
-
-// Find models by provider
-const openaiModels = models.fromProvider('openai');
-
-// Find models by creator
-const metaModels = models.fromCreator('meta');
-
-// Find models by context window
-const largeContextModels = models.withMinContext(32768);
-
-// Find specific model
+console.log(`Available chat models: ${chatModels.length}`);
+// Example output: "Available chat models: 99"
+
+// 2. Find all chat models with vision capabilities from OpenAI
+const visionModelsFromOpenAI = models.canChat().canSee().fromProvider('openai');
+console.log(visionModelsFromOpenAI.map(model => model.name));
+// Example output: ["GPT-4o", "GPT-4 Vision", ...]
+
+// 3. Check if a specific model can process images
 const model = models.id('gpt-4o');
-console.log(model?.context.total); // Context window size
-console.log(model?.providers); // ['openai']
+if (model?.canSee()) {
+  console.log(`${model.name} can process images`);
+  // Enable image upload in your UI
+  const allowAttachingImgs = true;
+}
+
+// You can also check multiple capabilities with a single method
+if (model?.can('img-in', 'chat')) {
+  console.log(`${model.name} can both chat and understand images`);
+}
+
+// And use capability checks to make UI decisions
+function renderModelControls(model) {
+  return {
+    showImageUpload: model.canSee(),
+    showAudioRecorder: model.canHear(),
+    showFunctionEditor: model.canCallFunctions(),
+    showResponseFormatting: model.canOutputJSON(),
+  };
+}
+
+// 4. Make decisions based on context window size
+function selectModelBasedOnInputLength(inputTokens) {
+  // Find models that can handle your content's size
+  const suitableModels = models.canChat().filter(model => 
+    (model.context.total || 0) >= inputTokens
+  );
+  
+  // Sort by context window size (smallest suitable model first)
+  return suitableModels.sort((a, b) => 
+    (a.context.total || 0) - (b.context.total || 0)
+  )[0];
+}
+
+const contentLength = 10000; // tokens
+const recommendedModel = selectModelBasedOnInputLength(contentLength);
+console.log(`Recommended model: ${recommendedModel?.name}`);
+
+// 5. Utility function to trim chat messages to fit a model's context window
+function trimChatHistory(messages, model, reserveTokens = 500) {
+  // Only proceed if we have a valid model with a context window
+  if (!model || !model.context?.total) {
+    console.warn('Invalid model or missing context window information');
+    return messages;
+  }
+  
+  const contextWindow = model.context.total;
+  let totalTokens = 0;
+  const availableTokens = contextWindow - reserveTokens;
+  const trimmedMessages = [];
+  
+  // This is a simplified token counting approach
+  // In production, you may use a proper tokenizer for your model
+  for (const msg of messages.reverse()) {
+    // If the model can't process images, remove any image attachments
+    if (!model.canSee() && msg.attachments?.some(a => a.type === 'image')) {
+      msg.attachments = msg.attachments.filter(a => a.type !== 'image');
+    }
+    
+    const estimatedTokens = JSON.stringify(msg).length / 4;
+    if (totalTokens + estimatedTokens <= availableTokens) {
+      trimmedMessages.unshift(msg);
+      totalTokens += estimatedTokens;
+    } else {
+      break;
+    }
+  }
+  
+  return trimmedMessages;
+}
+
+// Example usage
+const chatHistory = [/* array of message objects */];
+const gpt4 = models.id('gpt-4');
+const fittedMessages = trimChatHistory(chatHistory, gpt4);
+```
+
+### Available API Methods
+
+```typescript
+// Capability methods
+models.canChat()               // Models with chat capability
+models.canReason()             // Models with reasoning capability
+models.canRead()               // Models that can process text input
+models.canWrite()              // Models that can output text
+models.canSee()                // Models that understand images
+models.canGenerateImages()     // Models that can create images
+models.canHear()               // Models that understand audio
+models.canSpeak()              // Models that can generate speech
+models.canOutputJSON()         // Models that provide structured JSON output
+models.canCallFunctions()      // Models with function calling capability
+models.canGenerateEmbeddings() // Models that output vector embeddings
+
+// Provider and creator methods
+models.fromProvider('openai')  // Find models by provider
+models.fromCreator('meta')     // Find models by creator
+
+// Context window methods
+models.withMinContext(32768)   // Find models with at least this context size
+
+// Model lookup
+models.id('gpt-4o')            // Find a specific model by ID
 ```
 
 ## Features
@@ -69,31 +150,17 @@ console.log(model?.providers); // ['openai']
 - Universal JavaScript support (Node.js, browsers, Deno)
 - Regular updates with new models
 
-## Types
+## License
 
-### Model
-```typescript
-interface Model {
-  /** Unique identifier */
-  id: string;
-  /** Display name */
-  name: string;
-  /** Model capabilities */
-  can: Capability[];
-  /** Available providers */
-  providers: string[];
-  /** Context window information */
-  context: ModelContext;
-  /** License or creator */
-  license: string;
-}
-```
+MIT
 
-For more detailed information, see:
-- [Model Capabilities](/docs/model-capabilities.md)
-- [Model Structure](/docs/model-structure.md)
-- [Providers](/docs/providers.md)
+## Development
 
-## License
+### Build Process
 
-MIT
+This project uses [tsup](https://github.com/egoist/tsup) (built on esbuild) for bundling. The build process is simple:
+
+```bash
+# Build the complete package and test
+npm run build
+```

package/dist/index.d.ts

@@ -1,46 +1,59 @@
+interface TokenBasedPricePerMillionTokens {
+    /** Price per million input tokens */
+    input: number;
+    /** Price per million output tokens */
+    output: number;
+    /** Price type */
+    type: 'token';
+}
+interface ImagePrice {
+    /** Price per image */
+    price: number;
+    /** Image size */
+    size: string;
+    /** Price type */
+    type: 'image';
+    /** Price unit */
+    unit: 'per_image';
+}
+
+/** Core organization data */
+interface Organization {
+    /** Unique identifier (e.g., "openai", "meta", "anthropic") */
+    id: string;
+    /** Display name (e.g., "OpenAI", "Meta", "Anthropic") */
+    name: string;
+    /** Organization's main website URL */
+    websiteUrl: string;
+    /** Organization's country of origin */
+    country: string;
+    /** Year founded */
+    founded: number;
+}
+
+interface ProviderSource {
+    id: string;
+    apiUrl: string;
+    apiDocsUrl: string;
+    pricing: Record<string, TokenBasedPricePerMillionTokens | ImagePrice>;
+}
+/** Provider-specific data */
+interface Provider extends Organization {
+    /** Provider's API endpoint URL */
+    apiUrl: string;
+    /** Provider's API documentation URL */
+    apiDocsUrl: string;
+    /** Whether this is a local provider */
+    isLocal?: number;
+    /** Model pricing information */
+    pricing: Record<string, TokenBasedPricePerMillionTokens | ImagePrice>;
+}
+
 /**
  * Defines all possible model capabilities
  */
 type Capability = "chat" | "reason" | "txt-in" | "txt-out" | "img-in" | "img-out" | "audio-in" | "audio-out" | "json-out" | "fn-out" | "vec-out";
 
-declare class ModelCollection extends Array<Model> {
-    /** Create a new ModelCollection from an array of models */
-    constructor(models?: Model[]);
-    /** Filter models by one or more capabilities (all must be present) */
-    can(...capabilities: Capability[]): ModelCollection;
-    /**
-     * Fluent capability filters for better readability
-     * Each method filters models by a specific capability
-     */
-    canChat(): ModelCollection;
-    canReason(): ModelCollection;
-    canRead(): ModelCollection;
-    canWrite(): ModelCollection;
-    canSee(): ModelCollection;
-    canGenerateImages(): ModelCollection;
-    canHear(): ModelCollection;
-    canSpeak(): ModelCollection;
-    canOutputJSON(): ModelCollection;
-    canCallFunctions(): ModelCollection;
-    canGenerateEmbeddings(): ModelCollection;
-    /** Filter models by one or more languages (all must be supported) */
-    know(...languages: string[]): ModelCollection;
-    /** Override array filter to return ModelCollection */
-    filter(predicate: (value: Model, index: number, array: Model[]) => boolean): ModelCollection;
-    /** Override array slice to return ModelCollection */
-    slice(start?: number, end?: number): ModelCollection;
-    /** Find a model by its ID or alias */
-    id(modelId: string): Model | undefined;
-    /** Get models available from a specific provider */
-    fromProvider(provider: string): ModelCollection;
-    /** Get models available from a specific creator */
-    fromCreator(creator: string): ModelCollection;
-    /** Filter models by minimum context window size */
-    withMinContext(tokens: number): ModelCollection;
-    /** Get all providers from all models in the collection deduplicated */
-    getProviders(): string[];
-    getCreators(): string[];
-}
 interface BaseContext {
     /** The type discriminator */
     type: string;
@@ -114,99 +127,177 @@ interface EmbeddingContext extends BaseContext {
     normalized?: boolean;
 }
 type ModelContext = TokenContext | CharacterContext | ImageContext | AudioInputContext | AudioOutputContext | EmbeddingContext;
-interface Model {
+
+/**
+ * Represents the raw model data exactly as it appears in the source files.
+ * This is a direct representation of the JSON structure.
+ */
+interface ModelSource {
     /** Unique identifier */
     id: string;
     /** Display name */
-    name: string;
-    /** Creator of the model */
-    creator: string;
-    /** License type (e.g., "proprietary", "apache-2.0", "llama-2-community") */
-    license: string;
-    /** List of providers that can serve this model */
-    providers: string[];
+    name?: string;
     /** Model capabilities */
-    can: Capability[];
+    capabilities?: Capability[];
+    /** Available providers */
+    providerIds?: string[];
+    /** Context window information */
+    context?: ModelContext;
+    /** Organization that created this model */
+    creatorId?: string;
+    /** License type (e.g., "proprietary", "apache-2.0", "llama-2-community") */
+    license?: string;
     /** Languages the model knows */
     languages?: string[];
     /** Alternative identifiers for this model */
     aliases?: string[];
-    /** Context window information */
-    context: ModelContext;
     /** Base model ID this model extends */
     extends?: string;
     /** Properties that override the base model */
-    overrides?: Partial<Omit<Model, 'id' | 'extends' | 'overrides'>>;
+    overrides?: Partial<Omit<ModelSource, 'id' | 'extends' | 'overrides'>>;
 }
 
-interface TokenBasedPricePerMillionTokens {
-    /** Price per million input tokens */
-    input: number;
-    /** Price per million output tokens */
-    output: number;
-    /** Price type */
-    type: 'token';
-}
-interface ImagePrice {
-    /** Price per image */
-    price: number;
-    /** Image size */
-    size: string;
-    /** Price type */
-    type: 'image';
-    /** Price unit */
-    unit: 'per_image';
+/**
+ * Enhanced Model class that provides functionality on top of raw model data.
+ * Handles inheritance resolution and provides access to related objects.
+ */
+declare class Model {
+    private source;
+    constructor(source: ModelSource);
+    get id(): string;
+    get extends(): string | undefined;
+    get overrides(): Partial<ModelSource> | undefined;
+    private resolveProperty;
+    get name(): string;
+    get capabilities(): Capability[];
+    get context(): ModelContext | undefined;
+    get license(): string | undefined;
+    get languages(): string[] | undefined;
+    get aliases(): string[] | undefined;
+    get providerIds(): string[];
+    get providers(): Provider[];
+    get creatorId(): string | undefined;
+    get creator(): Organization | undefined;
+    /**
+     * Check if model has all specified capabilities
+     * Uses same API pattern as ModelCollection.can() but returns boolean
+     */
+    can(...capabilities: Capability[]): boolean;
+    canChat(): boolean;
+    canReason(): boolean;
+    canRead(): boolean;
+    canWrite(): boolean;
+    canSee(): boolean;
+    canGenerateImages(): boolean;
+    canHear(): boolean;
+    canSpeak(): boolean;
+    canOutputJSON(): boolean;
+    canCallFunctions(): boolean;
+    canGenerateEmbeddings(): boolean;
 }
 
-interface Provider {
-    /** Provider identifier */
-    id: string;
-    /** Display name */
-    name: string;
-    /** Website URL */
-    websiteUrl: string;
-    /** API endpoint */
-    apiUrl: string;
-    /** Default model */
-    defaultModel?: string;
-    /** Whether this is a local provider */
-    isLocal?: number;
-    /** Model pricing */
-    models: Record<string, TokenBasedPricePerMillionTokens | ImagePrice>;
+declare class ModelCollection extends Array<Model> {
+    static providersData: Record<string, ProviderSource>;
+    static orgsData: Record<string, Organization>;
+    static modelSources: Record<string, ModelSource>;
+    /** Create a new ModelCollection from an array of models */
+    constructor(models?: Model[]);
+    /** Set the shared providers data */
+    static setProviders(providers: Record<string, Provider>): void;
+    /** Set the shared creators data */
+    static setOrgs(orgs: Record<string, Organization>): void;
+    /** Filter models by one or more capabilities (all must be present) */
+    can(...capabilities: Capability[]): ModelCollection;
+    /**
+     * Fluent capability filters for better readability
+     * Each method filters models by a specific capability
+     */
+    canChat(): ModelCollection;
+    canReason(): ModelCollection;
+    canRead(): ModelCollection;
+    canWrite(): ModelCollection;
+    canSee(): ModelCollection;
+    canGenerateImages(): ModelCollection;
+    canHear(): ModelCollection;
+    canSpeak(): ModelCollection;
+    canOutputJSON(): ModelCollection;
+    canCallFunctions(): ModelCollection;
+    canGenerateEmbeddings(): ModelCollection;
+    /** Filter models by one or more languages (all must be supported) */
+    know(...languages: string[]): ModelCollection;
+    /** Override array filter to return ModelCollection */
+    filter(predicate: (value: Model, index: number, array: Model[]) => boolean): ModelCollection;
+    /** Override array slice to return ModelCollection */
+    slice(start?: number, end?: number): ModelCollection;
+    /** Find a model by its ID or alias */
+    id(modelId: string): Model | undefined;
+    /** Get models available from a specific provider */
+    fromProvider(provider: string): ModelCollection;
+    /** Get models available from a specific creator */
+    fromCreator(creator: string): ModelCollection;
+    /** Filter models by minimum context window size */
+    withMinContext(tokens: number): ModelCollection;
+    /** Get all providers from all models in the collection deduplicated */
+    get providers(): Provider[];
+    /** Get all orgs from all models in the collection deduplicated */
+    get orgs(): Organization[];
+    /** Get a specific provider by ID */
+    getProvider(id: string): Provider | undefined;
+    /** Get a specific creator by ID */
+    getCreator(id: string): Organization | undefined;
+    /** Get providers for a specific model */
+    getProvidersForModel(modelId: string): Provider[];
+    /** Get creator for a specific model */
+    getCreatorForModel(modelId: string): Organization | undefined;
 }
 
-var creators = {
-	openai: {
-		name: "OpenAI",
-		website: "https://openai.com"
-	},
-	anthropic: {
-		name: "Anthropic",
-		website: "https://anthropic.com"
-	},
-	meta: {
-		name: "Meta",
-		website: "https://ai.meta.com"
-	},
-	mistral: {
-		name: "Mistral AI",
-		website: "https://mistral.ai"
-	}
-};
-var creators$1 = {
-	creators: creators
-};
-
+/**
+ * AIModels is a collection of AI models with associated metadata.
+ *
+ * This class follows the singleton pattern with a private constructor and a static getter.
+ * IMPORTANT: Do not instantiate this class directly. Instead, import the pre-configured
+ * singleton instance from the package:
+ *
+ * ```typescript
+ * import { models } from 'aimodels';
+ * ```
+ *
+ * The singleton instance contains all the model data and is the recommended way to use this package.
+ * If you need to access the class for type references, you can also import it:
+ *
+ * ```typescript
+ * import { AIModels, models } from 'aimodels';
+ * ```
+ */
 declare class AIModels extends ModelCollection {
-    constructor(models?: Model[]);
-    get creators(): string[];
-    get providers(): string[];
-    getPrice(modelId: string, provider: string): TokenBasedPricePerMillionTokens | undefined;
-    /** Get provider information by ID */
-    getProvider(providerId: string): Provider | undefined;
-    /** Get all providers that can serve a specific model */
-    getProvidersForModel(modelId: string): Provider[];
+    private static _instance;
+    /**
+     * @private
+     * Private constructor used only by the static instance getter.
+     * Users should import the pre-configured instance from the package.
+     */
+    private constructor();
+    /**
+   * Add data to the static data containers
+   * @param data Object containing model sources, providers, and organizations to add
+   */
+    static addStaticData({ models, providers, orgs }: {
+        models?: Record<string, ModelSource>;
+        providers?: Record<string, ProviderSource>;
+        orgs?: Record<string, Organization>;
+    }): void;
+    static get instance(): AIModels;
+    /**
+     * Override to return all providers directly without filtering through models.
+     * We want to return all known providers here.
+     */
+    get providers(): Provider[];
+    /**
+     * Override to return all creators directly without filtering through models.
+     * We want to return all known creators here.
+     */
+    get orgs(): Organization[];
 }
 declare const models: AIModels;
 
-export { AIModels, type Capability, type Model, ModelCollection, type ModelContext, type Provider, type TokenBasedPricePerMillionTokens, creators$1 as creators, models };
+export { AIModels, type AudioInputContext, type AudioOutputContext, type BaseContext, type Capability, type CharacterContext, type EmbeddingContext, type ImageContext, Model, ModelCollection, type ModelContext, type ModelSource, type Organization, type Provider, type ProviderSource, type TokenContext, models };