@molecule/api-ai-deepseek

DeepSeek AI provider for molecule.dev.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

// npm install @molecule/api-ai-deepseek --workspace=api
import { setProvider, requireProvider } from '@molecule/api-ai'
import { provider } from '@molecule/api-ai-deepseek'

// Named registration — several AI providers can be bonded side by side
// (getProviderByName('deepseek') targets this one); the FIRST one
// registered also answers requireProvider() (see @molecule/api-ai).
setProvider('deepseek', provider) // reads DEEPSEEK_API_KEY from the environment

let reply = ''
for await (const event of requireProvider().chat({
  messages: [{ role: 'user', content: 'Hello!' }],
})) {
  if (event.type === 'text') reply += event.content // or forward the chunk to the client (SSE)
}

Type

provider

Installation

npm install @molecule/api-ai-deepseek @molecule/api-ai @molecule/api-bond @molecule/api-i18n @molecule/api-secrets

API

Interfaces

DeepseekConfig

Configuration for DeepSeek.

interface DeepseekConfig {
  /** API key. Defaults to DEEPSEEK_API_KEY env var. */
  apiKey?: string
  /** Default model. Defaults to 'deepseek-v4-flash'. */
  defaultModel?: string
  /** Maximum tokens for completions. */
  maxTokens?: number
  /** Base URL override (for proxies). Defaults to 'https://api.deepseek.com'. */
  baseUrl?: string
  /**
   * Chat-completions path appended to {@link baseUrl}. Defaults to
   * `/v1/chat/completions` (DeepSeek-direct puts the version in the path). Set
   * this when the same open-weight model is served by a US OpenAI-compatible
   * host whose version prefix lives in the base URL instead — e.g. DeepInfra:
   * `baseUrl='https://api.deepinfra.com/v1/openai'` + `completionsPath='/chat/completions'`.
   */
  completionsPath?: string
  /**
   * Optional catalog-id → upstream-model-id map, applied to the outbound request
   * ONLY. Lets a US OpenAI-compatible host (DeepInfra) receive its namespaced id
   * (`deepseek-ai/DeepSeek-V4-Flash`) while the rest of the platform — pricing,
   * cost ceilings, display — keeps using the canonical catalog id
   * (`deepseek-v4-flash`). An id not in the map passes through unchanged.
   */
  modelMap?: Record<string, string>
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
  onRateLimit?: AiRateLimitCallback
  /** Called when a stream accepts the request and then produces no content for the whole first-token window. */
  onStreamStall?: AiStreamStallCallback
  /**
   * How long a stream may wait for its FIRST content event before the provider
   * abandons it and asks again (ms). Defaults to 45 000.
   *
   * Counted from the moment the request is sent, and cleared by the first
   * `text` / `thinking` / `tool_use` event — NOT by a liveness frame, because
   * DeepSeek keeps a stalled prefill's connection alive with `: keep-alive`
   * comments, so a byte-level idle timeout never sees the stall at all. A turn's
   * healthy first-token wait is ~1 s even on million-token prompts, so this
   * window is a stall bound, not a latency budget.
   */
  firstTokenTimeoutMs?: number
  /**
   * How long a stream that has ALREADY started may go without a single byte
   * before the provider abandons it (ms). Defaults to 60 000.
   *
   * Measured over the socket, not over content: once the reply has started, any
   * byte proves the connection is alive, and a stretch with none is a broken
   * stream rather than a slow one. Abandoning it here is not retried — the
   * partial reply is already on the wire — it is reported as an error event for
   * the caller's own ladder, which keeps the partial.
   */
  streamSilenceTimeoutMs?: number
}

ProcessEnv

Process Env interface.

interface ProcessEnv {
  DEEPSEEK_API_KEY: string
  /** Base URL override (for credential brokers / gateways / US OpenAI-compatible hosts). */
  DEEPSEEK_BASE_URL?: string
  /** Chat-completions path override (see {@link DeepseekConfig.completionsPath}). */
  DEEPSEEK_COMPLETIONS_PATH?: string
}

Functions

createProvider(config)

Creates a DeepSeek AI provider instance.

function createProvider(config?: DeepseekConfig): AIProvider

• config — DeepSeek-specific configuration (API key, model, max tokens, base URL).

Returns: An AIProvider backed by the DeepSeek Chat Completions API.

Constants

provider

The provider implementation.

const provider: AIProvider

DEFAULT_FIRST_TOKEN_TIMEOUT_MS

How long a stream may wait for its first content event.

const DEFAULT_FIRST_TOKEN_TIMEOUT_MS: 45000

DeepseekAIProvider

Back-compat alias for the provider class (the scaffold exported this name).

const DeepseekAIProvider: typeof DeepseekAIProviderImpl

aiDeepseekSecretDefinitions

Secret definitions required by the DeepSeek AI bond.

const aiDeepseekSecretDefinitions: SecretDefinition[]

Core Interface

Implements @molecule/api-ai interface.

Bond Wiring

Setup function to register this provider with the bond system:

import { bond } from '@molecule/api-bond'
import { provider } from '@molecule/api-ai-deepseek'

export function setupAiDeepseek(): void {
  bond('ai', 'deepseek', provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-ai ^1.0.1
• @molecule/api-bond ^1.0.1
• @molecule/api-i18n ^1.0.1
• @molecule/api-secrets ^1.0.1

Environment Variables

• DEEPSEEK_API_KEY (required) — DeepSeek API key
  • Setup: Create an API key on the DeepSeek open platform.
  • Get it here: https://platform.deepseek.com/api_keys
  • Example: sk-...

Runtime Dependencies

• @molecule/api-ai
• @molecule/api-bond
• @molecule/api-i18n
• @molecule/api-secrets

Config: DEEPSEEK_API_KEY (SERVER-side only) plus an optional default model id/base URL.

Missing DEEPSEEK_API_KEY fails fast: the provider throws naming the exact env var on first use (the exported provider is a lazy proxy, so this fires on the first chat() call, not at bond/module-load time) — it never silently sends an empty key.

Error message disambiguation: a plain 400 that ISN'T a context-length error (bad param, malformed tool schema) gets its own non-retryable message distinct from the generic "AI service error. Please try again." used for retryable failures.

A stream that opens and then produces nothing is bounded, not waited on. DeepSeek answers 200 and then keeps a stalled prefill alive with : keep-alive comments, so no HTTP status is ever wrong and a byte-level idle timeout never sees the stall. chat() therefore bounds the wait for the first CONTENT event (45 s, MOL_DEEPSEEK_FIRST_TOKEN_TIMEOUT_MS) and asks once more with a fresh stream; after the reply has started it bounds the silence between chunks instead (60 s, MOL_DEEPSEEK_STREAM_SILENCE_TIMEOUT_MS) and surfaces an error event, keeping the partial reply. Hosts observe both through the onStreamStall callback.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual chat/AI screens, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip. The sandbox HAS an AI provider bonded, so the flow runs live end-to-end; AI output is NON-DETERMINISTIC, so assert on STRUCTURE/behavior, not exact text:

• [ ] A message sent through the real chat UI comes back as a RELEVANT AI reply — not an echo of the prompt, a hardcoded stub, or an empty bubble. Ask something with a checkable answer (e.g. "What is 2 + 2?") and confirm the response actually contains it ("4"), proving a live model answered.
• [ ] If the app streams, tokens render INCREMENTALLY — text grows word by word in the UI, not one final blob dumped after a long frozen spinner. (A streamed chat() yields text chunks then a final done; a single late blob means the reply was awaited whole and streaming is broken.)
• [ ] Multi-turn CONTEXT is preserved: a follow-up that refers back to the previous turn (e.g. after "2 + 2", ask "now double that" -> understood as 8) works — proving the full messages history is sent, not just the last line.
• [ ] A provider failure (bad/missing key, rate limit, timeout) surfaces as a graceful in-UI error message, NOT a crash, blank screen, a spinner that never resolves, or an unhandled 500. Force one and watch the UI recover.
• [ ] The provider key + the provider call are SERVER-side only: the key never reaches the browser (check the network tab, the JS bundle, and page globals), and no route proxies arbitrary prompts to the model without auth
  • a token cap — an open AI endpoint is an unbounded bill and abuse vector.