@kweaver-ai/kweaver-sdk 0.8.2 → 0.8.4

package/dist/commands/model.js

@@ -5,6 +5,7 @@ import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/
 import { resolveBusinessDomain } from "../config/store.js";
 import { addLlmModel, addSmallModel, deleteLlmModels, deleteSmallModels, editLlmModel, editSmallModel, getLlmModel, getSmallModel, listLlmModels, listSmallModels, testLlmModel, testSmallModel, } from "../api/models.js";
 import { modelChatCompletions, modelEmbeddings, modelRerank } from "../api/model-invocation.js";
+import { renderHelp } from "../help/format.js";
 import { formatCallOutput } from "./call.js";
 const DEFAULT_LIST_LIMIT = 30;
 /** Strip global flags; fill default business domain. */
@@ -51,48 +52,58 @@ export function parseModelGlobalFlags(args) {
     return { rest, businessDomain, mfManagerBaseUrl, mfApiBaseUrl, pretty };
 }
 function printModelUsage() {
-    console.log(`kweaver model
-
-Usage:
-  kweaver model llm   list [--keyword X] [--type llm|rlm|vu] [--series S] [--api-model M] [--page N] [--limit N] [--json] [-bd value]
-  kweaver model llm   get <model_id> [--json] [-bd value]
-  kweaver model llm   add --body-file <path.json> [--upstream-url <url>] [--api-model <id>] [--api-key <secret>|--api-key-file <path>] [--json] [-bd value]
-  kweaver model llm   edit [<model_id>] --body-file <path.json> [--upstream-url <url>] [--api-model <id>] [--api-key <secret>|--api-key-file <path>] [--json] [-bd value]
-                        (optional leading model_id overrides body.model_id after merge)
-                        OR: kweaver model llm edit <model_id> [sparse flags] (GET /llm/get then merge only flags you pass)
-                        Sparse flags: --name, --series, --type|-t, --max-model-len, --quota, --model-config-file, upstream flags (same as --body-file)
-  kweaver model llm   delete <model_id> [<model_id> ...] [-y] [-bd value]
-  kweaver model llm   test --body-file <path.json> [--upstream-url <url>] [--api-model <id>] [--api-key <secret>|--api-key-file <path>] [--json] [-bd value]
-  kweaver model llm   chat <model_id> (-m|--message) "text" [--model-name <registry_model_name>] [--skip-model-name-resolve] [--stream] [--no-stream] [--verbose] [--temperature N] [--max-tokens N] [--mf-api-base-url url] [-bd value]
-  kweaver model llm   --template [--json]                     (offline: bundled llm registration JSON stub)
-
-  kweaver model small list [--name X] [--type embedding|reranker] [--series S] [--page N] [--limit N] [--json] [-bd value]
-  kweaver model small get <model_id> [--json] [-bd value]
-  kweaver model small add --name N --type embedding|reranker --batch-size N
-                        (--model-config-file <path.json> | --adapter --adapter-code-file <path.py>)
-                        [--upstream-url <url>] [--api-model <id>] [--api-key <secret>|--api-key-file <path>]
-                        [--max-tokens N] [--embedding-dim N] [--json] [-bd value]
-                        (embedding requires --max-tokens and --embedding-dim; upstream flags merge into model_config.api_* — not valid with --adapter)
-  kweaver model small edit <model_id> [--body-file <path.json> | partial flags]
-                        (without --body-file: loads current model via GET, then applies only the flags you pass)
-  kweaver model small delete <model_id> [<model_id> ...] [-y] [-bd value]
-  kweaver model small test [--body-file <path.json>|<model_id>] [--json] [-bd value]
-  kweaver model small embeddings <model_id> (-i|--input <text>) ... [--model-name <registry_model_name>] [--skip-model-name-resolve] [--mf-api-base-url url] [-bd value]
-                        (runtime: POST mf-model-api /small-model/embeddings — like llm chat for vectors)
-  kweaver model small rerank <model_id> (-q|--query) <text> (-d|--document <text>) ... [--model-name <registry_model_name>] [--skip-model-name-resolve] [--mf-api-base-url url] [-bd value]
-                        (runtime: POST mf-model-api /small-model/reranker)
-  kweaver model small --template [--json]                   (offline: bundled small model_config JSON stub)
-
-Global:
-  --mf-base-url <url>       Override origin for mf-model-manager (default: KWEAVER_BASE_URL or KWEAVER_MF_MODEL_MANAGER_URL)
-  --mf-api-base-url <url>   Override origin for mf-model-api / chat (default: KWEAVER_BASE_URL or KWEAVER_MF_MODEL_API_URL)
-  -bd, --biz-domain        Business domain (default from config)
-
-Upstream secrets:
-  Prefer --api-key-file over --api-key (shell history). For LLM add/edit/test, flags merge into body.model_config as api_url, api_model, api_key (creating model_config if missing). Small-model upstream flags merge into model_config the same way.
-
-Bundled templates:
-  model llm --template | model small --template — print offline JSON stub (no auth).`);
+    console.log(renderHelp({
+        tagline: "Model factory — LLM / small-model CRUD (mf-model-manager) + runtime invocation (mf-model-api)",
+        usage: [
+            "kweaver model llm   <subcommand> [flags]",
+            "kweaver model small <subcommand> [flags]",
+        ],
+        sections: [
+            {
+                title: "LLM",
+                items: [
+                    { name: "list", desc: "List LLM models" },
+                    { name: "get", desc: "Get an LLM model by id" },
+                    { name: "add", desc: "Register an LLM model (--body-file or sparse flags)" },
+                    { name: "edit", desc: "Update an LLM model (merge mode by default)" },
+                    { name: "delete", desc: "Delete one or more LLM models" },
+                    { name: "test", desc: "Run model registration self-test (mf-model-manager)" },
+                    { name: "chat", desc: "OpenAI-compatible chat completion (mf-model-api)" },
+                    { name: "--template", desc: "Print bundled LLM registration JSON stub (offline)" },
+                ],
+            },
+            {
+                title: "SMALL MODEL",
+                items: [
+                    { name: "list", desc: "List small models (embedding / reranker)" },
+                    { name: "get", desc: "Get a small model by id" },
+                    { name: "add", desc: "Register a small model (--model-config-file | --adapter)" },
+                    { name: "edit", desc: "Update a small model (sparse-merge or --body-file)" },
+                    { name: "delete", desc: "Delete one or more small models" },
+                    { name: "test", desc: "Run small-model registration self-test" },
+                    { name: "embeddings", desc: "Runtime: POST mf-model-api /small-model/embeddings" },
+                    { name: "rerank", desc: "Runtime: POST mf-model-api /small-model/reranker" },
+                    { name: "--template", desc: "Print bundled small-model config JSON stub (offline)" },
+                ],
+            },
+        ],
+        flags: [
+            { name: "--mf-base-url <url>", desc: "Override mf-model-manager origin (env: KWEAVER_MF_MODEL_MANAGER_URL)" },
+            { name: "--mf-api-base-url <url>", desc: "Override mf-model-api origin (env: KWEAVER_MF_MODEL_API_URL)" },
+            { name: "-bd, --biz-domain <s>", desc: "Business domain (default from config)" },
+            { name: "--json", desc: "Print raw API JSON output" },
+        ],
+        inheritedFlags: "--base-url, --token, --user, --help",
+        examples: [
+            "kweaver model llm list --type llm --limit 20",
+            "kweaver model llm chat <model_id> -m \"hello\" --stream",
+            "kweaver model small embeddings <model_id> -i \"text\"",
+        ],
+        learnMore: [
+            "Upstream secrets: prefer --api-key-file over --api-key (shell history)",
+            "Use `kweaver help all` for full per-subcommand signatures",
+        ],
+    }));
 }
 async function printBundledModelBranchTemplate(branch, g) {
     try {

package/dist/commands/resource.d.ts

@@ -0,0 +1 @@
+export declare function runResourceCommand(args: string[]): Promise<number>;

package/dist/commands/{dataview.js → resource.js}

@@ -1,35 +1,39 @@
 import { createInterface } from "node:readline";
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
-import { deleteDataView, findDataView, getDataView, listDataViews, queryDataView, } from "../api/dataviews.js";
+import { RESOURCE_LIST_DEFAULT_LIMIT, deleteResource, findResource, getResource, listResources, queryResource, } from "../api/resources.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
-/**
- * Strip SQL line/block comments and leading whitespace, then return the first identifier token (lowercase).
- * Used to reject DDL/DML passed to dataview query (server applies LIMIT semantics).
- */
-export function getFirstSqlTokenAfterComments(sql) {
-    let s = sql.replace(/\/\*[\s\S]*?\*\//g, " ");
-    const lines = s.split("\n").map((line) => {
-        const idx = line.indexOf("--");
-        return idx >= 0 ? line.slice(0, idx) : line;
-    });
-    s = lines.join("\n");
-    s = s.replace(/\s+/g, " ").trim();
-    if (!s)
-        return "";
-    const match = /^([a-zA-Z_][a-zA-Z0-9_]*|"(?:[^"]|"")*")/.exec(s);
-    if (!match)
-        return "";
-    const tok = match[1];
-    if (tok.startsWith('"'))
-        return tok.slice(1, -1).replace(/""/g, '"').toLowerCase();
-    return tok.toLowerCase();
-}
-/** True if ad-hoc SQL is safe for dataview query (SELECT / WITH only). */
-export function isDataviewSelectLikeSql(sql) {
-    const kw = getFirstSqlTokenAfterComments(sql);
-    return kw === "select" || kw === "with";
-}
+import { renderHelp } from "../help/format.js";
+const RESOURCE_HELP = renderHelp({
+    tagline: "Resources — list, find, get, query, delete (vega-backend)",
+    usage: "kweaver resource <subcommand> [flags]",
+    sections: [
+        {
+            title: "AVAILABLE COMMANDS",
+            items: [
+                { name: "list", desc: "List resources under a catalog/datasource (default limit: 30)" },
+                { name: "find", desc: "Search by name; default fuzzy, --exact for strict, --wait to poll" },
+                { name: "get", desc: "Get resource details" },
+                { name: "query", desc: "Fetch data rows from a vega-backend resource" },
+                { name: "delete", desc: "Delete a resource" },
+            ],
+        },
+    ],
+    flags: [
+        { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
+        { name: "--pretty / --compact", desc: "JSON output style (default: pretty)" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver resource list --datasource-id <id> --type table",
+        "kweaver resource find --name customers --exact",
+        "kweaver resource query <id> --limit 100",
+    ],
+    learnMore: [
+        "Alias: `kweaver res ...`",
+        "Use `kweaver resource <subcommand> --help` for flag details",
+    ],
+});
 function confirmYes(prompt) {
     return new Promise((resolve) => {
         const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -40,41 +44,30 @@ function confirmYes(prompt) {
         });
     });
 }
-export async function runDataviewCommand(args) {
+export async function runResourceCommand(args) {
     const [subcommand, ...rest] = args;
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
-        console.log(`kweaver dataview
-
-Subcommands:
-  list   [--datasource-id <id>] [--type <atomic|custom>] [--limit <n>] [-bd value] [--pretty]
-  find   --name <name> [--exact] [--datasource-id <id>] [--wait] [--no-wait] [--timeout <ms>] [-bd value] [--pretty]
-  get    <id> [-bd value] [--pretty]
-  query  <id> [--sql <sql>] [--limit <n>] [--offset <n>] [--need-total] [-bd value] [--pretty]
-  delete <id> [-y] [-bd value]
-
-  list  — list all data views (no keyword search)
-  find  — search by name; default fuzzy, --exact for strict match, --wait to poll
-  query — run SQL query against a data view (mdl-uniquery); omit --sql to use view default SQL; only SELECT/WITH unless --raw-sql`);
+        console.log(RESOURCE_HELP);
         return 0;
     }
     const dispatch = () => {
         if (subcommand === "list")
-            return runDataviewListCommand(rest);
+            return runResourceListCommand(rest);
         if (subcommand === "find")
-            return runDataviewFindCommand(rest);
+            return runResourceFindCommand(rest);
         if (subcommand === "get")
-            return runDataviewGetCommand(rest);
+            return runResourceGetCommand(rest);
         if (subcommand === "query")
-            return runDataviewQueryCommand(rest);
+            return runResourceQueryCommand(rest);
         if (subcommand === "delete")
-            return runDataviewDeleteCommand(rest);
+            return runResourceDeleteCommand(rest);
         return Promise.resolve(-1);
     };
     try {
         return await with401RefreshRetry(async () => {
             const code = await dispatch();
             if (code === -1) {
-                console.error(`Unknown dataview subcommand: ${subcommand}`);
+                console.error(`Unknown resource subcommand: ${subcommand}`);
                 return 1;
             }
             return code;
@@ -85,7 +78,7 @@ Subcommands:
         return 1;
     }
 }
-function parseDataviewCommonArgs(args) {
+function parseResourceCommonArgs(args) {
     let businessDomain = "";
     let pretty = true;
     for (let i = 0; i < args.length; i += 1) {
@@ -103,11 +96,11 @@ function parseDataviewCommonArgs(args) {
         businessDomain = resolveBusinessDomain();
     return { businessDomain, pretty };
 }
-async function runDataviewListCommand(args) {
+async function runResourceListCommand(args) {
     let datasourceId;
     let type;
-    let limit;
-    const { businessDomain, pretty } = parseDataviewCommonArgs(args);
+    let limit = RESOURCE_LIST_DEFAULT_LIMIT;
+    const { businessDomain, pretty } = parseResourceCommonArgs(args);
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "-bd" || arg === "--biz-domain") {
@@ -132,24 +125,24 @@ async function runDataviewListCommand(args) {
         }
     }
     const token = await ensureValidToken();
-    const views = await listDataViews({
+    const views = await listResources({
         baseUrl: token.baseUrl,
         accessToken: token.accessToken,
         businessDomain,
         datasourceId,
-        type,
+        category: type,
         limit,
     });
     console.log(formatCallOutput(JSON.stringify(views), pretty));
     return 0;
 }
-async function runDataviewFindCommand(args) {
+async function runResourceFindCommand(args) {
     let datasourceId;
     let name;
     let exact = false;
     let wait = false;
     let timeoutMs = 30_000;
-    const { businessDomain, pretty } = parseDataviewCommonArgs(args);
+    const { businessDomain, pretty } = parseResourceCommonArgs(args);
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "-bd" || arg === "--biz-domain") {
@@ -188,11 +181,11 @@ async function runDataviewFindCommand(args) {
         }
     }
     if (!name) {
-        console.error("Usage: kweaver dataview find --name <name> [--exact] [--datasource-id <id>] [--wait] [--timeout <ms>] [-bd value] [--pretty]");
+        console.error("Usage: kweaver resource find --name <name> [--exact] [--datasource-id <id>] [--wait] [--timeout <ms>] [-bd value] [--pretty]");
         return 1;
     }
     const token = await ensureValidToken();
-    const views = await findDataView({
+    const views = await findResource({
         baseUrl: token.baseUrl,
         accessToken: token.accessToken,
         businessDomain,
@@ -205,8 +198,8 @@ async function runDataviewFindCommand(args) {
     console.log(formatCallOutput(JSON.stringify(views), pretty));
     return 0;
 }
-async function runDataviewGetCommand(args) {
-    const { businessDomain, pretty } = parseDataviewCommonArgs(args);
+async function runResourceGetCommand(args) {
+    const { businessDomain, pretty } = parseResourceCommonArgs(args);
     let id = "";
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -222,11 +215,11 @@ async function runDataviewGetCommand(args) {
         }
     }
     if (!id) {
-        console.error("Usage: kweaver dataview get <id> [-bd value] [--pretty]");
+        console.error("Usage: kweaver resource get <id> [-bd value] [--pretty]");
         return 1;
     }
     const token = await ensureValidToken();
-    const view = await getDataView({
+    const view = await getResource({
         baseUrl: token.baseUrl,
         accessToken: token.accessToken,
         businessDomain,
@@ -235,15 +228,13 @@ async function runDataviewGetCommand(args) {
     console.log(formatCallOutput(JSON.stringify(view), pretty));
     return 0;
 }
-async function runDataviewQueryCommand(args) {
-    const { businessDomain, pretty } = parseDataviewCommonArgs(args);
-    let sql;
+async function runResourceQueryCommand(args) {
+    const { businessDomain, pretty } = parseResourceCommonArgs(args);
     let limit = 50;
     let offset = 0;
     let needTotal = false;
-    let rawSql = false;
     if (args.length === 0 || args[0].startsWith("-")) {
-        console.error("Usage: kweaver dataview query <id> [--sql <sql>] [--limit <n>] [--offset <n>] [--need-total] [--raw-sql] [-bd value] [--pretty]");
+        console.error("Usage: kweaver resource query <id> [--limit <n>] [--offset <n>] [--need-total] [-bd value] [--pretty]");
         return 1;
     }
     const id = args[0];
@@ -256,14 +247,6 @@ async function runDataviewQueryCommand(args) {
         }
         if (arg === "--pretty")
             continue;
-        if (arg === "--raw-sql") {
-            rawSql = true;
-            continue;
-        }
-        if ((arg === "--sql" || arg === "-s") && tail[i + 1]) {
-            sql = tail[++i];
-            continue;
-        }
         if (arg === "--limit" && tail[i + 1]) {
             const n = Number.parseInt(tail[++i], 10);
             if (!Number.isNaN(n))
@@ -281,17 +264,12 @@ async function runDataviewQueryCommand(args) {
             continue;
         }
     }
-    if (sql !== undefined && sql !== "" && !rawSql && !isDataviewSelectLikeSql(sql)) {
-        console.error("dataview query only supports SELECT statements (or WITH for CTEs). Use --raw-sql to send other SQL at your own risk.");
-        return 1;
-    }
     const token = await ensureValidToken();
-    const result = await queryDataView({
+    const result = await queryResource({
         baseUrl: token.baseUrl,
         accessToken: token.accessToken,
         businessDomain,
         id,
-        sql,
         offset,
         limit,
         needTotal,
@@ -299,7 +277,7 @@ async function runDataviewQueryCommand(args) {
     console.log(formatCallOutput(JSON.stringify(result), pretty));
     return 0;
 }
-async function runDataviewDeleteCommand(args) {
+async function runResourceDeleteCommand(args) {
     let id = "";
     let yes = false;
     let businessDomain = "";
@@ -317,18 +295,18 @@ async function runDataviewDeleteCommand(args) {
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
     if (!id) {
-        console.error("Usage: kweaver dataview delete <id> [-y] [-bd value]");
+        console.error("Usage: kweaver resource delete <id> [-y] [-bd value]");
         return 1;
     }
     if (!yes) {
-        const confirmed = await confirmYes("Are you sure you want to delete this data view?");
+        const confirmed = await confirmYes("Are you sure you want to delete this resource?");
         if (!confirmed) {
             console.error("Aborted.");
             return 1;
         }
     }
     const token = await ensureValidToken();
-    await deleteDataView({
+    await deleteResource({
         baseUrl: token.baseUrl,
         accessToken: token.accessToken,
         businessDomain,