@keo-ai/axiom 0.1.0

package/README.md

@@ -0,0 +1,187 @@
+<div align="center">
+
+# ⚡ AXIOM
+
+> **The execution foundation for LLM agents.**
+
+
+**Axiom 不是编排框架。它是大模型调用工具的「底盘」**
+
+
+</div>
+
+---
+
+## 什么是 Axiom
+
+Axiom 是 **keo** 的 LLM 底座库。它不碰业务编排（意图路由、节点流、客服话术），只解决一个问题：
+
+> **当模型说「我要调用工具」时，确保它真的调了、真的拿到了结果、并且基于事实继续推理。**
+
+上层只管写业务节点（Conductor / 意图层 / 多模态预处理），Axiom 负责把 LLM → 工具 → 结果 → LLM 的循环跑稳。
+
+```
+┌────────────────────────────────────────────┐
+│              你的项目层（业务）              │
+│   意图路由 · 节点编排 · 客服话术 · 业务Tool   │
+├────────────────────────────────────────────┤
+│                 ⚡ AXIOM                    │
+│  ┌─────────┐ ┌──────────┐ ┌─────────────┐ │
+│  │ LLM调用  │ │ Harness  │ │   记忆系统   │ │
+│  │  故障转移 │ │ 状态机   │ │  · Faiss    │ │
+│  │  流式输出 │ │ 副作用   │ │  · 槽位     │ │
+│  └─────────┘ │ 传播     │ │  · 语义     │ │
+│              │ 幻觉防控 │ └─────────────┘ │
+│              └──────────┘ ┌─────────────┐ │
+│                         │  RAG基础      │ │
+│                         │  Embedding   │ │
+│                         └─────────────┘ │
+└────────────────────────────────────────────┘
+```
+
+## 架构边界
+
+**Axiom 做：**
+- ✅ LLM 统一调用 + Provider 故障转移
+- ✅ Function Call Loop 的驱动、记录、校验、副作用传播
+- ✅ 记忆系统的抽象与基础实现
+- ✅ RAG 基础（Embedding / 向量检索）
+- ✅ 基础配置中心
+
+**Axiom 不做：**
+- ❌ 意图识别与路由
+- ❌ 业务节点编排（Conductor / DAG）
+- ❌ 多模态预处理（语音/图片转文本）
+- ❌ 消息队列与削峰
+- ❌ 具体业务 Tool 的实现逻辑
+- ❌ Provider 排序策略（成本/能力/速度）
+
+> 上层写业务，Axiom 跑底盘。
+
+---
+
+## Predict 模块（LLM 调用）
+
+Predict 是 Axiom 的 LLM 调用层。它封装了 Provider 连接、请求组装、故障转移和返回解析，让上层只需关心「用什么模型、传什么消息」。
+
+### 快速开始
+
+设置环境变量（百炼）：
+
+```bash
+export BAILIAN_API_KEY="your-api-key"
+```
+
+一行调用：
+
+```ts
+import { LLM } from '@keo-ai/axiom';
+
+const res = await LLM.predict({ model: 'qwen3.7-max', prompt: '你好' });
+console.log(res.content);
+```
+
+### API 概览
+
+| 方法 | 用途 | 返回类型 |
+|---|---|---|
+| `LLM.predict(config)` | 单轮快速调用，自动构建 user message | 依 `responseFormat` 而定（见下） |
+| `LLM.predictWithMessages(messages, config)` | 传入完整消息列表，适用于多轮对话 | 同上 |
+| `LLM.streamPredict(config)` | 流式调用，逐块返回内容 | `AsyncGenerator<StreamChunk>` |
+| `LLM.streamPredictWithMessages(messages, config)` | 流式 + 自定义消息列表 | `AsyncGenerator<StreamChunk>` |
+
+### responseFormat 与返回类型
+
+`predict` 和 `predictWithMessages` 的返回类型由 `responseFormat` 决定：
+
+| `responseFormat` | 返回值 | 说明 |
+|---|---|---|
+| `'text'` | `string` | 直接返回模型输出的文本 |
+| `'json'` | `any` | 自动 `JSON.parse` |
+| 未设置 | `LLMResponse` | 完整响应（含 `content`、`usage`、`model`） |
+
+```ts
+// text → string
+const text = await LLM.predict({ model: 'qwen3.7-max', prompt: '讲个故事', responseFormat: 'text' });
+
+// json → 自动解析为对象
+const obj = await LLM.predict({
+  model: 'qwen3.7-max',
+  prompt: '生成一个 JSON',
+  responseFormat: 'json',
+});
+console.log(obj.name);
+```
+
+### Provider 配置
+
+设置环境变量即可，无需代码改动。
+
+```bash
+BAILIAN_API_KEY           # 必填
+BAILIAN_BASE_URL          # 可选，默认 https://dashscope.aliyuncs.com/compatible-mode/v1
+BAILIAN_DEFAULT_MODEL     # 可选，默认 qwen3.7-max
+```
+
+### 故障转移
+
+Predictor 内部按模型查询 `MODEL_REGISTRY`，获取候选 Provider 队列，再通过 `provider.supports(model)` 做二次校验。当某个 Provider 失败或不支持该模型时，自动尝试下一个，直到成功或全部失败。
+
+全部失败时抛出汇总错误：`All providers failed: bailian: HTTP 500...; bailian: timeout...`
+
+### 流式调用
+
+流式版本返回 `AsyncGenerator<StreamChunk>`，迭代即可逐块消费：
+
+```ts
+for await (const chunk of LLM.streamPredict({ model: 'qwen3.7-max', prompt: '讲个故事' })) {
+  if (chunk.type === 'content') {
+    process.stdout.write(chunk.delta);
+  }
+}
+```
+
+### 模型列表
+
+当前支持的模型（通过 `Model` 类型枚举）：
+
+- `qwen3.7-max`
+- `qwen-plus`
+- `qwen-turbo`
+- `qwq-plus`
+- `deepseek-v4-pro`
+- `deepseek-v4-flash`
+- `kimi-k2.6`
+- `qwen-vl-plus`
+
+> 目前所有模型均路由到百炼 Provider。后续接入其他厂商时，通过 `MODEL_REGISTRY` 扩展映射即可。
+
+### 错误处理
+
+Predict 模块遵循 Axiom 的统一错误策略：**直接抛异常，调用方 `try/catch`**。不使用 `Result<T, E>` 包装，不定义自定义错误类。
+
+```ts
+try {
+  const res = await LLM.predict({ model: 'qwen3.7-max', prompt: 'hi' });
+} catch (e) {
+  // e.message 包含 Provider 汇总错误信息
+}
+```
+
+---
+
+## 设计理念
+
+```
+┌────────────────────────────────────────┐
+│  Axiom 不纠正模型。                     │
+│  Axiom 保证模型永远不会基于幻觉推理。     │
+└────────────────────────────────────────┘
+```
+
+- **底座驱动循环** — Axiom 串起 LLM → 解析 → 校验 → 执行 → 记录的闭环
+- **项目层填充内容** — 上层准备消息、工具、业务逻辑，Axiom 负责可靠执行
+- **副作用即状态** — 工具调用改变外部世界，Harness 让这种改变在 Loop 间可见
+- **单一事实来源** — Harness 的执行记录是 Function Call 的唯一权威来源
+
+---

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { LLM } from './predict';
+export type { LLMRequest, LLMResponse, Message, ProviderConfig, StreamChunk, } from './predict';
+export type { LLMProvider, PredictorOptions } from './predict';
+export { Predictor, BailianProvider, MODEL_REGISTRY } from './predict';
+export type { Model, PredictConfig, PredictWithMessagesConfig } from './predict';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_REGISTRY = exports.BailianProvider = exports.Predictor = exports.LLM = void 0;
+var predict_1 = require("./predict");
+Object.defineProperty(exports, "LLM", { enumerable: true, get: function () { return predict_1.LLM; } });
+var predict_2 = require("./predict");
+Object.defineProperty(exports, "Predictor", { enumerable: true, get: function () { return predict_2.Predictor; } });
+Object.defineProperty(exports, "BailianProvider", { enumerable: true, get: function () { return predict_2.BailianProvider; } });
+Object.defineProperty(exports, "MODEL_REGISTRY", { enumerable: true, get: function () { return predict_2.MODEL_REGISTRY; } });

package/dist/predict/config.d.ts

@@ -0,0 +1,37 @@
+import type { Message } from './types';
+import type { Model } from './models';
+/**
+ * `predict()` 的配置参数。用于单轮快速调用场景，内部自动构建 user message。
+ */
+export interface PredictConfig {
+    /** 模型枚举值，决定路由到哪个 Provider */
+    readonly model: Model;
+    /** 用户输入的 prompt */
+    readonly prompt: string;
+    /** 系统提示（可选） */
+    readonly systemPrompt?: string;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly topP?: number;
+    readonly reasoningEffort?: 'low' | 'medium' | 'high';
+    readonly responseFormat?: 'text' | 'json';
+}
+/**
+ * `predictWithMessages()` 的配置参数。不含 prompt，因为消息由调用方自行构建。
+ */
+export interface PredictWithMessagesConfig {
+    readonly model: Model;
+    readonly systemPrompt?: string;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly topP?: number;
+    readonly reasoningEffort?: 'low' | 'medium' | 'high';
+    readonly responseFormat?: 'text' | 'json';
+}
+/**
+ * 将 system prompt 前置到消息列表中。
+ * @param config - 含可选 systemPrompt 字段的配置
+ * @param userMessages - 用户提供的消息列表
+ * @returns 带 system message 前缀的完整列表
+ */
+export declare function buildMessages(config: PredictConfig | PredictWithMessagesConfig, userMessages: ReadonlyArray<Message>): Message[];

package/dist/predict/config.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMessages = buildMessages;
+/**
+ * 将 system prompt 前置到消息列表中。
+ * @param config - 含可选 systemPrompt 字段的配置
+ * @param userMessages - 用户提供的消息列表
+ * @returns 带 system message 前缀的完整列表
+ */
+function buildMessages(config, userMessages) {
+    const messages = [];
+    if (config.systemPrompt) {
+        messages.push({ role: 'system', content: config.systemPrompt });
+    }
+    messages.push(...userMessages);
+    return messages;
+}

package/dist/predict/index.d.ts

@@ -0,0 +1,8 @@
+export type { LLMRequest, LLMResponse, Message, ProviderConfig, StreamChunk, } from './types';
+export type { LLMProvider, PredictorOptions } from './llm';
+export { Predictor } from './llm';
+export { BailianProvider } from './providers/bailian';
+export type { Model } from './models';
+export { MODEL_REGISTRY } from './models';
+export type { PredictConfig, PredictWithMessagesConfig } from './config';
+export { LLM } from './predict';

package/dist/predict/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM = exports.MODEL_REGISTRY = exports.BailianProvider = exports.Predictor = void 0;
+var llm_1 = require("./llm");
+Object.defineProperty(exports, "Predictor", { enumerable: true, get: function () { return llm_1.Predictor; } });
+var bailian_1 = require("./providers/bailian");
+Object.defineProperty(exports, "BailianProvider", { enumerable: true, get: function () { return bailian_1.BailianProvider; } });
+var models_1 = require("./models");
+Object.defineProperty(exports, "MODEL_REGISTRY", { enumerable: true, get: function () { return models_1.MODEL_REGISTRY; } });
+var predict_1 = require("./predict");
+Object.defineProperty(exports, "LLM", { enumerable: true, get: function () { return predict_1.LLM; } });

package/dist/predict/llm.d.ts

@@ -0,0 +1,72 @@
+import type { LLMRequest, LLMResponse, ProviderConfig, StreamChunk } from './types';
+import type { Model } from './models';
+/**
+ * LLM Provider 抽象接口。每个 Provider 实现负责对接具体的模型服务
+ *（如百炼、OpenAI、Anthropic 等），处理 HTTP 请求、流式解析和错误转换。
+ */
+export interface LLMProvider {
+    /** Provider 标识名，用于路由和故障转移日志 */
+    readonly name: string;
+    /** Provider 配置（API Key、Base URL、默认模型等） */
+    readonly config: ProviderConfig;
+    /**
+     * 校验当前 Provider 是否支持指定模型。
+     * 框架层在 MODEL_REGISTRY 候选过滤后，再调用此方法做二次确认。
+     * @param model - 模型标识名
+     * @returns true 表示支持，false 表示不支持（将自动轮询下一个候选）
+     */
+    supports(model: string): boolean;
+    /**
+     * 发送非流式请求，返回完整的模型响应。
+     * @param request - LLM 请求参数
+     * @returns 模型生成的完整响应
+     * @throws 网络异常、HTTP 错误、解析失败等均抛 {@link Error}
+     */
+    generate(request: LLMRequest): Promise<LLMResponse>;
+    /**
+     * 发送流式请求，逐块返回模型输出。
+     * @param request - LLM 请求参数
+     * @yields 内容片段或结束标记
+     * @throws 网络异常、HTTP 错误等均抛 {@link Error}
+     */
+    stream(request: LLMRequest): AsyncGenerator<StreamChunk, void, unknown>;
+}
+/** Predictor 构造选项 */
+export interface PredictorOptions {
+    /** Provider 列表，按优先级排序 */
+    readonly providers: ReadonlyArray<LLMProvider>;
+    /** 单个 Provider 失败后的最大重试次数，默认 1 */
+    readonly maxRetries?: number;
+    /** 重试间隔（毫秒），默认 0 */
+    readonly retryDelayMs?: number;
+}
+/**
+ * 预测器核心类。负责按模型路由到对应 Provider，执行故障转移和重试。
+ * 对外透明：调用方只需指定模型，无需关心底层是哪个 Provider。
+ */
+export declare class Predictor {
+    private readonly providers;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    constructor(options: PredictorOptions);
+    /** 当前已注册的 Provider 数量 */
+    get providerCount(): number;
+    /**
+     * 非流式生成。按模型找到对应 Provider 队列，逐个尝试直到成功。
+     * @param model - 模型枚举值
+     * @param request - 标准化后的 LLM 请求
+     * @returns 模型响应
+     * @throws Error - 模型不存在、无可用 Provider、或所有 Provider 均失败时抛出
+     */
+    generateForModel(model: Model, request: LLMRequest): Promise<LLMResponse>;
+    /**
+     * 流式生成。按模型找到对应 Provider 队列，逐个尝试直到成功建立流。
+     * @param model - 模型枚举值
+     * @param request - 标准化后的 LLM 请求
+     * @yields 内容片段或结束标记
+     * @throws Error - 模型不存在、无可用 Provider、或所有 Provider 均失败时抛出
+     */
+    streamForModel(model: Model, request: LLMRequest): AsyncGenerator<StreamChunk, void, unknown>;
+    private buildProviderQueue;
+    private sleep;
+}

package/dist/predict/llm.js

@@ -0,0 +1,154 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Predictor = void 0;
+const models_1 = require("./models");
+/**
+ * 预测器核心类。负责按模型路由到对应 Provider，执行故障转移和重试。
+ * 对外透明：调用方只需指定模型，无需关心底层是哪个 Provider。
+ */
+class Predictor {
+    constructor(options) {
+        var _a, _b;
+        if (options.providers.length === 0) {
+            throw new Error('At least one provider is required');
+        }
+        this.providers = [...options.providers];
+        this.maxRetries = (_a = options.maxRetries) !== null && _a !== void 0 ? _a : 1;
+        this.retryDelayMs = (_b = options.retryDelayMs) !== null && _b !== void 0 ? _b : 0;
+    }
+    /** 当前已注册的 Provider 数量 */
+    get providerCount() {
+        return this.providers.length;
+    }
+    /**
+     * 非流式生成。按模型找到对应 Provider 队列，逐个尝试直到成功。
+     * @param model - 模型枚举值
+     * @param request - 标准化后的 LLM 请求
+     * @returns 模型响应
+     * @throws Error - 模型不存在、无可用 Provider、或所有 Provider 均失败时抛出
+     */
+    generateForModel(model, request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const candidates = models_1.MODEL_REGISTRY[model];
+            if (!candidates || candidates.length === 0) {
+                throw new Error(`Unknown model: ${model}`);
+            }
+            const providerQueue = this.buildProviderQueue(candidates);
+            if (providerQueue.length === 0) {
+                throw new Error(`No provider available for model: ${model}`);
+            }
+            const errors = [];
+            for (const { provider, modelConfig } of providerQueue) {
+                const modelRequest = Object.assign(Object.assign({}, request), { model: modelConfig.model });
+                for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+                    try {
+                        return yield provider.generate(modelRequest);
+                    }
+                    catch (error) {
+                        const err = error instanceof Error ? error : new Error(String(error));
+                        errors.push({ provider: provider.name, error: err });
+                    }
+                    if (attempt < this.maxRetries - 1 && this.retryDelayMs > 0) {
+                        yield this.sleep(this.retryDelayMs);
+                    }
+                }
+            }
+            const summary = errors.map((e) => `${e.provider}: ${e.error.message}`).join('; ');
+            throw new Error(`All providers failed: ${summary}`);
+        });
+    }
+    /**
+     * 流式生成。按模型找到对应 Provider 队列，逐个尝试直到成功建立流。
+     * @param model - 模型枚举值
+     * @param request - 标准化后的 LLM 请求
+     * @yields 内容片段或结束标记
+     * @throws Error - 模型不存在、无可用 Provider、或所有 Provider 均失败时抛出
+     */
+    streamForModel(model, request) {
+        return __asyncGenerator(this, arguments, function* streamForModel_1() {
+            var _a, e_1, _b, _c;
+            const candidates = models_1.MODEL_REGISTRY[model];
+            if (!candidates || candidates.length === 0) {
+                throw new Error(`Unknown model: ${model}`);
+            }
+            const providerQueue = this.buildProviderQueue(candidates);
+            if (providerQueue.length === 0) {
+                throw new Error(`No provider available for model: ${model}`);
+            }
+            const errors = [];
+            for (const { provider, modelConfig } of providerQueue) {
+                const modelRequest = Object.assign(Object.assign({}, request), { model: modelConfig.model });
+                try {
+                    try {
+                        for (var _d = true, _e = (e_1 = void 0, __asyncValues(provider.stream(modelRequest))), _f; _f = yield __await(_e.next()), _a = _f.done, !_a; _d = true) {
+                            _c = _f.value;
+                            _d = false;
+                            const chunk = _c;
+                            yield yield __await(chunk);
+                        }
+                    }
+                    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                    finally {
+                        try {
+                            if (!_d && !_a && (_b = _e.return)) yield __await(_b.call(_e));
+                        }
+                        finally { if (e_1) throw e_1.error; }
+                    }
+                    return yield __await(void 0);
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    errors.push({ provider: provider.name, error: err });
+                }
+            }
+            const summary = errors.map((e) => `${e.provider}: ${e.error.message}`).join('; ');
+            throw new Error(`All providers failed: ${summary}`);
+        });
+    }
+    buildProviderQueue(candidates) {
+        const queue = [];
+        const seen = new Set();
+        for (const provider of this.providers) {
+            for (const mc of candidates) {
+                if (provider.name === mc.provider && !seen.has(provider) && provider.supports(mc.model)) {
+                    seen.add(provider);
+                    queue.push({ provider, modelConfig: mc });
+                }
+            }
+        }
+        return queue;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.Predictor = Predictor;

package/dist/predict/models.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 支持的模型枚举。项目层通过此枚举选择模型，Axiom 内部路由到对应 Provider。
+ */
+export type Model = 'qwen3.7-max' | 'qwen-plus' | 'qwen-turbo' | 'qwq-plus' | 'deepseek-v4-pro' | 'deepseek-v4-flash' | 'kimi-k2.6' | 'qwen-vl-plus';
+/** 模型到 Provider 的映射配置 */
+export interface ModelConfig {
+    readonly model: string;
+    readonly provider: string;
+}
+/**
+ * 模型注册表。每个模型对应一个或多个 Provider 候选，按优先级排序。
+ * 当首选 Provider 失败时，Predictor 按此表顺序尝试下一个。
+ */
+export declare const MODEL_REGISTRY: Readonly<Record<Model, ReadonlyArray<ModelConfig>>>;

package/dist/predict/models.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_REGISTRY = void 0;
+/**
+ * 模型注册表。每个模型对应一个或多个 Provider 候选，按优先级排序。
+ * 当首选 Provider 失败时，Predictor 按此表顺序尝试下一个。
+ */
+exports.MODEL_REGISTRY = {
+    'qwen3.7-max': [{ model: 'qwen3.7-max', provider: 'bailian' }],
+    'qwen-plus': [{ model: 'qwen-plus', provider: 'bailian' }],
+    'qwen-turbo': [{ model: 'qwen-turbo', provider: 'bailian' }],
+    'qwq-plus': [{ model: 'qwq-plus', provider: 'bailian' }],
+    'deepseek-v4-pro': [{ model: 'deepseek-v4-pro', provider: 'bailian' }],
+    'deepseek-v4-flash': [{ model: 'deepseek-v4-flash', provider: 'bailian' }],
+    'kimi-k2.6': [{ model: 'kimi-k2.6', provider: 'bailian' }],
+    'qwen-vl-plus': [{ model: 'qwen-vl-plus', provider: 'bailian' }],
+};

package/dist/predict/predict.d.ts

@@ -0,0 +1,82 @@
+import type { Message, LLMResponse, StreamChunk } from './types';
+import type { PredictConfig, PredictWithMessagesConfig } from './config';
+/**
+ * LLM 静态类。封装 Provider 连接、请求组装、故障转移和返回解析。
+ * 上层只需关心「用什么模型、传什么消息」，通过静态方法直接调用。
+ *
+ * @example
+ * ```ts
+ * import { LLM } from 'axiom';
+ *
+ * const res = await LLM.predict({ model: 'qwen-max', prompt: '你好' });
+ * console.log(res.content);
+ * ```
+ */
+export declare class LLM {
+    private static globalPredictor;
+    private static getPredictor;
+    /**
+     * 快速调用 LLM，传入 prompt 和配置即可。
+     * 内部自动构造单条 user message，支持可选的 system prompt。
+     *
+     * 根据 `responseFormat` 返回不同类型：
+     * - `'text'` → `string`
+     * - `'json'` → 解析后的对象（`any`）
+     * - 未设置 → `LLMResponse`
+     *
+     * @param config - 预测配置（模型、prompt、温度等）
+     * @returns 模型生成的完整响应
+     * @throws Error - Provider 未配置、模型不存在、或所有 Provider 均失败时抛出
+     */
+    static predict(config: PredictConfig & {
+        responseFormat: 'text';
+    }): Promise<string>;
+    static predict(config: PredictConfig & {
+        responseFormat: 'json';
+    }): Promise<any>;
+    static predict(config: PredictConfig): Promise<LLMResponse>;
+    /**
+     * 使用自定义消息列表调用 LLM。适用于多轮对话等需要精细控制 message 结构的场景。
+     *
+     * 根据 `responseFormat` 返回不同类型：
+     * - `'text'` → `string`
+     * - `'json'` → 解析后的对象（可用泛型指定类型）
+     * - 未设置 → `LLMResponse`
+     *
+     * @param messages - 消息列表（user/assistant 角色）
+     * @param config - 预测配置（不含 prompt，因为由 messages 提供）
+     * @returns 模型生成的完整响应
+     * @throws Error - Provider 未配置、模型不存在、或所有 Provider 均失败时抛出
+     */
+    static predictWithMessages(messages: ReadonlyArray<Message>, config: PredictWithMessagesConfig & {
+        responseFormat: 'text';
+    }): Promise<string>;
+    static predictWithMessages(messages: ReadonlyArray<Message>, config: PredictWithMessagesConfig & {
+        responseFormat: 'json';
+    }): Promise<any>;
+    static predictWithMessages(messages: ReadonlyArray<Message>, config: PredictWithMessagesConfig): Promise<LLMResponse>;
+    /**
+     * 流式调用 LLM，逐块返回模型输出。
+     *
+     * @param config - 预测配置
+     * @yields 内容片段（`content`）或结束标记（`finish`）
+     * @throws Error - Provider 未配置、模型不存在、或所有 Provider 均失败时抛出
+     *
+     * @example
+     * ```ts
+     * for await (const chunk of LLM.streamPredict({ model: 'qwen-max', prompt: '讲个故事' })) {
+     *   if (chunk.type === 'content') process.stdout.write(chunk.delta);
+     * }
+     * ```
+     */
+    static streamPredict(config: PredictConfig): AsyncGenerator<StreamChunk, void, unknown>;
+    /**
+     * 使用自定义消息列表进行流式调用。
+     *
+     * @param messages - 消息列表
+     * @param config - 预测配置
+     * @yields 内容片段或结束标记
+     * @throws Error - Provider 未配置、模型不存在、或所有 Provider 均失败时抛出
+     */
+    static streamPredictWithMessages(messages: ReadonlyArray<Message>, config: PredictWithMessagesConfig): AsyncGenerator<StreamChunk, void, unknown>;
+}

package/dist/predict/predict.js

@@ -0,0 +1,163 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM = void 0;
+const llm_1 = require("./llm");
+const config_1 = require("./config");
+const bailian_1 = require("./providers/bailian");
+const DEFAULT_BAILIAN_BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
+const DEFAULT_BAILIAN_MODEL = 'qwen-max';
+function createBailianProvider() {
+    var _a, _b;
+    if (!process.env.BAILIAN_API_KEY)
+        return null;
+    return new bailian_1.BailianProvider({
+        name: 'bailian',
+        apiKey: process.env.BAILIAN_API_KEY,
+        baseUrl: (_a = process.env.BAILIAN_BASE_URL) !== null && _a !== void 0 ? _a : DEFAULT_BAILIAN_BASE_URL,
+        defaultModel: (_b = process.env.BAILIAN_DEFAULT_MODEL) !== null && _b !== void 0 ? _b : DEFAULT_BAILIAN_MODEL,
+    });
+}
+function createDefaultProviders() {
+    return [
+        createBailianProvider(),
+        // createOpenAIProvider(),
+        // createAnthropicProvider(),
+    ].filter((p) => p !== null);
+}
+function toLLMRequest(config, messages) {
+    return {
+        messages,
+        temperature: config.temperature,
+        maxTokens: config.maxTokens,
+        topP: config.topP,
+        responseFormat: config.responseFormat,
+    };
+}
+function unwrapResponse(response, responseFormat) {
+    var _a;
+    if (responseFormat === 'text') {
+        return (_a = response.content) !== null && _a !== void 0 ? _a : '';
+    }
+    if (responseFormat === 'json') {
+        if (!response.content) {
+            throw new Error('Empty response content when responseFormat is json');
+        }
+        return JSON.parse(response.content);
+    }
+    return response;
+}
+/**
+ * LLM 静态类。封装 Provider 连接、请求组装、故障转移和返回解析。
+ * 上层只需关心「用什么模型、传什么消息」，通过静态方法直接调用。
+ *
+ * @example
+ * ```ts
+ * import { LLM } from 'axiom';
+ *
+ * const res = await LLM.predict({ model: 'qwen-max', prompt: '你好' });
+ * console.log(res.content);
+ * ```
+ */
+class LLM {
+    static getPredictor() {
+        if (!LLM.globalPredictor) {
+            LLM.globalPredictor = new llm_1.Predictor({ providers: createDefaultProviders() });
+        }
+        if (LLM.globalPredictor.providerCount === 0) {
+            throw new Error('No LLM provider configured. Set BAILIAN_API_KEY environment variable.');
+        }
+        return LLM.globalPredictor;
+    }
+    static predict(config) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const predictor = LLM.getPredictor();
+            const messages = (0, config_1.buildMessages)(config, [{ role: 'user', content: config.prompt }]);
+            const request = toLLMRequest(config, messages);
+            const response = yield predictor.generateForModel(config.model, request);
+            return unwrapResponse(response, config.responseFormat);
+        });
+    }
+    static predictWithMessages(messages, config) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const predictor = LLM.getPredictor();
+            const builtMessages = (0, config_1.buildMessages)(config, messages);
+            const request = toLLMRequest(config, builtMessages);
+            const response = yield predictor.generateForModel(config.model, request);
+            return unwrapResponse(response, config.responseFormat);
+        });
+    }
+    /**
+     * 流式调用 LLM，逐块返回模型输出。
+     *
+     * @param config - 预测配置
+     * @yields 内容片段（`content`）或结束标记（`finish`）
+     * @throws Error - Provider 未配置、模型不存在、或所有 Provider 均失败时抛出
+     *
+     * @example
+     * ```ts
+     * for await (const chunk of LLM.streamPredict({ model: 'qwen-max', prompt: '讲个故事' })) {
+     *   if (chunk.type === 'content') process.stdout.write(chunk.delta);
+     * }
+     * ```
+     */
+    static streamPredict(config) {
+        return __asyncGenerator(this, arguments, function* streamPredict_1() {
+            const predictor = LLM.getPredictor();
+            const messages = (0, config_1.buildMessages)(config, [{ role: 'user', content: config.prompt }]);
+            const request = toLLMRequest(config, messages);
+            yield __await(yield* __asyncDelegator(__asyncValues(predictor.streamForModel(config.model, request))));
+        });
+    }
+    /**
+     * 使用自定义消息列表进行流式调用。
+     *
+     * @param messages - 消息列表
+     * @param config - 预测配置
+     * @yields 内容片段或结束标记
+     * @throws Error - Provider 未配置、模型不存在、或所有 Provider 均失败时抛出
+     */
+    static streamPredictWithMessages(messages, config) {
+        return __asyncGenerator(this, arguments, function* streamPredictWithMessages_1() {
+            const predictor = LLM.getPredictor();
+            const builtMessages = (0, config_1.buildMessages)(config, messages);
+            const request = toLLMRequest(config, builtMessages);
+            yield __await(yield* __asyncDelegator(__asyncValues(predictor.streamForModel(config.model, request))));
+        });
+    }
+}
+exports.LLM = LLM;
+LLM.globalPredictor = null;

package/dist/predict/providers/bailian.d.ts

@@ -0,0 +1,27 @@
+import type { LLMProvider } from '../llm';
+import type { LLMRequest, LLMResponse, ProviderConfig, StreamChunk } from '../types';
+/**
+ * 阿里云百炼（兼容 OpenAI 协议）Provider 实现。
+ * 支持非流式调用和流式 SSE 输出。
+ */
+export declare class BailianProvider implements LLMProvider {
+    readonly config: ProviderConfig;
+    readonly name = "bailian";
+    constructor(config: ProviderConfig);
+    supports(model: string): boolean;
+    /**
+     * 发送非流式 chat completion 请求到百炼服务。
+     * @param request - 标准化 LLM 请求
+     * @returns 解析后的模型响应（含 content、usage、model）
+     * @throws Error - 网络异常时抛 `[bailian] ...`；HTTP 非 2xx 时抛 `[bailian] HTTP {status}: ...`
+     */
+    generate(request: LLMRequest): Promise<LLMResponse>;
+    /**
+     * 发送流式 chat completion 请求，解析 SSE 响应逐块返回。
+     * @param request - 标准化 LLM 请求
+     * @yields 内容片段（`content`）或结束标记（`finish`）
+     * @throws Error - 网络异常或 HTTP 错误时抛出
+     */
+    stream(request: LLMRequest): AsyncGenerator<StreamChunk, void, unknown>;
+    private buildRequestBody;
+}

package/dist/predict/providers/bailian.js

@@ -0,0 +1,185 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BailianProvider = void 0;
+const models_1 = require("../models");
+/**
+ * 阿里云百炼（兼容 OpenAI 协议）Provider 实现。
+ * 支持非流式调用和流式 SSE 输出。
+ */
+class BailianProvider {
+    constructor(config) {
+        this.config = config;
+        this.name = 'bailian';
+    }
+    supports(model) {
+        return Object.entries(models_1.MODEL_REGISTRY).some(([m, configs]) => m === model && configs.some((c) => c.provider === this.name));
+    }
+    /**
+     * 发送非流式 chat completion 请求到百炼服务。
+     * @param request - 标准化 LLM 请求
+     * @returns 解析后的模型响应（含 content、usage、model）
+     * @throws Error - 网络异常时抛 `[bailian] ...`；HTTP 非 2xx 时抛 `[bailian] HTTP {status}: ...`
+     */
+    generate(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = `${this.config.baseUrl}/chat/completions`;
+            const body = this.buildRequestBody(request);
+            let response;
+            try {
+                response = yield fetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${this.config.apiKey}`,
+                    },
+                    body: JSON.stringify(Object.assign(Object.assign({}, body), { stream: false })),
+                });
+            }
+            catch (cause) {
+                throw new Error(`[${this.name}] ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+            if (!response.ok) {
+                const text = yield response.text();
+                throw new Error(`[${this.name}] HTTP ${response.status}: ${text}`);
+            }
+            const data = (yield response.json());
+            const choice = data.choices[0];
+            if (!choice) {
+                throw new Error(`[${this.name}] No choice in response`);
+            }
+            return {
+                content: choice.message.content,
+                usage: data.usage
+                    ? {
+                        promptTokens: data.usage.prompt_tokens,
+                        completionTokens: data.usage.completion_tokens,
+                        totalTokens: data.usage.total_tokens,
+                    }
+                    : undefined,
+                model: data.model,
+            };
+        });
+    }
+    /**
+     * 发送流式 chat completion 请求，解析 SSE 响应逐块返回。
+     * @param request - 标准化 LLM 请求
+     * @yields 内容片段（`content`）或结束标记（`finish`）
+     * @throws Error - 网络异常或 HTTP 错误时抛出
+     */
+    stream(request) {
+        return __asyncGenerator(this, arguments, function* stream_1() {
+            var _a, _b;
+            const url = `${this.config.baseUrl}/chat/completions`;
+            const body = this.buildRequestBody(request);
+            let response;
+            try {
+                response = yield __await(fetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${this.config.apiKey}`,
+                    },
+                    body: JSON.stringify(Object.assign(Object.assign({}, body), { stream: true })),
+                }));
+            }
+            catch (cause) {
+                throw new Error(`[${this.name}] ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+            if (!response.ok) {
+                const text = yield __await(response.text());
+                throw new Error(`[${this.name}] HTTP ${response.status}: ${text}`);
+            }
+            if (!response.body) {
+                throw new Error(`[${this.name}] Response body is null`);
+            }
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            try {
+                while (true) {
+                    const { done, value } = yield __await(reader.read());
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split('\n');
+                    buffer = (_a = lines.pop()) !== null && _a !== void 0 ? _a : '';
+                    for (const line of lines) {
+                        const trimmed = line.trim();
+                        if (!trimmed || !trimmed.startsWith('data: '))
+                            continue;
+                        const data = trimmed.slice(6);
+                        if (data === '[DONE]')
+                            continue;
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(data);
+                        }
+                        catch (_c) {
+                            continue;
+                        }
+                        const choice = (_b = parsed.choices) === null || _b === void 0 ? void 0 : _b[0];
+                        if (!choice)
+                            continue;
+                        const delta = choice.delta;
+                        if (delta.content) {
+                            yield yield __await({ type: 'content', delta: delta.content });
+                        }
+                        if (choice.finish_reason && parsed.usage) {
+                            yield yield __await({
+                                type: 'finish',
+                                usage: {
+                                    promptTokens: parsed.usage.prompt_tokens,
+                                    completionTokens: parsed.usage.completion_tokens,
+                                    totalTokens: parsed.usage.total_tokens,
+                                },
+                            });
+                        }
+                    }
+                }
+                yield yield __await({ type: 'finish' });
+            }
+            finally {
+                reader.releaseLock();
+            }
+        });
+    }
+    buildRequestBody(request) {
+        var _a;
+        return {
+            model: (_a = request.model) !== null && _a !== void 0 ? _a : this.config.defaultModel,
+            messages: request.messages.map((m) => ({
+                role: m.role,
+                content: m.content,
+            })),
+            temperature: request.temperature,
+            max_tokens: request.maxTokens,
+            top_p: request.topP,
+            response_format: request.responseFormat
+                ? { type: request.responseFormat === 'json' ? 'json_object' : 'text' }
+                : undefined,
+        };
+    }
+}
+exports.BailianProvider = BailianProvider;

package/dist/predict/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * LLM 对话消息。支持 system、user、assistant 三种角色。
+ */
+export interface Message {
+    readonly role: 'system' | 'user' | 'assistant';
+    readonly content: string;
+}
+/**
+ * 标准化 LLM 请求参数。各 Provider 据此构建自身的协议请求。
+ */
+export interface LLMRequest {
+    readonly messages: ReadonlyArray<Message>;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly topP?: number;
+    readonly stream?: boolean;
+    readonly model?: string;
+    readonly responseFormat?: 'text' | 'json';
+}
+/**
+ * 标准化 LLM 响应。各 Provider 将原始响应解析为此格式后返回。
+ */
+export interface LLMResponse {
+    readonly content: string | null;
+    readonly usage?: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+        readonly totalTokens: number;
+    };
+    readonly model: string;
+}
+/**
+ * 流式输出片段。迭代器每次 yield 一个 chunk。
+ */
+export type StreamChunk = {
+    readonly type: 'content';
+    readonly delta: string;
+} | {
+    readonly type: 'finish';
+    readonly usage?: LLMResponse['usage'];
+};
+/**
+ * Provider 配置。每个 Provider 实例需要一组连接参数。
+ */
+export interface ProviderConfig {
+    readonly name: string;
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly defaultModel: string;
+    readonly timeoutMs?: number;
+}

package/dist/predict/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@keo-ai/axiom",
+  "version": "0.1.0",
+  "description": "基于 LLM 的预测与推理库，支持多 Provider 切换",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "dotenv": "^17.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^5.5.3",
+    "vitest": "^4.1.7"
+  }
+}