hyacinth-ai 0.9.6

package/dist/local-model/llamacpp-provider.js

@@ -0,0 +1,379 @@
+import { withRetry } from '../provider/retry.js';
+// ---------------------------------------------------------------------------
+// LlamaCppProvider
+// ---------------------------------------------------------------------------
+/**
+ * LlamaCppProvider — 通过原生 fetch + SSE 调用 llama-server 的 OpenAI 兼容 API。
+ *
+ * 与 LocalProvider 的区别：
+ *  - 不依赖 openai npm 包，使用原生 fetch
+ *  - 提供健康检查（checkHealth）
+ *  - 提供 Adapter（LoRA）管理
+ *  - 暴露 getCapabilities()
+ *  - ProviderType 为 'llamacpp'
+ */
+export class LlamaCppProvider {
+    endpoint;
+    model;
+    maxTokens;
+    maxContextTokens;
+    loadedAdapters = new Map();
+    constructor(opts = {}) {
+        this.endpoint = opts.endpoint ?? 'http://127.0.0.1:8080';
+        this.model = opts.model ?? 'llama-3-8b-q4_k_m';
+        this.maxTokens = opts.maxTokens ?? 4096;
+        this.maxContextTokens = opts.maxContextTokens ?? 8192;
+    }
+    // ---- Provider 元信息 ----
+    getProviderType() {
+        return 'llamacpp';
+    }
+    getModel() {
+        return this.model;
+    }
+    getCapabilities() {
+        return {
+            toolCalling: true,
+            streaming: true,
+            adapterSupport: true,
+            maxContextTokens: this.maxContextTokens,
+            isLocal: true,
+            vision: false,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // 健康检查
+    // -----------------------------------------------------------------------
+    /**
+     * 检查 llama-server 是否正常运行。
+     *
+     * 发送 GET {endpoint}/health，解析响应中的 status / model 字段。
+     * 构造函数中不自动调用，由调用方按需使用。
+     *
+     * @returns { ok: boolean, model?: string }
+     */
+    async checkHealth() {
+        try {
+            const response = await fetch(`${this.endpoint}/health`, {
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!response.ok) {
+                return { ok: false };
+            }
+            const data = (await response.json());
+            return {
+                ok: data.status === 'ok' || data.status === 'healthy' || response.status === 200,
+                model: data.model,
+            };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Adapter 管理（llama-server 的 LoRA API）
+    // -----------------------------------------------------------------------
+    /**
+     * 通过 llama-server 的 /v1/lora 端点动态加载 LoRA Adapter。
+     *
+     * @param name - Adapter 标识名称
+     * @param path - Adapter 权重文件路径
+     */
+    async loadAdapter(name, path) {
+        try {
+            const response = await fetch(`${this.endpoint}/v1/lora`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ name, path }),
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => '');
+                throw new Error(`Failed to load adapter: HTTP ${response.status}${body ? ` — ${body}` : ''}`);
+            }
+            this.loadedAdapters.set(name, path);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[LlamaCppProvider] Failed to load adapter '${name}': ${message}. ` +
+                'Make sure llama-server supports the /v1/lora endpoint.');
+            throw error;
+        }
+    }
+    /**
+     * 卸载指定的 Adapter（从内部 Map 移除）。
+     *
+     * @param name - Adapter 名称
+     */
+    async unloadAdapter(name) {
+        this.loadedAdapters.delete(name);
+    }
+    /**
+     * 列出当前已加载的 Adapter 名称。
+     */
+    async listAdapters() {
+        return Array.from(this.loadedAdapters.keys());
+    }
+    // -----------------------------------------------------------------------
+    // 流式对话 — createStream
+    // -----------------------------------------------------------------------
+    async *createStream(messages, tools) {
+        const body = {
+            model: this.model,
+            messages: this.convertMessages(messages),
+            max_tokens: this.maxTokens,
+            stream: true,
+        };
+        if (tools && tools.length > 0) {
+            body.tools = this.convertTools(tools);
+        }
+        const toolCallAccumulators = new Map();
+        // 发起请求（含重试）
+        let response;
+        try {
+            response = await withRetry(() => fetch(`${this.endpoint}/v1/chat/completions`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            }), {}, 'llamacpp.fetch');
+        }
+        catch (error) {
+            throw new Error(`Cannot connect to llama.cpp server at ${this.endpoint}. ` +
+                'Make sure llama-server is running.');
+        }
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => '');
+            throw new Error(`llama.cpp API error (HTTP ${response.status}): ${errorText || response.statusText}`);
+        }
+        if (!response.body) {
+            throw new Error('llama.cpp server returned an empty response body.');
+        }
+        // 消费 SSE 流
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                // 最后一段可能不完整，保留到下次拼接
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || !trimmed.startsWith('data:'))
+                        continue;
+                    const dataStr = trimmed.slice(5).trimStart(); // 去掉 "data:" 及可能的空格
+                    if (dataStr === '[DONE]')
+                        continue;
+                    let data;
+                    try {
+                        data = JSON.parse(dataStr);
+                    }
+                    catch {
+                        // 无效 JSON 行，跳过
+                        continue;
+                    }
+                    const choice = data.choices?.[0];
+                    if (!choice) {
+                        // usage 可能出现在没有 choices 的 chunk 中
+                        if (data.usage) {
+                            yield {
+                                type: 'USAGE',
+                                input_tokens: data.usage.prompt_tokens ?? 0,
+                                output_tokens: data.usage.completion_tokens ?? 0,
+                            };
+                        }
+                        continue;
+                    }
+                    const delta = choice.delta;
+                    // ---- usage（某些实现放在 choice 所在的 chunk 中） ----
+                    if (data.usage) {
+                        yield {
+                            type: 'USAGE',
+                            input_tokens: data.usage.prompt_tokens ?? 0,
+                            output_tokens: data.usage.completion_tokens ?? 0,
+                        };
+                    }
+                    // ---- reasoning_content（thinking 输出） ----
+                    if (delta?.reasoning_content) {
+                        yield { type: 'THINKING', content: delta.reasoning_content };
+                    }
+                    // ---- 文本内容 ----
+                    if (delta?.content) {
+                        yield { type: 'TEXT', content: delta.content };
+                    }
+                    // ---- tool_calls ----
+                    if (delta?.tool_calls) {
+                        for (const tc of delta.tool_calls) {
+                            const idx = tc.index;
+                            if (!toolCallAccumulators.has(idx)) {
+                                toolCallAccumulators.set(idx, {
+                                    id: tc.id ?? '',
+                                    name: tc.function?.name ?? '',
+                                    arguments: '',
+                                });
+                            }
+                            const acc = toolCallAccumulators.get(idx);
+                            if (tc.id)
+                                acc.id = tc.id;
+                            if (tc.function?.name)
+                                acc.name = tc.function.name;
+                            if (tc.function?.arguments)
+                                acc.arguments += tc.function.arguments;
+                        }
+                    }
+                    // ---- finish_reason → 输出累积完成的 tool call ----
+                    if (choice.finish_reason) {
+                        for (const [, acc] of toolCallAccumulators) {
+                            let input = {};
+                            try {
+                                input = JSON.parse(acc.arguments || '{}');
+                            }
+                            catch {
+                                // JSON 解析失败时保留空对象
+                            }
+                            yield {
+                                type: 'TOOL_USE',
+                                id: acc.id,
+                                name: acc.name,
+                                input,
+                            };
+                        }
+                        toolCallAccumulators.clear();
+                        yield { type: 'STOP', reason: choice.finish_reason };
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    // -----------------------------------------------------------------------
+    // 消息转换
+    // -----------------------------------------------------------------------
+    /**
+     * 将内部 Message[] 转换为 OpenAI 兼容格式的普通对象数组。
+     *
+     * 转换规则：
+     * - system / user 角色 → { role, content }（文本拼接）
+     * - user 消息中的 tool_result → 独立的 { role: 'tool', tool_call_id, content } 消息
+     * - assistant 角色 → { role: 'assistant', content, tool_calls }
+     * - cache_control（ephemeral）保留在消息上
+     */
+    convertMessages(messages) {
+        const result = [];
+        for (const msg of messages) {
+            const blocks = Array.isArray(msg.content) ? msg.content : [msg.content];
+            if (msg.role === 'assistant') {
+                const textParts = [];
+                const toolCalls = [];
+                for (const block of blocks) {
+                    if (block.type === 'text') {
+                        textParts.push(block.text);
+                    }
+                    else if (block.type === 'tool_use') {
+                        toolCalls.push({
+                            id: block.id,
+                            type: 'function',
+                            function: {
+                                name: block.name,
+                                arguments: JSON.stringify(block.input),
+                            },
+                        });
+                    }
+                }
+                const assistantMsg = {
+                    role: 'assistant',
+                    content: textParts.length > 0 ? textParts.join('') : null,
+                };
+                if (toolCalls.length > 0) {
+                    assistantMsg.tool_calls = toolCalls;
+                }
+                result.push(assistantMsg);
+            }
+            else {
+                // system 或 user 角色
+                const textParts = [];
+                const toolResults = [];
+                let hasCacheControl = false;
+                for (const block of blocks) {
+                    if (block.type === 'text') {
+                        textParts.push(block.text);
+                        if (block.cache_control?.type === 'ephemeral') {
+                            hasCacheControl = true;
+                        }
+                    }
+                    else if (block.type === 'tool_result') {
+                        toolResults.push({
+                            role: 'tool',
+                            tool_call_id: block.tool_use_id,
+                            content: block.content,
+                        });
+                    }
+                }
+                if (textParts.length > 0) {
+                    const userMsg = {
+                        role: msg.role,
+                        content: textParts.join(''),
+                    };
+                    if (hasCacheControl) {
+                        userMsg.cache_control = { type: 'ephemeral' };
+                    }
+                    result.push(userMsg);
+                }
+                result.push(...toolResults);
+            }
+        }
+        return result;
+    }
+    // -----------------------------------------------------------------------
+    // 工具定义转换
+    // -----------------------------------------------------------------------
+    /**
+     * 将 ToolDefinition[] 转换为 OpenAI function calling 格式。
+     *
+     * { name, description, input_schema }
+     *   → { type: 'function', function: { name, description, parameters: input_schema } }
+     */
+    convertTools(tools) {
+        return tools.map((tool) => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.input_schema,
+            },
+        }));
+    }
+}
+// ---------------------------------------------------------------------------
+// 便捷工厂函数
+// ---------------------------------------------------------------------------
+/**
+ * 创建 LlamaCppProvider 实例。
+ *
+ * @param opts - 可选配置
+ * @returns LlamaCppProvider
+ *
+ * @example
+ * ```ts
+ * const provider = createLlamaCppProvider({
+ *   endpoint: 'http://127.0.0.1:8080',
+ *   model: 'qwen2.5-7b-q4_k_m',
+ * });
+ *
+ * const health = await provider.checkHealth();
+ * if (!health.ok) throw new Error('llama-server not available');
+ *
+ * for await (const event of provider.createStream(messages)) {
+ *   // handle event
+ * }
+ * ```
+ */
+export function createLlamaCppProvider(opts) {
+    return new LlamaCppProvider(opts);
+}
+//# sourceMappingURL=llamacpp-provider.js.map

package/dist/local-model/model-bridge.d.ts

@@ -0,0 +1,48 @@
+import { EventEmitter } from 'node:events';
+import { ProcessManager } from '../lifecycle/manager.js';
+import type { ProcessState } from '../lifecycle/interface.js';
+import type { ModelEntry, ModelRegisterOptions, RunningModelInfo } from './types.js';
+export type { RunningModelInfo };
+declare interface ModelBridgeEvents {
+    'model-starting': [string];
+    'model-running': [RunningModelInfo];
+    'model-stopped': [string];
+    'model-error': [string, string];
+    'active-changed': [string | null];
+    'all-stopped': [];
+}
+/**
+ * 模型桥接层 — 连接 ModelRegistry 与 llama-server 进程
+ */
+export declare class ModelBridge extends EventEmitter<ModelBridgeEvents> {
+    private managers;
+    private lastStartedModel;
+    private runningPorts;
+    private registry;
+    private llamaServerPath;
+    constructor(llamaServerPath?: string);
+    startAll(): Promise<RunningModelInfo[]>;
+    start(name: string): Promise<RunningModelInfo | null>;
+    stop(name: string): Promise<void>;
+    switch(toName: string, options?: {
+        stopOthers?: boolean;
+    }): Promise<RunningModelInfo | null>;
+    stopAll(): Promise<void>;
+    getAllStatus(): Array<{
+        name: string;
+        state: ProcessState;
+        pid: number | null;
+    }>;
+    getActiveModel(): string | null;
+    getProcessManager(name: string): ProcessManager | undefined;
+    getAllProcessManagers(): ProcessManager[];
+    isRunning(name: string): boolean;
+    registerModel(options: ModelRegisterOptions): ModelEntry;
+    unregisterModel(name: string): boolean;
+    private buildConfig;
+    private resolveOllamaPath;
+    private findAvailablePort;
+    private extractPortFromConfig;
+    private toRunningInfo;
+}
+//# sourceMappingURL=model-bridge.d.ts.map

package/dist/local-model/model-bridge.js

@@ -0,0 +1,256 @@
+import { EventEmitter } from 'node:events';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ProcessManager } from '../lifecycle/manager.js';
+import { ModelRegistry } from './model-registry.js';
+/**
+ * 模型桥接层 — 连接 ModelRegistry 与 llama-server 进程
+ */
+export class ModelBridge extends EventEmitter {
+    managers = new Map();
+    lastStartedModel = null;
+    runningPorts = new Map();
+    registry;
+    llamaServerPath;
+    constructor(llamaServerPath) {
+        super();
+        this.registry = ModelRegistry.getInstance();
+        if (llamaServerPath && existsSync(llamaServerPath)) {
+            this.llamaServerPath = llamaServerPath;
+        }
+        else {
+            const candidates = [
+                join(process.cwd(), 'libs', 'llama.cpp', 'build', 'bin', 'Release', 'llama-server.exe'),
+                join(process.cwd(), 'libs', 'llama.cpp', 'build', 'bin', 'llama-server'),
+                join(process.cwd(), 'libs', 'llama.cpp', 'llama-server.exe'),
+                join(process.cwd(), 'libs', 'llama.cpp', 'llama-server'),
+                'llama-server',
+                'llama-server.exe',
+            ];
+            const found = candidates.find((c) => existsSync(c));
+            this.llamaServerPath = found ?? 'llama-server';
+        }
+    }
+    // ── 生命周期 ──
+    async startAll() {
+        const models = this.registry.list().filter((m) => m.enabled);
+        const results = [];
+        for (const model of models) {
+            const info = await this.start(model.name);
+            if (info)
+                results.push(info);
+        }
+        return results;
+    }
+    async start(name) {
+        const model = this.registry.find(name);
+        if (!model)
+            return null;
+        const existing = this.managers.get(name);
+        if (existing) {
+            if (existing.getState() === 'running') {
+                return this.toRunningInfo(model);
+            }
+            await existing.start();
+            return this.toRunningInfo(model);
+        }
+        const config = this.buildConfig(model);
+        const actualPort = this.extractPortFromConfig(config);
+        this.runningPorts.set(name, actualPort);
+        const callbacks = {
+            onStateChange: (_name, _from, to) => {
+                if (to === 'running') {
+                    this.lastStartedModel = name;
+                    this.emit('active-changed', name);
+                    this.emit('model-running', this.toRunningInfo(model));
+                }
+                else if (to === 'stopped' || to === 'failed' || to === 'crashed') {
+                    if (this.lastStartedModel === name) {
+                        this.lastStartedModel = null;
+                        this.emit('active-changed', null);
+                    }
+                    if (to === 'failed' || to === 'crashed') {
+                        this.emit('model-error', name, `Process ${to}`);
+                    }
+                }
+            },
+            onCrash: (_name, exitCode) => {
+                this.emit('model-error', name, `Crashed exit=${exitCode}`);
+            },
+        };
+        const pm = new ProcessManager(config, callbacks);
+        this.managers.set(name, pm);
+        this.emit('model-starting', name);
+        await pm.start();
+        if (pm.getState() !== 'running') {
+            this.emit('model-error', name, 'Failed to start');
+            return null;
+        }
+        return this.toRunningInfo(model);
+    }
+    async stop(name) {
+        const pm = this.managers.get(name);
+        if (!pm)
+            return;
+        await pm.stop();
+        this.managers.delete(name);
+        this.runningPorts.delete(name);
+        this.emit('model-stopped', name);
+        if (this.lastStartedModel === name) {
+            this.lastStartedModel = null;
+            this.emit('active-changed', null);
+        }
+    }
+    async switch(toName, options) {
+        const target = this.registry.find(toName);
+        if (!target)
+            return null;
+        if (options?.stopOthers) {
+            const others = Array.from(this.managers.keys()).filter((n) => n !== toName);
+            await Promise.all(others.map((n) => this.stop(n)));
+        }
+        else if (this.lastStartedModel && this.lastStartedModel !== toName) {
+            await this.stop(this.lastStartedModel);
+        }
+        return this.start(toName);
+    }
+    async stopAll() {
+        const stops = Array.from(this.managers.keys()).map((name) => this.stop(name));
+        await Promise.all(stops);
+        this.lastStartedModel = null;
+        this.emit('active-changed', null);
+        this.emit('all-stopped');
+    }
+    // ── 状态查询 ──
+    getAllStatus() {
+        return Array.from(this.managers.entries()).map(([name, pm]) => ({
+            name,
+            state: pm.getState(),
+            pid: pm.getStatus().pid,
+        }));
+    }
+    getActiveModel() {
+        return this.lastStartedModel;
+    }
+    getProcessManager(name) {
+        return this.managers.get(name);
+    }
+    getAllProcessManagers() {
+        return Array.from(this.managers.values());
+    }
+    isRunning(name) {
+        const pm = this.managers.get(name);
+        return pm ? pm.getState() === 'running' : false;
+    }
+    // ── 注册/注销 ──
+    registerModel(options) {
+        return this.registry.register(options);
+    }
+    unregisterModel(name) {
+        if (this.isRunning(name)) {
+            this.stop(name);
+        }
+        return this.registry.unregister(name);
+    }
+    // ── 内部 ──
+    buildConfig(model) {
+        const port = model.port ?? this.findAvailablePort(model.backend);
+        const host = model.host ?? '127.0.0.1';
+        // Ollama backend
+        if (model.backend === 'ollama') {
+            return {
+                name: model.name,
+                command: this.resolveOllamaPath(),
+                args: ['serve'],
+                autoRestart: false,
+                healthCheck: {
+                    url: `http://${host}:${port}/api/tags`,
+                    intervalMs: 5000,
+                    timeoutMs: 3000,
+                    maxRetries: 5,
+                },
+            };
+        }
+        // llama.cpp backend (default)
+        const args = [
+            '-m', model.modelPath,
+            '--host', host,
+            '--port', String(port),
+        ];
+        if (model.ctxSize) {
+            args.push('-c', String(model.ctxSize));
+        }
+        if (model.nGpuLayers && model.nGpuLayers > 0) {
+            args.push('-ngl', String(model.nGpuLayers));
+        }
+        return {
+            name: model.name,
+            command: this.llamaServerPath,
+            args,
+            autoRestart: false,
+            healthCheck: {
+                url: `http://${host}:${port}/health`,
+                intervalMs: 5000,
+                timeoutMs: 3000,
+                maxRetries: 5,
+            },
+        };
+    }
+    resolveOllamaPath() {
+        const candidates = [
+            join(process.cwd(), 'libs', 'ollama', 'ollama.exe'),
+            join(process.cwd(), 'libs', 'ollama', 'ollama'),
+            'ollama',
+            'ollama.exe',
+        ];
+        const found = candidates.find((c) => existsSync(c));
+        return found ?? 'ollama';
+    }
+    findAvailablePort(backend) {
+        const used = new Set();
+        for (const [, pm] of this.managers) {
+            const hc = pm.config.healthCheck;
+            if (hc?.url) {
+                const m = hc.url.match(/:(\d+)/);
+                if (m)
+                    used.add(parseInt(m[1], 10));
+            }
+        }
+        for (const e of this.registry.list()) {
+            if (e.port)
+                used.add(e.port);
+        }
+        const startPort = backend === 'ollama' ? 11434 : 8080;
+        const maxPort = startPort + 20;
+        for (let p = startPort; p < maxPort; p++) {
+            if (!used.has(p))
+                return p;
+        }
+        return startPort;
+    }
+    extractPortFromConfig(config) {
+        if (!config.args)
+            return 8080;
+        const portIdx = config.args.indexOf('--port');
+        if (portIdx !== -1 && portIdx + 1 < config.args.length) {
+            return parseInt(config.args[portIdx + 1], 10);
+        }
+        return 8080;
+    }
+    toRunningInfo(model) {
+        const pm = this.managers.get(model.name);
+        const port = this.runningPorts.get(model.name) ?? model.port ?? 8080;
+        const host = model.host ?? '127.0.0.1';
+        return {
+            name: model.name,
+            modelFile: model.modelFile,
+            backend: model.backend,
+            port,
+            host,
+            state: pm ? pm.getState() : 'stopped',
+            pid: pm ? pm.getStatus().pid : null,
+            baseUrl: `http://${host}:${port}/v1`,
+        };
+    }
+}
+//# sourceMappingURL=model-bridge.js.map