@kweaver-ai/kweaver-sdk 0.7.3 → 0.7.4

package/README.md

@@ -174,12 +174,15 @@ kweaver token
 kweaver ds list/get/delete/tables/connect
 kweaver ds import-csv <ds_id> --files <glob> [--table-prefix <p>] [--batch-size 500] [--recreate]
 kweaver dataflow list/run/runs/logs
+kweaver model llm list/get/add/edit/delete/test/chat/--template
+kweaver model small list/get/add/edit/delete/test/embeddings/rerank/--template
 kweaver dataview list/find/get/query/delete
 kweaver bkn list/get/stats/export/create/update/delete
 kweaver bkn create-from-ds <ds_id> --name <name> [--tables t1,t2] [--build]
 kweaver bkn create-from-csv <ds_id> --files <glob> --name <name> [--build]
 kweaver bkn validate/push/pull
 kweaver bkn object-type list/get/create/update/delete/query/properties
+kweaver bkn metric list/get/create/search/validate/update/delete/query/dry-run
 kweaver bkn relation-type list/get/create/update/delete
 kweaver bkn action-type list/query/execute
 kweaver bkn subgraph / search
@@ -211,6 +214,30 @@ kweaver dataflow logs <dagId> <instanceId> --detail
 
 `kweaver dataflow runs --since` filters one local natural day. If the value cannot be parsed by `new Date(...)`, the CLI falls back to the most recent 20 runs. `kweaver dataflow logs` defaults to summary output; add `--detail` to print indented `input` and `output` payloads.
 
+### Model factory CLI examples
+
+`model` talks to **mf-model-manager** (`/api/mf-model-manager/v1`) for CRUD and **mf-model-api** (`/api/mf-model-api/v1`) for OpenAI-compatible **`chat`**, **`small embeddings`**, and **`small rerank`**. Override origins with `--mf-base-url` / `--mf-api-base-url` or `KWEAVER_MF_MODEL_MANAGER_URL` / `KWEAVER_MF_MODEL_API_URL`. `model llm --template` / `model small --template` prints one offline **`basic`** JSON stub per branch (no API calls). **LLM** `model_type` on the platform is one of **`llm`** (text), **`rlm`** (reasoning), or **`vu`** (vision / multimodal); filter with `kweaver model llm list --type …`. See [`skills/kweaver-core/references/model.md`](../../skills/kweaver-core/references/model.md#llm-model-types).
+
+```bash
+kweaver model llm list --limit 30
+kweaver model llm list --type rlm
+kweaver model llm get <model_id>
+kweaver model llm add --body-file ./llm.json --upstream-url https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions --api-model qwen-plus --api-key-file ~/.dashscope_key
+kweaver model llm chat <model_id> -m "Hello" --no-stream
+kweaver model llm --template > ./llm.json
+kweaver model small list
+kweaver model small add --name my-emb --type embedding --batch-size 8 --max-tokens 512 --embedding-dim 1536 \
+  --model-config-file ./cfg.json
+kweaver model small add --name my-emb --type embedding --batch-size 8 --max-tokens 8192 --embedding-dim 1024 \
+  --upstream-url https://dashscope-intl.aliyuncs.com/compatible-mode/v1/embeddings --api-model text-embedding-v4 --api-key-file ~/.dashscope_key
+kweaver model small test <model_id>
+kweaver model small embeddings <model_id> -i "hello" -i "world"
+kweaver model small rerank <model_id> -q "query" -d "doc a" -d "doc b"
+kweaver model small --template > ./embedding-model-config.json
+```
+
+Full flags: `kweaver model --help` and [`skills/kweaver-core/references/model.md`](../../skills/kweaver-core/references/model.md).
+
 ### Vega `sql` CLI examples
 
 Direct SQL against catalog-backed resources (`POST /api/vega-backend/v1/resources/query`). In SQL, use **`{{<resource_id>}}`** or **`{{.<resource_id>}}`** (Vega resource id from `vega resource list` / `get`) so the backend resolves the physical table and connector. `--resource-type` accepts the connector type of the target data source (run `kweaver vega connector-type list` to see available types). In simple mode, **quote the entire `--query` value** so the shell does not treat `{` / `}` specially.
@@ -256,6 +283,8 @@ kweaver tool debug --toolbox <BOX_ID> <TOOL_ID> \
 | Variable | Description |
 |---|---|
 | `KWEAVER_BASE_URL` | KWeaver instance URL |
+| `KWEAVER_MF_MODEL_MANAGER_URL` | Optional override for mf-model-manager API (defaults from `KWEAVER_BASE_URL` + `/api/mf-model-manager/v1`) |
+| `KWEAVER_MF_MODEL_API_URL` | Optional override for mf-model-api (defaults from `KWEAVER_BASE_URL` + `/api/mf-model-api/v1`) |
 | `KWEAVER_BUSINESS_DOMAIN` | Business domain identifier |
 | `KWEAVER_TOKEN` | Access token |
 | `KWEAVER_TOKEN_SOURCE` | Internal sentinel set by the CLI when `--token` is passed; do not set manually |

package/README.zh.md

@@ -165,9 +165,12 @@ kweaver config show / list-bd / set-bd <value>   # 业务域；show/list-bd 在
 kweaver token
 kweaver ds list/get/delete/tables/connect
 kweaver dataflow list/run/runs/logs
+kweaver model llm list/get/add/edit/delete/test/chat/--template
+kweaver model small list/get/add/edit/delete/test/embeddings/rerank/--template
 kweaver dataview list/find/get/query/delete
 kweaver bkn list/get/stats/export/create/update/delete
 kweaver bkn object-type list/get/create/update/delete/query/properties
+kweaver bkn metric list/get/create/search/validate/update/delete/query/dry-run
 kweaver bkn relation-type list/get/create/update/delete
 kweaver bkn action-type list/query/execute
 kweaver bkn subgraph
@@ -197,6 +200,27 @@ kweaver dataflow logs <dagId> <instanceId> --detail
 
 `kweaver dataflow runs --since` 会按本地自然日过滤；如果参数无法被 `new Date(...)` 解析，CLI 会回退到最近 20 条运行记录。`kweaver dataflow logs` 默认输出摘要；加上 `--detail` 会打印带缩进的 `input` 和 `output` 载荷。
 
+### 模型工厂 CLI 示例
+
+- **mf-model-manager**：`/api/mf-model-manager/v1`（配置 CRUD、`test`）
+- **mf-model-api**：`/api/mf-model-api/v1`（OpenAI 兼容 **`chat`**，以及小模型 **`embeddings` / `rerank`**）
+
+离线模版：`model llm --template` / `model small --template` 输出内置 **`basic`** JSON（不调后端）。大模型 **`model_type`** 在后端仅为 **`llm`**（文本）、**`rlm`**（推理）、**`vu`**（视觉/多模态，接口缩写不是 `vlm`）；列表过滤：`kweaver model llm list --type …`。详见 [`skills/kweaver-core/references/model.md`](../../skills/kweaver-core/references/model.md#llm-model-types)。
+
+```bash
+kweaver model llm list --limit 30
+kweaver model llm list --type vu
+kweaver model llm chat <model_id> -m "你好" --no-stream
+kweaver model llm --template > ./llm.json
+kweaver model small add --name my-emb --type embedding --batch-size 8 --max-tokens 512 --embedding-dim 1536 \
+  --model-config-file ./cfg.json
+kweaver model small embeddings <model_id> -i "hello" -i "world"
+kweaver model small rerank <model_id> -q "查询" -d "文档a" -d "文档b"
+kweaver model small --template > ./embedding-model-config.json
+```
+
+完整说明见 [`skills/kweaver-core/references/model.md`](../../skills/kweaver-core/references/model.md) 与 `kweaver model --help`。
+
 ### Vega `sql` CLI 示例
 
 对 Catalog 资源执行直连 SQL（`POST /api/vega-backend/v1/resources/query`）。SQL 中使用 **`{{<resource_id>}}`** 或 **`{{.<resource_id>}}`**（资源 id 来自 `vega resource list` / `get`），后端据此解析物理表与 connector。`--resource-type` 为目标数据源的连接器类型，可通过 `kweaver vega connector-type list` 查看。简单模式下请**用引号包住整个 `--query` 参数**，避免 shell 对花括号做特殊处理。
@@ -218,6 +242,8 @@ kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{res-1}} L
 | 变量 | 说明 |
 |---|---|
 | `KWEAVER_BASE_URL` | KWeaver 实例地址 |
+| `KWEAVER_MF_MODEL_MANAGER_URL` | 可选：mf-model-manager API 根地址（默认 `KWEAVER_BASE_URL` + `/api/mf-model-manager/v1`） |
+| `KWEAVER_MF_MODEL_API_URL` | 可选：mf-model-api 根地址（默认 `KWEAVER_BASE_URL` + `/api/mf-model-api/v1`） |
 | `KWEAVER_BUSINESS_DOMAIN` | 业务域标识 |
 | `KWEAVER_TOKEN` | 访问令牌 |
 | `KWEAVER_TOKEN_SOURCE` | CLI 传入 `--token` 时由程序设置的内部标记；请勿手动设置 |

package/bin/kweaver.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
 
+// Wait for stdout and stderr to fully flush before terminating. Checking
+// writableNeedDrain alone is not enough — a single console.log under the
+// highWaterMark returns synchronously while bytes are still queued, so
+// process.exit() can truncate piped output (~7-8KB) under spawn capture.
+// Empty write + callback fires only after all preceding writes drain.
 function exit(code) {
-  if (process.stdout.writableNeedDrain || process.stderr.writableNeedDrain) {
-    const done = () => {
-      if (!process.stdout.writableNeedDrain && !process.stderr.writableNeedDrain) {
-        process.exit(code);
-      }
-    };
-    process.stdout.once("drain", done);
-    process.stderr.once("drain", done);
-  } else {
-    process.exit(code);
-  }
+  let pending = 2;
+  const done = () => {
+    pending -= 1;
+    if (pending === 0) process.exit(code);
+  };
+  process.stdout.write("", done);
+  process.stderr.write("", done);
 }
 
 import("../dist/cli.js").then(({ run }) => {

package/dist/api/bkn-backend.d.ts

@@ -14,6 +14,7 @@ export interface BknBackendBaseOptions {
 export interface BknBackendKnOptions extends BknBackendBaseOptions {
     knId: string;
 }
+export declare function knUrl(baseUrl: string, knId: string, path: string): string;
 export interface ConceptGroupOptions extends BknBackendKnOptions {
     cgId: string;
 }

package/dist/api/bkn-backend.js

@@ -20,7 +20,7 @@ export async function uploadBkn(options) {
     return body;
 }
 const BKN_BASE = "/api/bkn-backend/v1";
-function knUrl(baseUrl, knId, path) {
+export function knUrl(baseUrl, knId, path) {
     const base = baseUrl.replace(/\/+$/, "");
     return `${base}${BKN_BASE}/knowledge-networks/${encodeURIComponent(knId)}/${path}`;
 }

package/dist/api/bkn-metrics.d.ts

@@ -0,0 +1,59 @@
+import type { BknBackendKnOptions } from "./bkn-backend.js";
+export interface ListMetricsOptions extends BknBackendKnOptions {
+    namePattern?: string;
+    sort?: "update_time" | "name";
+    direction?: "asc" | "desc";
+    offset?: number;
+    limit?: number;
+    tag?: string;
+    groupId?: string;
+    branch?: string;
+}
+export declare function listMetrics(options: ListMetricsOptions): Promise<string>;
+export interface CreateMetricsOptions extends BknBackendKnOptions {
+    body: string;
+    branch?: string;
+    strictMode?: boolean;
+}
+export declare function createMetrics(options: CreateMetricsOptions): Promise<string>;
+export interface SearchMetricsOptions extends BknBackendKnOptions {
+    body: string;
+    branch?: string;
+    strictMode?: boolean;
+}
+export declare function searchMetrics(options: SearchMetricsOptions): Promise<string>;
+export interface ValidateMetricsOptions extends BknBackendKnOptions {
+    body: string;
+    branch?: string;
+    strictMode?: boolean;
+    importMode?: "normal" | "ignore" | "overwrite";
+}
+export declare function validateMetrics(options: ValidateMetricsOptions): Promise<string>;
+export interface GetMetricOptions extends BknBackendKnOptions {
+    metricId: string;
+    branch?: string;
+}
+export declare function getMetric(options: GetMetricOptions): Promise<string>;
+export interface UpdateMetricOptions extends BknBackendKnOptions {
+    metricId: string;
+    body: string;
+    branch?: string;
+    strictMode?: boolean;
+}
+export declare function updateMetric(options: UpdateMetricOptions): Promise<string>;
+export interface DeleteMetricOptions extends BknBackendKnOptions {
+    metricId: string;
+    branch?: string;
+}
+export declare function deleteMetric(options: DeleteMetricOptions): Promise<string>;
+export interface GetMetricsByIdsOptions extends BknBackendKnOptions {
+    /** Comma-separated metric IDs in a single path segment. */
+    metricIds: string;
+    branch?: string;
+}
+export declare function getMetrics(options: GetMetricsByIdsOptions): Promise<string>;
+export interface DeleteMetricsByIdsOptions extends BknBackendKnOptions {
+    metricIds: string;
+    branch?: string;
+}
+export declare function deleteMetrics(options: DeleteMetricsByIdsOptions): Promise<string>;

package/dist/api/bkn-metrics.js

@@ -0,0 +1,129 @@
+import { HttpError } from "../utils/http.js";
+import { buildHeaders } from "./headers.js";
+import { knUrl } from "./bkn-backend.js";
+async function readTextOrThrow(response) {
+    const text = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, text);
+    }
+    return text;
+}
+function appendSearchParams(url, entries) {
+    for (const [k, v] of entries) {
+        if (v === undefined)
+            continue;
+        url.searchParams.set(k, String(v));
+    }
+}
+export async function listMetrics(options) {
+    const { baseUrl, accessToken, knId, businessDomain = "bd_public", namePattern, sort, direction, offset, limit, tag, groupId, branch, } = options;
+    const url = new URL(knUrl(baseUrl, knId, "metrics"));
+    appendSearchParams(url, [
+        ["name_pattern", namePattern],
+        ["sort", sort],
+        ["direction", direction],
+        ["offset", offset],
+        ["limit", limit],
+        ["tag", tag],
+        ["group_id", groupId],
+        ["branch", branch],
+    ]);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}
+export async function createMetrics(options) {
+    return postWithMethodOverride(options, "POST");
+}
+export async function searchMetrics(options) {
+    return postWithMethodOverride(options, "GET");
+}
+async function postWithMethodOverride(options, methodOverride) {
+    const { baseUrl, accessToken, knId, body, businessDomain = "bd_public", branch, strictMode } = options;
+    const url = new URL(knUrl(baseUrl, knId, "metrics"));
+    appendSearchParams(url, [
+        ["branch", branch],
+        ["strict_mode", strictMode],
+    ]);
+    const response = await fetch(url.toString(), {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+            "X-HTTP-Method-Override": methodOverride,
+        },
+        body,
+    });
+    return readTextOrThrow(response);
+}
+export async function validateMetrics(options) {
+    const { baseUrl, accessToken, knId, body, businessDomain = "bd_public", branch, strictMode, importMode } = options;
+    const url = new URL(knUrl(baseUrl, knId, "metrics/validation"));
+    appendSearchParams(url, [
+        ["branch", branch],
+        ["strict_mode", strictMode],
+        ["import_mode", importMode],
+    ]);
+    const response = await fetch(url.toString(), {
+        method: "POST",
+        headers: { ...buildHeaders(accessToken, businessDomain), "content-type": "application/json" },
+        body,
+    });
+    return readTextOrThrow(response);
+}
+export async function getMetric(options) {
+    const { baseUrl, accessToken, knId, metricId, businessDomain = "bd_public", branch } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${encodeURIComponent(metricId)}`));
+    appendSearchParams(url, [["branch", branch]]);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}
+export async function updateMetric(options) {
+    const { baseUrl, accessToken, knId, metricId, body, businessDomain = "bd_public", branch, strictMode } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${encodeURIComponent(metricId)}`));
+    appendSearchParams(url, [
+        ["branch", branch],
+        ["strict_mode", strictMode],
+    ]);
+    const response = await fetch(url.toString(), {
+        method: "PUT",
+        headers: { ...buildHeaders(accessToken, businessDomain), "content-type": "application/json" },
+        body,
+    });
+    return readTextOrThrow(response);
+}
+export async function deleteMetric(options) {
+    const { baseUrl, accessToken, knId, metricId, businessDomain = "bd_public", branch } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${encodeURIComponent(metricId)}`));
+    appendSearchParams(url, [["branch", branch]]);
+    const response = await fetch(url.toString(), {
+        method: "DELETE",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}
+export async function getMetrics(options) {
+    const { baseUrl, accessToken, knId, metricIds, businessDomain = "bd_public", branch } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${metricIds}`));
+    appendSearchParams(url, [["branch", branch]]);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}
+export async function deleteMetrics(options) {
+    const { baseUrl, accessToken, knId, metricIds, businessDomain = "bd_public", branch } = options;
+    const url = new URL(knUrl(baseUrl, knId, `metrics/${metricIds}`));
+    appendSearchParams(url, [["branch", branch]]);
+    const response = await fetch(url.toString(), {
+        method: "DELETE",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    return readTextOrThrow(response);
+}

package/dist/api/conversations.d.ts

@@ -16,16 +16,61 @@ export interface ListMessagesOptions {
 export interface GetTracesOptions {
     baseUrl: string;
     accessToken: string;
-    agentId: string;
     conversationId: string;
+    /** Deprecated. trace-ai keys spans by conversation_id only; kept for CLI compatibility. */
+    agentId?: string;
     businessDomain?: string;
+    /** Max distinct traceIds to fetch for one conversation. Default 100. */
+    maxTraceIds?: number;
+    /** Max spans returned by the second hop. Default 2000. */
+    maxSpans?: number;
+}
+export interface TraceSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind?: string;
+    startTime: string;
+    endTime?: string;
+    durationInNanos?: number;
+    status?: {
+        code?: string | number;
+        message?: string;
+    };
+    serviceName?: string;
+    attributes?: Record<string, unknown>;
+    events?: Array<{
+        name?: string;
+        time?: string;
+        attributes?: Record<string, unknown>;
+    }>;
+    /** Raw _source object from the trace store, kept verbatim for formatters that need extra fields. */
+    raw?: Record<string, unknown>;
+}
+export interface TracesByConversationResult {
+    conversationId: string;
+    traceIds: string[];
+    spans: TraceSpan[];
+    /** True if the traceId aggregation hit its bucket cap and may be incomplete. */
+    truncated: boolean;
 }
 /**
  * List conversations for an agent.
  * Returns empty array on 404 (endpoint may not be available in all deployments).
  */
 export declare function listConversations(opts: ListConversationsOptions): Promise<string>;
-export declare function getTracesByConversation(opts: GetTracesOptions): Promise<string>;
+/**
+ * Fetch all spans belonging to a conversation via trace-ai's OpenSearch-style _search.
+ *
+ * Two-hop strategy (see kweaver-sdk#115):
+ *   1. Aggregate traceIds for spans tagged with gen_ai.conversation.id == conversationId.
+ *   2. Fetch every span sharing those traceIds — this recovers pipeline spans
+ *      (HTTP entry, internal RPCs, prompt-build) that are not tagged with conversation_id.
+ *
+ * Returns a structured result; callers can format as tree/perf/evidence views or stringify.
+ */
+export declare function getTracesByConversation(opts: GetTracesOptions): Promise<TracesByConversationResult>;
 /**
  * List messages for a conversation.
  * Returns empty array on 404 (endpoint may not be available in all deployments).

package/dist/api/conversations.js

@@ -29,33 +29,129 @@ export async function listConversations(opts) {
     }
     return body || "[]";
 }
-function buildTracesUrl(baseUrl, agentId, conversationId) {
+function buildTraceSearchUrl(baseUrl) {
     const base = baseUrl.replace(/\/+$/, "");
-    return `${base}/api/agent-factory/v1/observability/agent/${agentId}/conversation/${conversationId}/session`;
+    return `${base}/api/agent-observability/v1/traces/_search`;
 }
-export async function getTracesByConversation(opts) {
-    const { baseUrl, accessToken, agentId, conversationId, businessDomain = "bd_public" } = opts;
-    const url = buildTracesUrl(baseUrl, agentId, conversationId);
-    const response = await fetch(url, {
+async function postTraceSearch(baseUrl, accessToken, businessDomain, body) {
+    const response = await fetch(buildTraceSearchUrl(baseUrl), {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
-            accept: "application/json",
             ...buildHeaders(accessToken, businessDomain),
         },
-        body: JSON.stringify({
-            agent_id: agentId,
-            start_time: 1,
-            end_time: Date.now() + 86400000,
-            page: 1,
-            size: 50,
-        }),
+        body: JSON.stringify(body),
     });
-    const body = await response.text();
+    const text = await response.text();
     if (!response.ok) {
-        throw new Error(`getTracesByConversation failed: HTTP ${response.status} ${response.statusText} — ${body.slice(0, 200)}`);
+        throw new Error(`getTracesByConversation failed: HTTP ${response.status} ${response.statusText} — ${text.slice(0, 200)}`);
     }
-    return body || "{}";
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`getTracesByConversation: invalid JSON response — ${err.message}`);
+    }
+}
+function computeDurationNanos(source) {
+    if (typeof source.durationInNanos === "number")
+        return source.durationInNanos;
+    if (typeof source.duration === "number")
+        return source.duration;
+    const startTime = source.startTime ?? source.start_time;
+    const endTime = source.endTime ?? source.end_time;
+    if (typeof startTime !== "string" || typeof endTime !== "string")
+        return undefined;
+    const startMs = Date.parse(startTime);
+    const endMs = Date.parse(endTime);
+    if (Number.isNaN(startMs) || Number.isNaN(endMs))
+        return undefined;
+    return Math.max(0, (endMs - startMs) * 1e6);
+}
+function extractServiceName(source) {
+    if (typeof source.serviceName === "string")
+        return source.serviceName;
+    if (typeof source.service_name === "string")
+        return source.service_name;
+    const attributes = source.attributes;
+    if (typeof attributes?.["service.name"] === "string")
+        return attributes["service.name"];
+    const resource = source.resource;
+    if (typeof resource?.["service.name"] === "string")
+        return resource["service.name"];
+    const resourceService = resource?.service?.name;
+    if (typeof resourceService === "string")
+        return resourceService;
+    return undefined;
+}
+function normalizeSpan(source) {
+    const traceId = String(source.traceId ?? source.trace_id ?? "");
+    const spanId = String(source.spanId ?? source.span_id ?? "");
+    if (!traceId || !spanId)
+        return null;
+    const parentRaw = source.parentSpanId ?? source.parent_span_id ?? source.parentSpanID;
+    const parentSpanId = parentRaw ? String(parentRaw) : undefined;
+    const status = source.status;
+    const attributes = source.attributes ?? undefined;
+    const events = source.events;
+    return {
+        traceId,
+        spanId,
+        parentSpanId: parentSpanId && parentSpanId !== "" && parentSpanId !== "0" ? parentSpanId : undefined,
+        name: String(source.name ?? ""),
+        kind: source.kind,
+        startTime: String(source.startTime ?? source.start_time ?? ""),
+        endTime: source.endTime ? String(source.endTime) : undefined,
+        durationInNanos: computeDurationNanos(source),
+        status,
+        serviceName: extractServiceName(source),
+        attributes,
+        events,
+        raw: source,
+    };
+}
+/**
+ * Fetch all spans belonging to a conversation via trace-ai's OpenSearch-style _search.
+ *
+ * Two-hop strategy (see kweaver-sdk#115):
+ *   1. Aggregate traceIds for spans tagged with gen_ai.conversation.id == conversationId.
+ *   2. Fetch every span sharing those traceIds — this recovers pipeline spans
+ *      (HTTP entry, internal RPCs, prompt-build) that are not tagged with conversation_id.
+ *
+ * Returns a structured result; callers can format as tree/perf/evidence views or stringify.
+ */
+export async function getTracesByConversation(opts) {
+    const { baseUrl, accessToken, conversationId, businessDomain = "bd_public", maxTraceIds = 100, maxSpans = 2000, } = opts;
+    const aggResult = await postTraceSearch(baseUrl, accessToken, businessDomain, {
+        size: 0,
+        query: { term: { "attributes.gen_ai.conversation.id.keyword": conversationId } },
+        aggs: { tids: { terms: { field: "traceId.keyword", size: maxTraceIds } } },
+    });
+    const aggregations = aggResult.aggregations;
+    const tids = aggregations?.tids;
+    const buckets = tids?.buckets ?? [];
+    const truncated = (tids?.sum_other_doc_count ?? 0) > 0;
+    const traceIds = buckets.map((b) => b.key).filter((k) => typeof k === "string" && k.length > 0);
+    if (traceIds.length === 0) {
+        return { conversationId, traceIds: [], spans: [], truncated: false };
+    }
+    const spansResult = await postTraceSearch(baseUrl, accessToken, businessDomain, {
+        size: maxSpans,
+        query: { terms: { "traceId.keyword": traceIds } },
+        sort: [{ startTime: "asc" }],
+    });
+    const hits = spansResult.hits?.hits ?? [];
+    const spans = [];
+    for (const hit of hits) {
+        if (!hit._source)
+            continue;
+        const span = normalizeSpan(hit._source);
+        if (span)
+            spans.push(span);
+    }
+    return { conversationId, traceIds, spans, truncated };
 }
 /**
  * List messages for a conversation.

package/dist/api/datasources.js

@@ -162,15 +162,52 @@ export async function listTablesWithColumns(options) {
             const colData = (await colResponse.json());
             columnsRaw = Array.isArray(colData) ? colData : (colData.entries ?? colData.data ?? []);
         }
-        const columns = columnsRaw.map((c) => ({
-            name: String(c.name ?? c.field_name ?? ""),
-            type: String(c.type ?? c.field_type ?? "varchar"),
-            comment: typeof c.comment === "string" ? c.comment : undefined,
-        }));
-        tables.push({ name: tableName, columns });
+        const tablePkArray = extractPrimaryKeys(t);
+        const columns = columnsRaw.map((c) => {
+            const name = String(c.name ?? c.field_name ?? "");
+            const flagged = isColumnPrimaryKey(c) || tablePkArray.includes(name);
+            return {
+                name,
+                type: String(c.type ?? c.field_type ?? "varchar"),
+                comment: typeof c.comment === "string" ? c.comment : undefined,
+                ...(flagged ? { isPrimaryKey: true } : {}),
+            };
+        });
+        // Reconcile: if backend gave per-column flags but no table-level array,
+        // synthesize one so downstream callers have a single PK source of truth.
+        const synthesizedPks = tablePkArray.length > 0
+            ? tablePkArray
+            : columns.filter((c) => c.isPrimaryKey).map((c) => c.name);
+        tables.push({
+            name: tableName,
+            columns,
+            ...(synthesizedPks.length > 0 ? { primaryKeys: synthesizedPks } : {}),
+        });
     }
     return JSON.stringify(tables);
 }
+// Two PK metadata shapes are recognized — both confirmed conventions:
+//   - per-column `is_primary_key: true` (data-connection metadata standard)
+//   - per-column `column_key === "PRI"` (MySQL INFORMATION_SCHEMA pass-through)
+//   - table-level `primary_keys: string[]` (composite-PK carrier)
+// Other plausible spellings (camelCase, singular keys, SQLite `pk` integer) are
+// intentionally NOT recognized here — adding them speculatively risks false
+// matches and creates code paths the test suite can't pin down. Extend only when
+// a real backend response demonstrates the need.
+function isColumnPrimaryKey(col) {
+    if (col.is_primary_key === true)
+        return true;
+    if (typeof col.column_key === "string" && col.column_key.toUpperCase() === "PRI")
+        return true;
+    return false;
+}
+function extractPrimaryKeys(table) {
+    const arr = table.primary_keys;
+    if (Array.isArray(arr)) {
+        return arr.filter((x) => typeof x === "string");
+    }
+    return [];
+}
 export async function scanMetadata(options) {
     const { baseUrl, accessToken, id, dsType = "mysql", businessDomain = "bd_public", } = options;
     const base = baseUrl.replace(/\/+$/, "");