@kweaver-ai/kweaver-sdk 0.8.3 → 0.8.4

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

@@ -43,13 +43,21 @@ export interface AgentInfo {
 }
 export declare function buildChatUrl(baseUrl: string, agentKey: string): string;
 export declare function buildAgentInfoUrl(baseUrl: string, agentId: string, version: string): string;
-export declare function fetchAgentInfo(options: {
+/** Options for fetching agent data from the agent-factory API. */
+export interface AgentFetchOptions {
     baseUrl: string;
     accessToken: string;
     agentId: string;
     version: string;
     businessDomain?: string;
-}): Promise<AgentInfo>;
+}
+/**
+ * Fetch the full agent configuration body (system_prompt, llms, skills, …) from
+ * the agent-factory API. Returns the raw parsed JSON object unchanged — callers
+ * narrow it as needed (see fetchAgentInfo).
+ */
+export declare function fetchAgentConfig(options: AgentFetchOptions): Promise<Record<string, unknown>>;
+export declare function fetchAgentInfo(options: AgentFetchOptions): Promise<AgentInfo>;
 export declare function extractText(data: unknown): string;
 export declare function processIncrementalUpdate(data: {
     key?: string[];

package/dist/api/agent-chat.js

@@ -17,7 +17,12 @@ function applyConversationOptions(body, conversationId) {
     body.conversation_id = conversationId;
     body.chat_option = { is_need_history: true };
 }
-export async function fetchAgentInfo(options) {
+/**
+ * Fetch the full agent configuration body (system_prompt, llms, skills, …) from
+ * the agent-factory API. Returns the raw parsed JSON object unchanged — callers
+ * narrow it as needed (see fetchAgentInfo).
+ */
+export async function fetchAgentConfig(options) {
     const { baseUrl, accessToken, agentId, version, businessDomain = "bd_public" } = options;
     const url = buildAgentInfoUrl(baseUrl, agentId, version);
     const agentHeaders = {
@@ -35,13 +40,22 @@ export async function fetchAgentInfo(options) {
         headers: agentHeaders,
     });
     const data = JSON.parse(body);
-    if (!data.id || !data.key) {
+    if (data === null || typeof data !== "object") {
+        throw new Error("Agent config response was not a JSON object.");
+    }
+    return data;
+}
+export async function fetchAgentInfo(options) {
+    const data = await fetchAgentConfig(options);
+    const id = data["id"];
+    const key = data["key"];
+    if (typeof id !== "string" || !id || typeof key !== "string" || !key) {
         throw new Error("Agent info response did not include id and key.");
     }
     return {
-        id: data.id,
-        key: data.key,
-        version: typeof data.version === "string" ? data.version : version,
+        id,
+        key,
+        version: typeof data["version"] === "string" ? data["version"] : options.version,
     };
 }
 function getByPath(obj, path) {

package/dist/api/datasources.d.ts

@@ -1,3 +1,17 @@
+/**
+ * @deprecated The legacy `/datasources` API surface. The platform has migrated
+ * data-connection management to vega catalogs; prefer the equivalents from
+ * `../api/vega.js`:
+ *
+ *   testDatasource    → testVegaCatalogConnection
+ *   createDatasource  → createVegaCatalog
+ *   listDatasources   → listVegaCatalogs
+ *   getDatasource     → getVegaCatalog
+ *   deleteDatasource  → deleteVegaCatalogs
+ *
+ * Kept as thin back-compat shims for users on older backends; may be removed
+ * in a future major release.
+ */
 export interface TestDatasourceOptions {
     baseUrl: string;
     accessToken: string;

package/dist/api/datasources.js

@@ -1,3 +1,17 @@
+/**
+ * @deprecated The legacy `/datasources` API surface. The platform has migrated
+ * data-connection management to vega catalogs; prefer the equivalents from
+ * `../api/vega.js`:
+ *
+ *   testDatasource    → testVegaCatalogConnection
+ *   createDatasource  → createVegaCatalog
+ *   listDatasources   → listVegaCatalogs
+ *   getDatasource     → getVegaCatalog
+ *   deleteDatasource  → deleteVegaCatalogs
+ *
+ * Kept as thin back-compat shims for users on older backends; may be removed
+ * in a future major release.
+ */
 import { HttpError } from "../utils/http.js";
 import { encryptPassword } from "../utils/crypto.js";
 import { buildHeaders } from "./headers.js";

package/dist/cli.js

@@ -7,7 +7,6 @@ import { runCallCommand } from "./commands/call.js";
 import { runConfigCommand } from "./commands/config.js";
 import { runContextLoaderCommand } from "./commands/context-loader.js";
 import { runDataflowCommand } from "./commands/dataflow.js";
-import { runDsCommand } from "./commands/ds.js";
 import { runExploreCommand } from "./commands/explore.js";
 import { runResourceCommand } from "./commands/resource.js";
 import { runModelCommand } from "./commands/model.js";
@@ -46,7 +45,6 @@ function printHelp() {
                 title: "AI DATA PLATFORM",
                 items: [
                     { name: "bkn", desc: "Knowledge network — build, query, action, metric" },
-                    { name: "ds", desc: "Datasource (list, get, connect, tables)" },
                     { name: "resource (res)", desc: "Resources — list, find, get, query, delete" },
                     { name: "dataflow", desc: "Dataflow document workflows (run, runs, logs)" },
                     { name: "vega", desc: "Vega observability — catalog, resource, query" },
@@ -135,13 +133,6 @@ Usage:
   kweaver agent publish <agent_id> [-bd value]
   kweaver agent unpublish <agent_id> [-bd value]
 
-  kweaver ds list [--keyword X] [--type T] [-bd value]
-  kweaver ds get <id>
-  kweaver ds delete <id> [-y]
-  kweaver ds tables <id> [--keyword X]
-  kweaver ds connect <db_type> <host> <port> <database> --account X --password Y [--schema S] [--name N]
-                     [--reuse-existing|--force-new]
-
   kweaver dataflow templates [--json]
   kweaver dataflow create-dataset --template <name> --set "key=value" [--json] [-bd value]
   kweaver dataflow create-bkn --template <name> --set "key=value" [--json] [-bd value]
@@ -165,7 +156,8 @@ Usage:
   kweaver bkn get <kn-id> [options]
   kweaver bkn search <kn-id> <query> [--max-concepts N] [--mode M] [-bd value]
   kweaver bkn create [options]
-  kweaver bkn create-from-ds [options]
+  kweaver bkn create-from-catalog [options]
+  [deprecated] kweaver bkn create-from-ds [options]   (alias for create-from-catalog)
   kweaver bkn update <kn-id> [options]
   kweaver bkn delete <kn-id> [-y]
   kweaver bkn build <kn-id> [--wait] [--no-wait] [--timeout N]
@@ -252,7 +244,6 @@ Commands:
   token          Print the current access token, refreshing it first if needed
   call (curl)    Call an API with curl-style flags and auto-injected token headers
   agent          Agent CRUD, chat, sessions, history, publish/unpublish
-  ds             Manage datasources (list, get, delete, tables, connect)
   dataflow       Dataflow document workflows (list, run, runs, logs)
   model          Model factory: LLM/small-model CRUD (manager) and llm chat (OpenAI-compatible API)
   resource|res   List, find, get, query, delete vega-backend resources (table / logicview)
@@ -340,9 +331,6 @@ export async function run(argv) {
     if (command === "call" || command === "curl") {
         return runCallCommand(rest);
     }
-    if (command === "ds") {
-        return runDsCommand(rest);
-    }
     if (command === "dataflow") {
         return runDataflowCommand(rest);
     }

package/dist/client.d.ts

@@ -96,7 +96,13 @@ export declare class KWeaverClient implements ClientContext {
     readonly conversations: ConversationsResource;
     /** Dataflow DAG automation (create/run/poll/delete). */
     readonly dataflows: DataflowsResource;
-    /** Data source management (connect, test, list tables). */
+    /**
+     * Data source management (connect, test, list tables).
+     *
+     * @deprecated Datasource is a legacy concept. Use `client.vega.catalogs` for
+     * catalog CRUD and `client.resources` for resource queries. This property is
+     * kept as a thin back-compat layer and may be removed in a future major release.
+     */
     readonly datasources: DataSourcesResource;
     /** Vega-backend resource management (table/logicview resources under a catalog). */
     readonly resources: ResourcesResource;

package/dist/client.js

@@ -58,7 +58,13 @@ export class KWeaverClient {
     conversations;
     /** Dataflow DAG automation (create/run/poll/delete). */
     dataflows;
-    /** Data source management (connect, test, list tables). */
+    /**
+     * Data source management (connect, test, list tables).
+     *
+     * @deprecated Datasource is a legacy concept. Use `client.vega.catalogs` for
+     * catalog CRUD and `client.resources` for resource queries. This property is
+     * kept as a thin back-compat layer and may be removed in a future major release.
+     */
     datasources;
     /** Vega-backend resource management (table/logicview resources under a catalog). */
     resources;

package/dist/commands/bkn-ops.d.ts

@@ -44,7 +44,7 @@ export declare function generateObjectTypeBkn(tableName: string, dvId: string, p
     name: string;
     type: string;
 }>): string;
-export declare function runKnCreateFromDsCommand(args: string[], sampleRows?: Record<string, Array<Record<string, string | null>>>): Promise<number>;
+export declare function runKnCreateFromCatalogCommand(args: string[], sampleRows?: Record<string, Array<Record<string, string | null>>>, invokedAs?: "create-from-catalog" | "create-from-ds"): Promise<number>;
 export declare function parseKnCreateFromCsvArgs(args: string[]): {
     dsId: string;
     files: string;

package/dist/commands/bkn-ops.js

@@ -14,6 +14,7 @@ import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { runDsImportCsv } from "./ds.js";
 import { renderHelp } from "../help/format.js";
+import { warnDeprecated } from "../utils/deprecation.js";
 import { pollWithBackoff, detectDisplayKey, formatPkDetectionError, parsePkMap, resolvePrimaryKey, confirmYes, assertVegaCatalogId, } from "./bkn-utils.js";
 // ── BKN object name validation ──────────────────────────────────────────────
 // Mirrors bkn-backend OBJECT_NAME_MAX_LENGTH (interfaces/common.go:28) and
@@ -507,29 +508,45 @@ export async function runKnPullCommand(args) {
         return 1;
     }
 }
-// ── Create from datasource ──────────────────────────────────────────────────
+// ── Create from catalog (formerly create-from-ds) ──────────────────────────
+const CREATE_FROM_CATALOG_FLAGS = [
+    { name: "--name <s>", desc: "Knowledge network name (required)" },
+    { name: "--tables <a,b>", desc: "Comma-separated table names (default: all)" },
+    { name: "--pk-map <s>", desc: "Explicit primary keys <table>:<field>[,...]; required when auto-detection fails" },
+    { name: "--build", desc: "Build after creation (default)" },
+    { name: "--no-build", desc: "Skip build after creation" },
+    { name: "--timeout <n>", desc: "Build timeout in seconds (default: 300)" },
+    { name: "--no-rollback", desc: "Keep partially-created KN on failure (debug; default: rollback)" },
+    { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
+    { name: "--pretty", desc: "Pretty-print output (default)" },
+];
+const KN_CREATE_FROM_CATALOG_HELP = renderHelp({
+    tagline: "Create a knowledge network from a vega catalog (resources + object types + optional build).",
+    usage: "kweaver bkn create-from-catalog <vega-catalog-id> --name X [flags]",
+    flags: CREATE_FROM_CATALOG_FLAGS,
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver bkn create-from-catalog vcat-123 --name customers",
+        "kweaver bkn create-from-catalog vcat-123 --name orders --tables orders,items --no-build",
+    ],
+    learnMore: [
+        "<vega-catalog-id> is a vega catalog id (use `kweaver vega catalog list` to find one)",
+        "Legacy data-connection datasource UUIDs are no longer accepted",
+        "`kweaver bkn create-from-ds` is kept as a deprecated alias for back-compat",
+    ],
+});
 const KN_CREATE_FROM_DS_HELP = renderHelp({
-    tagline: "Create a knowledge network from a vega catalog datasource (resources + object types + optional build)",
+    tagline: "[DEPRECATED] Alias for `kweaver bkn create-from-catalog`. Subcommand name retained for back-compat; flags and behavior identical.",
     usage: "kweaver bkn create-from-ds <vega-catalog-id> --name X [flags]",
-    flags: [
-        { name: "--name <s>", desc: "Knowledge network name (required)" },
-        { name: "--tables <a,b>", desc: "Comma-separated table names (default: all)" },
-        { name: "--pk-map <s>", desc: "Explicit primary keys <table>:<field>[,...]; required when auto-detection fails" },
-        { name: "--build", desc: "Build after creation (default)" },
-        { name: "--no-build", desc: "Skip build after creation" },
-        { name: "--timeout <n>", desc: "Build timeout in seconds (default: 300)" },
-        { name: "--no-rollback", desc: "Keep partially-created KN on failure (debug; default: rollback)" },
-        { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
-        { name: "--pretty", desc: "Pretty-print output (default)" },
-    ],
+    flags: CREATE_FROM_CATALOG_FLAGS,
     inheritedFlags: "--base-url, --token, --user, --help",
     examples: [
         "kweaver bkn create-from-ds vcat-123 --name customers",
         "kweaver bkn create-from-ds vcat-123 --name orders --tables orders,items --no-build",
     ],
     learnMore: [
-        "<vega-catalog-id> is a vega catalog id (use `kweaver vega catalog list` to find one)",
-        "Legacy data-connection datasource UUIDs are no longer accepted",
+        "Prefer `kweaver bkn create-from-catalog` in new scripts.",
+        "<vega-catalog-id> is a vega catalog id (use `kweaver vega catalog list` to find one).",
     ],
 });
 export function parseKnCreateFromDsArgs(args) {
@@ -590,7 +607,7 @@ export function parseKnCreateFromDsArgs(args) {
     }
     const tables = tablesStr ? tablesStr.split(",").map((s) => s.trim()).filter(Boolean) : [];
     if (!dsId || !name) {
-        throw new Error("Usage: kweaver bkn create-from-ds <ds-id> --name X [options]");
+        throw new Error("Usage: kweaver bkn create-from-catalog <vega-catalog-id> --name X [options]");
     }
     assertVegaCatalogId(dsId);
     const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
@@ -616,19 +633,23 @@ export function generateObjectTypeBkn(tableName, dvId, pk, dk, columns) {
     const frontmatter = `---\ntype: object_type\nid: ${safeId}\nname: ${tableName}\n---\n\n`;
     return `${frontmatter}${header}\n${dsTable}\n${dpHeader}${dpRows}\n`;
 }
-export async function runKnCreateFromDsCommand(args, sampleRows) {
+export async function runKnCreateFromCatalogCommand(args, sampleRows, invokedAs = "create-from-catalog") {
+    const help = invokedAs === "create-from-ds" ? KN_CREATE_FROM_DS_HELP : KN_CREATE_FROM_CATALOG_HELP;
     let options;
     try {
         options = parseKnCreateFromDsArgs(args);
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(KN_CREATE_FROM_DS_HELP);
+            console.log(help);
             return 0;
         }
         console.error(formatHttpError(error));
         return 1;
     }
+    if (invokedAs === "create-from-ds") {
+        warnDeprecated("kweaver bkn create-from-ds", "renamed to `kweaver bkn create-from-catalog`. The old name is kept as an alias and will be removed in a future major release.");
+    }
     try {
         const token = await ensureValidToken();
         const base = {
@@ -944,7 +965,7 @@ export function parseKnCreateFromCsvArgs(args) {
     }
     const tables = tablesStr ? tablesStr.split(",").map((s) => s.trim()).filter(Boolean) : [];
     if (!dsId || !files || !name) {
-        throw new Error("Usage: kweaver bkn create-from-csv <ds-id> --files <glob> --name X [options]");
+        throw new Error("Usage: kweaver bkn create-from-csv <vega-catalog-id> --files <glob> --name X [options]");
     }
     assertVegaCatalogId(dsId);
     const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
@@ -994,7 +1015,7 @@ export async function runKnCreateFromCsvCommand(args) {
         return importResult.code;
     }
     // (Phase 1.5 metadata scan removed — runDsImportCsv now self-scans on
-    // success, and runKnCreateFromDsCommand's table-discovery retry triggers
+    // success, and runKnCreateFromCatalogCommand's table-discovery retry triggers
     // a scan if the catalog still lags. Two layers of fallback are enough.)
     // Phase 2: Create KN from datasource
     console.error("Phase 2: Creating knowledge network ...");
@@ -1016,7 +1037,7 @@ export async function runKnCreateFromCsvCommand(args) {
             : []),
         ...(options.noRollback ? ["--no-rollback"] : []),
     ];
-    return runKnCreateFromDsCommand(knArgs, importResult.sampleRows);
+    return runKnCreateFromCatalogCommand(knArgs, importResult.sampleRows, "create-from-catalog");
 }
 export function parseActionScheduleArgs(args) {
     const [action, ...rest] = args;

package/dist/commands/bkn.js

@@ -7,7 +7,7 @@ import { resolveBusinessDomain } from "../config/store.js";
 import { renderHelp } from "../help/format.js";
 import { runKnObjectTypeCommand, runKnRelationTypeCommand, runKnActionTypeCommand, runKnConceptGroupCommand, } from "./bkn-schema.js";
 import { runKnSubgraphCommand, runKnActionExecutionCommand, runKnActionLogCommand, runKnSearchCommand, runKnRelationTypePathsCommand, runKnResourcesCommand, } from "./bkn-query.js";
-import { runKnBuildCommand, runKnValidateCommand, runKnPushCommand, runKnPullCommand, runKnCreateFromDsCommand, runKnCreateFromCsvCommand, runKnActionScheduleCommand, runKnJobCommand, } from "./bkn-ops.js";
+import { runKnBuildCommand, runKnValidateCommand, runKnPushCommand, runKnPullCommand, runKnCreateFromCatalogCommand, runKnCreateFromCsvCommand, runKnActionScheduleCommand, runKnJobCommand, } from "./bkn-ops.js";
 import { runKnMetricCommand } from "./bkn-metric.js";
 // Re-export shared utils for backward compatibility (tests import from bkn.js)
 export { pollWithBackoff, parseOntologyQueryFlags, parseJsonObject, parseSearchAfterArray, confirmYes, DISPLAY_HINTS, detectPrimaryKey, detectDisplayKey, } from "./bkn-utils.js";
@@ -368,7 +368,8 @@ const KN_HELP = renderHelp({
                 { name: "list", desc: "List knowledge networks" },
                 { name: "get", desc: "Get KN detail (use --stats or --export)" },
                 { name: "create", desc: "Create a KN (empty or from --body-file)" },
-                { name: "create-from-ds", desc: "Create KN from datasource (--name --tables --build)" },
+                { name: "create-from-catalog", desc: "Create KN from a vega catalog (--name --tables --build)" },
+                { name: "create-from-ds", desc: "[deprecated] Alias for `create-from-catalog`; kept for back-compat" },
                 { name: "create-from-csv", desc: "Import CSVs then create KN (--files glob --name --build)" },
                 { name: "update", desc: "Update a KN" },
                 { name: "delete", desc: "Delete a KN" },
@@ -442,8 +443,10 @@ export async function runKnCommand(args) {
             return runKnGetCommand(rest);
         if (subcommand === "create")
             return runKnCreateCommand(rest);
+        if (subcommand === "create-from-catalog")
+            return runKnCreateFromCatalogCommand(rest, undefined, "create-from-catalog");
         if (subcommand === "create-from-ds")
-            return runKnCreateFromDsCommand(rest);
+            return runKnCreateFromCatalogCommand(rest, undefined, "create-from-ds");
         if (subcommand === "create-from-csv")
             return runKnCreateFromCsvCommand(rest);
         if (subcommand === "update")

package/dist/commands/ds.d.ts

@@ -1,33 +1,3 @@
-export declare function runDsCommand(args: string[]): Promise<number>;
-export declare function parseDsListArgs(args: string[]): {
-    keyword?: string;
-    type?: string;
-    businessDomain: string;
-    pretty: boolean;
-};
-/**
- * Match candidate signature against a list response (the kind returned by
- * `listDatasources`). Connection metadata lives under `bin_data` — host,
- * port, account, plus type-specific fields (`database_name` for MySQL etc.).
- *
- * Exported for unit testing.
- */
-export interface DsMatchSignature {
-    type: string;
-    host: string;
-    port: number;
-    database: string;
-    account: string;
-    name?: string;
-}
-export interface DsMatchHit {
-    id: string;
-    name: string;
-    matchedByName: boolean;
-    matchedByTuple: boolean;
-}
-export declare function findExistingDatasource(listBody: string, sig: DsMatchSignature): DsMatchHit | undefined;
-export declare function findDatasourceIdByName(listBody: string, name: string): string | undefined;
 export declare function parseImportCsvArgs(args: string[]): {
     datasourceId: string;
     files: string;
@@ -44,4 +14,3 @@ export interface ImportCsvResult {
     sampleRows: Record<string, Array<Record<string, string | null>>>;
 }
 export declare function runDsImportCsv(args: string[]): Promise<ImportCsvResult>;
-export declare function runDsImportCsvCommand(args: string[]): Promise<number>;