Model

The model module handles parsing model identifiers (e.g. openai/gpt-4o), auto-resolving bare model IDs, maintaining a global model registry, resolving model strings into live LanguageModel instances, and listing providers and their available models.

How Model Resolution Works

When createAgent() receives a model string, resolveModel() resolves it into a live LanguageModel. Two formats are supported:

1. Explicit "providerID/modelID" — e.g. "openai/gpt-4o". The provider is used directly.
2. Bare model ID — e.g. "gpt-4o". The model catalog is queried to find all providers that list the model. Each candidate provider is checked for configured credentials; the first one with a matching credential wins.

Resolution order for both formats:

1. Direct model registry — exact match via registerModel(). Ideal for tests and mocking. Checked first, before any parsing or catalog lookup.
2. Explicit provider (contains /) — parses the string into provider/model parts, looks up credentials via the global credential store, then creates a LanguageModel via the global provider resolver.
3. Auto-resolution (no /) — queries the reverse model index for candidate providers (sorted alphabetically), checks credentials for each candidate, and resolves the first one with configured credentials.

import { registerModel, registerProvider, createAgent } from "@comma-agents/core";

// Option 1: Register a model directly (great for tests)
registerModel("mock/test", myMockLanguageModel);
const agent = createAgent({ name: "test", model: "mock/test" });

// Option 2: Register a provider (for custom/non-standard providers)
registerProvider("my-llm", {
  factory: (credential) => (modelId) => myProvider({ apiKey: credential.key, model: modelId }),
});
const agent2 = createAgent({ name: "custom", model: "my-llm/latest" });

// Option 3: Known providers resolve automatically (openai, anthropic, etc.)
// Just ensure credentials are configured and the provider's npm package is installed.
const agent3 = createAgent({ name: "writer", model: "openai/gpt-4o" });

// Option 4: Bare model ID — auto-resolves provider from catalog
// The first provider with credentials for "gpt-4o" wins
const agent4 = createAgent({ name: "assistant", model: "gpt-4o" });

When no provider has credentials for a bare model ID, resolveModel throws a ModelResolutionError listing all providers that support the model, so you know exactly which credentials to configure.

Model Registry

registerModel

Register a LanguageModel instance for a specific model string. Registered models take precedence over provider-based resolution.

import { registerModel } from "@comma-agents/core";

registerModel("mock/test", mockLanguageModel);

unregisterModel

Remove a previously registered model. Returns true if it was registered and removed.

resetModelRegistry

Reset the global model registry to empty state. Primarily for tests.

Model Metadata Lookup

Query the catalog for metadata about a specific model by its bare ID.

getModelMetadata

Returns full ModelInfo for a bare model ID — capabilities, modalities, cost, context window, and more. The catalog is checked for the first provider that lists the model.

import { getModelMetadata } from "@comma-agents/core";

const info = getModelMetadata("gpt-4o");
console.log(info?.contextWindow);              // 128000
console.log(info?.capabilities?.reasoning);    // true
console.log(info?.cost?.input);                // 2.5 (USD per 1M tokens)

Returns undefined if the model is not found in any provider catalog.

getModelCapabilities

Convenience wrapper for checking capability flags. Returns ModelCapabilities | undefined for a bare model ID.

import { getModelCapabilities } from "@comma-agents/core";

const caps = getModelCapabilities("gpt-4o");
if (caps?.reasoning) {
  // Use reasoning-related provider options
}
if (caps?.vision) {
  // Send image inputs
}

Provider Resolution

Providers are resolved via registerProvider() in the defaults module. The global provider resolver checks:

1. Custom provider registrations (via registerProvider())
2. Built-in overrides (e.g. ollama, deepseek, github-copilot)
3. The bundled provider catalog, which maps each provider id to its npm package
4. Last resort: attempt a dynamic import for the provider package

Provider Discovery

The model module also exposes APIs to list known providers and their models. Data comes from three sources merged together:

• Catalog — a bundled snapshot of the models.dev catalog, covering 50+ providers and their models. The snapshot is shipped with the package and refreshed on disk every 24 hours.
• Built-in overrides — hardcoded entries for providers that need custom package resolution or live discovery (Ollama, Deepseek, GitHub Copilot).
• Live listers — optional runtime discovery for Ollama (via the local /api/tags endpoint) and GitHub Copilot (via the Copilot API). Enabled by passing { live: true }.

listProviders

Return every known provider enriched with its model list.

import { listProviders } from "@comma-agents/core";

const providers = await listProviders();
for (const provider of providers) {
  console.log(provider.id, provider.models.length);
}

// Include live discovery (Ollama + Copilot)
const liveProviders = await listProviders({ live: true });

getProviderInfo

Fetch information for a single provider by id.

import { getProviderInfo } from "@comma-agents/core";

const info = await getProviderInfo("openai");
console.log(info?.name, info?.models[0]?.id);

ProviderInfo

The shape returned by listProviders and getProviderInfo.

ModelInfo

A single model entry in ProviderInfo.models.

Types

ParsedModel

The result of parsing a provider/model string.

ProviderFactory

A function that creates a LanguageModel from a model ID.

ProviderResolver

A function that translates a (providerId, credential) pair into a ProviderFactory.