@verevoir/llm

Provider-agnostic LLM call surface with token + cost accounting. The core export holds the contract and shared types; provider SDK adapters live in subpaths so consumers only pay for the SDK they actually use.

Status

0.1.0 — first deliberate release. Pre-stable: the 0.x line communicates that the API surface can shift before 1.0. Bumps to 1.0 follow validation by the first real consumer.

Install

npm install @verevoir/llm @anthropic-ai/sdk

Each provider SDK is an optional peer dependency — install only the SDK(s) that match the subpath(s) you import.

Quickstart (Anthropic)

import { anthropic } from '@verevoir/llm/anthropic';

const reply = await anthropic.chat({
  systemPrompt: 'You are a helpful assistant.',
  turns: [{ role: 'user', content: 'Hello' }],
  apiKey: process.env.ANTHROPIC_API_KEY!,
  modelClass: 'reasoning',
});

console.log(reply.content);
// reply.usage → { provider, model, direction, inputTokens, outputTokens, ... }

Why subpaths

The core export (@verevoir/llm) carries provider-agnostic types — TokenUsage, PerModelUsage, ModelClass, the chat() contract, cost-accounting helpers. Each adapter lives under its own subpath so the unused provider SDK never enters the consumer's bundle:

| Subpath | SDK dep | Status | | ------------------------- | ------------------- | ----------------------- | | @verevoir/llm | none | shipped | | @verevoir/llm/anthropic | @anthropic-ai/sdk | shipped | | @verevoir/llm/google | @google/genai | chat() only (0.4.0) | | @verevoir/llm/openai | openai | chat() only (0.5.0) | | @verevoir/llm/deepseek | openai | chat() only (0.6.0) |

Multi-provider deployments depend on the same chat() contract; consumers switch backends by importing a different subpath, not by changing call sites.

Cost accounting

Every call returns a TokenUsage shaped as { provider, model, direction, inputTokens, outputTokens, ... }. The package exports sumUsages, formatTokensCompact, and a per-model rate table so per-conversation / per-project rollups need no external lookups. The direction field tracks the model-class semantic (reasoning / extraction) so rollups can break down "spent X on reasoning + Y on extraction" natively.

See also

• llms.txt — LLM-agent-facing description of this package.
• CHANGELOG.md — release history.
• examples/ — runnable usage examples per subpath (land with the extraction slice).

License

Apache-2.0 — see LICENSE.