@im-bot/llm-client 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# @im-bot/llm-client (TypeScript)
+
+Unified multi-provider LLM client — TypeScript port of the
+Python [`im_bot_llm`](../../python) SDK. Same feature set:
+
+- Multi-provider with automatic fallback chain
+- Retry with exponential backoff on 429 / 5xx
+- Streaming via async iterables (SSE)
+- Tool use / function calling loop
+- Token counting + cost estimation (USD)
+- TypeScript-native: full type definitions, ESM output, zero runtime deps
+  (uses Node 18+ global `fetch`)
+
+## Install
+
+```bash
+# from the im-bot repo (development):
+pnpm install -w packages/llm-client/typescript
+# or in a standalone project:
+npm install @im-bot/llm-client
+```
+
+## Quick Start
+
+### Simple chat
+
+```ts
+import { LLMClient, Provider, Message } from '@im-bot/llm-client';
+
+const client = new LLMClient({
+  defaultProvider: 'deepseek',
+  providers: {
+    deepseek: new Provider({ apiKey: process.env.DEEPSEEK_API_KEY! }),
+    openrouter: new Provider({ apiKey: process.env.OPENROUTER_API_KEY! }),
+  },
+  fallbackOrder: ['deepseek', 'openrouter'],
+});
+
+const reply = await client.chat(
+  [Message.user('Say hello in 5 words.')],
+  { model: 'deepseek-flash' },
+);
+console.log(reply.text);
+console.log(`cost: $${reply.costUsd.toFixed(5)}`);
+```
+
+### Streaming
+
+```ts
+for await (const chunk of client.streamChat(
+  [Message.user('Write a short poem.')],
+  { model: 'deepseek-flash' },
+)) {
+  if (chunk.delta) process.stdout.write(chunk.delta);
+  if (chunk.isFinal) console.log(`\n[tokens: ${chunk.usage.totalTokens}]`);
+}
+```
+
+### Tool use
+
+```ts
+import { LLMClient, Provider, Message, ToolSpec } from '@im-bot/llm-client';
+
+const searchTool = new ToolSpec({
+  name: 'search',
+  description: 'Search the web.',
+  parameters: {
+    type: 'object',
+    properties: { query: { type: 'string' } },
+    required: ['query'],
+  },
+  handler: ({ query }: { query: string }) => `Results for ${query}`,
+});
+
+const client = new LLMClient({
+  defaultProvider: 'deepseek',
+  providers: { deepseek: new Provider({ apiKey: process.env.DEEPSEEK_API_KEY! }) },
+});
+
+const reply = await client.chatWithTools(
+  [Message.user('find latest Python 3.13 release')],
+  { tools: [searchTool], maxToolIterations: 3, model: 'deepseek-flash' },
+);
+console.log(reply.text);
+```
+
+### Multi-provider fallback
+
+```ts
+const client = new LLMClient({
+  defaultProvider: 'deepseek',
+  providers: {
+    deepseek: new Provider({ apiKey: 'sk-deepseek-...' }),
+    openrouter: new Provider({ apiKey: 'sk-or-...' }),
+  },
+  fallbackOrder: ['deepseek', 'openrouter'],
+  retry: { maxAttempts: 3, backoffFactor: 0.5, jitter: true },
+});
+
+// If deepseek is down or returns 429/5xx, automatically retries on openrouter.
+const reply = await client.chat([Message.user('hi')], { model: 'deepseek-flash' });
+```
+
+## API surface
+
+### `LLMClient`
+
+```ts
+class LLMClient {
+  constructor(config: {
+    defaultProvider: string;
+    providers: Record<string, Provider>;
+    fallbackOrder?: string[];
+    retry?: RetryConfig;
+    timeout?: number;
+  });
+
+  chat(
+    messages: Message[],
+    options?: {
+      model?: string;
+      provider?: string;
+      temperature?: number;
+      maxTokens?: number;
+      tools?: ToolSpec[];
+    },
+  ): Promise<ChatResponse>;
+
+  streamChat(
+    messages: Message[],
+    options?: { model?: string; provider?: string; temperature?: number; maxTokens?: number; },
+  ): AsyncIterable<StreamChunk>;
+
+  chatWithTools(
+    messages: Message[],
+    options: { tools: ToolSpec[]; maxToolIterations?: number; model?: string; provider?: string },
+  ): Promise<ChatResponse>;
+
+  close(): Promise<void>;
+}
+```
+
+### `Message`
+
+```ts
+class Message {
+  constructor(
+    public role: 'system' | 'user' | 'assistant' | 'tool',
+    public content: string,
+    public name?: string,
+    public toolCallId?: string,
+    public toolCalls?: ToolCall[],
+  );
+
+  static system(content: string): Message;
+  static user(content: string): Message;
+  static assistant(content: string, toolCalls?: ToolCall[]): Message;
+  static toolResult(toolCallId: string, name: string, content: string): Message;
+
+  toOpenAIDict(): Record<string, unknown>;
+}
+```
+
+### `ChatResponse`
+
+```ts
+interface ChatResponse {
+  text: string;
+  finishReason: 'stop' | 'tool_calls' | 'length' | 'error';
+  usage: Usage;
+  costUsd: number;
+  model: string;
+  provider: string;
+  raw?: unknown;
+}
+```
+
+## Environment-variable convention
+
+LLMClient auto-detects keys via standard names when `Provider({ apiKey })` is
+left blank:
+
+| Provider  | Env var                |
+|-----------|------------------------|
+| deepseek  | DEEPSEEK_API_KEY       |
+| openrouter| OPENROUTER_API_KEY     |
+| openai    | OPENAI_API_KEY         |
+| minimax   | MINIMAX_API_KEY        |
+| minimax_cn| MINIMAX_CN_API_KEY     |
+| zhipu     | GLM_API_KEY            |
+
+## License
+
+MIT — same as im-bot.

package/dist/async-client.d.ts

@@ -0,0 +1,20 @@
+import { LLMClientConfig } from './client.js';
+import { Message } from './messages.js';
+import type { ChatResponse, StreamChunk, ChatOptions, StreamOptions, ToolChatOptions } from './types.js';
+/**
+ * AsyncLLMClient — thin async-only wrapper around LLMClient.
+ *
+ * Node.js has no real async I/O advantage for HTTP (global fetch is already
+ * promise-based), so this class simply re-exports the sync API as async-only.
+ * Use this when you want a clean async surface and don't need the streaming
+ * generator pattern.
+ */
+export declare class AsyncLLMClient {
+    private client;
+    constructor(config: LLMClientConfig);
+    chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse>;
+    streamChat(messages: Message[], options?: StreamOptions): AsyncIterable<StreamChunk>;
+    chatWithTools(messages: Message[], options: ToolChatOptions): Promise<ChatResponse>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=async-client.d.ts.map

package/dist/async-client.js

@@ -0,0 +1,29 @@
+// @im-bot/llm-client — async LLMClient (delegates to sync via to_thread-like approach)
+import { LLMClient } from './client.js';
+/**
+ * AsyncLLMClient — thin async-only wrapper around LLMClient.
+ *
+ * Node.js has no real async I/O advantage for HTTP (global fetch is already
+ * promise-based), so this class simply re-exports the sync API as async-only.
+ * Use this when you want a clean async surface and don't need the streaming
+ * generator pattern.
+ */
+export class AsyncLLMClient {
+    client;
+    constructor(config) {
+        this.client = new LLMClient(config);
+    }
+    async chat(messages, options) {
+        return this.client.chat(messages, options);
+    }
+    streamChat(messages, options) {
+        return this.client.streamChat(messages, options);
+    }
+    async chatWithTools(messages, options) {
+        return this.client.chatWithTools(messages, options);
+    }
+    async close() {
+        return this.client.close();
+    }
+}
+//# sourceMappingURL=async-client.js.map

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import { Message } from './messages.js';
+import { Provider, RetryConfigOptions } from './config.js';
+import type { ChatResponse, StreamChunk, ChatOptions, StreamOptions, ToolChatOptions } from './types.js';
+export interface LLMClientConfig {
+    defaultProvider: string;
+    providers: Record<string, Provider>;
+    fallbackOrder?: string[];
+    retry?: RetryConfigOptions;
+    timeout?: number;
+}
+export declare class LLMClient {
+    private defaultProvider;
+    private providers;
+    private fallbackOrder;
+    private retry;
+    private timeout;
+    constructor(config: LLMClientConfig);
+    chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse>;
+    streamChat(messages: Message[], options?: StreamOptions): AsyncIterable<StreamChunk>;
+    chatWithTools(messages: Message[], options: ToolChatOptions): Promise<ChatResponse>;
+    private resolveChain;
+    private defaultModelFor;
+    private url;
+    private headers;
+    private provTimeout;
+    private postWithRetry;
+    private streamWithRetry;
+    private extractToolCalls;
+    private runTools;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,385 @@
+// @im-bot/llm-client — sync LLMClient
+import { Message } from './messages.js';
+import { RetryConfig } from './config.js';
+import { LLMError, ProviderError, RateLimitError, AllProvidersFailedError, StreamInterruptedError, } from './errors.js';
+// ── helpers ────────────────────────────────────────────────────────────
+function defaultTimeout() {
+    return 60;
+}
+function shouldRetry(status, retry) {
+    return retry.shouldRetry(status);
+}
+function estimateCost(model, usage) {
+    // Mirror the Python SDK's pricing map (config.ts).
+    const pricing = {
+        'deepseek-flash': [0.07, 0.27],
+        'deepseek-v4-flash': [0.07, 0.27],
+        'deepseek-chat': [0.27, 1.10],
+        'minimax/MiniMax-M3': [1.0, 3.0],
+        'minimax/MiniMax-M2': [1.0, 3.0],
+    };
+    const p = pricing[model];
+    if (!p || usage.totalTokens === 0)
+        return 0;
+    return (usage.inputTokens / 1_000_000) * p[0] + (usage.outputTokens / 1_000_000) * p[1];
+}
+function buildRequestBody(opts) {
+    const body = {
+        model: opts.model,
+        messages: opts.messages.map((m) => m.toOpenAIDict()),
+        temperature: opts.temperature,
+        stream: opts.stream,
+    };
+    if (opts.maxTokens !== undefined)
+        body.max_tokens = opts.maxTokens;
+    if (opts.tools && opts.tools.length > 0) {
+        body.tools = opts.tools.map((t) => t.toOpenAIDict());
+    }
+    return body;
+}
+async function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function httpErrorToException(provider, status, body) {
+    if (status === 429) {
+        return new RateLimitError(provider, status, 'rate limited', body);
+    }
+    return new ProviderError(provider, status, `HTTP ${status}`, body);
+}
+function parseUsage(raw) {
+    if (!raw)
+        return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    return {
+        inputTokens: Number(raw.prompt_tokens ?? 0),
+        outputTokens: Number(raw.completion_tokens ?? 0),
+        totalTokens: Number(raw.total_tokens ?? 0),
+    };
+}
+function parseChatResponse(provider, data) {
+    const choice = (data.choices ?? [])[0] ?? {};
+    const message = choice.message ?? {};
+    const text = message.content ?? '';
+    const finishReason = choice.finish_reason ?? 'stop';
+    const usage = parseUsage(data.usage);
+    const model = data.model ?? '';
+    const costUsd = estimateCost(model, usage);
+    return { text, finishReason, usage, costUsd, model, provider, raw: data };
+}
+// ── LLMClient ─────────────────────────────────────────────────────────
+export class LLMClient {
+    defaultProvider;
+    providers;
+    fallbackOrder;
+    retry;
+    timeout;
+    constructor(config) {
+        this.defaultProvider = config.defaultProvider;
+        this.providers = config.providers;
+        this.fallbackOrder = config.fallbackOrder ?? [config.defaultProvider];
+        this.retry = RetryConfig.fromOptions(config.retry);
+        this.timeout = config.timeout ?? defaultTimeout();
+    }
+    // ── chat (non-streaming) ──────────────────────────────────────────
+    async chat(messages, options = {}) {
+        const chain = this.resolveChain(options.provider);
+        const effectiveModel = options.model ?? this.defaultModelFor(chain[0]);
+        const body = buildRequestBody({
+            messages,
+            model: effectiveModel,
+            temperature: options.temperature ?? 0.7,
+            maxTokens: options.maxTokens,
+            tools: options.tools,
+            stream: false,
+        });
+        const attempts = [];
+        for (let i = 0; i < chain.length; i++) {
+            const provName = chain[i];
+            try {
+                return await this.postWithRetry(provName, body);
+            }
+            catch (err) {
+                if (err instanceof RateLimitError || err instanceof ProviderError) {
+                    attempts.push({ provider: provName, error: err });
+                    // Only swallow provider-level errors if there's another to try.
+                    if (i + 1 >= chain.length)
+                        throw err;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw new AllProvidersFailedError(attempts);
+    }
+    // ── streamChat ────────────────────────────────────────────────────
+    async *streamChat(messages, options = {}) {
+        const chain = this.resolveChain(options.provider);
+        const effectiveModel = options.model ?? this.defaultModelFor(chain[0]);
+        const body = buildRequestBody({
+            messages,
+            model: effectiveModel,
+            temperature: options.temperature ?? 0.7,
+            maxTokens: options.maxTokens,
+            stream: true,
+        });
+        let lastErr = null;
+        for (let i = 0; i < chain.length; i++) {
+            const provName = chain[i];
+            try {
+                for await (const chunk of this.streamWithRetry(provName, body)) {
+                    yield chunk;
+                }
+                return;
+            }
+            catch (err) {
+                if (err instanceof RateLimitError ||
+                    err instanceof ProviderError ||
+                    err instanceof StreamInterruptedError) {
+                    lastErr = err;
+                    if (i + 1 >= chain.length)
+                        throw err;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw new AllProvidersFailedError(chain.map((p) => ({ provider: p, error: lastErr ?? new Error('unknown') })));
+    }
+    // ── chatWithTools ───────────────────────────────────────────────
+    async chatWithTools(messages, options) {
+        const { tools, maxToolIterations = 5, ...chatOpts } = options;
+        let currentMessages = [...messages];
+        let cumulative = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        let last = null;
+        for (let i = 0; i < maxToolIterations; i++) {
+            const response = await this.chat(currentMessages, { ...chatOpts, tools });
+            cumulative = {
+                inputTokens: cumulative.inputTokens + response.usage.inputTokens,
+                outputTokens: cumulative.outputTokens + response.usage.outputTokens,
+                totalTokens: cumulative.totalTokens + response.usage.totalTokens,
+            };
+            last = response;
+            if (response.finishReason !== 'tool_calls')
+                break;
+            const toolCalls = this.extractToolCalls(response);
+            if (!toolCalls || toolCalls.length === 0)
+                break;
+            currentMessages.push(Message.assistant(response.text || '', toolCalls));
+            const results = await this.runTools(toolCalls, tools);
+            for (const r of results) {
+                currentMessages.push(Message.toolResult(r.toolCallId, r.name, r.output));
+            }
+        }
+        if (!last)
+            throw new LLMError('chatWithTools: no response produced');
+        return {
+            ...last,
+            usage: cumulative,
+            costUsd: estimateCost(last.model, cumulative),
+        };
+    }
+    // ── internal ─────────────────────────────────────────────────────
+    resolveChain(override) {
+        if (override) {
+            if (!(override in this.providers)) {
+                throw new Error(`Unknown provider: ${override}`);
+            }
+            return [override];
+        }
+        return [...this.fallbackOrder];
+    }
+    defaultModelFor(provName) {
+        const p = this.providers[provName];
+        return p ? p.defaultModel() : '';
+    }
+    url(provName) {
+        const p = this.providers[provName];
+        if (!p)
+            throw new Error(`Unknown provider: ${provName}`);
+        return `${p.resolveBaseUrl(provName).replace(/\/$/, '')}/chat/completions`;
+    }
+    headers(provName) {
+        const p = this.providers[provName];
+        if (!p)
+            throw new Error(`Unknown provider: ${provName}`);
+        return {
+            Authorization: `Bearer ${p.resolveApiKey(provName)}`,
+            'Content-Type': 'application/json',
+            ...p.extraHeaders(),
+        };
+    }
+    provTimeout(provName) {
+        const p = this.providers[provName];
+        return p ? p.timeout(this.timeout) : this.timeout;
+    }
+    async postWithRetry(provName, body) {
+        let lastErr = null;
+        for (let attempt = 0; attempt < this.retry.maxAttempts; attempt++) {
+            try {
+                const resp = await fetch(this.url(provName), {
+                    method: 'POST',
+                    headers: this.headers(provName),
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(this.provTimeout(provName) * 1000),
+                });
+                if (resp.ok) {
+                    const data = await resp.json();
+                    return parseChatResponse(provName, data);
+                }
+                const text = await resp.text().catch(() => '');
+                const err = httpErrorToException(provName, resp.status, text.slice(0, 500));
+                lastErr = err;
+                if (shouldRetry(resp.status, this.retry) && attempt + 1 < this.retry.maxAttempts) {
+                    await this.retry.delay(attempt);
+                    continue;
+                }
+                throw err;
+            }
+            catch (err) {
+                if (err instanceof ProviderError) {
+                    lastErr = err;
+                    throw err;
+                }
+                // Network/abort errors
+                const wrapped = new ProviderError(provName, null, String(err.message ?? err));
+                lastErr = wrapped;
+                if (attempt + 1 < this.retry.maxAttempts) {
+                    await this.retry.delay(attempt);
+                    continue;
+                }
+                throw wrapped;
+            }
+        }
+        throw lastErr ?? new ProviderError(provName, null, 'no attempts made');
+    }
+    async *streamWithRetry(provName, body) {
+        let lastErr = null;
+        for (let attempt = 0; attempt < this.retry.maxAttempts; attempt++) {
+            try {
+                const resp = await fetch(this.url(provName), {
+                    method: 'POST',
+                    headers: this.headers(provName),
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(this.provTimeout(provName) * 1000),
+                });
+                if (!resp.ok) {
+                    const text = await resp.text().catch(() => '');
+                    const err = httpErrorToException(provName, resp.status, text.slice(0, 500));
+                    lastErr = err;
+                    if (shouldRetry(resp.status, this.retry) && attempt + 1 < this.retry.maxAttempts) {
+                        await this.retry.delay(attempt);
+                        continue;
+                    }
+                    throw err;
+                }
+                const reader = resp.body?.getReader();
+                if (!reader)
+                    throw new StreamInterruptedError('no response body');
+                const decoder = new TextDecoder();
+                let buffer = '';
+                let finalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+                let finalReason = '';
+                let finalModel = String(body.model || '');
+                while (true) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    let nlIdx;
+                    while ((nlIdx = buffer.indexOf('\n')) !== -1) {
+                        const line = buffer.slice(0, nlIdx).trim();
+                        buffer = buffer.slice(nlIdx + 1);
+                        if (!line.startsWith('data:'))
+                            continue;
+                        const payload = line.slice(5).trim();
+                        if (payload === '[DONE]')
+                            continue;
+                        let evt;
+                        try {
+                            evt = JSON.parse(payload);
+                        }
+                        catch {
+                            continue;
+                        }
+                        let deltaText = '';
+                        for (const ch of evt.choices ?? []) {
+                            deltaText += (ch.delta?.content ?? '');
+                        }
+                        if (deltaText) {
+                            yield { delta: deltaText, isFinal: false, usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, finishReason: '' };
+                        }
+                        if (evt.usage)
+                            finalUsage = parseUsage(evt.usage);
+                        for (const ch of evt.choices ?? []) {
+                            if (ch.finish_reason)
+                                finalReason = ch.finish_reason;
+                            if (ch.model)
+                                finalModel = ch.model;
+                        }
+                    }
+                }
+                yield {
+                    delta: '',
+                    isFinal: true,
+                    usage: finalUsage,
+                    finishReason: finalReason || 'stop',
+                };
+                return;
+            }
+            catch (err) {
+                if (err instanceof ProviderError || err instanceof RateLimitError) {
+                    lastErr = err;
+                    throw err;
+                }
+                const wrapped = new StreamInterruptedError(String(err.message ?? err));
+                lastErr = wrapped;
+                if (attempt + 1 < this.retry.maxAttempts) {
+                    await this.retry.delay(attempt);
+                    continue;
+                }
+                throw wrapped;
+            }
+        }
+        throw lastErr ?? new StreamInterruptedError('no attempts made');
+    }
+    extractToolCalls(response) {
+        const data = response.raw;
+        if (!data)
+            return null;
+        const choice = (data.choices ?? [])[0];
+        if (!choice)
+            return null;
+        return choice.message?.tool_calls ?? null;
+    }
+    async runTools(calls, specs) {
+        const byName = new Map(specs.map((s) => [s.config.name, s]));
+        const results = [];
+        for (const call of calls) {
+            const fn = call.function ?? {};
+            const name = fn.name;
+            let parsed = {};
+            try {
+                parsed = JSON.parse(fn.arguments ?? '{}');
+            }
+            catch {
+                parsed = {};
+            }
+            const spec = byName.get(name);
+            if (!spec) {
+                results.push({ toolCallId: call.id, name, output: `Error: unknown tool '${name}'` });
+                continue;
+            }
+            try {
+                const out = await Promise.resolve(spec.config.handler(parsed));
+                results.push({ toolCallId: call.id, name, output: String(out) });
+            }
+            catch (err) {
+                results.push({ toolCallId: call.id, name, output: `Error: ${String(err)}` });
+            }
+        }
+        return results;
+    }
+    async close() {
+        // No persistent connections in Node global fetch — nothing to close.
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/config.d.ts

@@ -0,0 +1,46 @@
+export type ProviderEnvVar = 'deepseek' | 'openrouter' | 'openai' | 'minimax' | 'minimax_cn' | 'zhipu' | 'kimi' | 'anthropic';
+export declare const PROVIDER_ENV_VARS: Record<ProviderEnvVar, string>;
+export declare const PROVIDER_BASE_URLS: Record<ProviderEnvVar, string>;
+export declare const MODEL_PRICING: Record<string, [number, number]>;
+export interface ProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    name?: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+export declare class Provider {
+    config: ProviderConfig;
+    constructor(config?: ProviderConfig);
+    /** The display name for this provider (defaults to the key in `LLMClient.providers`). */
+    displayName(fallback: string): string;
+    /** Resolve the base URL (Provider override → PROVIDER_BASE_URLS default). */
+    resolveBaseUrl(name: string): string;
+    /** Resolve the API key (Provider.apiKey → env var). */
+    resolveApiKey(name: string): string;
+    /** Default model (or empty string if unset). */
+    defaultModel(): string;
+    /** Per-request timeout in seconds. */
+    timeout(defaultTimeout: number): number;
+    /** Extra HTTP headers for every request. */
+    extraHeaders(): Record<string, string>;
+}
+export interface RetryConfigOptions {
+    maxAttempts?: number;
+    backoffFactor?: number;
+    jitter?: boolean;
+    retryOnStatus?: number[];
+}
+export declare class RetryConfig {
+    maxAttempts: number;
+    backoffFactor: number;
+    jitter: boolean;
+    retryOnStatus: readonly number[];
+    constructor(maxAttempts?: number, backoffFactor?: number, jitter?: boolean, retryOnStatus?: readonly number[]);
+    static fromOptions(opts?: RetryConfigOptions): RetryConfig;
+    shouldRetry(status: number): boolean;
+    sleepForBackoff(attempt: number): number;
+    delay(attempt: number): Promise<void>;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,98 @@
+// @im-bot/llm-client — Provider + RetryConfig
+// Standard env var per provider (for auto-detect when apiKey is omitted)
+export const PROVIDER_ENV_VARS = {
+    deepseek: 'DEEPSEEK_API_KEY',
+    openrouter: 'OPENROUTER_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    minimax: 'MINIMAX_API_KEY',
+    minimax_cn: 'MINIMAX_CN_API_KEY',
+    zhipu: 'GLM_API_KEY',
+    kimi: 'KIMI_API_KEY',
+    anthropic: 'ANTHROPIC_API_KEY',
+};
+// Default base_url per provider (override per-Provider if needed)
+export const PROVIDER_BASE_URLS = {
+    deepseek: 'https://api.deepseek.com/v1',
+    openrouter: 'https://openrouter.ai/api/v1',
+    openai: 'https://api.openai.com/v1',
+    minimax: 'https://api.minimax.chat/v1',
+    minimax_cn: 'https://api.minimaxi.com/anthropic',
+    zhipu: 'https://open.bigmodel.cn/api/paas/v4/',
+    kimi: 'https://api.moonshot.cn/v1',
+    anthropic: 'https://api.anthropic.com/v1',
+};
+// Approximate cost per 1M tokens (input, output). Conservative defaults.
+export const MODEL_PRICING = {
+    'deepseek-flash': [0.07, 0.27],
+    'deepseek-v4-flash': [0.07, 0.27],
+    'deepseek-chat': [0.27, 1.10],
+    'minimax/MiniMax-M3': [1.0, 3.0],
+    'minimax/MiniMax-M2': [1.0, 3.0],
+};
+export class Provider {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /** The display name for this provider (defaults to the key in `LLMClient.providers`). */
+    displayName(fallback) {
+        return this.config.name || fallback;
+    }
+    /** Resolve the base URL (Provider override → PROVIDER_BASE_URLS default). */
+    resolveBaseUrl(name) {
+        if (this.config.baseUrl)
+            return this.config.baseUrl;
+        if (name in PROVIDER_BASE_URLS)
+            return PROVIDER_BASE_URLS[name];
+        throw new Error(`Unknown provider '${name}' and no baseUrl configured`);
+    }
+    /** Resolve the API key (Provider.apiKey → env var). */
+    resolveApiKey(name) {
+        if (this.config.apiKey)
+            return this.config.apiKey;
+        const envVar = PROVIDER_ENV_VARS[name];
+        if (envVar && process.env[envVar]) {
+            return process.env[envVar];
+        }
+        throw new Error(`No API key for provider '${name}': set Provider.apiKey or env var ${envVar}`);
+    }
+    /** Default model (or empty string if unset). */
+    defaultModel() {
+        return this.config.model || '';
+    }
+    /** Per-request timeout in seconds. */
+    timeout(defaultTimeout) {
+        return this.config.timeout ?? defaultTimeout;
+    }
+    /** Extra HTTP headers for every request. */
+    extraHeaders() {
+        return this.config.headers || {};
+    }
+}
+export class RetryConfig {
+    maxAttempts;
+    backoffFactor;
+    jitter;
+    retryOnStatus;
+    constructor(maxAttempts = 3, backoffFactor = 0.5, jitter = true, retryOnStatus = [429, 500, 502, 503, 504]) {
+        this.maxAttempts = maxAttempts;
+        this.backoffFactor = backoffFactor;
+        this.jitter = jitter;
+        this.retryOnStatus = retryOnStatus;
+    }
+    static fromOptions(opts = {}) {
+        return new RetryConfig(opts.maxAttempts, opts.backoffFactor, opts.jitter, opts.retryOnStatus);
+    }
+    shouldRetry(status) {
+        return this.retryOnStatus.includes(status);
+    }
+    sleepForBackoff(attempt) {
+        const base = this.backoffFactor * 2 ** attempt;
+        return this.jitter ? base * (0.5 + Math.random()) : base;
+    }
+    async delay(attempt) {
+        const ms = this.sleepForBackoff(attempt) * 1000;
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+export declare class LLMError extends Error {
+    constructor(message: string);
+}
+export declare class ProviderError extends LLMError {
+    provider: string;
+    statusCode: number | null;
+    body?: string | undefined;
+    constructor(provider: string, statusCode: number | null, message: string, body?: string | undefined);
+}
+export declare class RateLimitError extends ProviderError {
+    constructor(provider: string, statusCode: number | null, message: string, body?: string);
+}
+export declare class StreamInterruptedError extends LLMError {
+    constructor(message: string);
+}
+export declare class AllProvidersFailedError extends LLMError {
+    attempts: Array<{
+        provider: string;
+        error: Error;
+    }>;
+    constructor(attempts: Array<{
+        provider: string;
+        error: Error;
+    }>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,44 @@
+// @im-bot/llm-client — error hierarchy
+export class LLMError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LLMError';
+    }
+}
+export class ProviderError extends LLMError {
+    provider;
+    statusCode;
+    body;
+    constructor(provider, statusCode, message, body) {
+        super(`[${provider}] ${statusCode}: ${message}`);
+        this.provider = provider;
+        this.statusCode = statusCode;
+        this.body = body;
+        this.name = 'ProviderError';
+    }
+}
+export class RateLimitError extends ProviderError {
+    constructor(provider, statusCode, message, body) {
+        super(provider, statusCode, 'rate limited', body);
+        this.name = 'RateLimitError';
+    }
+}
+export class StreamInterruptedError extends LLMError {
+    constructor(message) {
+        super(message);
+        this.name = 'StreamInterruptedError';
+    }
+}
+export class AllProvidersFailedError extends LLMError {
+    attempts;
+    constructor(attempts) {
+        const lines = [`All ${attempts.length} providers failed:`];
+        for (const { provider, error } of attempts) {
+            lines.push(`  - ${provider}: ${String(error)}`);
+        }
+        super(lines.join('\n'));
+        this.attempts = attempts;
+        this.name = 'AllProvidersFailedError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { LLMClient } from './client.js';
+export { AsyncLLMClient } from './async-client.js';
+export { Message } from './messages.js';
+export { ToolSpec } from './tools.js';
+export { Provider, RetryConfig, type ProviderConfig, type RetryConfigOptions, type ProviderEnvVar, } from './config.js';
+export { LLMError, ProviderError, RateLimitError, AllProvidersFailedError, StreamInterruptedError, } from './errors.js';
+export type { ChatResponse, StreamChunk, Usage, ToolCall, ChatOptions, StreamOptions, ToolChatOptions, } from './types.js';
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+// @im-bot/llm-client — TypeScript SDK for multi-provider LLM calls.
+export { LLMClient } from './client.js';
+export { AsyncLLMClient } from './async-client.js';
+export { Message } from './messages.js';
+export { ToolSpec } from './tools.js';
+export { Provider, RetryConfig, } from './config.js';
+export { LLMError, ProviderError, RateLimitError, AllProvidersFailedError, StreamInterruptedError, } from './errors.js';
+export const VERSION = '0.1.0';
+//# sourceMappingURL=index.js.map

package/dist/messages.d.ts

@@ -0,0 +1,15 @@
+import type { ToolCall } from './types.js';
+export declare class Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    name?: string | undefined;
+    toolCallId?: string | undefined;
+    toolCalls?: ToolCall[] | undefined;
+    constructor(role: 'system' | 'user' | 'assistant' | 'tool', content: string, name?: string | undefined, toolCallId?: string | undefined, toolCalls?: ToolCall[] | undefined);
+    static system(content: string): Message;
+    static user(content: string): Message;
+    static assistant(content: string, toolCalls?: ToolCall[]): Message;
+    static toolResult(toolCallId: string, name: string, content: string): Message;
+    toOpenAIDict(): Record<string, unknown>;
+}
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.js

@@ -0,0 +1,38 @@
+// @im-bot/llm-client — Message class
+export class Message {
+    role;
+    content;
+    name;
+    toolCallId;
+    toolCalls;
+    constructor(role, content, name, toolCallId, toolCalls) {
+        this.role = role;
+        this.content = content;
+        this.name = name;
+        this.toolCallId = toolCallId;
+        this.toolCalls = toolCalls;
+    }
+    static system(content) {
+        return new Message('system', content);
+    }
+    static user(content) {
+        return new Message('user', content);
+    }
+    static assistant(content, toolCalls) {
+        return new Message('assistant', content, undefined, undefined, toolCalls);
+    }
+    static toolResult(toolCallId, name, content) {
+        return new Message('tool', content, name, toolCallId);
+    }
+    toOpenAIDict() {
+        const d = { role: this.role, content: this.content };
+        if (this.name)
+            d.name = this.name;
+        if (this.toolCallId)
+            d.tool_call_id = this.toolCallId;
+        if (this.toolCalls)
+            d.tool_calls = this.toolCalls;
+        return d;
+    }
+}
+//# sourceMappingURL=messages.js.map

package/dist/tools.d.ts

@@ -0,0 +1,35 @@
+export interface ToolHandlerArgs {
+    [key: string]: unknown;
+}
+export type ToolHandler = (args: ToolHandlerArgs) => string | Promise<string> | unknown | Promise<unknown>;
+export interface ToolSpecParams {
+    type: 'object';
+    properties: Record<string, {
+        type: string;
+        description?: string;
+        enum?: string[];
+    }>;
+    required?: string[];
+}
+export interface ToolSpecConfig {
+    name: string;
+    description: string;
+    parameters: ToolSpecParams;
+    handler: ToolHandler;
+}
+export declare class ToolSpec {
+    config: ToolSpecConfig;
+    constructor(config: ToolSpecConfig);
+    toOpenAIDict(): Record<string, unknown>;
+}
+export interface ToolResult {
+    toolCallId: string;
+    name: string;
+    output: string;
+}
+export interface ToolCallResult {
+    tool_call_id: string;
+    name: string;
+    output: string;
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.js

@@ -0,0 +1,18 @@
+// @im-bot/llm-client — ToolSpec
+export class ToolSpec {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    toOpenAIDict() {
+        return {
+            type: 'function',
+            function: {
+                name: this.config.name,
+                description: this.config.description,
+                parameters: this.config.parameters,
+            },
+        };
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+export interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+export interface ChatResponse {
+    text: string;
+    finishReason: 'stop' | 'tool_calls' | 'length' | 'error';
+    usage: Usage;
+    costUsd: number;
+    model: string;
+    provider: string;
+    raw?: unknown;
+}
+export interface StreamChunk {
+    delta: string;
+    isFinal: boolean;
+    usage: Usage;
+    finishReason: string;
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ChatOptions {
+    model?: string;
+    provider?: string;
+    temperature?: number;
+    maxTokens?: number;
+    tools?: Array<{
+        config: {
+            name: string;
+        };
+    }>;
+}
+export interface StreamOptions {
+    model?: string;
+    provider?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface ToolChatOptions extends ChatOptions {
+    tools: Array<{
+        config: {
+            name: string;
+        };
+    }>;
+    maxToolIterations?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,3 @@
+// Type definitions for @im-bot/llm-client
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@im-bot/llm-client",
+  "version": "0.1.0",
+  "description": "Unified multi-provider LLM client for im-bot and Sun Shuhuan apps \u2014 DeepSeek, OpenRouter, MiniMax, Zhipu, and any OpenAI-compatible provider. TypeScript port of the Python im_bot_llm SDK.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/client.js",
+    "dist/client.d.ts",
+    "dist/config.js",
+    "dist/config.d.ts",
+    "dist/messages.js",
+    "dist/messages.d.ts",
+    "dist/tools.js",
+    "dist/tools.d.ts",
+    "dist/errors.js",
+    "dist/errors.d.ts",
+    "dist/responses.js",
+    "dist/responses.d.ts",
+    "dist/async-client.js",
+    "dist/async-client.d.ts",
+    "dist/types.js",
+    "dist/types.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit -p tsconfig.test.json && node --test --import tsx tests/*.test.ts",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "im-bot",
+    "llm",
+    "openai-compatible",
+    "deepseek",
+    "openrouter",
+    "minimax",
+    "zhipu",
+    "agent"
+  ]
+}