@kweaver-ai/kweaver-sdk 0.7.3 → 0.8.1

package/dist/api/conversations.js

@@ -1,4 +1,5 @@
 import { buildHeaders } from "./headers.js";
+import { fetchRawSpansByConversation } from "./agent-observability.js";
 function buildConversationsUrl(baseUrl, agentKey) {
     const base = baseUrl.replace(/\/+$/, "");
     return `${base}/api/agent-factory/v1/app/${agentKey}/conversation`;
@@ -29,33 +30,86 @@ export async function listConversations(opts) {
     }
     return body || "[]";
 }
-function buildTracesUrl(baseUrl, agentId, conversationId) {
-    const base = baseUrl.replace(/\/+$/, "");
-    return `${base}/api/agent-factory/v1/observability/agent/${agentId}/conversation/${conversationId}/session`;
+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, shaped as `TraceSpan[]` for UI
+ * rendering (tree/perf/evidence/reasoning views). The wire-level two-hop and
+ * auth/header concerns live in `./agent-observability`; this function only
+ * normalizes the raw `_source` documents.
+ */
 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, {
-        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,
-        }),
+    const { baseUrl, accessToken, conversationId, businessDomain = "bd_public", maxTraceIds, maxSpans, } = opts;
+    const fetched = await fetchRawSpansByConversation({
+        baseUrl,
+        accessToken,
+        businessDomain,
+        conversationId,
+        maxTraceIds,
+        maxSpans,
     });
-    const body = await response.text();
-    if (!response.ok) {
-        throw new Error(`getTracesByConversation failed: HTTP ${response.status} ${response.statusText} — ${body.slice(0, 200)}`);
+    const spans = [];
+    for (const src of fetched.rawSources) {
+        const span = normalizeSpan(src);
+        if (span)
+            spans.push(span);
     }
-    return body || "{}";
+    return { conversationId, traceIds: fetched.traceIds, spans, truncated: fetched.truncated };
 }
 /**
  * List messages for a conversation.

package/dist/api/datasources.d.ts

@@ -58,23 +58,5 @@ export interface ListTablesOptions {
     businessDomain?: string;
 }
 export declare function listTables(options: ListTablesOptions): Promise<string>;
-export interface ListTablesWithColumnsOptions extends ListTablesOptions {
-    autoScan?: boolean;
-}
-/** List tables with column details. Optionally triggers metadata scan if no tables found. */
-export declare function listTablesWithColumns(options: ListTablesWithColumnsOptions): Promise<string>;
-export interface ScanMetadataOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    dsType?: string;
-    businessDomain?: string;
-}
-export declare function scanMetadata(options: ScanMetadataOptions): Promise<string>;
-export interface ScanDatasourceMetadataOptions {
-    baseUrl: string;
-    accessToken: string;
-    id: string;
-    businessDomain?: string;
-}
-export declare function scanDatasourceMetadata(options: ScanDatasourceMetadataOptions): Promise<string>;
+export { listTablesWithColumns, scanMetadata, scanDatasourceMetadata, } from "./vega.js";
+export type { ListTablesWithColumnsOptions, ScanMetadataOptions, ScanDatasourceMetadataOptions, } from "./vega.js";

package/dist/api/datasources.js

@@ -130,89 +130,10 @@ export async function listTables(options) {
     }
     return body;
 }
-/** List tables with column details. Optionally triggers metadata scan if no tables found. */
-export async function listTablesWithColumns(options) {
-    const { id, autoScan = true, ...rest } = options;
-    let body = await listTables({ ...rest, id });
-    const parsed = JSON.parse(body);
-    let items = Array.isArray(parsed) ? parsed : (parsed.entries ?? parsed.data ?? []);
-    if (items.length === 0 && autoScan) {
-        await scanMetadata({
-            baseUrl: rest.baseUrl,
-            accessToken: rest.accessToken,
-            id,
-            businessDomain: rest.businessDomain,
-        });
-        body = await listTables({ ...rest, id });
-        const parsed2 = JSON.parse(body);
-        items = Array.isArray(parsed2) ? parsed2 : (parsed2.entries ?? parsed2.data ?? []);
-    }
-    const base = rest.baseUrl.replace(/\/+$/, "");
-    const tables = [];
-    for (const t of items) {
-        const tableId = String(t.id ?? "");
-        const tableName = String(t.name ?? "");
-        let columnsRaw = (t.columns ?? t.fields ?? []);
-        if (columnsRaw.length === 0 && tableId) {
-            const tableUrl = `${base}/api/data-connection/v1/metadata/table/${encodeURIComponent(tableId)}?limit=-1`;
-            const colResponse = await fetch(tableUrl, {
-                method: "GET",
-                headers: buildHeaders(rest.accessToken, rest.businessDomain ?? "bd_public"),
-            });
-            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 });
-    }
-    return JSON.stringify(tables);
-}
-export async function scanMetadata(options) {
-    const { baseUrl, accessToken, id, dsType = "mysql", businessDomain = "bd_public", } = options;
-    const base = baseUrl.replace(/\/+$/, "");
-    const scanUrl = `${base}/api/data-connection/v1/metadata/scan`;
-    const statusUrl = (taskId) => `${base}/api/data-connection/v1/metadata/scan/${taskId}`;
-    const scanBody = JSON.stringify({
-        scan_name: `sdk_scan_${id.slice(0, 8)}`,
-        type: 0,
-        ds_info: { ds_id: id, ds_type: dsType },
-        use_default_template: true,
-        use_multi_threads: true,
-        status: "open",
-    });
-    const scanResponse = await fetch(scanUrl, {
-        method: "POST",
-        headers: {
-            ...buildHeaders(accessToken, businessDomain),
-            "content-type": "application/json",
-        },
-        body: scanBody,
-    });
-    const scanResult = await scanResponse.json();
-    const taskId = scanResult.id ?? "";
-    for (let i = 0; i < 30; i += 1) {
-        const delay = Math.min(2000 * Math.pow(1.5, i), 15000);
-        await new Promise((r) => setTimeout(r, delay));
-        const statusResponse = await fetch(statusUrl(taskId), {
-            method: "GET",
-            headers: buildHeaders(accessToken, businessDomain),
-        });
-        const statusData = (await statusResponse.json());
-        if (statusData.status === "success" || statusData.status === "fail") {
-            break;
-        }
-    }
-    return taskId;
-}
-// Looks up a datasource's type then triggers a metadata scan, so callers
-// don't have to repeat the GET-then-scan dance whenever a flow needs the
-// platform catalog refreshed (after import-csv, before discovering tables).
-export async function scanDatasourceMetadata(options) {
-    const dsBody = await getDatasource(options);
-    const dsType = JSON.parse(dsBody).type ?? "mysql";
-    return scanMetadata({ ...options, dsType });
-}
+// ── Vega catalog re-exports (backward compatibility) ─────────────────────────
+//
+// listTablesWithColumns, scanMetadata, and scanDatasourceMetadata now live in
+// vega.ts (they talk exclusively to vega-backend, not data-connection).
+// Re-exported here so existing callers don't break — new code should import
+// from "../api/vega.js" directly.
+export { listTablesWithColumns, scanMetadata, scanDatasourceMetadata, } from "./vega.js";

package/dist/api/model-invocation.d.ts

@@ -0,0 +1,58 @@
+export declare const MF_MODEL_API_PATH_PREFIX = "/api/mf-model-api/v1";
+export interface MfApiBaseOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    /**
+     * Replace platform origin for mf-model-api (still appends `/api/mf-model-api/v1`).
+     * Overrides `KWEAVER_MF_MODEL_API_URL` when set.
+     */
+    mfApiBaseUrl?: string;
+}
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+}
+export interface ModelChatCompletionsOptions extends MfApiBaseOptions {
+    /** Platform LLM config id (snowflake); always sent as `model_id`. */
+    modelId: string;
+    /**
+     * Registry **`model_name`** for the OpenAI-style **`model`** field in the request body.
+     * When omitted, **`model`** defaults to **`modelId`** (historical CLI behaviour).
+     * Some gateways resolve routing via display name and reject numeric-only **`model`**.
+     */
+    modelName?: string;
+    messages: ChatMessage[];
+    stream?: boolean;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    topK?: number;
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    cache?: boolean;
+    verbose?: boolean;
+}
+export interface ModelChatResult {
+    text: string;
+    raw?: unknown;
+}
+/**
+ * Consume an OpenAI-style SSE stream (`data: {...}` / `data: [DONE]`).
+ */
+export declare function consumeOpenAiSseText(response: Response, verbose?: boolean): Promise<string>;
+export declare function modelChatCompletions(options: ModelChatCompletionsOptions): Promise<ModelChatResult>;
+export interface ModelEmbeddingOptions extends MfApiBaseOptions {
+    modelId?: string;
+    modelName?: string;
+    input: string[];
+}
+export declare function modelEmbedding(options: ModelEmbeddingOptions): Promise<unknown>;
+export declare function modelEmbeddings(options: ModelEmbeddingOptions): Promise<unknown>;
+export interface ModelRerankOptions extends MfApiBaseOptions {
+    modelId?: string;
+    modelName?: string;
+    query: string;
+    documents: string[];
+}
+export declare function modelRerank(options: ModelRerankOptions): Promise<unknown>;

package/dist/api/model-invocation.js

@@ -0,0 +1,203 @@
+import { buildHeaders } from "./headers.js";
+import { HttpError } from "../utils/http.js";
+export const MF_MODEL_API_PATH_PREFIX = "/api/mf-model-api/v1";
+function resolveApiOrigin(options) {
+    const env = process.env.KWEAVER_MF_MODEL_API_URL;
+    const raw = options.mfApiBaseUrl ?? (env && env.length > 0 ? env : undefined) ?? options.baseUrl;
+    return raw.replace(/\/+$/, "");
+}
+function apiEndpoint(options, relPath) {
+    const origin = resolveApiOrigin(options);
+    const path = relPath.startsWith("/") ? relPath : `/${relPath}`;
+    return `${origin}${MF_MODEL_API_PATH_PREFIX}${path}`;
+}
+function buildChatBody(options) {
+    const { modelId, modelName, messages, stream = false, temperature, maxTokens, topP, topK, presencePenalty, frequencyPenalty, cache, } = options;
+    const trimmedName = typeof modelName === "string" ? modelName.trim() : "";
+    const modelField = trimmedName.length > 0 ? trimmedName : modelId;
+    const body = {
+        model: modelField,
+        model_id: modelId,
+        messages,
+        stream,
+    };
+    if (temperature !== undefined)
+        body.temperature = temperature;
+    if (maxTokens !== undefined)
+        body.max_tokens = maxTokens;
+    if (topP !== undefined)
+        body.top_p = topP;
+    if (topK !== undefined)
+        body.top_k = topK;
+    if (presencePenalty !== undefined)
+        body.presence_penalty = presencePenalty;
+    if (frequencyPenalty !== undefined)
+        body.frequency_penalty = frequencyPenalty;
+    if (cache !== undefined)
+        body.cache = cache;
+    return body;
+}
+function extractOpenAiCompletionText(json) {
+    const choices = json.choices;
+    const msg = choices?.[0]?.message;
+    const content = msg?.content;
+    if (typeof content === "string")
+        return content;
+    return "";
+}
+function extractOpenAiDeltaChunk(chunk) {
+    const choices = chunk.choices;
+    if (!choices?.[0])
+        return "";
+    const delta = choices[0].delta;
+    const c = delta?.content;
+    if (typeof c === "string")
+        return c;
+    return "";
+}
+/**
+ * Consume an OpenAI-style SSE stream (`data: {...}` / `data: [DONE]`).
+ */
+export async function consumeOpenAiSseText(response, verbose) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error("No response body for stream");
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let out = "";
+    const processLine = (line) => {
+        const trimmed = line.trimEnd();
+        if (!trimmed.startsWith("data:"))
+            return;
+        const payload = trimmed.slice(5).trim();
+        if (payload === "[DONE]")
+            return;
+        try {
+            const chunk = JSON.parse(payload);
+            out += extractOpenAiDeltaChunk(chunk);
+        }
+        catch (e) {
+            if (verbose) {
+                const msg = e instanceof Error ? e.message : String(e);
+                console.error(`SSE parse skip: ${msg} payload=${payload.slice(0, 120)}`);
+            }
+        }
+    };
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const ln of lines) {
+            processLine(ln);
+        }
+    }
+    if (buffer.trim())
+        processLine(buffer);
+    return out;
+}
+export async function modelChatCompletions(options) {
+    const { accessToken, businessDomain = "bd_public", stream = false, verbose } = options;
+    const url = apiEndpoint(options, "/chat/completions");
+    const body = buildChatBody({ ...options, stream });
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+            accept: stream ? "text/event-stream" : "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!response.ok) {
+        const text = await response.text();
+        throw new HttpError(response.status, response.statusText, text);
+    }
+    if (stream && contentType.includes("text/event-stream")) {
+        const text = await consumeOpenAiSseText(response, verbose);
+        return { text };
+    }
+    const text = await response.text();
+    const json = JSON.parse(text);
+    return { text: extractOpenAiCompletionText(json), raw: json };
+}
+// ── Small model invocation (mf-model-api) ───────────────────────────────────
+/** OpenAI-style **`model`** for small-model routes: registry name when set, else **`model_id`** (matches chat completions). */
+function resolveSmallInvokeModelField(modelName, modelId) {
+    const trimmedName = typeof modelName === "string" ? modelName.trim() : "";
+    if (trimmedName.length > 0)
+        return trimmedName;
+    const id = typeof modelId === "string" ? modelId.trim() : "";
+    if (id.length > 0)
+        return id;
+    return undefined;
+}
+export async function modelEmbedding(options) {
+    const { accessToken, businessDomain = "bd_public", modelId, modelName, input } = options;
+    const url = apiEndpoint(options, "/small-model/embedding");
+    const body = { input };
+    if (modelId)
+        body.model_id = modelId;
+    const modelField = resolveSmallInvokeModelField(modelName, modelId);
+    if (modelField !== undefined)
+        body.model = modelField;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    if (!response.ok)
+        throw new HttpError(response.status, response.statusText, text);
+    return text ? JSON.parse(text) : null;
+}
+export async function modelEmbeddings(options) {
+    const { accessToken, businessDomain = "bd_public", modelId, modelName, input } = options;
+    const url = apiEndpoint(options, "/small-model/embeddings");
+    const body = { input };
+    if (modelId)
+        body.model_id = modelId;
+    const modelField = resolveSmallInvokeModelField(modelName, modelId);
+    if (modelField !== undefined)
+        body.model = modelField;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    if (!response.ok)
+        throw new HttpError(response.status, response.statusText, text);
+    return text ? JSON.parse(text) : null;
+}
+export async function modelRerank(options) {
+    const { accessToken, businessDomain = "bd_public", modelId, modelName, query, documents } = options;
+    const url = apiEndpoint(options, "/small-model/reranker");
+    const body = { query, documents };
+    if (modelId)
+        body.model_id = modelId;
+    const modelField = resolveSmallInvokeModelField(modelName, modelId);
+    if (modelField !== undefined)
+        body.model = modelField;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    if (!response.ok)
+        throw new HttpError(response.status, response.statusText, text);
+    return text ? JSON.parse(text) : null;
+}

package/dist/api/models.d.ts

@@ -0,0 +1,79 @@
+export declare const MF_MODEL_MANAGER_PATH_PREFIX = "/api/mf-model-manager/v1";
+export interface MfManagerBaseOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    /**
+     * Replace platform origin for mf-model-manager (still appends `/api/mf-model-manager/v1`).
+     * Overrides `KWEAVER_MF_MODEL_MANAGER_URL` when set.
+     */
+    mfManagerBaseUrl?: string;
+}
+/**
+ * Ensure small-model request bodies do not combine direct `model_config` with adapter mode.
+ */
+export declare function assertSmallModelConfigAdapterExclusive(body: Record<string, unknown>): void;
+/** For edit: validate mutual exclusion only when config or adapter fields are present. */
+export declare function assertSmallModelEditBody(body: Record<string, unknown>): void;
+export interface ListLlmModelsOptions extends MfManagerBaseOptions {
+    page: number;
+    size: number;
+    order?: string;
+    rule?: string;
+    series?: string;
+    name?: string;
+    apiModel?: string;
+    modelType?: string;
+    quota?: boolean;
+}
+export declare function listLlmModels(options: ListLlmModelsOptions): Promise<unknown>;
+export interface GetLlmModelOptions extends MfManagerBaseOptions {
+    modelId: string;
+}
+export declare function getLlmModel(options: GetLlmModelOptions): Promise<unknown>;
+export interface AddLlmModelOptions extends MfManagerBaseOptions {
+    body: Record<string, unknown>;
+}
+export declare function addLlmModel(options: AddLlmModelOptions): Promise<unknown>;
+export interface EditLlmModelOptions extends MfManagerBaseOptions {
+    body: Record<string, unknown>;
+}
+export declare function editLlmModel(options: EditLlmModelOptions): Promise<unknown>;
+export interface DeleteLlmModelsOptions extends MfManagerBaseOptions {
+    modelIds: string[];
+}
+export declare function deleteLlmModels(options: DeleteLlmModelsOptions): Promise<unknown>;
+export interface TestLlmModelOptions extends MfManagerBaseOptions {
+    body: Record<string, unknown>;
+}
+export declare function testLlmModel(options: TestLlmModelOptions): Promise<unknown>;
+export interface ListSmallModelsOptions extends MfManagerBaseOptions {
+    page: number;
+    size: number;
+    order?: string;
+    rule?: string;
+    modelName?: string;
+    modelType?: string;
+    modelSeries?: string;
+}
+export declare function listSmallModels(options: ListSmallModelsOptions): Promise<unknown>;
+export interface GetSmallModelOptions extends MfManagerBaseOptions {
+    modelId: string;
+}
+export declare function getSmallModel(options: GetSmallModelOptions): Promise<unknown>;
+export interface AddSmallModelOptions extends MfManagerBaseOptions {
+    body: Record<string, unknown>;
+}
+export declare function addSmallModel(options: AddSmallModelOptions): Promise<unknown>;
+export interface EditSmallModelOptions extends MfManagerBaseOptions {
+    body: Record<string, unknown>;
+}
+export declare function editSmallModel(options: EditSmallModelOptions): Promise<unknown>;
+export interface DeleteSmallModelsOptions extends MfManagerBaseOptions {
+    modelIds: string[];
+}
+export declare function deleteSmallModels(options: DeleteSmallModelsOptions): Promise<unknown>;
+export interface TestSmallModelOptions extends MfManagerBaseOptions {
+    body: Record<string, unknown>;
+}
+export declare function testSmallModel(options: TestSmallModelOptions): Promise<unknown>;