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.
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:
aliasMapalways wins:{ "venom-default": "qwen3:8b", "venom-fast": "qwen3:4b" }. The request'smodelfield 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 forVENOM_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.
Related
- Sessions, events and cost
- Subagents and model tiers
- Orchestrator section and Venom Cloud section, for the servers that serve the aliases