Skip to content
Docs menu

Model provider

Point harness sessions at any OpenAI-compatible server, map venom's model aliases to real models, and understand the provider's errors and model discovery.

View .md

Sessions talk to one OpenAI-compatible chat-completions server through venom's provider. That can be the venom orchestrator, Venom Cloud, vLLM, SGLang, llama.cpp, Ollama, LM Studio, or a hosted provider's OpenAI endpoint. @venom/harness/provider holds the pure parts (options, discovery, prices, error text); the root entry wires them into sessions.

Configure it

import { createHarness, provider } from "@venom/harness";

// From an environment map you choose to pass:
const fromEnv = provider.providerOptionsFromEnv(process.env);

// Or explicitly:
const harness = createHarness({
  provider: {
    baseUrl: "https://cloud.usevenom.dev/v1",
    apiKey: process.env.MYAPP_VENOM_KEY,    // a vck_… key; never log it
    defaultModel: "venom-default",
  },
});
Option Env var (providerOptionsFromEnv) Default Meaning
baseUrl VENOM_BASE_URL http://localhost:8787/v1 the server, including /v1
apiKey VENOM_API_KEY none (no Authorization header) bearer key
defaultModel VENOM_MODEL venom-default model when a session names none
aliasMap VENOM_ALIAS_MAP (venom-default=gpt-5.4-mini,venom-fast=…) automatic, see below rewrite venom aliases to the server's model ids
contextWindow VENOM_CONTEXT_WINDOW the server's report, else 131072 a cap: each model gets min(server window, contextWindow)
maxTokensField VENOM_MAX_TOKENS_FIELD max_completion_tokens which request field carries the output limit
adminToken VENOM_ADMIN_TOKEN none the orchestrator's admin token: /cost reads the orchestrator's figures for the session
visionModel VENOM_VISION_MODEL venom-vision describes images for a text-only model
maxTokens 16384 max output tokens
discover true fetch GET /v1/models in the background
discoveryTimeoutMs 2500 discovery timeout
cachePath under venomHome where discovered model ids are cached
preflightTimeoutMs 3000 the reachability check before a session's first request
notice stderr where one-line notices go without a UI
fetch global fetch inject a transport (tests, a proxy)

Pass provider: false to register no venom provider at all (when your app brings its own pi provider).

Model aliases

Venom names models by role: venom-default (the session), venom-fast (cheap reads, summaries, the explorer subagent), venom-smart (hard problems), venom-vision, venom-decide. The orchestrator and Venom Cloud serve these aliases. Against a server that does not:

  • aliasMap always wins: { "venom-default": "qwen3:8b", "venom-fast": "qwen3:4b" }. The request's model field is rewritten; the session still shows the alias.
  • Without one, a server that lists no venom-* id gets an automatic mapping: api.openai.com maps to its current small, nano and large models; a server with one model maps all three to it; otherwise models are ranked by the parameter count in their ids. With more than 12 models or nothing to rank by, nothing is mapped and a notice asks for VENOM_ALIAS_MAP.

Model discovery

The provider lists GET /v1/models once (cached), drops non-chat models (embeddings, TTS, transcription, moderation, image generation, rerankers), and records per model whether it accepts images and its context window. provider.fetchModels, fetchModelIds, supportsImages and isChatModelId expose the same logic; modelCostFor and pricedModelFor give the bundled list price used for cost estimates.

Headers venom sends

Header From Purpose
Authorization: Bearer … apiKey auth
x-venom-profile HarnessOptions.routeProfile an orchestrator route profile
x-venom-gear HarnessOptions.gear a Venom Cloud gear, so spend counts toward its budget
x-venom-experiment HarnessOptions.experiment a gear experiment arm (<id>; arm=a)

Subagents inherit all three. None of them enters the prompt.

Errors

The provider rewrites the common failures into one message that names the setting to fix:

Situation What the session reports
Server unreachable before the first request fails at once, naming VENOM_BASE_URL and venom doctor (no retry storm)
A transport failure later re-checks the server: still down, the same message; back up, pi retries
401 or 403 a line naming VENOM_API_KEY; a 403 model_not_allowed says the key is valid but restricted
404 naming a model the list of models the server does serve
429 with a reset time a long task waits for the reset and continues (long tasks)
429 spend_limit_reached from Venom Cloud not retried; names the gear whose budget ran out

provider.classifyFetchError, httpErrorMessages and isPermanentLimit give the same classification to your own code.