Ubinity
← Back to Blog
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:

  1. 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.
  2. 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-llm executes 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 unsupported cache.ttl where the backend cannot honor it, @ubinity/node-llm rejects with NodeLlmError (code: 'unsupported') instead of quietly dropping the option.
  • Unified Reasoning effort & Prompt Caching: Maps 'low', 'medium', 'high', 'max', or { native } cleanly across providers, while exposing cache_read_tokens, cache_creation_tokens, and reasoning_tokens in normalized usage without ever guessing 0 when 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.