Import
import {
clearModelProviders,
ensureModelReady,
getRegisteredModelProviders,
hasModelProvider,
registerModelProvider,
resolveModel,
} from "veryfront/provider";
Examples
Resolve a model
import { resolveModel } from "veryfront/provider";
const model = resolveModel("veryfront-cloud/openai/gpt-5-nano");
API
registerModelProvider(name, factory)
Register a custom model provider factory for the active project scope or application bootstrap.
Returns: ModelProviderRegistrationDisposer
resolveModel(modelString)
Resolve a “provider/model” string to a framework-compatible model runtime.
Returns: ModelRuntime
hasModelProvider(name)
Check whether a model provider is available in the current scope.
Returns: boolean
getRegisteredModelProviders()
Get provider names available in the current scope.
Returns: string[]
clearModelProviders()
Clear all registered model providers and reset lazy built-ins (for testing).
Returns: void
Exports
Components
| Name | Description | Source |
|---|---|---|
DEFAULT_VERYFRONT_CLOUD_MODEL_ID | Short ID of the built-in default model, used when no model is configured and the served catalog has not been loaded. | source |
VERYFRONT_CLOUD_CHAT_MODELS | Chat models shipped with this package. | source |
VERYFRONT_CLOUD_MODEL_PREFIX | Shared Veryfront Cloud model prefix value. | source |
Functions
| Name | Description | Source |
|---|---|---|
clearModelProviders | Clear all registered model providers and reset lazy built-ins (for testing). | source |
ensureModelReady | Eagerly verify that the resolved model’s runtime is available. | source |
findVeryfrontCloudModel | Find a shipped chat model by its short id. | source |
findVeryfrontCloudModelByModelId | Find a shipped chat model by its provider-qualified id, in any provider spelling. | source |
getRegisteredModelProviders | Get provider names available in the current scope. | source |
getVeryfrontCloudProviderFromModelId | Return the Veryfront Cloud provider named by a model ID, including a provider this package does not list. | source |
groupVeryfrontCloudModelsByProvider | Group the shipped chat models by provider, in display order. | source |
hasModelProvider | Check whether a model provider is available in the current scope. | source |
loadVeryfrontCloudModelCatalog | Load the model catalog Veryfront Cloud serves, with the Veryfront Cloud credentials and project in effect, so model facts read synchronously afterward (thinking defaults, short aliases such as opus, the default model) come from it. Resolves to whether a catalog is available. Never throws. When a refresh fails, the last catalog loaded for these credentials stays in use; only when none has loaded (no credentials, or no load has succeeded yet) do the facts shipped with this package apply. | source |
normalizeVeryfrontCloudModelId | Normalizes Veryfront Cloud model ID. | source |
registerModelProvider | Register a custom model provider factory for the active project scope or application bootstrap. | source |
resolveModel | Resolve a “provider/model” string to a framework-compatible model runtime. | source |
resolveVeryfrontCloudDefaultModelId | Provider-qualified ID of the default model: the one the served catalog names once it is loaded, otherwise the built-in default. | source |
resolveVeryfrontCloudGatewayModelId | Prefix a model ID so it resolves through the Veryfront Cloud gateway, including a provider this package does not list. | source |
resolveVeryfrontCloudModelId | Resolve a model ID or short alias to a provider-qualified model ID. | source |
resolveVeryfrontCloudModelThinking | Resolves Veryfront Cloud model thinking. | source |
resolveVeryfrontCloudReasoningOption | Resolves provider-neutral runtime reasoning for a Veryfront Cloud model. | source |
resolveVeryfrontCloudThinkingProviderOptions | Options accepted by resolve Veryfront Cloud thinking provider. | source |
tryGetVeryfrontCloudProviderFromModelId | Return the Veryfront Cloud provider named by a model ID, including one this package does not list, or undefined when the ID names none. | source |
Types
| Name | Description | Source |
|---|---|---|
ModelProviderFactory | Public API contract for model provider factory. | source |
ModelProviderRegistrationDisposer | source | |
ModelRuntime | Public API contract for model runtime. | source |
VeryfrontCloudChatModel | Public API contract for Veryfront Cloud chat model. | source |
VeryfrontCloudModelId | A provider-qualified Veryfront Cloud model ID, for example anthropic/claude-sonnet-4-6. Any provider and model the platform serves fits, so a new model needs no release of this package. | source |
VeryfrontCloudModelThinkingConfig | Configuration used by Veryfront Cloud model thinking. | source |
VeryfrontCloudProviderId | A Veryfront Cloud provider ID: a listed provider, or any other well-formed provider string. | source |
VeryfrontCloudRuntimeModelId | A model ID routed through Veryfront Cloud: veryfront-cloud/<provider>/<model>. | source |
Constants
| Name | Description | Source |
|---|---|---|
resolveHostedVeryfrontCloudModelId | Prefix a model ID for a hosted run. Alias of resolveVeryfrontCloudGatewayModelId, with the same contract: call it only once Veryfront Cloud is the chosen backend, because it prefixes ANY well-formed provider segment, including providers this package does not list. Read that function’s documentation before calling this one. | source |
Deep imports
These import paths group focused functionality under this module. Each is a separate barrel; import only what you need.veryfront/provider/openai-reasoning
import {
getDefaultOpenAIReasoningEffort,
isOpenAIReasoningModel,
rejectsOpenAISamplingParams,
} from "veryfront/provider/openai-reasoning";
Functions
Types
veryfront/provider/shared
Shared plumbing consumed by the @veryfront/ext-* provider extensions. This barrel is the stable extension-facing surface. Implementations remain internal to runtime-loader.ts and runtime-loader/; their physical location may change without changing extension imports.
import {
buildProviderError,
createAnthropicRequestInit,
createGoogleRequestInit,
} from "veryfront/provider/shared";
Components
| Name | Description | Source |
|---|---|---|
DEFAULT_PROVIDER_STREAM_HEADERS_TIMEOUT_MS | Default deadline for one stream attempt to return response headers. | source |
DEFAULT_PROVIDER_STREAM_IDLE_TIMEOUT_MS | Default deadline for the next chunk of a stream response body. | source |
DEFAULT_PROVIDER_STREAM_TOTAL_HEADERS_BUDGET_MS | Ceiling on the wall time replays may spend waiting for stream response headers. | source |
MAX_PROVIDER_SSE_BUFFER_CODE_UNITS | Maximum decoded provider SSE data retained or parsed in one pass. | source |
STREAM_FRAGMENT_COMPACTION_SIZE | Fragments joined into one string at a time, bounding array growth. | source |
TOOL_INPUT_PENDING_THRESHOLD_MS | Shared tool input pending threshold ms value. | source |
VERYFRONT_PROVIDER_STREAM_IDLE_TIMEOUT_ENV | Environment key overriding the stream body idle deadline, in milliseconds. | source |
Functions
| Name | Description | Source |
|---|---|---|
buildProviderError | Inspect a non-2xx response and build the most specific ProviderError subclass we can. Reads the response body as text (it’s already dead on the wire by this point). Body classification handles the cases where HTTP status alone is ambiguous - notably OpenAI insufficient_quota vs rate_limit_exceeded both arriving as 429. | source |
createAnthropicRequestInit | Create Anthropic request init. | source |
createGoogleRequestInit | Create Google request init. | source |
createOpenAIRequestInit | Create request init options for OpenAI-compatible providers. | source |
createStreamRetentionBudget | Create an empty retention budget. | source |
createWarningCollector | Create warning collector. | source |
getAnthropicMessagesUrl | Return Anthropic messages URL. | source |
getGoogleEmbeddingUrl | Return Google embedding URL. | source |
getGoogleGenerateContentUrl | Return Google generate content URL. | source |
getGoogleStreamGenerateContentUrl | Return Google stream generate content URL. | source |
getOpenAIChatCompletionsUrl | Return OpenAI chat completions URL. | source |
getOpenAIEmbeddingUrl | Return OpenAI embedding URL. | source |
getOpenAIResponsesUrl | Return OpenAI responses URL. | source |
isNumberArray | Check whether a value is an array of numbers. | source |
isProxyWithoutHooks | Identify a Proxy without evaluating any trap on the proxied value. | source |
jsonValuesEqual | Compare JSON-compatible values independently of object key order. | source |
mergeUsage | Merge provider usage counters. | source |
notifyProviderRequestRetry | Report a provider request retry to the debug log and to the active observer. An observer that throws, or whose promise rejects, never affects the request. | source |
parseFinalSseChunk | Parse the final unterminated SSE block without making the synthetic frame delimiter count against the caller-visible retention boundary. | source |
parseRetryAfterMs | Parses retry after ms. | source |
parseSseChunk | Parse a bounded provider SSE buffer. | source |
readGatewayBillingMode | Read a trusted gateway billing mode from provider metadata. | source |
readGatewayUsageCosts | Read the cost and credit amounts of a gateway veryfront usage envelope. | source |
readProviderOptions | Options accepted by read provider. | source |
readRecord | Record shape for read. | source |
readTextParts | Read text content parts from provider messages. | source |
requestJson | Request and parse a bounded JSON response. | source |
requestStream | Request a streaming response. When the request body is replayable, typed retryable failures are retried up to two times before provider output is exposed. Each attempt gets a fresh stream header deadline, and replays are capped so the whole header wait stays inside one shared budget. ReadableStream request bodies are not retried because fetch can consume them on the first attempt. | source |
reserveStreamRetention | Reserve room for one streamed fragment. Returns the exceeded limit without changing the budget, or undefined once the fragment is accounted for. | source |
snapshotJsonValue | Create a bounded, deeply owned, accessor-free snapshot of a JSON value. | source |
snapshotProviderJsonValue | Create the provider-boundary snapshot used by request builders. | source |
stringifyJsonValue | Serialize a JSON-compatible value. | source |
stringifyToolArguments | Preserve provider-native argument text while serializing structured tool inputs. | source |
stringifyToolResultValue | Preserve text tool results while serializing structured tool results. | source |
toOpenAICompatibleMessages | Convert runtime prompt messages into OpenAI-compatible chat messages. Adjacent non-empty system layers become one ordered instruction so strict Chat Completions providers receive a compatible message sequence. A verified transport capability can preserve the original system message boundaries. | source |
toOpenAICompatibleTools | Convert runtime tool definitions into OpenAI-compatible function tools. | source |
unwrapToolInputSchema | Zod schema for unwrap tool input. | source |
waitForProviderStreamRetry | Wait out a retry delay, rejecting the moment the caller cancels. Shared with providers that must replay a request the SSE body failed, so every retry path honors cancellation the same way. | source |
withToolInputStatusTransitions | Applies tool input status transitions. | source |
Classes
| Name | Description | Source |
|---|---|---|
ProviderError | Base class for typed provider errors. The retryable flag is the primary signal for callers (or a retry wrapper) to decide whether to re-issue the request. retryAfterMs is set when the provider gave an explicit delay hint (Retry-After header, Retry-Info trailer). | source |
ProviderOutputTruncatedError | Provider stopped generating at the output token limit, leaving the response incomplete (for example a tool_use block whose input JSON never closed). | source |
ProviderOverloadedError | Provider reports it is overloaded (Anthropic 529, OpenAI/Google 503). | source |
ProviderQuotaError | Provider account quota is exhausted - non-retryable. | source |
ProviderRateLimitError | Provider is rate limiting this API key (OpenAI/Google 429 with Retry-After). | source |
ProviderRequestError | Non-retryable 4xx/5xx that doesn’t fit another bucket. | source |
StreamFragmentBuffer | Accumulates streamed string fragments with storage proportional to their content rather than to how many fragments the provider sent. Every STREAM_FRAGMENT_COMPACTION_SIZE fragments are joined into one string, so millions of one-byte deltas do not become millions of array entries. | source |
Types
| Name | Description | Source |
|---|---|---|
JsonSnapshotOptions | Resource limits applied while taking a provider-boundary JSON snapshot. | source |
JsonSnapshotValue | A deeply owned JSON value returned by snapshotJsonValue. | source |
ModelRuntimeCallOptions | Canonical request contract passed to ModelRuntime generation hooks. | source |
ModelRuntimePromptMessage | Immutable prompt view accepted by model-runtime calls. | source |
ModelRuntimeToolDefinition | Canonical tool definition sent to a model runtime. | source |
OpenAICompatibleChatMessage | Message shape for OpenAI-compatible chat requests. | source |
OpenAICompatibleChatRequest | Request payload for OpenAI-compatible chat completion providers. | source |
ProviderWarning | Structured warning emitted when a provider runtime drops or rewrites a caller-provided option. Mirrors the AI ecosystem convention (Vercel AI SDK, LangChain) of returning unsupported-setting warnings on the runtime result so callers can discover silently-dropped fields without having to read the source. | source |
RuntimeAssistantContentPart | Canonical assistant content accepted when invoking a model runtime. | source |
RuntimePromptMessage | Historical mutable provider-facing prompt contract retained for source compatibility. | source |
RuntimeReasoningOption | Provider-neutral reasoning controls accepted by model runtimes. | source |
RuntimeResponseFormat | Provider-neutral structured-output request. | source |
RuntimeUsage | Canonical provider-neutral usage reported by text-generation runtimes. | source |
StreamRetentionBudget | Running totals for one retention budget. Create with createStreamRetentionBudget. | source |
StreamRetentionLimits | Retention bounds for content a provider stream adapter keeps while it assembles a response: tool-call arguments, and raw text or reasoning kept for replay. | source |
StreamRetentionOverflow | Which limit a fragment would exceed. | source |
Constants
| Name | Description | Source |
|---|---|---|
canIdentifyProxyWithoutHooks | Whether this runtime can distinguish Proxy values without evaluating a trap. Callers that need a fail-closed guarantee must not treat a false result from isProxyWithoutHooks as proof when this capability is absent. | source |
veryfront/provider/types
import type {
EmbeddingRuntime,
ModelRuntime,
ModelRuntimeCallOptions,
} from "veryfront/provider/types";
Types
| Name | Description | Source |
|---|---|---|
EmbeddingRuntime | source | |
ModelRuntime | Public API contract for model runtime. | source |
ModelRuntimeCallOptions | Canonical request contract passed to ModelRuntime generation hooks. | source |
ModelRuntimeCapabilities | Explicit behavioral support advertised by a model runtime. | source |
ModelRuntimeGenerateResult | source | |
ModelRuntimePromptMessage | Immutable prompt view accepted by model-runtime calls. | source |
ModelRuntimeStreamResult | source | |
ModelRuntimeToolDefinition | Canonical tool definition sent to a model runtime. | source |
RuntimeAssistantContentPart | Canonical assistant content accepted when invoking a model runtime. | source |
RuntimeMetadata | source | |
RuntimePromptMessage | Historical mutable provider-facing prompt contract retained for source compatibility. | source |
RuntimeReasoningOption | Provider-neutral reasoning controls accepted by model runtimes. | source |
RuntimeResponseFormat | Provider-neutral structured-output request. | source |
RuntimeStructuredOutputVariant | source |