# @clinebot/llms

> Config-driven SDK for selecting, extending, and instantiating LLM providers and models

Latest version **0.0.38** (published 2026-05-05) · 0 weekly downloads

## Install

```sh
npm install @clinebot/llms
pnpm add @clinebot/llms
yarn add @clinebot/llms
bun add @clinebot/llms
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.38 |
| Published | 2026-05-05 |
| First published | 2026-03-18 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 21 |
| Unpacked size | 1.6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | johnsimbot, saoudcline, beatrix-cline, barreirot, maxpaulus, arakhan |

## Links

- npm: https://www.npmjs.com/package/@clinebot/llms
- Repository: https://github.com/cline/sdk-wip
- npm.io page: https://npm.io/package/@clinebot/llms

## Dependencies (21)

- [ai](https://npm.io/package/ai.md) ^6.0.144
- [zod](https://npm.io/package/zod.md) ^4.3.6
- [nanoid](https://npm.io/package/nanoid.md) ^5.1.7
- [@ai-sdk/google](https://npm.io/package/@ai-sdk/google.md) ^3.0.60
- [@ai-sdk/openai](https://npm.io/package/@ai-sdk/openai.md) ^3.0.52
- [@langfuse/otel](https://npm.io/package/@langfuse/otel.md) ^4.0.0
- [@ai-sdk/mistral](https://npm.io/package/@ai-sdk/mistral.md) ^3.0.28
- [@ai-sdk/provider](https://npm.io/package/@ai-sdk/provider.md) ^3.0.8
- [@clinebot/shared](https://npm.io/package/@clinebot/shared.md) 0.0.38
- [dify-ai-provider](https://npm.io/package/dify-ai-provider.md) ^1.1.0
- [@ai-sdk/anthropic](https://npm.io/package/@ai-sdk/anthropic.md) ^3.0.68
- [@opentelemetry/api](https://npm.io/package/@opentelemetry/api.md) ^1.9.0
- [@streamparser/json](https://npm.io/package/@streamparser/json.md) ^0.0.21
- [@ai-sdk/google-vertex](https://npm.io/package/@ai-sdk/google-vertex.md) ^4.0.100
- [@ai-sdk/amazon-bedrock](https://npm.io/package/@ai-sdk/amazon-bedrock.md) ^4.0.89
- [@ai-sdk/openai-compatible](https://npm.io/package/@ai-sdk/openai-compatible.md) ^2.0.38
- [ai-sdk-provider-codex-cli](https://npm.io/package/ai-sdk-provider-codex-cli.md) ^1.1.0
- [ai-sdk-provider-claude-code](https://npm.io/package/ai-sdk-provider-claude-code.md) ^3.4.3
- [ai-sdk-provider-opencode-sdk](https://npm.io/package/ai-sdk-provider-opencode-sdk.md) ^3.0.1
- [@aws-sdk/credential-providers](https://npm.io/package/@aws-sdk/credential-providers.md) ^3.922.0
- [@opentelemetry/sdk-trace-node](https://npm.io/package/@opentelemetry/sdk-trace-node.md) ^2.6.1

## Recent versions

- 0.0.38 (latest) — 2026-05-05
- 0.0.38-nightly.1778038008 (nightly) — 2026-05-06
- 0.0.37-nightly.1777950585 — 2026-05-05
- 0.0.37-nightly.1777940884 — 2026-05-05
- 0.0.37-nightly.1777939956 — 2026-05-05
- 0.0.37 — 2026-04-28
- 0.0.36 — 2026-04-22
- 0.0.35 — 2026-04-21
- 0.0.34 — 2026-04-14
- 0.0.33 — 2026-04-12
- 0.0.32 — 2026-04-11
- 0.0.31 — 2026-04-11
- 0.0.30 — 2026-04-11
- 0.0.29 — 2026-04-10
- 0.0.28 — 2026-04-03
- … 24 more at https://npm.io/package/@clinebot/llms/versions

## README

# [experimental] @clinebot/llms

`@clinebot/llms` is the model and provider layer for the Cline SDK. It gives
you typed provider settings, model catalogs, shared gateway contracts, and
AI SDK-backed handler creation for supported LLM backends.

## What You Get

- `@clinebot/llms/runtime` for declarative config and runtime registry creation
- `@clinebot/llms/providers` for handler creation and provider settings/types
- `@clinebot/llms/models` for model catalogs and query helpers
- `@clinebot/llms` root exports for the gateway registry and shared llm contracts

## Installation

```bash
npm install @clinebot/llms zod
```

## Quick Start

```ts
import { createHandler } from "@clinebot/llms";

const handler = createHandler({
	providerId: "anthropic",
	apiKey: process.env.ANTHROPIC_API_KEY ?? "",
	modelId: "claude-sonnet-4-6",
});

for await (const chunk of handler.createMessage("You are a concise assistant.", [
	{ role: "user", content: [{ type: "text", text: "Say hello." }] },
])) {
	console.log(chunk);
}
```

## Main APIs

### Runtime

Use `createLlmsRuntime(...)` when you want a small registry around:

- configured providers and their default models
- builtin provider discovery via `getBuiltInProviders()`
- custom provider registration via `registerBuiltinProvider(...)`
- handler creation for builtin or custom providers

Preferred import:

```ts
import { createLlmsRuntime, defineLlmsConfig } from "@clinebot/llms/runtime";
```

### Providers

Use `@clinebot/llms/providers` for:

- `createHandler(...)` and `createHandlerAsync(...)`
- `ProviderSettings` and `ProviderSettingsSchema`
- `ProviderConfig`
- `Message` and `ApiStreamChunk`

Built-in providers are routed through the internal gateway registry and backed by
AI SDK provider implementations. Shared gateway contracts are exported from both
`@clinebot/llms` and `@clinebot/shared`.

### Models

Use `@clinebot/llms/models` when you need generated provider/model metadata for
selection UIs, defaults, or validation.

## Entry Points

- `@clinebot/llms`: runtime-focused convenience entrypoint
- `@clinebot/llms/node`: explicit Node/runtime entrypoint
- `@clinebot/llms/browser`: browser-safe bundle
- `@clinebot/llms/runtime`: focused runtime entrypoint
- `@clinebot/llms/models`: model catalog/query entrypoint
- `@clinebot/llms/providers`: provider handler/settings entrypoint

## Related Packages

- `@clinebot/agents`: agent loop and tool execution
- `@clinebot/core`: stateful runtime assembly and provider settings storage

## More Examples

- Workspace overview: [README.md](https://github.com/cline/cline/blob/main/README.md)
- API and architecture references: [DOC.md](https://github.com/cline/cline/blob/main/DOC.md), [ARCHITECTURE.md](https://github.com/cline/cline/blob/main/ARCHITECTURE.md)

## Live Provider Smoke Test

Use this for API-key-backed provider validation against real endpoints.

1. Ensure provider keys are present in your environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `CLINE_API_KEY`, etc.).
2. Use the sample config at `packages/llms/scripts/live-providers.example.json` as the providers list.
3. Run:

```bash
LLMS_LIVE_TESTS=1 \
LLMS_LIVE_PROVIDERS_PATH=/absolute/path/to/packages/llms/scripts/live-providers.example.json \
bun -F @clinebot/llms run test:live
```

Reasoning-focused live run (same command, different flags):

```bash
LLMS_LIVE_REASONING_TESTS=1 \
LLMS_LIVE_REASONING_PROVIDERS_PATH=/absolute/path/to/packages/llms/scripts/live-providers.reasoning.example.json \
bun -F @clinebot/llms run test:live
```

Tool-use-focused live run (same command, different flags):

```bash
LLMS_LIVE_TOOL_TESTS=1 \
LLMS_LIVE_TOOL_PROVIDERS_PATH=/absolute/path/to/packages/llms/scripts/live-providers.tools.example.json \
bun -F @clinebot/llms run test:live
```

Optional:

- `LLMS_LIVE_PROVIDER_TIMEOUT_MS=120000` to increase per-provider timeout.
- `LLMS_LIVE_PROVIDER_RETRIES=2` to retry transient upstream/provider failures per provider (total attempts = retries + 1).
- Point `LLMS_LIVE_PROVIDERS_PATH` to a custom file if you want a narrower provider set.
- Point `LLMS_LIVE_REASONING_PROVIDERS_PATH` to a custom file for reasoning-enabled suites.
- Point `LLMS_LIVE_TOOL_PROVIDERS_PATH` to a custom file for tool-use suites.

Per-provider live assertions are configured in the JSON via `expectations`:

- `requireUsage`: fail if no `usage` chunk is emitted (defaults to `true`; set to `false` to opt out).
- `requireCacheReadTokens`: fail unless `cacheReadTokens > 0` (auto-runs at least 2 attempts with a long cache probe prompt if no prompt override is provided).
- `minCacheReadTokens`: stricter cache floor check.
- `requireReasoningChunk`: fail unless at least one reasoning chunk is emitted.
- `requireNoReasoningChunk`: fail if any reasoning chunk is emitted.
- `minInputTokens` / `minOutputTokens`: enforce lower bounds.
- `requireToolCall`: fail unless at least one `tool_calls` chunk is emitted.

In reasoning suites, set `requireReasoningSignal: true` to require either a reasoning chunk or `thoughtsTokenCount > 0` (provider-dependent; can be flaky on some endpoints).
To check that disabling reasoning actually suppresses reasoning output across models, use `packages/llms/scripts/live-providers.reasoning-disabled.example.json`; it covers direct and routed provider paths across `cline`, `openai`, `openrouter`, `anthropic`, `gemini`, `vercel-ai-gateway`, `zai`, and `deepseek` where model support exists, with `reasoning.enabled: false` and `requireNoReasoningChunk: true`.

Common live failure classes:

- `Overloaded`: provider/model capacity issue or transient upstream saturation.
- `Insufficient Balance`: the provider account needs funds.
- `Model Not Exist`: the model id is not available for that provider/account.
- assertion failures such as `expected no reasoning chunks`: likely real SDK/provider-option behavior regressions.

### Adding A Model To Live Tests

Add a new entry under the `providers` object in either config file:

- Cache/smoke suite: `packages/llms/scripts/live-providers.example.json`
- Reasoning suite: `packages/llms/scripts/live-providers.reasoning.example.json`
- Reasoning-disabled suite (asserts no reasoning chunks when reasoning is off): `packages/llms/scripts/live-providers.reasoning-disabled.example.json`
- Tool-use suite: `packages/llms/scripts/live-providers.tools.example.json`

Minimal smoke/cache entry:

```json
"my-openai-model": {
  "settings": {
    "provider": "openai",
    "model": "gpt-5.4"
  },
  "expectations": {
    "requireUsage": true
  }
}
```

Cache-asserted entry (auto-enforces multi-run cache probe):

```json
"my-cache-model": {
  "settings": {
    "provider": "openai",
    "model": "gpt-5.4"
  },
  "expectations": {
    "requireUsage": true,
    "requireCacheReadTokens": true
  }
}
```

Reasoning entry:

```json
"my-reasoning-model": {
  "settings": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "reasoning": {
      "effort": "high"
    }
  },
  "expectations": {
    "requireUsage": true,
    "requireReasoningChunk": true
  }
}
```

Tool-use entry:

```json
"my-tools-model": {
  "settings": {
    "provider": "openai",
    "model": "gpt-5.4"
  },
  "expectations": {
    "requireUsage": true,
    "requireToolCall": true
  }
}
```

---
_Source: https://npm.io/package/@clinebot/llms · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._