@molecule/api-ai-alibaba

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.

Alibaba Qwen AI provider for molecule.dev.

Type

provider

Installation

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

API

Interfaces

AlibabaConfig

Configuration for Alibaba Qwen.

interface AlibabaConfig {
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
  onRateLimit?: AiRateLimitCallback
  /** API key. Defaults to the `DASHSCOPE_API_KEY` (or `ALIBABA_API_KEY`) env var. */
  apiKey?: string
  /** Default model. Defaults to 'qwen3.8-max'. */
  defaultModel?: string
  /** Maximum tokens for completions. */
  maxTokens?: number
  /**
   * Base URL override (for proxies). Defaults to the `DASHSCOPE_BASE_URL` env
   * var, then 'https://dashscope-us.aliyuncs.com/compatible-mode'.
   */
  baseUrl?: string
  /**
   * Chat-completions path appended to {@link baseUrl}. Defaults to
   * `/v1/chat/completions`. Unchanged for DashScope-US; also correct for
   * DeepInfra when baseUrl='https://api.deepinfra.com/v1/openai' would need
   * `/chat/completions` — set it accordingly for that host.
   */
  completionsPath?: string
  /**
   * Catalog-id → upstream-model-id map, applied to the outbound request only, so
   * a US host (DeepInfra) receives its namespaced id
   * (`Qwen/Qwen3-Coder-480B-A35B-Instruct-Turbo`) while pricing/cost/display keep
   * the canonical catalog id (`qwen3-coder-plus`).
   */
  modelMap?: Record<string, string>
}

ProcessEnv

Process env vars read by the Alibaba DashScope AI bond.

interface ProcessEnv {
  /** Alibaba DashScope API key. */
  DASHSCOPE_API_KEY: string
  /** Alternate key env var (same value; checked after DASHSCOPE_API_KEY). */
  ALIBABA_API_KEY?: string
  /** Base URL override (for credential brokers / gateways / US OpenAI-compatible hosts). */
  DASHSCOPE_BASE_URL?: string
  /** Chat-completions path override (see {@link AlibabaConfig.completionsPath}). */
  DASHSCOPE_COMPLETIONS_PATH?: string
}

Functions

createProvider(config)

Creates an Alibaba Qwen AI provider instance.

function createProvider(config?: AlibabaConfig): AIProvider

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

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

Constants

aiAlibabaSecretDefinitions

Secret definitions required by the Alibaba DashScope AI bond.

const aiAlibabaSecretDefinitions: SecretDefinition[]

provider

The provider implementation.

const provider: AIProvider

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-alibaba'

export function setupAiAlibaba(): void {
  bond('ai', 'alibaba', 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

• DASHSCOPE_API_KEY (required) — Alibaba DashScope API key
  • Setup: Create an API key in Alibaba Cloud Model Studio (DashScope).
  • Get it here: https://www.alibabacloud.com/help/en/model-studio/get-api-key
  • Example: sk-...

Runtime Dependencies

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

Config: DASHSCOPE_API_KEY (or ALIBABA_API_KEY, SERVER-side only) plus an optional default model id/base URL.

Missing key fails fast: the provider throws naming both accepted env vars 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/invalid-param error already handled above gets its own non-retryable message distinct from the generic "AI service error. Please try again." used for retryable failures.

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.