@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/dist/api/dataviews.js

@@ -1,265 +0,0 @@
-import { createHash } from "node:crypto";
-import { HttpError } from "../utils/http.js";
-import { buildHeaders } from "./headers.js";
-function extractViewId(data) {
-    if (Array.isArray(data) && data.length > 0) {
-        const item = data[0];
-        if (typeof item === "string")
-            return item;
-        if (item && typeof item === "object" && "id" in item) {
-            return String(item.id ?? "");
-        }
-    }
-    if (data && typeof data === "object" && "id" in data) {
-        return String(data.id ?? "");
-    }
-    return null;
-}
-export function parseDataView(raw) {
-    const fieldsRaw = raw.fields;
-    let fields;
-    if (Array.isArray(fieldsRaw) && fieldsRaw.length > 0) {
-        fields = [];
-        for (const f of fieldsRaw) {
-            if (f && typeof f === "object") {
-                const fr = f;
-                fields.push({
-                    name: String(fr.name ?? ""),
-                    type: String(fr.type ?? "varchar"),
-                    display_name: fr.display_name != null ? String(fr.display_name) : undefined,
-                    comment: fr.comment != null ? String(fr.comment) : undefined,
-                });
-            }
-        }
-    }
-    const dv = {
-        id: String(raw.id ?? ""),
-        name: String(raw.name ?? ""),
-        query_type: String(raw.query_type ?? "SQL"),
-        datasource_id: String(raw.data_source_id ?? raw.group_id ?? ""),
-    };
-    if (raw.type != null)
-        dv.type = String(raw.type);
-    if (raw.data_source_type != null)
-        dv.data_source_type = String(raw.data_source_type);
-    if (raw.data_source_name != null)
-        dv.data_source_name = String(raw.data_source_name);
-    if (raw.sql_str != null)
-        dv.sql_str = String(raw.sql_str);
-    if (raw.meta_table_name != null)
-        dv.meta_table_name = String(raw.meta_table_name);
-    if (fields)
-        dv.fields = fields;
-    return dv;
-}
-function extractListPayload(data) {
-    if (Array.isArray(data))
-        return data;
-    if (data && typeof data === "object") {
-        const obj = data;
-        const items = obj.entries ?? obj.data;
-        if (Array.isArray(items))
-            return items;
-    }
-    return [];
-}
-export async function createDataView(options) {
-    const { baseUrl, accessToken, name, datasourceId, table, fields = [], businessDomain = "bd_public", } = options;
-    const viewId = createHash("md5").update(`${datasourceId}:${table}`).digest("hex").slice(0, 35);
-    const body = JSON.stringify([
-        {
-            id: viewId,
-            name,
-            technical_name: table,
-            type: "atomic",
-            query_type: "SQL",
-            data_source_id: datasourceId,
-            group_id: datasourceId,
-            fields,
-        },
-    ]);
-    const base = baseUrl.replace(/\/+$/, "");
-    const url = `${base}/api/mdl-data-model/v1/data-views`;
-    const response = await fetch(url, {
-        method: "POST",
-        headers: {
-            ...buildHeaders(accessToken, businessDomain),
-            "content-type": "application/json",
-        },
-        body,
-    });
-    const responseBody = await response.text();
-    if (!response.ok) {
-        // If DataView already exists (403 with "Existed" error code), delete and recreate
-        if (response.status === 403) {
-            try {
-                const errBody = JSON.parse(responseBody);
-                if (errBody.error_code?.includes("Existed")) {
-                    const actualId = await findDataViewByName({ baseUrl, accessToken, name, groupId: datasourceId, businessDomain });
-                    if (actualId && fields.length > 0) {
-                        // Delete the bare DataView (created by scanMetadata) and recreate with fields
-                        await deleteDataView({ baseUrl, accessToken, id: actualId, businessDomain });
-                        const retryResponse = await fetch(url, {
-                            method: "POST",
-                            headers: { ...buildHeaders(accessToken, businessDomain), "content-type": "application/json" },
-                            body,
-                        });
-                        if (retryResponse.ok) {
-                            const retryBody = await retryResponse.text();
-                            const retryId = extractViewId(JSON.parse(retryBody));
-                            return retryId ?? viewId;
-                        }
-                    }
-                    if (actualId)
-                        return actualId;
-                    return viewId;
-                }
-            }
-            catch { /* fall through to throw */ }
-        }
-        throw new HttpError(response.status, response.statusText, responseBody);
-    }
-    const createdId = extractViewId(JSON.parse(responseBody));
-    return createdId ?? viewId;
-}
-async function findDataViewByName(options) {
-    const list = await listDataViews({
-        baseUrl: options.baseUrl,
-        accessToken: options.accessToken,
-        businessDomain: options.businessDomain,
-        name: options.name,
-    });
-    const match = list.find((e) => e.name === options.name && e.datasource_id === options.groupId);
-    return match?.id ?? null;
-}
-export async function listDataViews(options) {
-    const { baseUrl, accessToken, businessDomain = "bd_public", datasourceId, name, type, limit = 30, } = options;
-    const base = baseUrl.replace(/\/+$/, "");
-    const url = new URL(`${base}/api/mdl-data-model/v1/data-views`);
-    url.searchParams.set("limit", String(limit));
-    if (datasourceId)
-        url.searchParams.set("data_source_id", datasourceId);
-    if (name)
-        url.searchParams.set("keyword", name);
-    if (type)
-        url.searchParams.set("type", type);
-    const response = await fetch(url.toString(), {
-        method: "GET",
-        headers: buildHeaders(accessToken, businessDomain),
-    });
-    const bodyText = await response.text();
-    if (!response.ok) {
-        throw new HttpError(response.status, response.statusText, bodyText);
-    }
-    const parsed = JSON.parse(bodyText);
-    const items = extractListPayload(parsed);
-    const out = [];
-    for (const item of items) {
-        if (item && typeof item === "object") {
-            out.push(parseDataView(item));
-        }
-    }
-    return out;
-}
-export async function deleteDataView(options) {
-    const { baseUrl, accessToken, id, businessDomain = "bd_public" } = options;
-    const base = baseUrl.replace(/\/+$/, "");
-    const url = `${base}/api/mdl-data-model/v1/data-views/${encodeURIComponent(id)}`;
-    const response = await fetch(url, {
-        method: "DELETE",
-        headers: buildHeaders(accessToken, businessDomain),
-    });
-    const bodyText = await response.text();
-    if (!response.ok) {
-        throw new HttpError(response.status, response.statusText, bodyText);
-    }
-}
-export async function getDataView(options) {
-    const { baseUrl, accessToken, id, businessDomain = "bd_public", } = options;
-    const base = baseUrl.replace(/\/+$/, "");
-    const url = `${base}/api/mdl-data-model/v1/data-views/${encodeURIComponent(id)}`;
-    const response = await fetch(url, {
-        method: "GET",
-        headers: buildHeaders(accessToken, businessDomain),
-    });
-    const body = await response.text();
-    if (!response.ok) {
-        throw new HttpError(response.status, response.statusText, body);
-    }
-    let parsed = JSON.parse(body);
-    if (Array.isArray(parsed) && parsed.length > 0) {
-        parsed = parsed[0];
-    }
-    if (!parsed || typeof parsed !== "object") {
-        throw new HttpError(500, "Invalid response", body);
-    }
-    return parseDataView(parsed);
-}
-function sleepMs(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/**
- * Find data views by name. Uses server-side keyword filtering; when `exact` is true,
- * applies client-side `name ===` filter. Optional polling with exponential backoff.
- */
-export async function findDataView(options) {
-    const { baseUrl, accessToken, businessDomain = "bd_public", name, datasourceId, exact = false, wait = false, timeoutMs = 30_000, } = options;
-    const deadline = Date.now() + timeoutMs;
-    let attempt = 0;
-    while (true) {
-        const list = await listDataViews({
-            baseUrl,
-            accessToken,
-            businessDomain,
-            datasourceId,
-            name,
-            limit: -1,
-        });
-        const results = exact ? list.filter((v) => v.name === name) : list;
-        if (results.length > 0 || !wait || Date.now() >= deadline)
-            return results;
-        const delayMs = Math.min(5000, 1000 * 2 ** attempt);
-        attempt += 1;
-        await sleepMs(delayMs);
-    }
-}
-/**
- * Execute a query against a data view (POST /api/mdl-uniquery/v1/data-views/:id).
- * When `sql` is omitted, the server uses the view's stored SQL definition.
- */
-export async function queryDataView(options) {
-    const { baseUrl, accessToken, id, sql, offset = 0, limit = 50, needTotal = false, outputFields, filters, sort, businessDomain = "bd_public", } = options;
-    const base = baseUrl.replace(/\/+$/, "");
-    const url = `${base}/api/mdl-uniquery/v1/data-views/${encodeURIComponent(id)}`;
-    const body = {
-        offset,
-        limit,
-        need_total: needTotal,
-    };
-    if (sql !== undefined && sql !== "")
-        body.sql = sql;
-    if (outputFields !== undefined)
-        body.output_fields = outputFields;
-    if (filters !== undefined)
-        body.filters = filters;
-    if (sort !== undefined)
-        body.sort = sort;
-    const response = await fetch(url, {
-        method: "POST",
-        headers: {
-            ...buildHeaders(accessToken, businessDomain),
-            "content-type": "application/json",
-            "x-http-method-override": "GET",
-        },
-        body: JSON.stringify(body),
-    });
-    const bodyText = await response.text();
-    if (!response.ok) {
-        throw new HttpError(response.status, response.statusText, bodyText);
-    }
-    const parsed = JSON.parse(bodyText);
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-        return parsed;
-    }
-    return {};
-}

package/dist/commands/dataview.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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 declare function getFirstSqlTokenAfterComments(sql: string): string;
-/** True if ad-hoc SQL is safe for dataview query (SELECT / WITH only). */
-export declare function isDataviewSelectLikeSql(sql: string): boolean;
-export declare function runDataviewCommand(args: string[]): Promise<number>;

package/dist/trace-core/diagnose/index.d.ts

@@ -1,9 +0,0 @@
-import { RuleLoadError } from "./rule-loader.js";
-import { RuleProbeError } from "./signal-probe.js";
-import type { DiagnoseOpts, Report } from "./types.js";
-import "./builtin-rules/register.js";
-export declare class TraceNotFoundError extends Error {
-    constructor(conversationId: string);
-}
-export declare function diagnose(conversationId: string, opts: DiagnoseOpts): Promise<Report>;
-export { TraceNotFoundError as DiagnoseTraceNotFound, RuleLoadError, RuleProbeError };

package/dist/trace-core/diagnose/index.js

@@ -1,104 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import yaml from "js-yaml";
-import { fileURLToPath } from "node:url";
-import { getSpansByConversationId } from "../../api/trace.js";
-import { assembleTraceTree } from "./trace-shaper.js";
-import { loadRules, RuleLoadError } from "./rule-loader.js";
-import { runRules, RuleProbeError } from "./signal-probe.js";
-import { templateSynthesize } from "./synthesizer-template.js";
-import { assembleReport, reportToYamlObject } from "./report-assembler.js";
-import "./builtin-rules/register.js"; // side effect: registers all builtin predicates
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const BUILTIN_DIR = path.join(__dirname, "builtin-rules");
-export class TraceNotFoundError extends Error {
-    constructor(conversationId) {
-        super(`no spans found for conversation: ${conversationId}`);
-        this.name = "TraceNotFoundError";
-    }
-}
-export async function diagnose(conversationId, opts) {
-    // PR-A: opts.noLlm, opts.agentProvider, opts.timeoutMs are reserved for PR-B's
-    // agent / rubric path; they are accepted by the interface but not consumed here.
-    const cwdRulesDir = opts.rulesDir ?? path.join(process.cwd(), "diagnosis-rules");
-    const fetched = await getSpansByConversationId({
-        baseUrl: opts.baseUrl,
-        token: opts.token,
-        businessDomain: opts.businessDomain,
-        conversationId,
-    });
-    const rawSpans = fetched.spans;
-    if (rawSpans.length === 0)
-        throw new TraceNotFoundError(conversationId);
-    // A conversation may produce multiple OTel traces (one per turn). PR-A
-    // diagnose is single-trace: pick the first observed traceId; warn on extras.
-    const observedTraceIds = fetched.traceIds.length > 0
-        ? fetched.traceIds
-        : [...new Set(rawSpans.map((s) => s.traceId).filter((t) => Boolean(t)))];
-    const primaryTraceId = observedTraceIds[0] ?? conversationId;
-    if (observedTraceIds.length > 1) {
-        process.stderr.write(`warning: conversation ${conversationId} has ${observedTraceIds.length} traces; diagnosing the first (${primaryTraceId})\n`);
-    }
-    const spansForPrimary = observedTraceIds.length > 0
-        ? rawSpans.filter((s) => !s.traceId || s.traceId === primaryTraceId)
-        : rawSpans;
-    const tree = assembleTraceTree(primaryTraceId, spansForPrimary);
-    const rules = await loadRules({
-        builtinDir: BUILTIN_DIR,
-        cwdRulesDir,
-        extraRulesDir: null,
-        noBuiltin: opts.noBuiltin,
-    });
-    const hits = await runRules(rules, tree);
-    const version = await cliVersion();
-    // Build provisional findings list to feed the synthesizer.
-    const provisionalReport = assembleReport({
-        traceId: primaryTraceId,
-        agentId: extractAgentId(tree),
-        tenant: extractTenant(tree),
-        cliVersion: version,
-        rules,
-        hits,
-        summary: { headline: "", primaryRootCause: null, fixPriority: [], crossFindingLinks: [] },
-    });
-    const summary = templateSynthesize(provisionalReport.findings);
-    const report = { ...provisionalReport, summary };
-    if (opts.out !== null) {
-        await fs.mkdir(path.dirname(opts.out), { recursive: true });
-        await fs.writeFile(opts.out, yaml.dump(reportToYamlObject(report)), "utf8");
-    }
-    else {
-        process.stdout.write(yaml.dump(reportToYamlObject(report)));
-    }
-    if (report.findings.length === 0) {
-        process.stderr.write("no findings\n");
-    }
-    return report;
-}
-function extractAgentId(tree) {
-    for (const s of tree.spans) {
-        const v = s.attributes["gen_ai.agent.id"];
-        if (typeof v === "string")
-            return v;
-    }
-    return null;
-}
-function extractTenant(tree) {
-    for (const s of tree.spans) {
-        const v = s.attributes["tenant"];
-        if (typeof v === "string")
-            return v;
-    }
-    return null;
-}
-async function cliVersion() {
-    try {
-        const pkgPath = path.join(__dirname, "..", "..", "..", "package.json");
-        const txt = await fs.readFile(pkgPath, "utf8");
-        return JSON.parse(txt).version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}
-export { TraceNotFoundError as DiagnoseTraceNotFound, RuleLoadError, RuleProbeError };

package/dist/trace-core/diagnose/report-assembler.d.ts

@@ -1,12 +0,0 @@
-import type { Hit, Report, Rule, Summary } from "./types.js";
-export interface AssembleReportOpts {
-    traceId: string;
-    agentId: string | null;
-    tenant: string | null;
-    cliVersion: string;
-    rules: Rule[];
-    hits: Map<string, Hit[]>;
-    summary: Summary;
-}
-export declare function assembleReport(opts: AssembleReportOpts): Report;
-export declare function reportToYamlObject(r: Report): unknown;

package/dist/trace-core/diagnose/schemas.js

@@ -1,94 +0,0 @@
-import { z } from "zod";
-const TaxonomySchema = z.object({
-    signals_axis: z.enum(["interaction", "execution", "environment"]),
-    ms_class: z.enum([
-        "retry_loop",
-        "tool_misuse",
-        "context_loss",
-        "goal_drift",
-        "cascading_error",
-        "silent_quality_degradation",
-    ]),
-});
-const SuggestedFixSchema = z.object({
-    target: z.string().min(1),
-    change_template: z.string().min(1),
-});
-const VerifyWithSchema = z.object({
-    assertion_templates: z.array(z.string()).default([]),
-});
-// PR-A: only `predicate` branch (rubric XOR enforced in PR-B).
-// We still encode the XOR shape so PR-B can enable rubric without breaking parsers.
-export const RuleSchema = z
-    .object({
-    schema_version: z.literal("diagnosis-rule/v1"),
-    id: z.string().regex(/^[a-z][a-z0-9_]*$/),
-    severity: z.enum(["low", "medium", "high"]),
-    symptom: z.string().min(1),
-    taxonomy: TaxonomySchema,
-    suggested_fix: SuggestedFixSchema,
-    verify_with: VerifyWithSchema,
-    predicate: z.string().regex(/^builtin:[a-z][a-z0-9_]*$/).optional(),
-    rubric: z.unknown().optional(), // PR-B will define a real schema
-    params: z.record(z.string(), z.unknown()).default({}),
-})
-    .refine((r) => Boolean(r.predicate) !== Boolean(r.rubric), { message: "exactly one of `predicate` or `rubric` must be present" });
-const FindingSchema = z.object({
-    rule_id: z.string(),
-    judgment_kind: z.enum(["symbolic"]), // PR-B will add "rubric"
-    severity: z.enum(["low", "medium", "high"]),
-    symptom: z.string(),
-    likely_cause: z.string(),
-    evidence: z.object({
-        spans: z.array(z.string()),
-        excerpt: z.string(),
-    }),
-    suggested_fix: z.object({
-        target: z.string(),
-        change: z.string(),
-    }),
-    confidence: z.literal("low"),
-    verify_with: z.object({
-        suggested_eval_case: z.object({
-            query_id: z.string().nullable(),
-            query: z.string().nullable(),
-            assertions: z.array(z.string()),
-        }),
-    }),
-});
-const SummarySchema = z.object({
-    headline: z.string().max(160),
-    primary_root_cause: z
-        .object({
-        finding_ids: z.array(z.number().int().nonnegative()).min(1),
-        description: z.string(),
-        target_for_fix: z.string(),
-    })
-        .nullable(),
-    fix_priority: z.array(z.object({
-        finding_id: z.number().int().nonnegative(),
-        reason: z.string(),
-    })),
-    cross_finding_links: z.array(z.object({
-        finding_ids: z.array(z.number().int().nonnegative()).min(2),
-        relation: z.string(),
-    })),
-});
-export const ReportSchema = z.object({
-    schema_version: z.literal("trace-diagnose-report/v1"),
-    trace: z.object({
-        trace_id: z.string(),
-        agent_id: z.string().nullable(),
-        tenant: z.string().nullable(),
-    }),
-    run: z.object({
-        diagnosed_at: z.string(),
-        cli_version: z.string(),
-        mode: z.enum(["symbolic-only", "rubric-only", "hybrid"]),
-        rules_applied: z.array(z.string()),
-        rules_skipped: z.array(z.object({ rule_id: z.string(), reason: z.string() })),
-        synthesizer_mode: z.enum(["template", "agent"]),
-    }),
-    summary: SummarySchema,
-    findings: z.array(FindingSchema),
-});

package/dist/trace-core/diagnose/signal-probe.d.ts

@@ -1,5 +0,0 @@
-import type { Hit, Rule, TraceTree } from "./types.js";
-export declare class RuleProbeError extends Error {
-    constructor(ruleId: string, cause: Error);
-}
-export declare function runRules(rules: Rule[], tree: TraceTree): Promise<Map<string, Hit[]>>;

package/dist/trace-core/diagnose/signal-probe.js

@@ -1,21 +0,0 @@
-import { resolvePredicate } from "./predicate-registry.js";
-export class RuleProbeError extends Error {
-    constructor(ruleId, cause) {
-        super(`predicate failed for rule '${ruleId}': ${cause.message}`);
-        this.name = "RuleProbeError";
-    }
-}
-export async function runRules(rules, tree) {
-    const out = new Map();
-    for (const rule of rules) {
-        const fn = resolvePredicate(rule.predicateRef);
-        try {
-            const hits = fn(tree, rule.params);
-            out.set(rule.id, hits);
-        }
-        catch (e) {
-            throw new RuleProbeError(rule.id, e);
-        }
-    }
-    return out;
-}