Skip to content

About

TypeScript library that fetches and normalizes the Vultr Inference model catalog for client and agent integrations. Provides consistent model capabilities, limits, pricing, and cache fallback behavior.

Resources

Code of conduct

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

@vultr/model-catalog

Fetch GET /v1/models from Vultr Inference and turn each Model Document 2.4 entry into a flat CatalogModel. This is the base the TypeScript harness integrations (Pi, OpenClaw, OpenCode) build on. The Python twin is model-catalog-python; both produce the same output for the same input.

Install

npm install @vultr/model-catalog

No runtime dependencies. Node 20+ or Bun.

import { isChatModel, loadCatalog, pricePerMillion } from "@vultr/model-catalog";

const catalog = await loadCatalog({ cachePath: "/home/me/.cache/vultr/catalog.json", maxAgeMs: 300_000 });
for (const model of catalog.models.filter(isChatModel)) {
  console.log(model.id, model.contextWindow, pricePerMillion(model).prompt);
}

Surface

  • loadCatalog(options): fetch, normalize, fall back to the last good payload when the network fails. catalog.source is network, cache or stale-cache. Throws CatalogError only when there is nothing to serve
  • fetchCatalog(options): the raw JSON payload. The catalog is public; apiKey is optional. userAgent puts the caller's product token ahead of the library's own User-Agent (docs/catalog.md, Request)
  • parseCatalog(payload): documents plus issues. A bad entry is skipped and reported, it never fails the catalog
  • normalizeModel(document): one CatalogModel
  • isChatModel, isAgentModel, acceptsInput, pricePerMillion, usdPerMillion
  • toCanonical(model): the snake_case form shared with the Python library
  • outputOf(model, type), inputOf(model, type): one modality of outputs / inputs, or null
  • loadMediaCatalog(options): the per-surface catalogs (image, video, music, voices, tiers, price options, limits and alignment languages), one ModelMedia per model, its alignment an AlignmentRecord; fetchMediaPayloads, buildMediaCatalog, speechModelIds, toCanonicalMedia and MEDIA_SOURCES are its parts (docs/catalog.md, Media catalog)

CatalogModel carries contextWindow, maxOutputTokens, inputModalities, outputModalities, pricing (exact USD per token strings), tools, structuredOutputs, streaming, supportedParameters, parameters, reasoning, isReady, deprecationDate, and every modality as outputs and inputs. Rerankers, embedders, image generators, transcription and decision models are in the catalog too; isChatModel keeps the ones that output text. isAgentModel keeps the chat models a coding harness can drive: ready, with tool calling and a known context window. A safety classifier outputs text but calls no tools, so it is a chat model and not an agent model.

See docs/catalog.md for the field mapping and the cache format.

Development

npm install
npm run typecheck
npm test
npm run build

Tests run the .ts sources directly on Node's type stripping. fixtures/ is shared with the Python project: after changing normalization, run UPDATE_FIXTURES=1 npm test and copy fixtures/*.json to model-catalog-python/fixtures/.

About

TypeScript library that fetches and normalizes the Vultr Inference model catalog for client and agent integrations. Provides consistent model capabilities, limits, pricing, and cache fallback behavior.

Resources

Code of conduct

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages