@kweaver-ai/kweaver-sdk 0.4.0

package/dist/kweaver.js

@@ -0,0 +1,184 @@
+/**
+ * Module-level simple API — cognee-style usage without instantiating KWeaverClient.
+ *
+ * @example Read-only (search + chat, no weaver needed)
+ * ```typescript
+ * import kweaver from "kweaver-sdk/kweaver";
+ *
+ * kweaver.configure({ config: true, bknId: "your-bkn-id", agentId: "your-agent-id" });
+ *
+ * const results = await kweaver.search("供应链有哪些风险？");
+ * const reply   = await kweaver.chat("总结前三大风险");
+ * console.log(reply.text);
+ * ```
+ *
+ * @example Write then build
+ * ```typescript
+ * kweaver.configure({ baseUrl: "https://...", accessToken: "token", bknId: "abc" });
+ * // ... add datasource, object types via kweaver.client ...
+ * await kweaver.weaver({ wait: true });
+ * const results = await kweaver.search("新接入的数据");
+ * ```
+ */
+import { KWeaverClient } from "./client.js";
+import { getCurrentPlatform, loadTokenConfig, } from "./config/store.js";
+// ── Global state ──────────────────────────────────────────────────────────────
+let _client = null;
+let _defaultBknId = null;
+let _defaultAgentId = null;
+/**
+ * Initialize the default KWeaver client.
+ * Must be called before any other kweaver.* function.
+ *
+ * @example
+ * ```typescript
+ * kweaver.configure({ config: true, bknId: "abc", agentId: "ag1" });
+ * kweaver.configure({ baseUrl: "https://...", accessToken: "token", bknId: "abc" });
+ * ```
+ */
+export function configure(opts) {
+    // Reset all state first so a failed re-configure never leaves a stale client.
+    _client = null;
+    _defaultBknId = null;
+    _defaultAgentId = null;
+    const { bknId, agentId, businessDomain, config, baseUrl, accessToken } = opts;
+    if (config) {
+        // Use saved credentials — do NOT pass baseUrl to avoid cross-env leaks
+        const platform = getCurrentPlatform();
+        if (!platform) {
+            throw new Error("No active platform. Run `kweaver auth login` first.");
+        }
+        const stored = loadTokenConfig(platform);
+        if (!stored?.accessToken) {
+            throw new Error(`No token for ${platform}. Run \`kweaver auth login\` first.`);
+        }
+        _client = new KWeaverClient({
+            baseUrl: platform,
+            accessToken: stored.accessToken,
+            businessDomain,
+        });
+    }
+    else {
+        if (!baseUrl && !process.env.KWEAVER_BASE_URL) {
+            throw new Error("Provide baseUrl=, config=true, or set KWEAVER_BASE_URL.");
+        }
+        if (!accessToken && !process.env.KWEAVER_TOKEN) {
+            throw new Error("Provide accessToken=, config=true, or set KWEAVER_TOKEN.");
+        }
+        _client = new KWeaverClient({ baseUrl, accessToken, businessDomain });
+    }
+    _defaultBknId = bknId ?? null;
+    _defaultAgentId = agentId ?? null;
+}
+function requireClient() {
+    if (!_client) {
+        throw new Error("No KWeaver client configured. Call kweaver.configure() first.");
+    }
+    return _client;
+}
+function requireBknId(bknId) {
+    const id = bknId ?? _defaultBknId;
+    if (!id) {
+        throw new Error("No bknId provided. Pass bknId or set it in kweaver.configure().");
+    }
+    return id;
+}
+function requireAgentId(agentId) {
+    const id = agentId ?? _defaultAgentId;
+    if (!id) {
+        throw new Error("No agentId provided. Pass agentId or set it in kweaver.configure().");
+    }
+    return id;
+}
+// ── Top-level API ─────────────────────────────────────────────────────────────
+/**
+ * Semantic search over a BKN.
+ *
+ * @example
+ * ```typescript
+ * const results = await kweaver.search("供应链风险");
+ * for (const c of results.concepts) console.log(c.concept_name);
+ * ```
+ */
+export async function search(query, opts = {}) {
+    const client = requireClient();
+    const bknId = requireBknId(opts.bknId);
+    return client.bkn.semanticSearch(bknId, query, opts);
+}
+/**
+ * List published agents.
+ *
+ * @example
+ * ```typescript
+ * const list = await kweaver.agents({ keyword: "supply" });
+ * list.forEach(a => console.log(a));
+ * ```
+ */
+export async function agents(opts = {}) {
+    return requireClient().agents.list(opts);
+}
+/**
+ * Send a message to an agent.
+ *
+ * @example
+ * ```typescript
+ * const reply = await kweaver.chat("分析供应链风险");
+ * console.log(reply.text);
+ * ```
+ */
+export async function chat(message, opts = {}) {
+    const client = requireClient();
+    const agentId = requireAgentId(opts.agentId);
+    return client.agents.chat(agentId, message, {
+        conversationId: opts.conversationId,
+        stream: false,
+    });
+}
+/**
+ * List BKNs (Business Knowledge Networks).
+ *
+ * @example
+ * ```typescript
+ * const list = await kweaver.bkns();
+ * list.forEach(b => console.log(b));
+ * ```
+ */
+export async function bkns(opts = {}) {
+    return requireClient().knowledgeNetworks.list(opts);
+}
+/**
+ * Trigger a full build (index rebuild) of a BKN.
+ *
+ * Only needed after write-side changes (added datasource, modified object/relation
+ * types). Pure read-only usage (search, chat) does not require weaver().
+ *
+ * @param opts.wait     If true, poll until completed and return the final BuildStatus.
+ * @param opts.timeout  Max wait time in **milliseconds** (default 300_000 = 5 min).
+ *                      Note: Python SDK uses seconds; multiply by 1000 when porting.
+ * @param opts.interval Poll interval in **milliseconds** (default 2_000).
+ *
+ * @example
+ * ```typescript
+ * await kweaver.weaver({ wait: true });              // block until done
+ * await kweaver.weaver({ wait: true, timeout: 60_000 }); // 60-second timeout
+ * await kweaver.weaver();                            // fire-and-forget (returns void)
+ * ```
+ */
+export async function weaver(opts = {}) {
+    const client = requireClient();
+    const bknId = requireBknId(opts.bknId);
+    if (opts.wait) {
+        return client.knowledgeNetworks.buildAndWait(bknId, {
+            timeout: opts.timeout,
+            interval: opts.interval,
+        });
+    }
+    await client.knowledgeNetworks.build(bknId);
+}
+// ── Expose underlying client ──────────────────────────────────────────────────
+/** Access the underlying KWeaverClient for advanced operations. */
+export function getClient() {
+    return requireClient();
+}
+// ── Default export ────────────────────────────────────────────────────────────
+export default { configure, search, agents, chat, bkns, weaver, getClient };

package/dist/resources/agents.d.ts

@@ -0,0 +1,37 @@
+import type { ChatResult, SendChatRequestStreamCallbacks } from "../api/agent-chat.js";
+import type { ClientContext } from "../client.js";
+export declare class AgentsResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    list(opts?: {
+        name?: string;
+        keyword?: string;
+        offset?: number;
+        limit?: number;
+    }): Promise<unknown[]>;
+    /** Resolve agent key and version for a given agent id. */
+    info(agentId: string, version?: string): Promise<{
+        id: string;
+        key: string;
+        version: string;
+    }>;
+    /**
+     * Send a single message and return the full response.
+     * Automatically resolves the agent key/version before sending.
+     */
+    chat(agentId: string, message: string, opts?: {
+        conversationId?: string;
+        version?: string;
+        stream?: boolean;
+        verbose?: boolean;
+    }): Promise<ChatResult>;
+    /**
+     * Send a message with streaming callbacks.
+     * Automatically resolves the agent key/version before sending.
+     */
+    stream(agentId: string, message: string, callbacks: SendChatRequestStreamCallbacks, opts?: {
+        conversationId?: string;
+        version?: string;
+        verbose?: boolean;
+    }): Promise<ChatResult>;
+}

package/dist/resources/agents.js

@@ -0,0 +1,60 @@
+import { listAgents } from "../api/agent-list.js";
+import { fetchAgentInfo, sendChatRequest, sendChatRequestStream, } from "../api/agent-chat.js";
+export class AgentsResource {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async list(opts = {}) {
+        const { keyword, ...rest } = opts;
+        const raw = await listAgents({ ...this.ctx.base(), name: keyword, ...rest });
+        const parsed = JSON.parse(raw);
+        const items = parsed && typeof parsed === "object" && "data" in parsed
+            ? parsed.data?.records ?? []
+            : Array.isArray(parsed)
+                ? parsed
+                : [];
+        return items;
+    }
+    /** Resolve agent key and version for a given agent id. */
+    async info(agentId, version = "v0") {
+        const info = await fetchAgentInfo({ ...this.ctx.base(), agentId, version });
+        return info;
+    }
+    /**
+     * Send a single message and return the full response.
+     * Automatically resolves the agent key/version before sending.
+     */
+    async chat(agentId, message, opts = {}) {
+        const { version = "v0", stream = false, conversationId, verbose } = opts;
+        const info = await fetchAgentInfo({ ...this.ctx.base(), agentId, version });
+        return sendChatRequest({
+            ...this.ctx.base(),
+            agentId: info.id,
+            agentKey: info.key,
+            agentVersion: info.version,
+            query: message,
+            conversationId,
+            stream,
+            verbose,
+        });
+    }
+    /**
+     * Send a message with streaming callbacks.
+     * Automatically resolves the agent key/version before sending.
+     */
+    async stream(agentId, message, callbacks, opts = {}) {
+        const { version = "v0", conversationId, verbose } = opts;
+        const info = await fetchAgentInfo({ ...this.ctx.base(), agentId, version });
+        return sendChatRequestStream({
+            ...this.ctx.base(),
+            agentId: info.id,
+            agentKey: info.key,
+            agentVersion: info.version,
+            query: message,
+            conversationId,
+            stream: true,
+            verbose,
+        }, callbacks);
+    }
+}

package/dist/resources/bkn.d.ts

@@ -0,0 +1,45 @@
+import type { ClientContext } from "../client.js";
+export interface SemanticSearchResult {
+    concepts: Array<{
+        concept_type: string;
+        concept_id: string;
+        concept_name: string;
+        intent_score: number;
+        match_score: number;
+        rerank_score: number;
+        concept_detail?: Record<string, unknown>;
+        samples?: unknown[];
+    }>;
+    hits_total: number;
+    query_understanding?: Record<string, unknown>;
+}
+/** BKN engine resource — instance queries, subgraph, action execution and logs. */
+export declare class BknResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    /**
+     * Semantic search over a BKN (Business Knowledge Network).
+     *
+     * @param bknId   BKN ID to search against.
+     * @param query   Natural-language query string.
+     * @param opts    Optional retrieval mode and max concepts.
+     */
+    semanticSearch(bknId: string, query: string, opts?: {
+        mode?: string;
+        maxConcepts?: number;
+    }): Promise<SemanticSearchResult>;
+    queryInstances(knId: string, otId: string, body: Record<string, unknown>): Promise<unknown>;
+    queryProperties(knId: string, otId: string, body: Record<string, unknown>): Promise<unknown>;
+    querySubgraph(knId: string, body: Record<string, unknown>): Promise<unknown>;
+    queryAction(knId: string, atId: string, body: Record<string, unknown>): Promise<unknown>;
+    executeAction(knId: string, atId: string, body: Record<string, unknown>): Promise<unknown>;
+    getExecution(knId: string, executionId: string): Promise<unknown>;
+    listActionLogs(knId: string, opts?: {
+        offset?: number;
+        limit?: number;
+        atId?: string;
+        status?: string;
+    }): Promise<unknown[]>;
+    getActionLog(knId: string, logId: string): Promise<unknown>;
+    cancelActionLog(knId: string, logId: string): Promise<unknown>;
+}

package/dist/resources/bkn.js

@@ -0,0 +1,86 @@
+import { objectTypeQuery, objectTypeProperties, subgraph, actionTypeQuery, actionTypeExecute, actionExecutionGet, actionLogsList, actionLogGet, actionLogCancel, } from "../api/ontology-query.js";
+import { fetchTextOrThrow } from "../utils/http.js";
+/** BKN engine resource — instance queries, subgraph, action execution and logs. */
+export class BknResource {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Semantic search over a BKN (Business Knowledge Network).
+     *
+     * @param bknId   BKN ID to search against.
+     * @param query   Natural-language query string.
+     * @param opts    Optional retrieval mode and max concepts.
+     */
+    async semanticSearch(bknId, query, opts = {}) {
+        const { baseUrl, accessToken, businessDomain } = this.ctx.base();
+        const { mode = "keyword_vector_retrieval", maxConcepts = 10 } = opts;
+        const url = `${baseUrl}/api/agent-retrieval/v1/kn/semantic-search`;
+        const { body } = await fetchTextOrThrow(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${accessToken}`,
+                token: accessToken,
+                "x-business-domain": businessDomain,
+            },
+            body: JSON.stringify({
+                kn_id: bknId,
+                query,
+                mode,
+                rerank_action: "default",
+                max_concepts: maxConcepts,
+                return_query_understanding: false,
+            }),
+        });
+        const data = JSON.parse(body);
+        return {
+            concepts: data.concepts ?? [],
+            hits_total: data.hits_total ?? 0,
+            query_understanding: data.query_understanding,
+        };
+    }
+    async queryInstances(knId, otId, body) {
+        const raw = await objectTypeQuery({ ...this.ctx.base(), knId, otId, body: JSON.stringify(body) });
+        return JSON.parse(raw);
+    }
+    async queryProperties(knId, otId, body) {
+        const raw = await objectTypeProperties({ ...this.ctx.base(), knId, otId, body: JSON.stringify(body) });
+        return JSON.parse(raw);
+    }
+    async querySubgraph(knId, body) {
+        const raw = await subgraph({ ...this.ctx.base(), knId, body: JSON.stringify(body) });
+        return JSON.parse(raw);
+    }
+    async queryAction(knId, atId, body) {
+        const raw = await actionTypeQuery({ ...this.ctx.base(), knId, atId, body: JSON.stringify(body) });
+        return JSON.parse(raw);
+    }
+    async executeAction(knId, atId, body) {
+        const raw = await actionTypeExecute({ ...this.ctx.base(), knId, atId, body: JSON.stringify(body) });
+        return JSON.parse(raw);
+    }
+    async getExecution(knId, executionId) {
+        const raw = await actionExecutionGet({ ...this.ctx.base(), knId, executionId });
+        return JSON.parse(raw);
+    }
+    async listActionLogs(knId, opts = {}) {
+        const raw = await actionLogsList({ ...this.ctx.base(), knId, ...opts });
+        const parsed = JSON.parse(raw);
+        const items = parsed && typeof parsed === "object" && "data" in parsed
+            ? (parsed.data?.records ?? [])
+            : Array.isArray(parsed)
+                ? parsed
+                : [];
+        return items;
+    }
+    async getActionLog(knId, logId) {
+        const raw = await actionLogGet({ ...this.ctx.base(), knId, logId });
+        return JSON.parse(raw);
+    }
+    async cancelActionLog(knId, logId) {
+        const raw = await actionLogCancel({ ...this.ctx.base(), knId, logId });
+        return JSON.parse(raw);
+    }
+}

package/dist/resources/context-loader.d.ts

@@ -0,0 +1,15 @@
+import type { KnSearchArgs, KnSchemaSearchArgs, QueryObjectInstanceArgs, QueryInstanceSubgraphArgs, GetLogicPropertiesValuesArgs, GetActionInfoArgs } from "../api/context-loader.js";
+import type { ClientContext } from "../client.js";
+export declare class ContextLoaderResource {
+    private readonly ctx;
+    private readonly mcpUrl;
+    private readonly knId;
+    constructor(ctx: ClientContext, mcpUrl: string, knId: string);
+    private opts;
+    search(args: KnSearchArgs): Promise<unknown>;
+    schemaSearch(args: KnSchemaSearchArgs): Promise<unknown>;
+    queryInstances(args: QueryObjectInstanceArgs): Promise<unknown>;
+    querySubgraph(args: QueryInstanceSubgraphArgs): Promise<unknown>;
+    getLogicProperties(args: GetLogicPropertiesValuesArgs): Promise<unknown>;
+    getActionInfo(args: GetActionInfoArgs): Promise<unknown>;
+}

package/dist/resources/context-loader.js

@@ -0,0 +1,32 @@
+import { knSearch, knSchemaSearch, queryObjectInstance, queryInstanceSubgraph, getLogicPropertiesValues, getActionInfo, } from "../api/context-loader.js";
+export class ContextLoaderResource {
+    ctx;
+    mcpUrl;
+    knId;
+    constructor(ctx, mcpUrl, knId) {
+        this.ctx = ctx;
+        this.mcpUrl = mcpUrl;
+        this.knId = knId;
+    }
+    opts() {
+        return { mcpUrl: this.mcpUrl, knId: this.knId, accessToken: this.ctx.base().accessToken };
+    }
+    async search(args) {
+        return knSearch(this.opts(), args);
+    }
+    async schemaSearch(args) {
+        return knSchemaSearch(this.opts(), args);
+    }
+    async queryInstances(args) {
+        return queryObjectInstance(this.opts(), args);
+    }
+    async querySubgraph(args) {
+        return queryInstanceSubgraph(this.opts(), args);
+    }
+    async getLogicProperties(args) {
+        return getLogicPropertiesValues(this.opts(), args);
+    }
+    async getActionInfo(args) {
+        return getActionInfo(this.opts(), args);
+    }
+}

package/dist/resources/conversations.d.ts

@@ -0,0 +1,11 @@
+import type { ClientContext } from "../client.js";
+export declare class ConversationsResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    list(agentId: string, opts?: {
+        limit?: number;
+    }): Promise<unknown[]>;
+    listMessages(conversationId: string, opts?: {
+        limit?: number;
+    }): Promise<unknown[]>;
+}

package/dist/resources/conversations.js

@@ -0,0 +1,17 @@
+import { listConversations, listMessages } from "../api/conversations.js";
+export class ConversationsResource {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async list(agentId, opts = {}) {
+        const raw = await listConversations({ ...this.ctx.base(), agentId, ...opts });
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    async listMessages(conversationId, opts = {}) {
+        const raw = await listMessages({ ...this.ctx.base(), conversationId, ...opts });
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+}

package/dist/resources/knowledge-networks.d.ts

@@ -0,0 +1,65 @@
+import type { ClientContext } from "../client.js";
+export interface BuildStatus {
+    state: "running" | "completed" | "failed" | string;
+    state_detail?: string;
+}
+export declare class KnowledgeNetworksResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    list(opts?: {
+        offset?: number;
+        limit?: number;
+        name_pattern?: string;
+        tag?: string;
+    }): Promise<unknown[]>;
+    get(knId: string, opts?: {
+        mode?: "export" | "";
+        include_statistics?: boolean;
+    }): Promise<unknown>;
+    create(opts: {
+        name: string;
+        description?: string;
+        tags?: string[];
+    }): Promise<unknown>;
+    update(knId: string, opts: {
+        name: string;
+        description?: string;
+        tags?: string[];
+    }): Promise<unknown>;
+    delete(knId: string): Promise<void>;
+    listObjectTypes(knId: string, opts?: {
+        branch?: string;
+        limit?: number;
+    }): Promise<unknown[]>;
+    listRelationTypes(knId: string, opts?: {
+        branch?: string;
+        limit?: number;
+    }): Promise<unknown[]>;
+    listActionTypes(knId: string, opts?: {
+        branch?: string;
+        limit?: number;
+    }): Promise<unknown[]>;
+    /**
+     * Trigger a full build (index rebuild) of a BKN.
+     * Call this after adding datasources or modifying object/relation types.
+     *
+     * @param bknId   BKN ID to build.
+     * @returns A promise that resolves immediately after the build is triggered.
+     *          Use `buildAndWait` to block until completion.
+     */
+    build(bknId: string): Promise<void>;
+    /** Poll build status for a BKN. */
+    buildStatus(bknId: string): Promise<BuildStatus>;
+    /**
+     * Trigger a full BKN build and wait for it to complete.
+     *
+     * @param bknId     BKN ID to build.
+     * @param timeout   Max wait time in milliseconds (default 300_000 = 5 min).
+     * @param interval  Poll interval in milliseconds (default 2_000).
+     * @throws Error if the build fails or times out.
+     */
+    buildAndWait(bknId: string, { timeout, interval }?: {
+        timeout?: number;
+        interval?: number;
+    }): Promise<BuildStatus>;
+}