Skip to content
ContractSpec
Start here

Package manual · platform

·Integrations and provider selection

lib.ai-providers

Unified AI provider abstraction layer

platformlibraryv6.2.5stableservernode
@lssm-tech/lib.ai-providers
bun add @lssm-tech/lib.ai-providers
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Website: https://contractspec.io

Unified AI provider abstraction layer.

Ollama uses ollama-ai-provider-v2 4.0.1, implementing the AI SDK 7 model interface with Zod 4. Existing provider/model/base URL/header configuration is unchanged; legacy LanguageModelV1 type casts are no longer used.

What It Provides

  • Layer: lib.
  • Consumers: ai-agent, content-gen, image-gen, voice.
  • Related ContractSpec packages include @lssm-tech/lib.provider-ranking, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.
  • Related ContractSpec packages include @lssm-tech/lib.provider-ranking, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.

Installation

npm install @lssm-tech/lib.ai-providers

or

bun add @lssm-tech/lib.ai-providers

Usage

Import the root entrypoint from @lssm-tech/lib.ai-providers, or choose a documented subpath when you only need one part of the package surface.

Architecture

  • src/factory.ts is part of the package's public or composition surface.
  • src/index.ts is the root public barrel and package entrypoint.
  • src/legacy.ts is part of the package's public or composition surface.
  • src/models.test.ts is part of the package's public or composition surface.
  • src/models.ts is part of the package's public or composition surface.
  • src/model-catalog/ holds one internal catalog data leaf per provider (ollama, openai, anthropic, mistral, gemini); src/models.ts assembles them and is the only public entry for catalog data.
  • src/selector-types.ts is part of the package's public or composition surface.
  • src/selector.ts is part of the package's public or composition surface.
  • src/types.ts is shared public type definitions.

Public Entry Points

  • Export . resolves through ./src/index.ts.
  • Export ./economic-evidence resolves through ./src/economic-evidence.ts.
  • Export ./factory resolves through ./src/factory.ts.
  • Export ./legacy resolves through ./src/legacy.ts.
  • Export ./models resolves through ./src/models.ts.
  • Export ./run-scoped-model-route resolves through ./src/run-scoped-model-route.ts.
  • Export ./selector-eligibility resolves through ./src/selector-eligibility.ts.
  • Export ./selector resolves through ./src/selector.ts.
  • Export ./selector-types resolves through ./src/selector-types.ts.
  • Export ./types resolves through ./src/types.ts.
  • Export ./validation resolves through ./src/validation.ts.

Production agent runs resolve a pinned, qualified ContractSpec model route with resolveRunScopedModelRoute. The resolver validates the exact plan, selection, route, capability profile, qualification, and release SHA before requesting an run- and route-scoped secret lease. Credential material is consumed inside provider construction and is never returned in route metadata. Legacy factory calls remain available for existing consumers.

Gateway-neutral V2 resolution uses the same governed path for direct/BYOK, managed OpenAI-compatible gateways, and local adapters. Route identity keeps model author, inference provider, deployment, gateway, commercial policy, connection, and price evidence distinct. Adapter-specific options resolve only from a digest-bound, secret-free registry and must pass the adapter allowlist; they cannot be supplied as per-call overrides. AI Providers constructs and validates the adapter but never selects a route or grants authority. Managed endpoint material is accepted only inside an expiring lease and rejects embedded credentials, query parameters, and fragments. Provider-receipt actual cost evidence is exact and supersedes catalog estimates; estimate evidence is explicitly labeled with its catalog source and policy.

Local Commands

  • bun run dev — contractspec-bun-build dev
  • bun run build — contractspec-bun-build build
  • bun run test — bun test --pass-with-no-tests
  • bun run lint — bun lint:fix
  • bun run lint:check — biome check .
  • bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
  • bun run typecheck — tsgo --noEmit
  • bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
  • bun run publish:pkg:canary — bun publish:pkg --tag canary
  • bun run clean — rimraf dist .turbo
  • bun run build:bundle — contractspec-bun-build transpile
  • bun run build:types — contractspec-bun-build types
  • bun run prebuild — contractspec-bun-build prebuild

Model Catalog and Defaults

@lssm-tech/lib.ai-providers/models exports MODELS, DEFAULT_MODELS and the getModelsForProvider, getModelInfo, getRecommendedModels and getDefaultModel lookups. Every DEFAULT_MODELS value is a catalog ID of its provider; models.test.ts enforces this.

ProviderDefault
anthropicclaude-sonnet-5-5
openaigpt-5.4
mistralmistral-large-latest
geminigemini-2.5-flash
ollamallama3.2

Claude Sonnet 5.5 rejects non-default sampling values. Callers that use the Anthropic default must not send temperature, top_p or top_k; pin claude-sonnet-4-6 to keep sending them.

Economic Evidence

@lssm-tech/lib.ai-providers/economic-evidence estimates provider token costs from the model catalog and creates neutral economic cost evidence refs. The helper returns reference-only evidence for downstream metering, billing, observability, and replay surfaces; it does not execute invoices, payments, or finance projections.

Recent Updates

  • Replace eslint+prettier by biomejs to optimize speed.
  • Add latest models and align defaults.
  • Resolve lint, build, and type errors across nine packages.
  • Add first-class transport, auth, versioning, and BYOK support across all integrations.
  • Add AI provider ranking system with ranking-driven model selection.
  • Add first-class mistral provider support.
  • Add provider/model token cost evidence helpers backed by @lssm-tech/lib.economic-evidence.

Notes

  • Provider interface is consumed by all AI-powered libs; breaking changes cascade widely.
  • Adding new providers must not break existing factory signatures.

Native Vercel Gateway routes

The additive ./vercel-gateway export provides createVercelGatewayModel and createVercelGatewayProvider. It uses the native Gateway SDK rather than the OpenAI-compatible proxy branch, preserving EU-zone inference, ZDR, no-training and an explicit non-Mistral inference-provider allowlist on every request. Caller-supplied Gateway policy overrides are rejected. Remote origins, endpoint paths, model namespaces and unpinned latest identifiers fail validation. Credentials are Gateway API keys or the SDK's OIDC resolution; no direct provider key or automatic model fallback is selected.

./vercel-gateway-auth resolves the Gateway credential per request: AI_GATEWAY_API_KEY, then (on Vercel only) the invocation's x-vercel-oidc-token header when it is a JWT whose project_id matches VERCEL_PROJECT_ID if exposed, then a VERCEL_OIDC_TOKEN value. vercelGatewayAuthFetch labels OIDC calls with the Gateway oidc auth method. CommunicationOS thread assist and OPA briefings share this resolver; tokens are never logged.

The default V2 adapter registry additionally supports adapter.ai-sdk.vercel-gateway.v1 with managed_gateway lease material and registry-bound options { modelAuthor, only }. Its lease endpoint must use the native /v4/ai protocol. Gateway identity remains in serving metadata; the generic Provider.name remains the model author. Existing OpenAI-compatible adapters and factory defaults retain their prior behavior. Validation is configuration-only, not proof of credentials, model availability or release qualification.

EU inference does not constrain the Gateway's own global processing. Hosts must obtain explicit processing approval for that boundary before private requests; see Vercel regional inference. No production credentials or private requests are used by adapter tests.

readVercelGatewayRoutingMetadata returns a bounded whitelist of the SDK's final provider and per-attempt inference endpoint facts. It does not infer regional success from request settings or grant approval: callers must verify the served provider and EU endpoint against their route. Missing evidence remains missing; out-of-region and global endpoints remain distinguishable. Unknown headers, provider bodies and arbitrary metadata are excluded from the returned projection.

Gateway EU response evidence accepts both zone and specific endpoint scopes only when geoRegion is explicitly eu. A more specific EU endpoint is not a global fallback. Missing/global/non-EU evidence remains rejected; requested routing flags alone never prove the served geography. This does not grant private Gateway transit approval.

Contract ownership imports use the canonical AgentProtocol, Core serialization and orchestration evidence owners. Provider execution, factory signatures, route authority and credential leases keep their existing behavior.

Gateway model profiles (D-226, D-241)

Every LLM use (agents, enrichment, CV generation and critique, assistant, scraping, summarization) goes through the Vercel AI SDK and the Vercel AI Gateway. Classifiers and decision models (Jev, luna) are out of scope. ./ai-gateway-profiles defines named profiles that map task roles to pinned Gateway model ids plus an ordered fallback list. Profiles are selected by environment variable name:

VariableMeaning
CONTRACTSPEC_AI_PROFILEopenai or anthropic; when unset, see "Default profile switch"
CONTRACTSPEC_AI_OPERATOR_CONFIRMED_MODELSComma list of exact model ids an operator confirmed (no patterns; malformed lists fail closed)
CONTRACTSPEC_AI_FALLBACKSoff removes every fallback model; unset or on keeps them
CONTRACTSPEC_AI_MODEL_<ROLE>Per-role primary override (openai/…, anthropic/…, google/…; never latest)
CONTRACTSPEC_AI_PROVIDERS_{OPENAI,ANTHROPIC,GEMINI}Comma list for the Gateway only restriction of that model author (defaults openai, bedrock, vertex; mistral is refused)
AI_GATEWAY_API_KEYGateway credential; on Vercel, OIDC (x-vercel-oidc-token / VERCEL_OIDC_TOKEN) is accepted instead

OPENAI_API_KEY and ANTHROPIC_API_KEY are never read by these helpers.

Roleopenai profile (D-226, rollback)anthropic profile (D-241): primary → fallback
agentopenai/gpt-6-lunaanthropic/claude-sonnet-5.5 → openai/gpt-6.1-sol
recoveryopenai/gpt-6-solanthropic/claude-opus-5.5 → openai/gpt-6.1-sol
extractionopenai/gpt-6-lunaanthropic/claude-haiku-5.5 → openai/gpt-6-luna
summarizationopenai/gpt-6-lunaanthropic/claude-haiku-5.5 → openai/gpt-6-luna
fastopenai/gpt-6-lunaanthropic/claude-haiku-5.5 → openai/gpt-6-luna
generation (CV and other drafts)openai/gpt-6-lunaanthropic/claude-sonnet-5.5 → openai/gpt-6.1-sol
critic (independent review)anthropic/claude-sonnet-5.5 (D-234 pair)openai/gpt-6.1-sol → anthropic/claude-sonnet-5.5 (see below)
assistantopenai/gpt-6-lunaanthropic/claude-sonnet-5.5 → openai/gpt-6.1-sol
enrichmentopenai/gpt-6-lunaanthropic/claude-haiku-5.5 → openai/gpt-6-luna

Only ids from approved sources are used. OpenAI values are the donor focused engine and enrichment production values (approved). Anthropic values come from lib.provider-spec's EU Gateway catalog and stay operator_confirmation_required, as does any per-role override. openai/gpt-6-sol is the donor recovery model of the openai rollback profile only; it is not in the EU catalog (which lists openai/gpt-6.1-sol), so the anthropic profile falls back to openai/gpt-6.1-sol instead (D-244). Embeddings are not routed by these profiles (AI_GATEWAY_EMBEDDING_ROUTING): they stay on their current binding, since the approved catalog has no Anthropic embedding model.

Ordered cross-author fallback

A role's fallbacks are sent with the Gateway's own mechanism: providerOptions.gateway.models lists the fallback model ids in order, and only/order become the ordered union of every chain model's inference providers (the Gateway applies one provider allowlist per call). The EU-zone, zero-retention and no-training options still apply to every attempt. Without fallbacks the provider options are unchanged. createVercelGatewayModel accepts fallbacks (at most 3, distinct, never the primary model); GatewayLLMProvider passes it through. The resolved role exposes fallbacks, approval (whole chain) and modelApproval (primary alone).

Because one only/order list covers the whole call, a provider listed for one author could otherwise serve another author's model of the chain. A provider may therefore appear under one author only: a chain whose CONTRACTSPEC_AI_PROVIDERS_* lists share a provider fails with AI_INFERENCE_PROVIDERS_INVALID (and vercelGatewayProviderOptions with GATEWAY_FALLBACK_INVALID); separate the lists or set CONTRACTSPEC_AI_FALLBACKS=off. Whether a provider listed for one author also hosts another author's chain models cannot be checked here, so such a serve is caught afterwards: servedAiGatewayModel refuses a model reported on a provider outside its own author's list.

Served model

servedAiGatewayModel(route, { routing, responseModelId }) returns the chain model that actually served a call, or undefined:

  • routing is readVercelGatewayRoutingMetadata(result.providerMetadata); it keeps each model attempt's canonicalSlug and success (Gateway model-fallback metadata) and the final provider, nothing else.
  • The served model is the successful last attempt's canonicalSlug, checked against result.response.modelId when that is a creator/model id; a disagreement, a model outside the chain, a failed last attempt, or a final provider outside that model's own provider list returns undefined.
  • A route without fallbacks may omit the model id (only its primary could serve); a route with fallbacks requires it.

Consumers record served.model (not route.model) as the model id of their evidence and fail closed when it is undefined.

Independent generation and critic

generation and critic must have different authors (AI_GATEWAY_INDEPENDENT_ROLE_PAIRS); a profile or override that collapses them fails with AI_CRITIC_NOT_INDEPENDENT. Because the Gateway may serve a generation from its fallback, the critic is chosen from the author that actually served it: servedAiGatewayAuthor(route, { routing, responseModelId }) is the author of servedAiGatewayModel (derived from the served model id, never guessed from the provider alone), and resolveIndependentCriticRoute(critic, author) keeps only critic models by another author. createAiGatewayRoleModel('critic', …) requires independentOf and refuses without it; a caller with an undefined served author refuses the critique.

Default profile switch (D-241)

When CONTRACTSPEC_AI_PROFILE is unset, the anthropic profile becomes the default only after an operator lists every AI_GATEWAY_D241_CONFIRMATION_MODEL_IDS entry (anthropic/claude-haiku-5.5, anthropic/claude-opus-5.5, anthropic/claude-sonnet-5.5) in CONTRACTSPEC_AI_OPERATOR_CONFIRMED_MODELS.

Catalog provenance (D-244): every model the switch introduces is an id of the lib.provider-spec EU catalog. The reasoning-role fallback is openai/gpt-6.1-sol (EU catalog), not the donor engine's openai/gpt-6-sol, which that catalog does not list; AI_GATEWAY_D241_EU_UNLISTED_MODEL_IDS is therefore empty and a test pins that every anthropic profile id is in the EU catalog. The openai rollback profile keeps the donor engine ids (openai/gpt-6-sol for recovery), unchanged since D-226: the focused engine was qualified and priced with them, and their EU-zone availability is its recorded convergence debt. Until then openai stays the default. The resolved profile reports selection (explicit, d241_operator_confirmed or d241_pending_operator_confirmation) and pendingConfirmation. A confirmed role reports operatorConfirmed: true; approval stays the catalog fact, so consumer-specific gates (for example a CV or enrichment confirmation variable) keep their own semantics. Consumers that pass their own environment object only see the switch when they include these variables.

The switch is per process, not one setting for every host. Setting CONTRACTSPEC_AI_OPERATOR_CONFIRMED_MODELS on a host flips only the consumers that read the shared environment there; each has its own gate, which must change in the same deployment or that consumer fails closed:

Host / consumerEffect of the flipCompanion setting
osint-worker public job enrichment (extraction role)Becomes anthropic/claude-haiku-5.5 (operator_confirmation_required); createGatewayEnrichmentModelV1 refuses with model_confirmation_requiredJOB_ENRICHMENT_MODEL_CONFIRMED=anthropic/claude-haiku-5.5 on the same host, or enrichment stops
osint-worker company blurb (summarization role)Becomes anthropic/claude-haiku-5.5 with the openai/gpt-6-luna fallbackNone (no separate gate)
Application effects engine (job-application-effects-engine)Not flipped by the shared variables: it reads every profile switch under its own names (JOB_APPLICATION_FOCUSED_ENGINE_AI_PROFILE, _AI_OPERATOR_CONFIRMED_MODELS, _AI_FALLBACKS, _AI_PROVIDERS_{OPENAI,ANTHROPIC,GEMINI}; AI_GATEWAY_EFFECTS_ENGINE_PROFILE_ENV_V1), because its anthropic profile is unqualified (prices and LIMITS sized for gpt-6-luna, INTEGRATION.md)JOB_APPLICATION_FOCUSED_ENGINE_AI_OPERATOR_CONFIRMED_MODELS (the three ids), only once its owner qualifies the profile
Tafio CV (tafio-web/src/cv/gateway.ts)Flipped with the shared selection: the generation role of the active profile (Anthropic first, OpenAI fallback) and a critic chosen per call from another author than the one that served the generation (servedAiGatewayModel, resolveIndependentCriticRoute)None: a chain model is admitted when catalog-approved, listed in CONTRACTSPEC_AI_OPERATOR_CONFIRMED_MODELS, or repeated in CAREER_CV_GENERATION_MODEL_CONFIRMED / CAREER_CV_CRITIC_MODEL_CONFIRMED
Tafio assistant (tafio-web/src/assistant/gateway.ts)Not tied to the shared selection: its primary route is always the anthropic profile's assistant route, its fallback the catalog OpenAI fallback of the assistant role (openai/gpt-6.1-sol, EU catalog; not the openai profile's donor-only recovery id openai/gpt-6-sol, D-244 item 6)CAREER_ASSISTANT_PRIMARY_MODEL_CONFIRMED=anthropic/claude-sonnet-5.5 admits the Anthropic route (independent of the flip)
Monthly author budget (all of the above, D-244)Only where the shared AI spend ledger is boundCAREER_CV_AI_SPEND_LEDGER=shared, CAREER_ASSISTANT_AI_SPEND_LEDGER=shared, JOB_ENRICHMENT_AI_SPEND_LEDGER=shared, each with the ai_spend migration applied in that host's database

One readiness check reports the gates together, so a partial flip is visible before it stops a consumer: checkAiGatewayFlipReadinessV1({ 'tafio-web': env, 'osint-worker': env, 'job-application-effects-engine': env }) returns flipped, not_flipped, partial or incomplete, and per gate (osint-enrichment, tafio-cv-generation, tafio-cv-critic, effects-engine-profile) the state (flipped, not_flipped, blocked, invalid), the variables still to set and the refused model ids. It reads names, never prints a value, and does no I/O: an operator runs it against each host's explicit environment before and after the flip, with the release script deploy/ai-gateway-flip/readiness.ts --host <host>=<env file> ... (exit 1 on a partial flip). Every host of AI_GATEWAY_FLIP_HOSTS_V1 must be passed or waived with a reason ({ waived: { <host>: '<reason>' } }, CLI --skip-host <host>:<reason>); a host that is neither is listed in unchecked and the state is incomplete (exit 1), so leaving a host out can never report a cross-host partial flip as flipped. The report also lists informational companions (AI_GATEWAY_FLIP_COMPANIONS_V1): the assistant's CAREER_ASSISTANT_PRIMARY_MODEL_CONFIRMED (set/unset) and the three D-244 shared-ledger opt-ins with their choice (or invalid); they never make the flip partial. Rollback: unset CONTRACTSPEC_AI_OPERATOR_CONFIRMED_MODELS (or set CONTRACTSPEC_AI_PROFILE=openai) on the same hosts, then the companion settings.

Budget-driven author fallback (D-241 "then the best model", D-244)

The spend owner (lib.cost-tracking) tracks AI spend per model author and UTC month (Anthropic: 200 USD by default, AI_SPEND_AUTHOR_ANTHROPIC_MONTHLY_MICROUSD) and marks an author exhausted until the month rolls over when the Gateway reports its quota exhausted. The routing owner turns that into routes:

  • promoteAiGatewayRouteForBudget(route, exhaustedAuthors): the role's chain without the exhausted authors; the first remaining model becomes the primary for the call (AI_AUTHOR_BUDGET_EXHAUSTED when none is left).
  • resolveIndependentCriticRoute(critic, generationAuthor, { exhaustedAuthors }): generation and critic stay by different authors; when only the generation's author is left the critic refuses with AI_CRITIC_UNAVAILABLE and never runs on the same author (callers show an honest refusal: Tafio CV ai_budget_month_exhausted).
  • classifyAiGatewayQuotaExhaustion(error, route): HTTP 402 or a structured quota/billing type/code (insufficient_funds, insufficient_quota, billing_error, ...), read through cause/RetryError chains with a bounded body read; never a message. It attributes the route's author only when the route has a single author; a multi-author chain is not guessed (the Gateway's own fallback already tried the other authors).

Per-call and daily caps (D-234) still apply: the promoted route's call is reserved in the spend port like any other. Reusing contracts-runtime-server-rest's ai-cost-guard is documented in the lib.cost-tracking README (it does not fit the shared port).

resolveAiGatewayProfile(env?, { auth?, request? }) validates everything and fails closed with AiGatewayProfileError (AI_PROFILE_UNKNOWN, AI_MODEL_OVERRIDE_INVALID, AI_INFERENCE_PROVIDERS_INVALID, AI_GATEWAY_CREDENTIAL_MISSING, AI_FALLBACKS_INVALID, AI_OPERATOR_CONFIRMATION_INVALID, AI_CRITIC_NOT_INDEPENDENT; AI_AUTHOR_BUDGET_EXHAUSTED and AI_CRITIC_UNAVAILABLE come from the budget helpers); errors name variables, never values.

Enrichment/scraping consumers use ./ai-gateway-profile-model:

ts
import { createAiGatewayRoleModelResolver } from '@lssm-tech/lib.ai-providers/ai-gateway-profile-model';
import { generateText } from 'ai';

const modelFor = createAiGatewayRoleModelResolver(); // resolve once at boot
const { model, route } = modelFor('extraction');
const result = await generateText({ model, prompt });
// record route.model / route.approval with your own cost evidence

The returned model is createVercelGatewayModel with the shared EU-zone, ZDR and no-training policy, so callers must not pass providerOptions.gateway. Hosts that pin their own AI SDK (the focused application engine) consume the resolved profile's model ids and inferenceProviders instead of the model object.

inferenceProviders holds the Gateway only list for every model author, whatever the active profile. A consumer that persists a model id (queued, retried or repeated work) must route each call by the author of the model it actually calls, not by the active profile, so a profile switch or rollback cannot send an openai/* model with an Anthropic-only restriction.

Relationships

THIS PACKAGElib.ai-providers27 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

13 declarations

  • @ai-sdk/anthropic

    catalog:ai

  • @ai-sdk/google

    catalog:ai

  • @ai-sdk/mistral

    catalog:ai

  • @ai-sdk/openai

    catalog:ai

  • @lssm-tech/lib.provider-ranking
  • ai

    catalog:ai

Declared capabilities

Lib Ai Providers

Unified AI provider abstraction layer

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../../scripts/biome.cjs check .
  • testbun test --pass-with-no-tests
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit