lib.ai-providers

@lssm-tech/lib.ai-providers

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.

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.