@minko-ai/minko 0.1.0 → 0.1.1

package/dist/providers/factory.js

@@ -0,0 +1,109 @@
+import { activeProvider } from "../config/store.js";
+import { HttpError } from "../util/errors.js";
+import { isRetryable } from "./retry.js";
+import { createAnthropicProvider } from "./anthropic.js";
+import { createOpenAiProvider } from "./openai.js";
+const BUILTIN_ANTHROPIC_ALIASES = {
+    sonnet: 'claude-sonnet-5-5',
+    opus: 'claude-opus-5-5',
+    haiku: 'claude-haiku-5-5',
+};
+export function createSingleProvider(config) {
+    return config.kind === 'anthropic'
+        ? createAnthropicProvider(config)
+        : createOpenAiProvider(config);
+}
+/** Applies `modelAliases` and built-in Anthropic short names. */
+export function resolveModelAlias(config, provider) {
+    const custom = config.modelAliases[provider.model];
+    if (custom) {
+        return custom;
+    }
+    if (provider.kind === 'anthropic') {
+        return BUILTIN_ANTHROPIC_ALIASES[provider.model.toLowerCase()] ?? provider.model;
+    }
+    return provider.model;
+}
+/** Provider failures that another provider may be able to handle. */
+export function shouldFallback(error) {
+    if (error instanceof HttpError) {
+        if (error.status === 401 || error.status === 403) {
+            return true;
+        }
+        return isRetryable(error);
+    }
+    return isRetryable(error);
+}
+export class FallbackProvider {
+    entries;
+    constructor(entries) {
+        this.entries = entries;
+    }
+    async stream(messages, tools, handlers, signal) {
+        let lastError;
+        for (let index = 0; index < this.entries.length; index += 1) {
+            const entry = this.entries[index];
+            try {
+                return await entry.provider.stream(messages, tools, handlers, signal);
+            }
+            catch (error) {
+                lastError = error;
+                if (signal.aborted || !shouldFallback(error) || index === this.entries.length - 1) {
+                    throw error;
+                }
+                const next = this.entries[index + 1];
+                handlers.onFallback?.({ from: entry.name, to: next.name, error });
+            }
+        }
+        throw lastError;
+    }
+}
+/**
+ * Builds the active provider plus its ordered fallback chain. Every provider
+ * keeps its own model; `modelOverride` only affects the primary.
+ */
+export function providerChain(config, modelOverride) {
+    const active = activeProvider(config);
+    if (!active) {
+        return null;
+    }
+    const seen = new Set();
+    const names = [];
+    for (const name of [active.name, ...config.fallbackProviders]) {
+        if (seen.has(name)) {
+            continue;
+        }
+        if (!config.providers[name]) {
+            continue;
+        }
+        seen.add(name);
+        names.push(name);
+    }
+    const entries = [];
+    let primaryModel = '';
+    for (const name of names) {
+        const providerConfig = config.providers[name];
+        const model = name === active.name && modelOverride
+            ? resolveModelAlias(config, { ...providerConfig, model: modelOverride })
+            : resolveModelAlias(config, providerConfig);
+        entries.push({
+            name,
+            provider: createSingleProvider({
+                ...providerConfig,
+                model,
+                maxTokens: config.maxTokens,
+            }),
+        });
+        if (name === active.name) {
+            primaryModel = model;
+        }
+    }
+    if (entries.length === 0) {
+        return null;
+    }
+    return {
+        name: active.name,
+        model: primaryModel || active.provider.model,
+        provider: entries.length === 1 ? entries[0].provider : new FallbackProvider(entries),
+    };
+}

package/dist/providers/openai.js

@@ -0,0 +1,182 @@
+import { HttpError } from "../util/errors.js";
+import { retryAfterFromHeaders, withRetry } from "./retry.js";
+import { sseEvents } from "./sse.js";
+export function toOpenAiMessages(messages, fillEmptyReasoning = false) {
+    return messages.map((message) => {
+        if (message.role === 'tool') {
+            return { role: 'tool', tool_call_id: message.toolCallId, content: message.content };
+        }
+        if (message.role === 'assistant') {
+            const out = {
+                role: 'assistant',
+                content: message.content.length > 0 ? message.content : null,
+            };
+            // Thinking models reject history that drops their reasoning.
+            if (message.reasoning && message.reasoning.length > 0) {
+                out.reasoning_content = message.reasoning;
+            }
+            else if (fillEmptyReasoning) {
+                out.reasoning_content = '';
+            }
+            if (message.toolCalls.length > 0) {
+                out.tool_calls = message.toolCalls.map((call) => ({
+                    id: call.id,
+                    type: 'function',
+                    function: { name: call.name, arguments: call.arguments },
+                }));
+            }
+            return out;
+        }
+        return { role: message.role, content: message.content };
+    });
+}
+export class OpenAiProvider {
+    config;
+    reasoningMode = false;
+    retry;
+    constructor(config, retry = {}) {
+        this.config = config;
+        this.retry = retry;
+    }
+    async request(messages, tools, signal, fillEmptyReasoning, onRetry) {
+        const body = {
+            model: this.config.model,
+            messages: toOpenAiMessages(messages, fillEmptyReasoning),
+            stream: true,
+            stream_options: { include_usage: true },
+        };
+        if (this.config.maxTokens && this.config.maxTokens > 0) {
+            body.max_tokens = this.config.maxTokens;
+        }
+        if (tools.length > 0) {
+            body.tools = tools.map((tool) => ({
+                type: 'function',
+                function: { name: tool.name, description: tool.description, parameters: tool.parameters },
+            }));
+            body.tool_choice = 'auto';
+        }
+        return await withRetry(async () => {
+            const headers = { 'content-type': 'application/json' };
+            if (this.config.apiKey.length > 0) {
+                headers.authorization = 'Bearer ' + this.config.apiKey;
+            }
+            const response = await fetch(joinUrl(this.config.baseUrl, 'chat/completions'), {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!response.ok) {
+                throw new HttpError(response.status, await response.text(), retryAfterFromHeaders(response.headers));
+            }
+            return response;
+        }, { ...this.retry, signal, onRetry });
+    }
+    async stream(messages, tools, handlers, signal) {
+        let response;
+        try {
+            response = await this.request(messages, tools, signal, this.reasoningMode, handlers.onRetry);
+        }
+        catch (error) {
+            if (error instanceof HttpError && error.status === 400 && /reasoning_content/i.test(error.body)) {
+                // Thinking models want the field on every assistant turn, even when a
+                // particular reply carried no reasoning text.
+                this.reasoningMode = true;
+                response = await this.request(messages, tools, signal, true, handlers.onRetry);
+            }
+            else {
+                throw error;
+            }
+        }
+        if (!response.body) {
+            throw new Error('服务端没有返回可读的流');
+        }
+        const textParts = [];
+        const reasoningParts = [];
+        const calls = new Map();
+        let usage = { input: 0, output: 0 };
+        for await (const event of sseEvents(response.body)) {
+            if (event.data === '[DONE]') {
+                break;
+            }
+            let payload;
+            try {
+                payload = JSON.parse(event.data);
+            }
+            catch {
+                continue;
+            }
+            const rawUsage = payload.usage;
+            if (rawUsage) {
+                const details = rawUsage.prompt_tokens_details;
+                const cached = numberOrZero(details?.cached_tokens)
+                    || numberOrZero(rawUsage.prompt_cache_hit_tokens);
+                const next = {
+                    input: numberOrZero(rawUsage.prompt_tokens),
+                    output: numberOrZero(rawUsage.completion_tokens),
+                };
+                if (cached > 0) {
+                    next.cached = cached;
+                }
+                usage = next;
+                handlers.onUsage?.(usage);
+            }
+            const choices = payload.choices;
+            const choice = choices && choices.length > 0 ? choices[0] : undefined;
+            if (!choice) {
+                continue;
+            }
+            const delta = (choice.delta ?? {});
+            const content = delta.content;
+            if (typeof content === 'string' && content.length > 0) {
+                textParts.push(content);
+                handlers.onText?.(content);
+            }
+            const reasoning = delta.reasoning_content;
+            if (typeof reasoning === 'string' && reasoning.length > 0) {
+                reasoningParts.push(reasoning);
+                handlers.onReasoning?.(reasoning);
+            }
+            const toolDeltas = delta.tool_calls;
+            if (Array.isArray(toolDeltas)) {
+                for (const raw of toolDeltas) {
+                    const index = typeof raw.index === 'number' ? raw.index : 0;
+                    const entry = calls.get(index) ?? { id: '', name: '', args: '' };
+                    if (typeof raw.id === 'string' && raw.id.length > 0) {
+                        entry.id = raw.id;
+                    }
+                    if (raw.function) {
+                        if (typeof raw.function.name === 'string') {
+                            entry.name += raw.function.name;
+                        }
+                        if (typeof raw.function.arguments === 'string') {
+                            entry.args += raw.function.arguments;
+                        }
+                    }
+                    calls.set(index, entry);
+                }
+            }
+        }
+        const toolCalls = [...calls.entries()]
+            .sort((a, b) => a[0] - b[0])
+            .flatMap(([index, entry]) => entry.name.length === 0
+            ? []
+            : [{ id: entry.id || 'call_' + index, name: entry.name, arguments: entry.args || '{}' }]);
+        return {
+            text: textParts.join(''),
+            reasoning: reasoningParts.join(''),
+            toolCalls,
+            usage,
+        };
+    }
+}
+function numberOrZero(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+export function joinUrl(baseUrl, suffix) {
+    const base = baseUrl.replace(/\/+$/, '');
+    return base + '/' + suffix.replace(/^\/+/, '');
+}
+export function createOpenAiProvider(config) {
+    return new OpenAiProvider(config);
+}

package/dist/providers/retry.js

@@ -0,0 +1,95 @@
+import { HttpError } from "../util/errors.js";
+/** HTTP statuses that are worth retrying. */
+export function isRetryable(error) {
+    if (error instanceof HttpError) {
+        if (error.status === 408 || error.status === 409 || error.status === 425 || error.status === 429) {
+            return true;
+        }
+        return error.status >= 500;
+    }
+    if (error instanceof Error) {
+        if (error.name === 'AbortError') {
+            return false;
+        }
+        return error instanceof TypeError
+            || /fetch failed|ECONN|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket hang up/i.test(error.message);
+    }
+    return false;
+}
+export function retryAfterMs(error) {
+    return error instanceof HttpError ? error.retryAfterMs : undefined;
+}
+/** Reads `Retry-After` as seconds or an HTTP date. */
+export function retryAfterFromHeaders(headers) {
+    const raw = headers.get('retry-after');
+    if (!raw) {
+        return undefined;
+    }
+    const seconds = Number(raw.trim());
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.floor(seconds * 1000);
+    }
+    const date = Date.parse(raw);
+    if (Number.isNaN(date)) {
+        return undefined;
+    }
+    return Math.max(0, date - Date.now());
+}
+/**
+ * Runs an operation with retries for transient provider failures.
+ * `Retry-After` wins over the computed backoff but is still capped.
+ */
+export async function withRetry(operation, options = {}) {
+    const maxRetries = options.maxRetries ?? 3;
+    const initialDelayMs = options.initialDelayMs ?? 500;
+    const maxDelayMs = options.maxDelayMs ?? 8000;
+    const random = options.random ?? Math.random;
+    const sleep = options.sleep ?? ((ms) => abortableSleep(ms, options.signal));
+    let attempt = 0;
+    for (;;) {
+        if (options.signal?.aborted) {
+            throw abortError();
+        }
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (attempt >= maxRetries || !isRetryable(error)) {
+                throw error;
+            }
+            attempt += 1;
+            const base = retryAfterMs(error) ?? Math.min(maxDelayMs, initialDelayMs * 2 ** (attempt - 1));
+            const jitter = Math.floor(base * 0.2 * random());
+            const delayMs = Math.min(maxDelayMs, base + jitter);
+            options.onRetry?.({ attempt, delayMs, error });
+            await sleep(delayMs);
+        }
+    }
+}
+function abortError() {
+    const error = new Error('已中断');
+    error.name = 'AbortError';
+    return error;
+}
+function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        let onAbort;
+        const timer = setTimeout(() => {
+            if (onAbort) {
+                signal?.removeEventListener('abort', onAbort);
+            }
+            resolve();
+        }, ms);
+        if (signal) {
+            onAbort = () => {
+                clearTimeout(timer);
+                reject(abortError());
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}

package/dist/providers/sse.js

@@ -0,0 +1,67 @@
+/**
+ * Parses a Server-Sent Events body. Handles CRLF, split chunks and comments.
+ */
+export async function* sseEvents(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let event = '';
+    let data = [];
+    const flush = () => {
+        if (data.length === 0) {
+            event = '';
+            return null;
+        }
+        const payload = { event: event || 'message', data: data.join('\n') };
+        event = '';
+        data = [];
+        return payload;
+    };
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            let index = buffer.indexOf('\n');
+            while (index >= 0) {
+                let line = buffer.slice(0, index);
+                buffer = buffer.slice(index + 1);
+                if (line.endsWith('\r')) {
+                    line = line.slice(0, -1);
+                }
+                if (line.length === 0) {
+                    const parsed = flush();
+                    if (parsed) {
+                        yield parsed;
+                    }
+                }
+                else if (line.startsWith(':')) {
+                    // heartbeat / comment
+                }
+                else if (line.startsWith('data:')) {
+                    data.push(line.slice(5).replace(/^ /, ''));
+                }
+                else if (line.startsWith('event:')) {
+                    event = line.slice(6).trim();
+                }
+                index = buffer.indexOf('\n');
+            }
+        }
+        buffer += decoder.decode();
+        if (buffer.trim().length > 0) {
+            const line = buffer.replace(/\r$/, '');
+            if (line.startsWith('data:')) {
+                data.push(line.slice(5).replace(/^ /, ''));
+            }
+        }
+        const tail = flush();
+        if (tail) {
+            yield tail;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/providers/types.js

@@ -0,0 +1,10 @@
+export function parseToolArguments(raw) {
+    if (raw.trim().length === 0) {
+        return {};
+    }
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('工具参数必须是 JSON 对象');
+    }
+    return parsed;
+}

package/dist/rag/embeddings.js

@@ -0,0 +1,171 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { activeProvider } from "../config/store.js";
+import { minkoHome } from "../config/paths.js";
+import { HttpError } from "../util/errors.js";
+import { retryAfterFromHeaders, withRetry } from "../providers/retry.js";
+const DEFAULT_BATCH_SIZE = 32;
+const REQUEST_TIMEOUT_MS = 60_000;
+/** OpenAI-compatible /embeddings client with batching and retries. */
+export class EmbeddingClient {
+    model;
+    baseUrl;
+    apiKey;
+    batchSize;
+    dimensions;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.apiKey = options.apiKey ?? '';
+        this.model = options.model;
+        this.batchSize = Math.max(1, Math.min(128, options.batchSize ?? DEFAULT_BATCH_SIZE));
+        this.dimensions = options.dimensions;
+    }
+    async embed(texts) {
+        const out = [];
+        for (let index = 0; index < texts.length; index += this.batchSize) {
+            const batch = texts.slice(index, index + this.batchSize);
+            out.push(...await this.request(batch));
+        }
+        return out;
+    }
+    async request(input) {
+        return await withRetry(async () => {
+            const headers = { 'content-type': 'application/json' };
+            if (this.apiKey.length > 0) {
+                headers.authorization = 'Bearer ' + this.apiKey;
+            }
+            const response = await fetch(joinUrl(this.baseUrl, 'embeddings'), {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    model: this.model,
+                    input,
+                    ...(this.dimensions ? { dimensions: this.dimensions } : {}),
+                }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                throw new HttpError(response.status, await response.text(), retryAfterFromHeaders(response.headers));
+            }
+            const payload = await response.json();
+            const data = Array.isArray(payload.data) ? payload.data.slice() : [];
+            data.sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+            if (data.length !== input.length) {
+                throw new Error('embedding 返回数量不匹配：期望 ' + input.length + '，实际 ' + data.length);
+            }
+            return data.map((item) => {
+                if (!Array.isArray(item.embedding) || item.embedding.length === 0) {
+                    throw new Error('embedding 返回了空向量');
+                }
+                return new Float32Array(item.embedding);
+            });
+        }, { maxRetries: 2, initialDelayMs: 500, maxDelayMs: 4_000 });
+    }
+}
+/** On-disk cache keyed by content hash; avoids re-embedding unchanged chunks. */
+export class EmbeddingCache {
+    file;
+    model;
+    entries = new Map();
+    constructor(file, model) {
+        this.file = file;
+        this.model = model;
+    }
+    load() {
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+            if (raw.model !== this.model) {
+                return;
+            }
+            if (raw.entries === null || typeof raw.entries !== 'object') {
+                return;
+            }
+            for (const [hash, encoded] of Object.entries(raw.entries)) {
+                if (typeof encoded === 'string') {
+                    this.entries.set(hash, decodeVector(encoded));
+                }
+            }
+        }
+        catch {
+            // A missing or corrupt cache merely means re-embedding.
+        }
+    }
+    get(hash) {
+        return this.entries.get(hash);
+    }
+    set(hash, vector) {
+        if (this.entries.size >= 20_000) {
+            return;
+        }
+        this.entries.set(hash, vector);
+    }
+    save() {
+        try {
+            fs.mkdirSync(path.dirname(this.file), { recursive: true });
+            const entries = {};
+            for (const [hash, vector] of this.entries) {
+                entries[hash] = encodeVector(vector);
+            }
+            const temporary = this.file + '.tmp';
+            const payload = JSON.stringify({ model: this.model, entries });
+            fs.writeFileSync(temporary, payload, 'utf8');
+            try {
+                fs.renameSync(temporary, this.file);
+            }
+            catch {
+                // Windows may refuse to replace an existing file; write directly.
+                fs.writeFileSync(this.file, payload, 'utf8');
+                try {
+                    fs.unlinkSync(temporary);
+                }
+                catch { /* best effort */ }
+            }
+        }
+        catch {
+            // The cache is an optimization; never break retrieval over it.
+        }
+    }
+}
+/**
+ * Resolves embedding settings. If baseUrl/apiKey are omitted, the active
+ * OpenAI-compatible provider is reused, so one API key is enough.
+ */
+export function resolveEmbedding(config, root, cacheDir) {
+    const settings = config?.rag?.embeddings;
+    if (!settings || settings.enabled === false) {
+        return null;
+    }
+    const active = config ? activeProvider(config) : null;
+    const provider = active && active.provider.kind === 'openai' ? active.provider : null;
+    const baseUrl = settings.baseUrl ?? provider?.baseUrl ?? '';
+    if (baseUrl.length === 0) {
+        return null;
+    }
+    const apiKey = settings.apiKey ?? provider?.apiKey ?? '';
+    const model = settings.model ?? 'text-embedding-3-small';
+    const embedder = new EmbeddingClient({
+        baseUrl,
+        apiKey,
+        model,
+        batchSize: settings.batchSize,
+        dimensions: settings.dimensions,
+    });
+    const key = crypto.createHash('sha1')
+        .update(path.resolve(root) + '|' + model)
+        .digest('hex')
+        .slice(0, 16);
+    const cache = new EmbeddingCache(path.join(cacheDir ?? minkoHome(), 'rag', key + '.json'), model);
+    cache.load();
+    return { embedder, cache, maxChunks: settings.maxChunks ?? 1_000 };
+}
+function joinUrl(baseUrl, suffix) {
+    return baseUrl.replace(/\/+$/, '') + '/' + suffix.replace(/^\/+/, '');
+}
+function encodeVector(vector) {
+    return Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength).toString('base64');
+}
+function decodeVector(encoded) {
+    const buffer = Buffer.from(encoded, 'base64');
+    return new Float32Array(buffer.buffer, buffer.byteOffset, Math.floor(buffer.byteLength / 4));
+}