@kweaver-ai/kweaver-sdk 0.7.3 → 0.8.1

package/dist/commands/bkn-ops.js

@@ -5,7 +5,7 @@ import { loadNetwork, allObjects, allRelations, allActions, generateChecksum, va
 import { prepareBknDirectoryForImport, stripBknEncodingCliArgs, } from "../utils/bkn-encoding.js";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
 import { createKnowledgeNetwork, createObjectTypes, deleteKnowledgeNetwork, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
-import { listTablesWithColumns, scanDatasourceMetadata } from "../api/datasources.js";
+import { listTablesWithColumns, scanDatasourceMetadata } from "../api/vega.js";
 import { createDataView, findDataView } from "../api/dataviews.js";
 import { resolveFiles } from "./ds.js";
 import { buildTableName } from "./import-csv.js";
@@ -13,7 +13,7 @@ import { downloadBkn, uploadBkn, listActionSchedules, getActionSchedule, createA
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { runDsImportCsv } from "./ds.js";
-import { pollWithBackoff, detectPrimaryKey, detectDisplayKey, formatPkDetectionError, parsePkMap, confirmYes, } from "./bkn-utils.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
 // validateObjectName (driveradapters/validate.go:85). 40 utf-8 codepoints,
@@ -473,9 +473,11 @@ export async function runKnPullCommand(args) {
     }
 }
 // ── Create from datasource ──────────────────────────────────────────────────
-const KN_CREATE_FROM_DS_HELP = `kweaver bkn create-from-ds <ds-id> --name X [options]
+const KN_CREATE_FROM_DS_HELP = `kweaver bkn create-from-ds <vega-catalog-id> --name X [options]
 
-Create a knowledge network from a datasource (dataviews + object types + optional build).
+Create a knowledge network from a vega catalog datasource (dataviews + object types + optional build).
+<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).
 
 Options:
   --name <s>       Knowledge network name (required)
@@ -548,6 +550,7 @@ export function parseKnCreateFromDsArgs(args) {
     if (!dsId || !name) {
         throw new Error("Usage: kweaver bkn create-from-ds <ds-id> --name X [options]");
     }
+    assertVegaCatalogId(dsId);
     const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
@@ -644,19 +647,25 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         }
         for (const t of targetTables) {
             const override = options.pkMap[t.name];
-            if (override) {
-                if (!t.columns.some((c) => c.name === override)) {
-                    throw new Error(`--pk-map specifies '${override}' for table '${t.name}', but no such column. ` +
-                        `Columns: ${t.columns.map((c) => c.name).join(", ")}`);
-                }
-                tablePks[t.name] = override;
+            if (override && !t.columns.some((c) => c.name === override)) {
+                throw new Error(`--pk-map specifies '${override}' for table '${t.name}', but no such column. ` +
+                    `Columns: ${t.columns.map((c) => c.name).join(", ")}`);
+            }
+            const resolution = resolvePrimaryKey(t, sampleRows?.[t.name], override);
+            if (resolution.pk) {
+                tablePks[t.name] = resolution.pk;
                 continue;
             }
-            const result = detectPrimaryKey(t, sampleRows?.[t.name]);
-            if (!result.pk) {
-                throw new Error(formatPkDetectionError(t.name, result));
+            if (resolution.source === "ambiguous") {
+                const cols = (resolution.ambiguous ?? []).join(", ");
+                throw new Error(`Table '${t.name}' has a composite PRIMARY KEY (${cols}). ` +
+                    `BKN object types take a single primary key — pick one with --pk-map ${t.name}:<column>.`);
             }
-            tablePks[t.name] = result.pk;
+            throw new Error(formatPkDetectionError(t.name, {
+                pk: null,
+                candidates: resolution.candidates ?? [],
+                sampleSize: resolution.sampleSize ?? 0,
+            }));
         }
         // Phase 1: Create DataViews for each table. findDataView is idempotent;
         // not tracked for rollback so a retry can reuse what's already there.
@@ -797,9 +806,11 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
     }
 }
 // ── Create from CSV ─────────────────────────────────────────────────────────
-const KN_CREATE_FROM_CSV_HELP = `kweaver bkn create-from-csv <ds-id> --files <glob> --name X [options]
+const KN_CREATE_FROM_CSV_HELP = `kweaver bkn create-from-csv <vega-catalog-id> --files <glob> --name X [options]
 
-Import CSV files into datasource, then create a knowledge network.
+Import CSV files into a vega catalog datasource, then create a knowledge network.
+<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).
 
 Options:
   --files <s>          CSV file paths (comma-separated or glob, required)
@@ -885,6 +896,7 @@ export function parseKnCreateFromCsvArgs(args) {
     if (!dsId || !files || !name) {
         throw new Error("Usage: kweaver bkn create-from-csv <ds-id> --files <glob> --name X [options]");
     }
+    assertVegaCatalogId(dsId);
     const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();

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

@@ -43,6 +43,35 @@ export declare function detectPrimaryKey(table: {
         type: string;
     }>;
 }, rows?: Array<Record<string, string | null>>): PkDetectionResult;
+export interface PkResolution {
+    /** Resolved PK column name, or null when caller must fail-fast. */
+    pk: string | null;
+    /** Origin of the resolution — used by callers for messaging and warnings. */
+    source: "override" | "schema" | "sample" | "ambiguous";
+    /** For 'sample' source: cardinality candidates from `detectPrimaryKey`. */
+    candidates?: PkCandidate[];
+    /** For 'sample' source: rows seen, propagated for error formatting. */
+    sampleSize?: number;
+    /** For 'ambiguous' source: schema-declared composite PK columns. */
+    ambiguous?: string[];
+}
+/**
+ * Resolve a single PK for a BKN object type, in priority order:
+ *   1. caller-provided override (e.g. --pk-map)
+ *   2. schema-declared single PK from datasource metadata
+ *   3. sample-based detection (CSV / schemaless sources)
+ * Composite SQL PKs intentionally surface as `source: "ambiguous"` — BKN
+ * object types take a single PK, so the caller must pick via --pk-map.
+ */
+export declare function resolvePrimaryKey(table: {
+    name: string;
+    columns: Array<{
+        name: string;
+        type: string;
+        isPrimaryKey?: boolean;
+    }>;
+    primaryKeys?: string[];
+}, sampleRows?: Array<Record<string, string | null>>, override?: string | null): PkResolution;
 /** Format a user-facing error message when PK auto-detection fails. */
 export declare function formatPkDetectionError(tableName: string, result: PkDetectionResult): string;
 /**
@@ -57,4 +86,13 @@ export declare function detectDisplayKey(table: {
         type: string;
     }>;
 }, primaryKey: string): string;
+/**
+ * Reject legacy data-connection datasource UUIDs.
+ *
+ * Since the SDK migration to vega-backend (#114), commands that call
+ * `listTablesWithColumns` / `scanMetadata` expect a vega catalog id (a short
+ * slug like `d7nicrcjto2s73d9g67g`), not the UUID-shaped id stored in
+ * data-connection.
+ */
+export declare function assertVegaCatalogId(id: string): void;
 export declare function confirmYes(prompt: string): Promise<boolean>;

package/dist/commands/bkn-utils.js

@@ -98,6 +98,43 @@ export function detectPrimaryKey(table, rows) {
         sampleSize: rows.length,
     };
 }
+/**
+ * Resolve a single PK for a BKN object type, in priority order:
+ *   1. caller-provided override (e.g. --pk-map)
+ *   2. schema-declared single PK from datasource metadata
+ *   3. sample-based detection (CSV / schemaless sources)
+ * Composite SQL PKs intentionally surface as `source: "ambiguous"` — BKN
+ * object types take a single PK, so the caller must pick via --pk-map.
+ */
+export function resolvePrimaryKey(table, sampleRows, override) {
+    if (override) {
+        return { pk: override, source: "override" };
+    }
+    const schemaPks = collectSchemaPks(table);
+    if (schemaPks.length === 1) {
+        return { pk: schemaPks[0], source: "schema" };
+    }
+    if (schemaPks.length > 1) {
+        return { pk: null, source: "ambiguous", ambiguous: schemaPks };
+    }
+    const sample = detectPrimaryKey(table, sampleRows);
+    return {
+        pk: sample.pk,
+        source: "sample",
+        candidates: sample.candidates,
+        sampleSize: sample.sampleSize,
+    };
+}
+function collectSchemaPks(table) {
+    // Filter against the actual column list — schema metadata can drift (stale
+    // catalog, post-rename) and an unusable PK should fall through cleanly to
+    // sample/fail rather than poison downstream object-type creation.
+    const colNames = new Set(table.columns.map((c) => c.name));
+    if (Array.isArray(table.primaryKeys) && table.primaryKeys.length > 0) {
+        return table.primaryKeys.filter((n) => colNames.has(n));
+    }
+    return table.columns.filter((c) => c.isPrimaryKey === true).map((c) => c.name);
+}
 /** Format a user-facing error message when PK auto-detection fails. */
 export function formatPkDetectionError(tableName, result) {
     const lines = [`Cannot auto-detect primary key for table '${tableName}'.`];
@@ -146,6 +183,23 @@ export function detectDisplayKey(table, primaryKey) {
     }
     return primaryKey;
 }
+// ── Vega catalog id guard ────────────────────────────────────────────────────
+const UUID_V4_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/**
+ * Reject legacy data-connection datasource UUIDs.
+ *
+ * Since the SDK migration to vega-backend (#114), commands that call
+ * `listTablesWithColumns` / `scanMetadata` expect a vega catalog id (a short
+ * slug like `d7nicrcjto2s73d9g67g`), not the UUID-shaped id stored in
+ * data-connection.
+ */
+export function assertVegaCatalogId(id) {
+    if (UUID_V4_RE.test(id)) {
+        throw new Error(`expected a vega catalog id, got UUID '${id}'. ` +
+            `This looks like a legacy data-connection datasource UUID. ` +
+            `Run \`kweaver vega catalog list --keyword <name>\` to find the corresponding catalog id.`);
+    }
+}
 // ── Interactive confirmation ─────────────────────────────────────────────────
 export function confirmYes(prompt) {
     return new Promise((resolve) => {

package/dist/commands/bkn.js

@@ -7,6 +7,7 @@ import { resolveBusinessDomain } from "../config/store.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 { 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";
 // Re-export schema types and parse functions for backward compatibility
@@ -404,6 +405,7 @@ Subcommands:
   job list|get|tasks|delete <kn-id> ...
   relation-type-paths <kn-id> '<json>'   Query relation type paths between OTs
   resources                              List available resources
+  metric list|get|create|search|validate|update|delete|query|dry-run <kn-id> ...   BKN metrics (definitions + data)
 
 Use 'kweaver bkn <subcommand> --help' for subcommand options.`;
 export async function runKnCommand(args) {
@@ -463,6 +465,8 @@ export async function runKnCommand(args) {
             return runKnRelationTypePathsCommand(rest);
         if (subcommand === "resources")
             return runKnResourcesCommand(rest);
+        if (subcommand === "metric")
+            return runKnMetricCommand(rest);
         return Promise.resolve(-1);
     };
     try {

package/dist/commands/ds.js

@@ -3,9 +3,11 @@ import { statSync } from "node:fs";
 import { glob } from "node:fs/promises";
 import { resolve as resolvePath } from "node:path";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
-import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, listTablesWithColumns, scanMetadata, } from "../api/datasources.js";
+import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, } from "../api/datasources.js";
+import { listTablesWithColumns, scanMetadata } from "../api/vega.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
+import { assertVegaCatalogId } from "./bkn-utils.js";
 import { parseCsvFile, buildTableName, splitBatches, buildFieldMappings, buildDagBody, } from "./import-csv.js";
 import { executeDataflow } from "../api/dataflow.js";
 function confirmYes(prompt) {
@@ -196,9 +198,12 @@ async function runDsTablesCommand(args) {
             id = arg;
     }
     if (!id) {
-        console.error("Usage: kweaver ds tables <id> [--keyword X]");
+        console.error("Usage: kweaver ds tables <vega-catalog-id> [--keyword X]\n" +
+            "  <vega-catalog-id> is a vega catalog id (use `kweaver vega catalog list` to find one;\n" +
+            "  legacy data-connection datasource UUIDs are no longer accepted).");
         return 1;
     }
+    assertVegaCatalogId(id);
     const token = await ensureValidToken();
     const body = await listTablesWithColumns({
         baseUrl: token.baseUrl,
@@ -389,7 +394,13 @@ async function printDsConnectOutput(base, dsId) {
         datasource_id: dsId,
         tables: tables.map((t) => ({
             name: t.name,
-            columns: t.columns.map((c) => ({ name: c.name, type: c.type, comment: c.comment })),
+            ...(t.primaryKeys && t.primaryKeys.length > 0 ? { primary_keys: t.primaryKeys } : {}),
+            columns: t.columns.map((c) => ({
+                name: c.name,
+                type: c.type,
+                comment: c.comment,
+                ...(c.isPrimaryKey ? { is_primary_key: true } : {}),
+            })),
         })),
     };
     console.log(JSON.stringify(output, null, 2));

package/dist/commands/explore-chat.js

@@ -175,7 +175,7 @@ export function registerChatRoutes(getToken, businessDomain) {
                 return;
             }
             const t = await getToken();
-            const raw = await getTracesByConversation({
+            const result = await getTracesByConversation({
                 baseUrl: t.baseUrl,
                 accessToken: t.accessToken,
                 agentId,
@@ -183,7 +183,7 @@ export function registerChatRoutes(getToken, businessDomain) {
                 businessDomain,
             });
             res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-            res.end(raw);
+            res.end(JSON.stringify(result));
         }
         catch (error) {
             handleApiError(res, error);

package/dist/commands/model.d.ts

@@ -0,0 +1,72 @@
+export interface ModelGlobalParse {
+    rest: string[];
+    businessDomain: string;
+    mfManagerBaseUrl?: string;
+    mfApiBaseUrl?: string;
+    pretty: boolean;
+}
+/** Strip global flags; fill default business domain. */
+export declare function parseModelGlobalFlags(args: string[]): ModelGlobalParse;
+/** Sparse flags for model llm edit (after leading model_id). Exported for unit tests. */
+export interface ParsedLlmSparseEditFlags {
+    name?: string;
+    modelSeries?: string;
+    modelType?: string;
+    maxModelLen?: number;
+    quota?: boolean;
+    modelConfigFile?: string;
+    upstreamUrl?: string;
+    apiModel?: string;
+    apiKey?: string;
+    apiKeyFile?: string;
+}
+/** Exported for unit tests. */
+export declare function parsedLlmSparseEditHasUpdates(p: ParsedLlmSparseEditFlags): boolean;
+/** Exported for unit tests. */
+export declare function parseLlmSparseEditFlags(tail: string[]): ParsedLlmSparseEditFlags;
+/**
+ * Normalize GET /llm/get JSON into a body suitable for POST /llm/edit.
+ * Exported for unit tests.
+ */
+export declare function llmModelGetToEditBase(raw: unknown): Record<string, unknown>;
+/** Apply sparse llm edit flags onto a normalized record from GET. Exported for unit tests. */
+export declare function mergeLlmEditOntoExistingBase(base: Record<string, unknown>, p: ParsedLlmSparseEditFlags): Promise<Record<string, unknown>>;
+/**
+ * Returns registry **model_name** from ``GET /llm/get`` JSON when present. Exported for unit tests.
+ */
+export declare function llmGetRecordModelName(raw: unknown): string;
+/** Registry **model_name** from ``GET /small-model/get``. Exported for unit tests. */
+export declare function smallGetRecordModelName(raw: unknown): string;
+export interface ParsedSmallAddFlags {
+    name?: string;
+    modelType?: "embedding" | "reranker";
+    batchSize?: number;
+    maxTokens?: number;
+    embeddingDim?: number;
+    modelConfigFile?: string;
+    adapter?: boolean;
+    adapterCodeFile?: string;
+    bodyFile?: string;
+    /** Outbound HTTP API base or full path (stored in model_config.api_url). */
+    upstreamUrl?: string;
+    /** Third-party model id / deployment name (model_config.api_model). */
+    apiModel?: string;
+    /** Inline API secret — prefer --api-key-file (shell history risk). */
+    apiKey?: string;
+    apiKeyFile?: string;
+}
+/** True when sparse CLI flags should perform an edit (excluding --body-file). Exported for unit tests. */
+export declare function parsedSmallFlagsHasEditUpdates(p: ParsedSmallAddFlags): boolean;
+/**
+ * Normalize GET /small-model/get JSON into a body suitable for POST /small-model/edit.
+ * Exported for unit tests.
+ */
+export declare function smallModelGetToEditBase(raw: unknown): Record<string, unknown>;
+/**
+ * Apply sparse edit flags onto a normalized small-model record (from GET). Exported for unit tests.
+ */
+export declare function mergeSmallEditOntoExistingBase(base: Record<string, unknown>, p: ParsedSmallAddFlags): Promise<Record<string, unknown>>;
+/** Parse small-model add/edit flags from argv tail (after action). Exported for unit tests. */
+export declare function parseSmallAddFlags(tail: string[]): ParsedSmallAddFlags;
+export declare function buildSmallBodyFromFlags(p: ParsedSmallAddFlags, modelId?: string): Promise<Record<string, unknown>>;
+export declare function runModelCommand(args: string[]): Promise<number>;