@kweaver-ai/kweaver-sdk 0.4.0 → 0.4.1

package/README.md

@@ -0,0 +1,139 @@
+# @kweaver-ai/kweaver-sdk
+
+TypeScript SDK and CLI for [KWeaver](https://github.com/kweaver-ai/kweaver-sdk) — gives AI agents and applications programmatic access to knowledge networks and Decision Agents.
+
+[中文文档](README.zh.md)
+
+## Installation
+
+```bash
+# CLI (global)
+npm install -g @kweaver-ai/kweaver-sdk
+
+# Library
+npm install @kweaver-ai/kweaver-sdk
+```
+
+Requires **Node.js >= 22**.
+
+## Quick Start
+
+### Authenticate
+
+```bash
+kweaver auth login https://your-kweaver-instance.com
+```
+
+Or use environment variables:
+
+```bash
+export KWEAVER_BASE_URL=https://your-kweaver-instance.com
+export KWEAVER_TOKEN=your-token
+```
+
+### Simple API (recommended)
+
+```typescript
+import kweaver from "@kweaver-ai/kweaver-sdk/kweaver";
+
+// Zero-config: reads credentials saved by `kweaver auth login`
+kweaver.configure({ config: true, bknId: "your-bkn-id", agentId: "your-agent-id" });
+
+// Search the knowledge network
+const results = await kweaver.search("What risks exist in the supply chain?");
+for (const concept of results.concepts) console.log(concept.concept_name);
+
+// Chat with an agent
+const reply = await kweaver.chat("Summarise the top 3 risks");
+console.log(reply.text);
+
+// After modifying object types or adding datasources, rebuild the BKN index
+await kweaver.weaver({ wait: true });
+
+// List available BKNs and agents
+const bknList   = await kweaver.bkns();
+const agentList = await kweaver.agents();
+```
+
+### Full Client API (advanced)
+
+```typescript
+import { KWeaverClient } from "@kweaver-ai/kweaver-sdk";
+
+// Zero-config: reads credentials saved by `kweaver auth login`
+const client = new KWeaverClient();
+
+// Or pass credentials explicitly
+const client = new KWeaverClient({
+  baseUrl: "https://your-kweaver-instance.com",
+  accessToken: "your-token",
+});
+
+// Knowledge networks
+const kns = await client.knowledgeNetworks.list({ limit: 10 });
+const ots = await client.knowledgeNetworks.listObjectTypes("bkn-id");
+const rts = await client.knowledgeNetworks.listRelationTypes("bkn-id");
+const ats = await client.knowledgeNetworks.listActionTypes("bkn-id");
+
+// Agent chat (single-shot)
+const reply = await client.agents.chat("agent-id", "Hello");
+console.log(reply.text, reply.conversationId);
+
+// Agent chat (streaming)
+await client.agents.stream("agent-id", "Hello", {
+  onTextDelta: (chunk) => process.stdout.write(chunk),
+});
+
+// BKN engine — instance queries, subgraph, action execution
+const instances = await client.bkn.queryInstances("bkn-id", "ot-id", { limit: 20 });
+const graph     = await client.bkn.querySubgraph("bkn-id", { /* path spec */ });
+await client.bkn.executeAction("bkn-id", "at-id", { /* params */ });
+const logs      = await client.bkn.listActionLogs("bkn-id");
+
+// Context Loader (semantic search over a BKN via MCP)
+const cl      = client.contextLoader(mcpUrl, "bkn-id");
+const results = await cl.search({ query: "hypertension treatment" });
+```
+
+## CLI Reference
+
+```
+kweaver auth login/status/list/use/delete/logout
+kweaver token
+kweaver bkn list/get/stats/export/create/update/delete
+kweaver bkn object-type list/get/create/update/delete/query/properties
+kweaver bkn relation-type list/get/create/update/delete
+kweaver bkn action-type list/query/execute
+kweaver bkn subgraph
+kweaver bkn action-execution get
+kweaver bkn action-log list/get/cancel
+kweaver agent list/get/chat/sessions/history
+kweaver context-loader config set/use/list/show
+kweaver context-loader kn-search/query-object-instance/...
+kweaver call <path> [-X METHOD] [-d BODY] [-H header]
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `KWEAVER_BASE_URL` | KWeaver instance URL |
+| `KWEAVER_BUSINESS_DOMAIN` | Business domain identifier |
+| `KWEAVER_TOKEN` | Access token |
+
+## Using with AI Agents
+
+Install the KWeaver skill for Claude Code, Cursor, or other AI coding agents:
+
+```bash
+npx skills add kweaver-ai/kweaver-sdk --skill kweaver-core
+```
+
+## Links
+
+- [GitHub](https://github.com/kweaver-ai/kweaver-sdk)
+- [Python SDK on PyPI](https://pypi.org/project/kweaver-sdk/)
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,139 @@
+# @kweaver-ai/kweaver-sdk
+
+KWeaver TypeScript SDK 和 CLI — 让 AI 智能体与应用程序以编程方式访问知识网络和 Decision Agent。
+
+[English](README.md)
+
+## 安装
+
+```bash
+# 全局安装 CLI
+npm install -g @kweaver-ai/kweaver-sdk
+
+# 作为库使用
+npm install @kweaver-ai/kweaver-sdk
+```
+
+需要 **Node.js >= 22**。
+
+## 快速上手
+
+### 认证
+
+```bash
+kweaver auth login https://your-kweaver-instance.com
+```
+
+或使用环境变量：
+
+```bash
+export KWEAVER_BASE_URL=https://your-kweaver-instance.com
+export KWEAVER_TOKEN=your-token
+```
+
+### 简洁 API（推荐）
+
+```typescript
+import kweaver from "@kweaver-ai/kweaver-sdk/kweaver";
+
+// 使用 `kweaver auth login` 保存的凭据，零配置
+kweaver.configure({ config: true, bknId: "your-bkn-id", agentId: "your-agent-id" });
+
+// 搜索知识网络
+const results = await kweaver.search("供应链有哪些关键风险？");
+for (const concept of results.concepts) console.log(concept.concept_name);
+
+// 与 Agent 对话
+const reply = await kweaver.chat("总结前三大风险");
+console.log(reply.text);
+
+// 接入数据源或修改对象类后，重建 BKN 索引
+await kweaver.weaver({ wait: true });
+
+// 查看所有 BKN 和 Agent
+const bknList   = await kweaver.bkns();
+const agentList = await kweaver.agents();
+```
+
+### 底层客户端（高级用法）
+
+```typescript
+import { KWeaverClient } from "@kweaver-ai/kweaver-sdk";
+
+// 零配置：自动读取 `kweaver auth login` 保存的凭据
+const client = new KWeaverClient();
+
+// 或显式传入凭据
+const client = new KWeaverClient({
+  baseUrl: "https://your-kweaver-instance.com",
+  accessToken: "your-token",
+});
+
+// 知识网络
+const kns = await client.knowledgeNetworks.list({ limit: 10 });
+const ots = await client.knowledgeNetworks.listObjectTypes("bkn-id");
+const rts = await client.knowledgeNetworks.listRelationTypes("bkn-id");
+const ats = await client.knowledgeNetworks.listActionTypes("bkn-id");
+
+// Agent 对话（单次）
+const reply = await client.agents.chat("agent-id", "你好");
+console.log(reply.text, reply.conversationId);
+
+// Agent 对话（流式）
+await client.agents.stream("agent-id", "你好", {
+  onTextDelta: (chunk) => process.stdout.write(chunk),
+});
+
+// BKN 引擎：实例查询、子图、Action 执行
+const instances = await client.bkn.queryInstances("bkn-id", "ot-id", { limit: 20 });
+const graph     = await client.bkn.querySubgraph("bkn-id", { /* 路径规格 */ });
+await client.bkn.executeAction("bkn-id", "at-id", { /* 参数 */ });
+const logs      = await client.bkn.listActionLogs("bkn-id");
+
+// Context Loader（通过 MCP 对 BKN 做语义搜索）
+const cl      = client.contextLoader(mcpUrl, "bkn-id");
+const results = await cl.search({ query: "高血压 治疗" });
+```
+
+## 命令速查
+
+```
+kweaver auth login/status/list/use/delete/logout
+kweaver token
+kweaver bkn list/get/stats/export/create/update/delete
+kweaver bkn object-type list/get/create/update/delete/query/properties
+kweaver bkn relation-type list/get/create/update/delete
+kweaver bkn action-type list/query/execute
+kweaver bkn subgraph
+kweaver bkn action-execution get
+kweaver bkn action-log list/get/cancel
+kweaver agent list/get/chat/sessions/history
+kweaver context-loader config set/use/list/show
+kweaver context-loader kn-search/query-object-instance/...
+kweaver call <path> [-X METHOD] [-d BODY] [-H header]
+```
+
+## 环境变量
+
+| 变量 | 说明 |
+|---|---|
+| `KWEAVER_BASE_URL` | KWeaver 实例地址 |
+| `KWEAVER_BUSINESS_DOMAIN` | 业务域标识 |
+| `KWEAVER_TOKEN` | 访问令牌 |
+
+## 在 AI 智能体中使用
+
+为 Claude Code、Cursor 等 AI 编程助手安装 KWeaver 技能：
+
+```bash
+npx skills add kweaver-ai/kweaver-sdk --skill kweaver-core
+```
+
+## 相关链接
+
+- [GitHub](https://github.com/kweaver-ai/kweaver-sdk)
+- [Python SDK on PyPI](https://pypi.org/project/kweaver-sdk/)
+
+## 许可证
+
+MIT

package/dist/api/agent-list.d.ts

@@ -10,3 +10,10 @@ export interface ListAgentsOptions {
     is_to_square?: number;
 }
 export declare function listAgents(options: ListAgentsOptions): Promise<string>;
+export interface GetAgentOptions {
+    baseUrl: string;
+    accessToken: string;
+    agentId: string;
+    businessDomain?: string;
+}
+export declare function getAgent(options: GetAgentOptions): Promise<string>;

package/dist/api/agent-list.js

@@ -20,8 +20,6 @@ export async function listAgents(options) {
             token: accessToken,
             "x-business-domain": businessDomain,
             "x-language": "zh-CN",
-            "x-requested-with": "XMLHttpRequest",
-            "content-type": "application/json",
         },
         body,
     });
@@ -31,3 +29,24 @@ export async function listAgents(options) {
     }
     return responseBody;
 }
+export async function getAgent(options) {
+    const { baseUrl, accessToken, agentId, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-factory/v3/agent/${encodeURIComponent(agentId)}`;
+    const response = await fetch(url, {
+        method: "GET",
+        headers: {
+            accept: "application/json, text/plain, */*",
+            "accept-language": "zh-CN",
+            authorization: `Bearer ${accessToken}`,
+            token: accessToken,
+            "x-business-domain": businessDomain,
+            "x-language": "zh-CN",
+        },
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}

package/dist/api/datasources.d.ts

@@ -0,0 +1,73 @@
+export interface TestDatasourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    type: string;
+    host: string;
+    port: number;
+    database: string;
+    account: string;
+    password: string;
+    schema?: string;
+    businessDomain?: string;
+}
+export declare function testDatasource(options: TestDatasourceOptions): Promise<void>;
+export interface CreateDatasourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    name: string;
+    type: string;
+    host: string;
+    port: number;
+    database: string;
+    account: string;
+    password: string;
+    schema?: string;
+    comment?: string;
+    businessDomain?: string;
+}
+export declare function createDatasource(options: CreateDatasourceOptions): Promise<string>;
+export interface ListDatasourcesOptions {
+    baseUrl: string;
+    accessToken: string;
+    keyword?: string;
+    type?: string;
+    businessDomain?: string;
+}
+export declare function listDatasources(options: ListDatasourcesOptions): Promise<string>;
+export interface GetDatasourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function getDatasource(options: GetDatasourceOptions): Promise<string>;
+export interface DeleteDatasourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function deleteDatasource(options: DeleteDatasourceOptions): Promise<void>;
+export interface ListTablesOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    keyword?: string;
+    limit?: number;
+    offset?: number;
+    businessDomain?: string;
+}
+export declare function listTables(options: ListTablesOptions): Promise<string>;
+export interface ListTablesWithColumnsOptions extends ListTablesOptions {
+    autoScan?: boolean;
+}
+/** List tables with column details. Optionally triggers metadata scan if no tables found. */
+export declare function listTablesWithColumns(options: ListTablesWithColumnsOptions): Promise<string>;
+export interface ScanMetadataOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    dsType?: string;
+    businessDomain?: string;
+}
+export declare function scanMetadata(options: ScanMetadataOptions): Promise<string>;

package/dist/api/datasources.js

@@ -0,0 +1,218 @@
+import { HttpError } from "../utils/http.js";
+import { encryptPassword } from "../utils/crypto.js";
+const HTTPS_PROTOCOLS = new Set(["maxcompute", "anyshare7", "opensearch"]);
+function connectProtocol(dsType) {
+    return HTTPS_PROTOCOLS.has(dsType) ? "https" : "jdbc";
+}
+function makeBinData(type, host, port, database, account, password, schema) {
+    const d = {
+        host,
+        port,
+        database_name: database,
+        connect_protocol: connectProtocol(type),
+        account,
+        password: encryptPassword(password),
+    };
+    if (schema !== undefined && schema !== "") {
+        d.schema = schema;
+    }
+    return d;
+}
+function buildHeaders(accessToken, businessDomain) {
+    return {
+        accept: "application/json, text/plain, */*",
+        "accept-language": "zh-cn",
+        authorization: `Bearer ${accessToken}`,
+        token: accessToken,
+        "x-business-domain": businessDomain,
+        "x-language": "zh-cn",
+    };
+}
+export async function testDatasource(options) {
+    const { baseUrl, accessToken, type, host, port, database, account, password, schema, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/data-connection/v1/datasource/test`;
+    const body = JSON.stringify({
+        type,
+        bin_data: makeBinData(type, host, port, database, account, password, schema),
+    });
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body,
+    });
+    if (!response.ok) {
+        const responseBody = await response.text();
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+}
+export async function createDatasource(options) {
+    const { baseUrl, accessToken, name, type, host, port, database, account, password, schema, comment, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/data-connection/v1/datasource`;
+    const bodyObj = {
+        name,
+        type,
+        bin_data: makeBinData(type, host, port, database, account, password, schema),
+    };
+    if (comment) {
+        bodyObj.comment = comment;
+    }
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(bodyObj),
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}
+export async function listDatasources(options) {
+    const { baseUrl, accessToken, keyword, type, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/data-connection/v1/datasource`);
+    if (keyword)
+        url.searchParams.set("keyword", keyword);
+    if (type)
+        url.searchParams.set("type", type);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}
+export async function getDatasource(options) {
+    const { baseUrl, accessToken, id, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/data-connection/v1/datasource/${encodeURIComponent(id)}`;
+    const response = await fetch(url, {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}
+export async function deleteDatasource(options) {
+    const { baseUrl, accessToken, id, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/data-connection/v1/datasource/${encodeURIComponent(id)}`;
+    const response = await fetch(url, {
+        method: "DELETE",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new HttpError(response.status, response.statusText, body);
+    }
+}
+export async function listTables(options) {
+    const { baseUrl, accessToken, id, keyword, limit = -1, offset, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/data-connection/v1/metadata/data-source/${encodeURIComponent(id)}`);
+    url.searchParams.set("limit", String(limit));
+    if (keyword)
+        url.searchParams.set("keyword", keyword);
+    if (offset !== undefined)
+        url.searchParams.set("offset", String(offset));
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}
+/** List tables with column details. Optionally triggers metadata scan if no tables found. */
+export async function listTablesWithColumns(options) {
+    const { id, autoScan = true, ...rest } = options;
+    let body = await listTables({ ...rest, id });
+    const parsed = JSON.parse(body);
+    let items = Array.isArray(parsed) ? parsed : (parsed.entries ?? parsed.data ?? []);
+    if (items.length === 0 && autoScan) {
+        await scanMetadata({
+            baseUrl: rest.baseUrl,
+            accessToken: rest.accessToken,
+            id,
+            businessDomain: rest.businessDomain,
+        });
+        body = await listTables({ ...rest, id });
+        const parsed2 = JSON.parse(body);
+        items = Array.isArray(parsed2) ? parsed2 : (parsed2.entries ?? parsed2.data ?? []);
+    }
+    const base = rest.baseUrl.replace(/\/+$/, "");
+    const tables = [];
+    for (const t of items) {
+        const tableId = String(t.id ?? "");
+        const tableName = String(t.name ?? "");
+        let columnsRaw = (t.columns ?? t.fields ?? []);
+        if (columnsRaw.length === 0 && tableId) {
+            const tableUrl = `${base}/api/data-connection/v1/metadata/table/${encodeURIComponent(tableId)}?limit=-1`;
+            const colResponse = await fetch(tableUrl, {
+                method: "GET",
+                headers: buildHeaders(rest.accessToken, rest.businessDomain ?? "bd_public"),
+            });
+            const colData = (await colResponse.json());
+            columnsRaw = Array.isArray(colData) ? colData : (colData.entries ?? colData.data ?? []);
+        }
+        const columns = columnsRaw.map((c) => ({
+            name: String(c.name ?? c.field_name ?? ""),
+            type: String(c.type ?? c.field_type ?? "varchar"),
+            comment: typeof c.comment === "string" ? c.comment : undefined,
+        }));
+        tables.push({ name: tableName, columns });
+    }
+    return JSON.stringify(tables);
+}
+export async function scanMetadata(options) {
+    const { baseUrl, accessToken, id, dsType = "mysql", businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const scanUrl = `${base}/api/data-connection/v1/metadata/scan`;
+    const statusUrl = (taskId) => `${base}/api/data-connection/v1/metadata/scan/${taskId}`;
+    const scanBody = JSON.stringify({
+        scan_name: `sdk_scan_${id.slice(0, 8)}`,
+        type: 0,
+        ds_info: { ds_id: id, ds_type: dsType },
+        use_default_template: true,
+        use_multi_threads: true,
+        status: "open",
+    });
+    const scanResponse = await fetch(scanUrl, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body: scanBody,
+    });
+    const scanResult = await scanResponse.json();
+    const taskId = scanResult.id ?? "";
+    for (let i = 0; i < 30; i += 1) {
+        await new Promise((r) => setTimeout(r, 2000));
+        const statusResponse = await fetch(statusUrl(taskId), {
+            method: "GET",
+            headers: buildHeaders(accessToken, businessDomain),
+        });
+        const statusData = (await statusResponse.json());
+        if (statusData.status === "success" || statusData.status === "fail") {
+            break;
+        }
+    }
+    return taskId;
+}

package/dist/api/dataviews.d.ts

@@ -0,0 +1,20 @@
+export interface CreateDataViewOptions {
+    baseUrl: string;
+    accessToken: string;
+    name: string;
+    datasourceId: string;
+    table: string;
+    fields?: Array<{
+        name: string;
+        type: string;
+    }>;
+    businessDomain?: string;
+}
+export declare function createDataView(options: CreateDataViewOptions): Promise<string>;
+export interface GetDataViewOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function getDataView(options: GetDataViewOptions): Promise<string>;