@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.2

package/dist/trace-ai/scan/scan-summary-markdown.js

@@ -0,0 +1,71 @@
+function rel(p) { return p; }
+export function renderScanSummaryMarkdown(s) {
+    const lines = [];
+    const scan = s.scan;
+    lines.push(`# Trace Diagnose Batch Summary — agent \`${scan.agent_id}\``);
+    lines.push("");
+    const resumeBanner = scan.resumed_from_partial
+        ? ` · resumed — ${scan.traces_reused} reused, ${scan.traces_freshly_diagnosed} freshly diagnosed`
+        : "";
+    lines.push(`> ${scan.trace_count} traces · ${scan.traces_with_findings} with findings · diagnosed ${scan.diagnosed_at} · cli \`${scan.cli_version}\`${resumeBanner}`);
+    lines.push("");
+    // ── Summary ────────────────────────────────────────────────────────────
+    lines.push("## Summary");
+    lines.push("");
+    if (s.summary === null) {
+        lines.push("_Stage-4 synthesizer did not complete; aggregates and per-trace reports are still emitted below._");
+        lines.push("");
+    }
+    else {
+        lines.push(`**${s.summary.headline}**`);
+        lines.push("");
+        if (s.summary.primary_root_cause) {
+            const rc = s.summary.primary_root_cause;
+            lines.push(`Primary root cause — rules ${rc.rule_ids.map((id) => `\`${id}\``).join(", ")}; target for fix: \`${rc.target_for_fix}\`.`);
+            lines.push("");
+            lines.push(`> ${rc.description.replace(/\r?\n+/g, " ")}`);
+            lines.push("");
+        }
+    }
+    // ── Fix priority ───────────────────────────────────────────────────────
+    if (s.summary && s.summary.fix_priority.length > 0) {
+        lines.push("## Fix priority");
+        lines.push("");
+        lines.push("| Order | Rule | Affected | Reason |");
+        lines.push("|---|---|---|---|");
+        s.summary.fix_priority.forEach((p, idx) => {
+            lines.push(`| ${idx + 1} | \`${p.rule_id}\` | ${p.affected_trace_count} | ${p.reason.replace(/\|/g, "\\|").replace(/\r?\n/g, " ")} |`);
+        });
+        lines.push("");
+    }
+    // ── Cross-rule links ───────────────────────────────────────────────────
+    if (s.summary && s.summary.cross_rule_links.length > 0) {
+        lines.push("## Cross-rule links");
+        lines.push("");
+        for (const link of s.summary.cross_rule_links) {
+            const ids = link.rule_ids.map((r) => `\`${r}\``).join(" ↔ ");
+            lines.push(`- ${ids} — ${link.relation}`);
+        }
+        lines.push("");
+    }
+    // ── Aggregates ─────────────────────────────────────────────────────────
+    lines.push("## Aggregates");
+    lines.push("");
+    lines.push("| Rule | Count | high | medium | low |");
+    lines.push("|---|---|---|---|---|");
+    for (const item of s.aggregates.rule_frequency) {
+        lines.push(`| \`${item.rule_id}\` | ${item.count} | ${item.severity_breakdown.high} | ${item.severity_breakdown.medium} | ${item.severity_breakdown.low} |`);
+    }
+    lines.push("");
+    // ── Per-trace index ────────────────────────────────────────────────────
+    lines.push("## Per-Trace Reports");
+    lines.push("");
+    lines.push("| conv_id | trace_id | findings | report |");
+    lines.push("|---|---|---|---|");
+    for (const item of s.per_trace_index) {
+        const mdPath = item.report_path.replace(/\.yaml$/, ".md");
+        lines.push(`| \`${item.conversation_id}\` | \`${item.trace_id.slice(0, 16)}…\` | ${item.finding_count} | [yaml](${item.report_path}) / [md](${mdPath}) |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/trace-ai/scan/scan-summary-schema.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+/**
+ * The `summary` block shape — used both as the embedded field of the full
+ * scan-summary report AND as the output schema the Stage-4 cross-trace
+ * synthesizer LLM must satisfy.
+ */
+export declare const ScanSummaryShape: z.ZodObject<{
+    headline: z.ZodString;
+    primary_root_cause: z.ZodNullable<z.ZodObject<{
+        rule_ids: z.ZodArray<z.ZodString>;
+        description: z.ZodString;
+        target_for_fix: z.ZodString;
+    }, z.core.$strip>>;
+    fix_priority: z.ZodArray<z.ZodObject<{
+        rule_id: z.ZodString;
+        affected_trace_count: z.ZodNumber;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    cross_rule_links: z.ZodArray<z.ZodObject<{
+        rule_ids: z.ZodArray<z.ZodString>;
+        relation: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ScanSummaryShape = z.infer<typeof ScanSummaryShape>;
+export declare const ScanSummarySchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"scan-summary/v1">;
+    scan: z.ZodObject<{
+        agent_id: z.ZodString;
+        trace_count: z.ZodNumber;
+        traces_with_findings: z.ZodNumber;
+        traces_reused: z.ZodNumber;
+        traces_freshly_diagnosed: z.ZodNumber;
+        resumed_from_partial: z.ZodBoolean;
+        diagnosed_at: z.ZodString;
+        cli_version: z.ZodString;
+        synthesizer_mode: z.ZodLiteral<"agent">;
+    }, z.core.$strip>;
+    summary: z.ZodNullable<z.ZodObject<{
+        headline: z.ZodString;
+        primary_root_cause: z.ZodNullable<z.ZodObject<{
+            rule_ids: z.ZodArray<z.ZodString>;
+            description: z.ZodString;
+            target_for_fix: z.ZodString;
+        }, z.core.$strip>>;
+        fix_priority: z.ZodArray<z.ZodObject<{
+            rule_id: z.ZodString;
+            affected_trace_count: z.ZodNumber;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
+        cross_rule_links: z.ZodArray<z.ZodObject<{
+            rule_ids: z.ZodArray<z.ZodString>;
+            relation: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    aggregates: z.ZodObject<{
+        rule_frequency: z.ZodArray<z.ZodObject<{
+            rule_id: z.ZodString;
+            count: z.ZodNumber;
+            severity_breakdown: z.ZodObject<{
+                high: z.ZodNumber;
+                medium: z.ZodNumber;
+                low: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    per_trace_index: z.ZodArray<z.ZodObject<{
+        trace_id: z.ZodString;
+        conversation_id: z.ZodString;
+        report_path: z.ZodString;
+        finding_count: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ScanSummary = z.infer<typeof ScanSummarySchema>;

package/dist/trace-ai/scan/scan-summary-schema.js

@@ -0,0 +1,61 @@
+// packages/typescript/src/trace-ai/scan/scan-summary-schema.ts
+import { z } from "zod";
+const PrimaryRootCauseShape = z.object({
+    rule_ids: z.array(z.string()).min(1),
+    description: z.string(),
+    target_for_fix: z.string(),
+});
+const FixPriorityItemShape = z.object({
+    rule_id: z.string(),
+    affected_trace_count: z.number().int().nonnegative(),
+    reason: z.string(),
+});
+const CrossRuleLinkShape = z.object({
+    rule_ids: z.array(z.string()).min(2),
+    relation: z.string(),
+});
+/**
+ * The `summary` block shape — used both as the embedded field of the full
+ * scan-summary report AND as the output schema the Stage-4 cross-trace
+ * synthesizer LLM must satisfy.
+ */
+export const ScanSummaryShape = z.object({
+    headline: z.string().max(160),
+    primary_root_cause: PrimaryRootCauseShape.nullable(),
+    fix_priority: z.array(FixPriorityItemShape),
+    cross_rule_links: z.array(CrossRuleLinkShape),
+});
+const RuleFrequencyItemShape = z.object({
+    rule_id: z.string(),
+    count: z.number().int().nonnegative(),
+    severity_breakdown: z.object({
+        high: z.number().int().nonnegative(),
+        medium: z.number().int().nonnegative(),
+        low: z.number().int().nonnegative(),
+    }),
+});
+const PerTraceIndexItemShape = z.object({
+    trace_id: z.string(),
+    conversation_id: z.string(),
+    report_path: z.string(),
+    finding_count: z.number().int().nonnegative(),
+});
+export const ScanSummarySchema = z.object({
+    schema_version: z.literal("scan-summary/v1"),
+    scan: z.object({
+        agent_id: z.string().min(1),
+        trace_count: z.number().int().nonnegative(),
+        traces_with_findings: z.number().int().nonnegative(),
+        traces_reused: z.number().int().nonnegative(),
+        traces_freshly_diagnosed: z.number().int().nonnegative(),
+        resumed_from_partial: z.boolean(),
+        diagnosed_at: z.string(),
+        cli_version: z.string(),
+        synthesizer_mode: z.literal("agent"),
+    }),
+    summary: ScanSummaryShape.nullable(),
+    aggregates: z.object({
+        rule_frequency: z.array(RuleFrequencyItemShape),
+    }),
+    per_trace_index: z.array(PerTraceIndexItemShape),
+});

package/dist/trace-ai/scan/single-agent-validator.d.ts

@@ -0,0 +1,23 @@
+export type SingleAgentValidationErrorCode = "empty" | "no-spans" | "mixed";
+export declare class SingleAgentValidationError extends Error {
+    readonly code: SingleAgentValidationErrorCode;
+    readonly byConvId: ReadonlyMap<string, string | undefined>;
+    constructor(code: SingleAgentValidationErrorCode, message: string, byConvId?: ReadonlyMap<string, string | undefined>);
+}
+export interface SingleAgentValidationResult {
+    agentId: string;
+    checkedConvIds: number;
+}
+export interface FetchSpansResult {
+    spans: Array<{
+        attributes: Record<string, unknown>;
+    }>;
+    conversation_id: string;
+}
+export type FetchSpansByConvId = (convId: string) => Promise<FetchSpansResult>;
+/**
+ * Verify every conv_id in the batch resolves to spans owned by the same
+ * agent_id. Throws SingleAgentValidationError on mismatch with a discrepancy
+ * map for the CLI to print.
+ */
+export declare function validateSingleAgent(convIds: string[], fetchSpansById: FetchSpansByConvId): Promise<SingleAgentValidationResult>;

package/dist/trace-ai/scan/single-agent-validator.js

@@ -0,0 +1,42 @@
+export class SingleAgentValidationError extends Error {
+    code;
+    byConvId;
+    constructor(code, message, byConvId = new Map()) {
+        super(message);
+        this.code = code;
+        this.byConvId = byConvId;
+        this.name = "SingleAgentValidationError";
+    }
+}
+function extractAgentId(spans) {
+    for (const s of spans) {
+        const v = s.attributes["gen_ai.agent.id"];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Verify every conv_id in the batch resolves to spans owned by the same
+ * agent_id. Throws SingleAgentValidationError on mismatch with a discrepancy
+ * map for the CLI to print.
+ */
+export async function validateSingleAgent(convIds, fetchSpansById) {
+    if (convIds.length === 0) {
+        throw new SingleAgentValidationError("empty", "no conversation_ids supplied");
+    }
+    const byConvId = new Map();
+    for (const convId of convIds) {
+        const fetched = await fetchSpansById(convId);
+        if (fetched.spans.length === 0) {
+            throw new SingleAgentValidationError("no-spans", `conversation_id has no spans: ${convId}`);
+        }
+        byConvId.set(convId, extractAgentId(fetched.spans));
+    }
+    const agentIds = new Set(byConvId.values());
+    if (agentIds.size > 1 || (agentIds.size === 1 && agentIds.has(undefined))) {
+        const lines = [...byConvId.entries()].map(([c, a]) => `  ${c} → ${a ?? "(no agent.id)"}`).join("\n");
+        throw new SingleAgentValidationError("mixed", `--traces conversation_ids span multiple agents:\n${lines}`, byConvId);
+    }
+    return { agentId: [...agentIds][0], checkedConvIds: convIds.length };
+}

package/dist/trace-ai/scan/traces-list-parser.d.ts

@@ -0,0 +1,15 @@
+export type TracesListErrorCode = "empty" | "file-not-found";
+export declare class TracesListError extends Error {
+    readonly code: TracesListErrorCode;
+    constructor(code: TracesListErrorCode, message: string);
+}
+/**
+ * Parse the `--traces` argument value into an array of conversation_ids.
+ * Two forms:
+ *   - comma-separated:  "conv1,conv2,conv3"
+ *   - @file path:       "@/path/to/ids.txt" (one id per line; # comments and blanks ignored)
+ *
+ * Throws TracesListError with code='empty' for empty result, 'file-not-found'
+ * when @file path does not exist.
+ */
+export declare function parseTracesList(arg: string): Promise<string[]>;

package/dist/trace-ai/scan/traces-list-parser.js

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+export class TracesListError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "TracesListError";
+    }
+}
+/**
+ * Parse the `--traces` argument value into an array of conversation_ids.
+ * Two forms:
+ *   - comma-separated:  "conv1,conv2,conv3"
+ *   - @file path:       "@/path/to/ids.txt" (one id per line; # comments and blanks ignored)
+ *
+ * Throws TracesListError with code='empty' for empty result, 'file-not-found'
+ * when @file path does not exist.
+ */
+export async function parseTracesList(arg) {
+    if (arg.startsWith("@")) {
+        const filePath = arg.slice(1);
+        let raw;
+        try {
+            raw = await fs.readFile(filePath, "utf8");
+        }
+        catch {
+            throw new TracesListError("file-not-found", `--traces file not found: ${filePath}`);
+        }
+        const ids = raw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith("#"));
+        if (ids.length === 0) {
+            throw new TracesListError("empty", `no conversation_ids found in ${filePath}`);
+        }
+        return ids;
+    }
+    const ids = arg
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (ids.length === 0) {
+        throw new TracesListError("empty", "empty --traces value");
+    }
+    return ids;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.7.4",
+  "version": "0.8.2",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,12 +24,17 @@
   ],
   "scripts": {
     "dev": "tsx watch src/cli.ts",
-    "build": "node node_modules/typescript/bin/tsc -p tsconfig.json && rm -rf dist/templates && cp -R src/templates dist/templates",
+    "build": "node node_modules/typescript/bin/tsc -p tsconfig.json && rm -rf dist/templates && cp -R src/templates dist/templates && cp src/trace-ai/diagnose/builtin-rules/*.yaml dist/trace-ai/diagnose/builtin-rules/ && mkdir -p dist/agent-providers/prompts && cp src/agent-providers/prompts/*.prompt.md dist/agent-providers/prompts/ && cp src/trace-ai/diagnose/builtin-rules/*.prompt.md dist/trace-ai/diagnose/builtin-rules/ 2>/dev/null || true && mkdir -p dist/trace-ai/scan/prompts/builtin && cp src/trace-ai/scan/prompts/builtin/*.prompt.md dist/trace-ai/scan/prompts/builtin/ && mkdir -p dist/trace-ai/eval-set/rubric-templates && cp src/trace-ai/eval-set/rubric-templates/*.prompt.md dist/trace-ai/eval-set/rubric-templates/",
     "start": "node ./dist/cli.js",
     "lint": "node node_modules/typescript/bin/tsc --noEmit -p tsconfig.json",
     "test": "node --import tsx --test test/*.test.ts",
     "test:e2e": "node --import tsx --test test/e2e/*.test.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "docs": "node scripts/build-docs.mjs",
+    "docs:zh": "node scripts/build-docs.mjs --zh",
+    "docs:all": "npm run docs && npm run docs:zh",
+    "docs:serve": "npm run docs && serve ../../docs/reference/typescript-api-html -p 8766 -n",
+    "docs:serve:zh": "npm run docs:zh && serve ../../docs/reference/typescript-api-html-zh -p 8767 -n"
   },
   "keywords": [
     "cli",
@@ -48,10 +53,13 @@
     "node": ">=22"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.6.0",
     "@types/react": "^19.2.14",
     "@types/yargs": "^17.0.35",
+    "serve": "^14.2.5",
     "tsx": "^4.20.5",
+    "typedoc": "^0.28.19",
     "typescript": "^5.9.3"
   },
   "dependencies": {
@@ -63,10 +71,12 @@
     "ink": "^6.8.0",
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
+    "js-yaml": "^4.1.1",
     "jszip": "^3.10.1",
     "marked": "^11.2.0",
     "react": "^19.2.4",
     "string-width": "^8.2.0",
-    "yargs": "^18.0.0"
+    "yargs": "^18.0.0",
+    "zod": "^4.4.3"
   }
 }