2026-11-21 · engineering · Ubinity
One Calling Contract for Every LLM Provider — By API Key or Subscription (@ubinity/node-llm v2.3)
Why we built @ubinity/node-llm around a strict calling contract (CONTRACT_VERSION) supporting OpenAI, DeepSeek, Qwen, Ollama, Anthropic, Gemini, and official subscription CLIs with zero silent parameter drops.
When building multi-provider AI tooling in Node.js, most teams quickly hit two painful traps:
- Wrapper Bloat & Drift: Giant orchestration frameworks pull in dozens of transitive dependencies and silently swallow unsupported options (
temperature,tools,cache) when switching between OpenAI, Anthropic, Gemini, DeepSeek, Qwen, or Ollama. - Subscription vs. API Key Friction: Individual developers and internal automation pipelines often already pay for Claude Pro/Max, ChatGPT Plus/Pro, or Antigravity subscriptions, yet provider terms forbid scraping session tokens directly into third-party HTTP wrappers.
Designing a Strict Calling Contract (CONTRACT_VERSION)
We built @ubinity/node-llm (v2.3.1, MPL-2.0, Node.js >= 22) around a single invariant: one request shape, one normalized OpenAI-compatible response shape, and one typed NodeLlmError — regardless of which provider answers.
Key Architectural Decisions
- Optional Peer Dependencies: Install only the official SDKs you actually call (
openai,@anthropic-ai/sdk,@google/genai). Subscription-only users need zero provider SDKs. - Sanctioned Subscription Execution (
auth: 'subscription'): Instead of violating Terms of Service with unofficial token extraction,@ubinity/node-llmexecutes the provider’s own official CLI headless (claude,codex,agy) in an empty temporary directory with every API-key environment variable explicitly stripped so a subscription call can never accidentally bill an API account. It also supports invoking WSL-installed clients cleanly from Windows. - Fail Fast on Unsupported Parameters: If a caller passes
tools,temperature,stream: true, or an unsupportedcache.ttlwhere the backend cannot honor it,@ubinity/node-llmrejects withNodeLlmError(code: 'unsupported') instead of quietly dropping the option. - Unified Reasoning
effort& Prompt Caching: Maps'low','medium','high','max', or{ native }cleanly across providers, while exposingcache_read_tokens,cache_creation_tokens, andreasoning_tokensin normalizedusagewithout ever guessing0when unreported.
const { completion } = require('@ubinity/node-llm');
const reply = await completion({
model: 'anthropic/claude-haiku-4-5',
auth: 'subscription',
timeout: 120000,
messages: [
{ role: 'system', content: 'Answer in one concise sentence.' },
{ role: 'user', content: 'Why should an LLM router fail fast on unsupported options?' },
],
});
console.log(reply.auth, reply.choices[0].message.content);
Explore the Source
Read the overview page or inspect the full contract and conformance test suite on GitHub.