@kweaver-ai/kweaver-sdk 0.5.2 → 0.6.1

package/dist/commands/explore-bkn.js

@@ -0,0 +1,273 @@
+import { HttpError } from "../utils/http.js";
+import { getKnowledgeNetwork, listObjectTypes, listRelationTypes, listActionTypes, } from "../api/knowledge-networks.js";
+import { objectTypeQuery, objectTypeProperties, subgraph } from "../api/ontology-query.js";
+import { semanticSearch } from "../api/semantic-search.js";
+// ── Constants ───────────────────────────────────────────────────────────────
+export const EXPLORE_BOOTSTRAP_RETRY_DELAY_MS = 300;
+export const EXPLORE_BOOTSTRAP_MAX_ATTEMPTS = 2;
+// ── Meta builder ────────────────────────────────────────────────────────────
+export function buildMeta(knRaw, otRaw, rtRaw, atRaw) {
+    const kn = JSON.parse(knRaw);
+    const otParsed = JSON.parse(otRaw);
+    const otItems = (Array.isArray(otParsed) ? otParsed
+        : Array.isArray(otParsed.entries) ? otParsed.entries
+            : Array.isArray(otParsed.object_types) ? otParsed.object_types
+                : []);
+    const rtParsed = JSON.parse(rtRaw);
+    const rtItems = (Array.isArray(rtParsed) ? rtParsed
+        : Array.isArray(rtParsed.entries) ? rtParsed.entries
+            : Array.isArray(rtParsed.relation_types) ? rtParsed.relation_types
+                : []);
+    const atParsed = JSON.parse(atRaw);
+    const atItems = (Array.isArray(atParsed) ? atParsed
+        : Array.isArray(atParsed.entries) ? atParsed.entries
+            : Array.isArray(atParsed.action_types) ? atParsed.action_types
+                : []);
+    return {
+        bkn: { id: kn.id, name: kn.name },
+        statistics: {
+            object_count: kn.statistics?.object_count ?? 0,
+            relation_count: kn.statistics?.relation_count ?? 0,
+        },
+        objectTypes: otItems.map((o) => {
+            const props = o.properties ?? o.data_properties ?? [];
+            return {
+                id: o.id,
+                name: o.name,
+                displayKey: o.display_key ?? "",
+                propertyCount: props.length,
+                properties: props.map((p) => ({
+                    name: p.name,
+                    ...(p.type !== undefined ? { type: p.type } : {}),
+                })),
+            };
+        }),
+        relationTypes: rtItems.map((r) => ({
+            id: r.id,
+            name: r.name,
+            sourceOtId: r.source_object_type_id,
+            targetOtId: r.target_object_type_id,
+            sourceOtName: r.source_object_type?.name ?? "",
+            targetOtName: r.target_object_type?.name ?? "",
+        })),
+        actionTypes: atItems.map((a) => ({
+            id: a.id,
+            name: a.name,
+        })),
+    };
+}
+// ── Bootstrap helpers ───────────────────────────────────────────────────────
+function getErrorMessage(error) {
+    const parts = [];
+    if (error instanceof Error) {
+        if (error.message) {
+            parts.push(error.message);
+        }
+        const cause = "cause" in error && error.cause instanceof Error ? error.cause.message : "";
+        if (cause) {
+            parts.push(cause);
+        }
+    }
+    else {
+        parts.push(String(error));
+    }
+    return parts.join(" ").toLowerCase();
+}
+export function isRetryableExploreBootstrapError(error) {
+    if (error instanceof HttpError) {
+        return false;
+    }
+    const message = getErrorMessage(error);
+    if (!message) {
+        return false;
+    }
+    return [
+        "fetch failed",
+        "client network socket disconnected",
+        "socket hang up",
+        "econnreset",
+        "econnrefused",
+        "etimedout",
+        "tls",
+        "secure tls connection",
+    ].some((token) => message.includes(token));
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export async function loadExploreMetaWithRetry(token, knId, businessDomain) {
+    for (let attempt = 1; attempt <= EXPLORE_BOOTSTRAP_MAX_ATTEMPTS; attempt++) {
+        try {
+            const [knRaw, otRaw, rtRaw, atRaw] = await Promise.all([
+                getKnowledgeNetwork({
+                    baseUrl: token.baseUrl,
+                    accessToken: token.accessToken,
+                    knId,
+                    businessDomain,
+                    include_statistics: true,
+                }),
+                listObjectTypes({
+                    baseUrl: token.baseUrl,
+                    accessToken: token.accessToken,
+                    knId,
+                    businessDomain,
+                }),
+                listRelationTypes({
+                    baseUrl: token.baseUrl,
+                    accessToken: token.accessToken,
+                    knId,
+                    businessDomain,
+                }),
+                listActionTypes({
+                    baseUrl: token.baseUrl,
+                    accessToken: token.accessToken,
+                    knId,
+                    businessDomain,
+                }),
+            ]);
+            return buildMeta(knRaw, otRaw, rtRaw, atRaw);
+        }
+        catch (error) {
+            if (attempt >= EXPLORE_BOOTSTRAP_MAX_ATTEMPTS || !isRetryableExploreBootstrapError(error)) {
+                throw error;
+            }
+            await sleep(EXPLORE_BOOTSTRAP_RETRY_DELAY_MS);
+        }
+    }
+    throw new Error("Failed to load explorer metadata.");
+}
+// ── HTTP helpers ────────────────────────────────────────────────────────────
+const MAX_BODY_BYTES = 1024 * 1024; // 1 MB
+export function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                req.destroy();
+                reject(new Error("Request body too large"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.on("error", reject);
+    });
+}
+export function jsonResponse(res, status, data) {
+    const body = JSON.stringify(data);
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(body);
+}
+export function handleApiError(res, error) {
+    if (error instanceof HttpError) {
+        let detail = "";
+        try {
+            const parsed = JSON.parse(error.body);
+            detail = typeof parsed.description === "string" ? parsed.description : "";
+        }
+        catch { /* ignore */ }
+        jsonResponse(res, error.status, {
+            error: detail || error.message,
+            upstream_status: error.status,
+        });
+    }
+    else if (error instanceof Error &&
+        "causeMessage" in error &&
+        typeof error.causeMessage === "string") {
+        // NetworkRequestError — include cause and URL for diagnosis
+        const net = error;
+        const detail = [net.causeMessage, net.url, net.hint].filter(Boolean).join(" | ");
+        console.error(`[network-error] ${detail}`);
+        jsonResponse(res, 502, { error: `Upstream unreachable: ${net.causeMessage}` });
+    }
+    else {
+        const message = error instanceof Error ? error.message : String(error);
+        jsonResponse(res, 500, { error: message });
+    }
+}
+export function registerBknRoutes(meta, getToken, businessDomain) {
+    const knId = meta.bkn.id;
+    const routes = new Map();
+    routes.set("GET /api/bkn/meta", (_req, res) => {
+        jsonResponse(res, 200, meta);
+    });
+    routes.set("POST /api/bkn/instances", async (req, res) => {
+        try {
+            const bodyStr = await readBody(req);
+            const body = JSON.parse(bodyStr);
+            const queryBody = JSON.stringify({
+                limit: body.limit ?? 50,
+                ...(body.search_after ? { search_after: body.search_after } : {}),
+                ...(body.condition ? { condition: body.condition } : {}),
+                ...(body._instance_identities ? { _instance_identities: body._instance_identities } : {}),
+            });
+            const t = await getToken();
+            const result = await objectTypeQuery({
+                baseUrl: t.baseUrl, accessToken: t.accessToken,
+                knId, otId: body.otId, body: queryBody, businessDomain,
+            });
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(result);
+        }
+        catch (error) {
+            handleApiError(res, error);
+        }
+    });
+    routes.set("POST /api/bkn/subgraph", async (req, res) => {
+        try {
+            const bodyStr = await readBody(req);
+            const parsed = JSON.parse(bodyStr);
+            const hasRelationPaths = Array.isArray(parsed.relation_type_paths);
+            const t = await getToken();
+            const result = await subgraph({
+                baseUrl: t.baseUrl, accessToken: t.accessToken,
+                knId, body: bodyStr, businessDomain,
+                ...(hasRelationPaths ? { queryType: "relation_path" } : {}),
+            });
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(result);
+        }
+        catch (error) {
+            handleApiError(res, error);
+        }
+    });
+    routes.set("POST /api/bkn/search", async (req, res) => {
+        try {
+            const bodyStr = await readBody(req);
+            const body = JSON.parse(bodyStr);
+            const t = await getToken();
+            const result = await semanticSearch({
+                baseUrl: t.baseUrl, accessToken: t.accessToken,
+                knId, query: body.query, businessDomain,
+                maxConcepts: body.maxConcepts,
+            });
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(result);
+        }
+        catch (error) {
+            handleApiError(res, error);
+        }
+    });
+    routes.set("POST /api/bkn/properties", async (req, res) => {
+        try {
+            const bodyStr = await readBody(req);
+            const body = JSON.parse(bodyStr);
+            const { otId, ...rest } = body;
+            const t = await getToken();
+            const result = await objectTypeProperties({
+                baseUrl: t.baseUrl, accessToken: t.accessToken,
+                knId, otId, body: JSON.stringify(rest), businessDomain,
+            });
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(result);
+        }
+        catch (error) {
+            handleApiError(res, error);
+        }
+    });
+    return routes;
+}

package/dist/commands/explore-chat.d.ts

@@ -0,0 +1,3 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import { type TokenProvider } from "./explore-bkn.js";
+export declare function registerChatRoutes(getToken: TokenProvider, businessDomain: string): Map<string, (req: IncomingMessage, res: ServerResponse) => void>;

package/dist/commands/explore-chat.js

@@ -0,0 +1,193 @@
+import { listAgents } from "../api/agent-list.js";
+import { fetchAgentInfo, sendChatRequestStream } from "../api/agent-chat.js";
+import { getTracesByConversation } from "../api/conversations.js";
+import { readBody, handleApiError, jsonResponse } from "./explore-bkn.js";
+// ── Chat route handlers ──────────────────────────────────────────────────────
+export function registerChatRoutes(getToken, businessDomain) {
+    const routes = new Map();
+    // GET /api/chat/agents — list published agents
+    routes.set("GET /api/chat/agents", async (_req, res) => {
+        try {
+            const t = await getToken();
+            const raw = await listAgents({
+                baseUrl: t.baseUrl,
+                accessToken: t.accessToken,
+                businessDomain,
+                limit: 200,
+            });
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(raw);
+        }
+        catch (error) {
+            handleApiError(res, error);
+        }
+    });
+    // POST /api/chat/send — stream a chat response via SSE
+    routes.set("POST /api/chat/send", async (req, res) => {
+        let bodyStr;
+        try {
+            bodyStr = await readBody(req);
+        }
+        catch {
+            res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ error: "Failed to read request body" }));
+            return;
+        }
+        let agentId;
+        let message;
+        let conversationId;
+        let version;
+        try {
+            const body = JSON.parse(bodyStr);
+            agentId = body.agentId ?? "";
+            message = body.message ?? "";
+            conversationId = body.conversationId;
+            version = body.version;
+        }
+        catch {
+            res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ error: "Invalid JSON body" }));
+            return;
+        }
+        if (!agentId || !message) {
+            res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ error: "agentId and message are required" }));
+            return;
+        }
+        // Fetch agent info to get key + version
+        const t = await getToken();
+        let agentInfo;
+        try {
+            agentInfo = await fetchAgentInfo({
+                baseUrl: t.baseUrl,
+                accessToken: t.accessToken,
+                agentId,
+                version: version ?? "v0",
+                businessDomain,
+            });
+        }
+        catch (error) {
+            handleApiError(res, error);
+            return;
+        }
+        // Set SSE response headers
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+            "X-Accel-Buffering": "no",
+        });
+        // SSE heartbeat — keeps connection alive and lets client detect stalls
+        const heartbeat = setInterval(() => {
+            try {
+                res.write(": heartbeat\n\n");
+            }
+            catch { /* connection gone */ }
+        }, 15000);
+        // Stream chat response
+        try {
+            const result = await sendChatRequestStream({
+                baseUrl: t.baseUrl,
+                accessToken: t.accessToken,
+                agentId: agentInfo.id,
+                agentKey: agentInfo.key,
+                agentVersion: agentInfo.version,
+                query: message,
+                conversationId,
+                stream: true,
+                businessDomain,
+            }, {
+                onTextDelta: (fullText, currentSegmentText) => {
+                    const event = JSON.stringify({ type: "text", fullText, currentText: currentSegmentText });
+                    res.write(`data: ${event}\n\n`);
+                },
+                onProgress: (items) => {
+                    const event = JSON.stringify({ type: "progress", items });
+                    res.write(`data: ${event}\n\n`);
+                },
+                onSegmentComplete: (segmentText, segmentIndex) => {
+                    const event = JSON.stringify({ type: "segment", text: segmentText, index: segmentIndex });
+                    res.write(`data: ${event}\n\n`);
+                },
+                onStepMeta: (meta) => {
+                    const event = JSON.stringify({ type: "step_meta", meta });
+                    res.write(`data: ${event}\n\n`);
+                },
+                onConversationId: (convId) => {
+                    const event = JSON.stringify({ type: "conversation_id", conversationId: convId });
+                    res.write(`data: ${event}\n\n`);
+                },
+            });
+            clearInterval(heartbeat);
+            const doneEvent = JSON.stringify({
+                type: "done",
+                conversationId: result.conversationId ?? conversationId ?? "",
+            });
+            res.write(`data: ${doneEvent}\n\n`);
+            res.end();
+        }
+        catch (error) {
+            clearInterval(heartbeat);
+            // Extract detailed error info — HttpError carries the upstream response body
+            let errMsg = error instanceof Error ? error.message : String(error);
+            let errDetail;
+            if (error && typeof error === "object" && "body" in error) {
+                const body = error.body;
+                if (body) {
+                    errDetail = body;
+                    // Try to extract a human-readable message from JSON body
+                    try {
+                        const parsed = JSON.parse(body);
+                        const desc = parsed.description || parsed.detail || parsed.message || parsed.error;
+                        if (desc)
+                            errMsg += `: ${desc}`;
+                        if (parsed.solution)
+                            errMsg += ` (${parsed.solution})`;
+                    }
+                    catch {
+                        errMsg += `: ${body.slice(0, 500)}`;
+                    }
+                }
+            }
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify({ error: errMsg, detail: errDetail }));
+            }
+            else {
+                const errEvent = JSON.stringify({
+                    type: "error",
+                    error: errMsg,
+                    detail: errDetail,
+                });
+                res.write(`data: ${errEvent}\n\n`);
+                res.end();
+            }
+        }
+    });
+    // GET /api/chat/trace?agentId=X&conversationId=Y — fetch trace data
+    routes.set("GET /api/chat/trace", async (req, res) => {
+        try {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            const agentId = url.searchParams.get("agentId") || "";
+            const conversationId = url.searchParams.get("conversationId") || "";
+            if (!agentId || !conversationId) {
+                jsonResponse(res, 400, { error: "agentId and conversationId are required" });
+                return;
+            }
+            const t = await getToken();
+            const raw = await getTracesByConversation({
+                baseUrl: t.baseUrl,
+                accessToken: t.accessToken,
+                agentId,
+                conversationId,
+                businessDomain,
+            });
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(raw);
+        }
+        catch (error) {
+            handleApiError(res, error);
+        }
+    });
+    return routes;
+}

package/dist/commands/explore-vega.d.ts

@@ -0,0 +1,3 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import { type TokenProvider } from "./explore-bkn.js";
+export declare function registerVegaRoutes(getToken: TokenProvider, businessDomain: string): Map<string, (req: IncomingMessage, res: ServerResponse) => void>;

package/dist/commands/explore-vega.js

@@ -0,0 +1,71 @@
+import { listVegaCatalogs, vegaCatalogHealthStatus, listVegaCatalogResources, queryVegaResourceData, } from "../api/vega.js";
+import { readBody, jsonResponse, handleApiError } from "./explore-bkn.js";
+// ── Vega route handlers ──────────────────────────────────────────────────────
+export function registerVegaRoutes(getToken, businessDomain) {
+    const routes = new Map();
+    // GET /api/vega/catalogs — list catalogs + health status in parallel
+    routes.set("GET /api/vega/catalogs", async (_req, res) => {
+        try {
+            const t = await getToken();
+            const [catalogsResult, healthResult] = await Promise.allSettled([
+                listVegaCatalogs({
+                    baseUrl: t.baseUrl, accessToken: t.accessToken, businessDomain,
+                }),
+                vegaCatalogHealthStatus({
+                    baseUrl: t.baseUrl, accessToken: t.accessToken, businessDomain, ids: "all",
+                }),
+            ]);
+            const catalogs = catalogsResult.status === "fulfilled"
+                ? JSON.parse(catalogsResult.value)
+                : { error: String(catalogsResult.reason) };
+            const health = healthResult.status === "fulfilled"
+                ? JSON.parse(healthResult.value)
+                : { error: String(healthResult.reason) };
+            jsonResponse(res, 200, { catalogs, health });
+        }
+        catch (error) {
+            handleApiError(res, error);
+        }
+    });
+    // GET /api/vega/catalog-resources?catalogId=<id> — list resources in a catalog
+    routes.set("GET /api/vega/catalog-resources", async (req, res) => {
+        try {
+            const catalogId = new URL(req.url ?? "/", "http://localhost").searchParams.get("catalogId");
+            if (!catalogId) {
+                jsonResponse(res, 400, { error: "catalogId query parameter is required" });
+                return;
+            }
+            const t = await getToken();
+            const raw = await listVegaCatalogResources({
+                baseUrl: t.baseUrl, accessToken: t.accessToken, businessDomain, id: catalogId,
+            });
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(raw);
+        }
+        catch (error) {
+            handleApiError(res, error);
+        }
+    });
+    // POST /api/vega/query — query resource data
+    routes.set("POST /api/vega/query", async (req, res) => {
+        try {
+            const bodyStr = await readBody(req);
+            const body = JSON.parse(bodyStr);
+            if (!body.resourceId) {
+                jsonResponse(res, 400, { error: "resourceId is required" });
+                return;
+            }
+            const t = await getToken();
+            const raw = await queryVegaResourceData({
+                baseUrl: t.baseUrl, accessToken: t.accessToken, businessDomain,
+                id: body.resourceId, body: JSON.stringify(body.query ?? {}),
+            });
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(raw);
+        }
+        catch (error) {
+            handleApiError(res, error);
+        }
+    });
+    return routes;
+}

package/dist/commands/explore.d.ts

@@ -0,0 +1,9 @@
+export interface ExploreOptions {
+    knId: string;
+    agentId: string;
+    port: number;
+    open: boolean;
+    businessDomain: string;
+}
+export declare function parseExploreArgs(args: string[]): ExploreOptions;
+export declare function runExploreCommand(args: string[]): Promise<number>;