@nikocraft/model-capabilities

Framework-free registry of exact model capabilities, reasoning wire parameters, modalities, and limits across Anthropic, OpenAI, Google, and OpenAI-wire proxy routes. Pure ESM; no Node built-ins; one runtime dependency (zod).

It answers: “what can this exact model do, and how do I express reasoning effort on this route?” SDK clients, live model discovery, credentials, and usage storage remain in the consumer app.

Usage

import { createRegistry, defaultCapabilities } from '@nikocraft/model-capabilities'

const registry = createRegistry(defaultCapabilities)
const model = registry.lookup('openai', 'gpt-5.4-mini')
// { context: 400000, maxOutput: 128000, reasoning: true, toolCall: true,
//   structuredOutput: true, inputModalities: ['text', 'image'], ... }

registry.effortParams('openai', 'gpt-5.4-mini', 'high')
// { providerOptions: { openai: { reasoningEffort: 'high' } } }

// Prefixes select the vendor record; the active proxy route still selects the wire format.
registry.effortParams('cliproxy', 'anthropic/claude-opus-4-8', 'high')
// { providerOptions: { openai: { reasoningEffort: 'high' } } }

Model identity

Version 0.2.0 intentionally replaces regex family rules with exact ids. A typo, an unreleased model name, or a future model is unknown rather than inheriting a neighbouring model’s limits. An unprefixed id behind a proxy resolves only when it is unique; use openai/model-id, anthropic/model-id, or google/model-id to be explicit.

The shipped snapshot includes all current direct OpenAI and Google records, including image, audio, video, live, research, and embedding records. inputModalities and outputModalities identify their surfaces. context and maxOutput are the provider catalogue values; 0 means that the provider does not publish a token limit (for example, OpenAI image-generation models), not a zero-token allowance.

Extending the registry

import { createRegistry, mergeCapabilities, defaultCapabilities } from '@nikocraft/model-capabilities'

const extended = mergeCapabilities(defaultCapabilities, {
  providers: {
    openai: {
      models: [{
        id: 'gpt-next-preview', aliases: [], mechanism: 'reasoning-effort',
        efforts: ['low', 'medium', 'high'], context: 400000, maxOutput: 128000,
        inputModalities: ['text', 'image'], outputModalities: ['text'],
        reasoning: true, toolCall: true, structuredOutput: true
      }]
    }
  }
})

createRegistry(extended)

An added entry with the same exact id replaces the shipped entry for that provider. Duplicate ids inside one provider block are rejected during validation.

API

| Export | What it does | |---|---| | createRegistry(doc) | Validates a capability document and returns a registry. | | Registry.lookup(provider, model) | Resolves exact model facts, with route overrides applied. | | Registry.effortLevels(...) | Returns selectable effort levels; [] means no control. | | Registry.effortParams(...) | Returns request-safe providerOptions and, where needed, maxOutputTokens. | | Registry.contextLimit(...) | Returns the route-aware context value. | | mergeCapabilities(...) | Adds or replaces exact provider records without mutating its inputs. | | contextPercent(...) | Calculates context occupancy from a request’s latest token usage. | | MODALITIES, EFFORTS, defaultCapabilities | The public vocabularies and shipped snapshot. |

The source research is in docs/MODEL-CAPABILITIES.md.