@kweaver-ai/kweaver-sdk 0.7.4 → 0.8.1

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

@@ -0,0 +1,94 @@
+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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,21 @@
+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;
+}

package/dist/trace-core/diagnose/synthesizer-template.d.ts

@@ -0,0 +1,2 @@
+import type { Finding, Summary } from "./types.js";
+export declare function templateSynthesize(findings: Finding[]): Summary;

package/dist/trace-core/diagnose/synthesizer-template.js

@@ -0,0 +1,49 @@
+const SEVERITY_RANK = { high: 3, medium: 2, low: 1 };
+function overlapRatio(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const setA = new Set(a);
+    const intersect = b.filter((x) => setA.has(x)).length;
+    const smaller = Math.min(a.length, b.length);
+    return intersect / smaller;
+}
+export function templateSynthesize(findings) {
+    if (findings.length === 0) {
+        return {
+            headline: "No findings",
+            primaryRootCause: null,
+            fixPriority: [],
+            crossFindingLinks: [],
+        };
+    }
+    // Sort indices by severity desc, stable on original index (so same input → same output).
+    const indices = findings.map((_, i) => i);
+    indices.sort((i, j) => {
+        const r = SEVERITY_RANK[findings[j].severity] - SEVERITY_RANK[findings[i].severity];
+        return r !== 0 ? r : i - j;
+    });
+    const topIdx = indices[0];
+    const top = findings[topIdx];
+    const headline = `see findings[${topIdx}]: ${top.symptom}`;
+    const primaryRootCause = {
+        findingIds: [topIdx],
+        description: `Top-severity finding from rule '${top.ruleId}': ${top.symptom}`,
+        targetForFix: top.suggestedFix.target,
+    };
+    const fixPriority = indices.map((i) => ({
+        findingId: i,
+        reason: `severity=${findings[i].severity}`,
+    }));
+    const crossFindingLinks = [];
+    for (let i = 0; i < findings.length; i++) {
+        for (let j = i + 1; j < findings.length; j++) {
+            if (overlapRatio(findings[i].evidence.spans, findings[j].evidence.spans) >= 0.5) {
+                crossFindingLinks.push({
+                    findingIds: [i, j],
+                    relation: "overlapping_evidence_spans",
+                });
+            }
+        }
+    }
+    return { headline, primaryRootCause, fixPriority, crossFindingLinks };
+}

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

@@ -0,0 +1,3 @@
+import type { TraceTree } from "./types.js";
+import type { RawSpan } from "../../api/trace.js";
+export declare function assembleTraceTree(traceId: string, raw: RawSpan[]): TraceTree;

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

@@ -0,0 +1,72 @@
+// Map from OTel GenAI `gen_ai.operation.name` (the cross-runtime standard) to
+// the diagnostic SpanKind buckets rules filter on. `agent.trace.type` is kept
+// as a fallback for runtimes/fixtures that pre-tag spans with our own taxonomy.
+const KIND_MAP = {
+    // OTel GenAI semconv operation names
+    chat: "llm",
+    text_completion: "llm",
+    embeddings: "retrieval",
+    execute_tool: "tool",
+    // pre-existing custom taxonomy (synthetic fixtures, optional runtime tag)
+    model: "llm",
+    llm: "llm",
+    tool: "tool",
+    retrieval: "retrieval",
+    reasoning: "reasoning",
+};
+function deriveKind(attrs) {
+    const op = attrs["gen_ai.operation.name"];
+    if (typeof op === "string" && op in KIND_MAP)
+        return KIND_MAP[op];
+    const t = attrs["agent.trace.type"];
+    if (typeof t === "string" && t in KIND_MAP)
+        return KIND_MAP[t];
+    return "unknown";
+}
+function deriveStatus(raw) {
+    const code = raw?.code?.toUpperCase();
+    if (code === "OK")
+        return "ok";
+    if (code === "ERROR")
+        return "error";
+    return "unset";
+}
+function durationMs(start, end) {
+    if (!start || !end)
+        return 0;
+    // string nanos → BigInt to avoid precision loss, then convert to ms.
+    const s = BigInt(start);
+    const e = BigInt(end);
+    return Number((e - s) / 1000000n);
+}
+export function assembleTraceTree(traceId, raw) {
+    const spans = raw.map((r) => {
+        const attrs = r.attributes ?? {};
+        return {
+            spanId: r.spanId,
+            parentSpanId: r.parentSpanId ?? null,
+            name: r.name ?? "",
+            kind: deriveKind(attrs),
+            startTimeUnixNano: r.startTimeUnixNano ?? "0",
+            endTimeUnixNano: r.endTimeUnixNano ?? "0",
+            durationMs: durationMs(r.startTimeUnixNano, r.endTimeUnixNano),
+            status: deriveStatus(r.status),
+            attributes: attrs,
+        };
+    });
+    const byId = new Map();
+    const parentToChildren = new Map();
+    const byKind = new Map();
+    for (const s of spans) {
+        byId.set(s.spanId, s);
+        const arr = parentToChildren.get(s.parentSpanId) ?? [];
+        arr.push(s);
+        parentToChildren.set(s.parentSpanId, arr);
+        const kindArr = byKind.get(s.kind) ?? [];
+        kindArr.push(s);
+        byKind.set(s.kind, kindArr);
+    }
+    const roots = parentToChildren.get(null) ?? [];
+    const root = roots.length > 0 ? roots[0] : null;
+    return { traceId, spans, byId, parentToChildren, byKind, root };
+}

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

@@ -0,0 +1,124 @@
+export interface SpanAttributes {
+    [key: string]: unknown;
+}
+export interface Span {
+    spanId: string;
+    parentSpanId: string | null;
+    name: string;
+    kind: SpanKind;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    durationMs: number;
+    status: 'ok' | 'error' | 'unset';
+    attributes: SpanAttributes;
+}
+export type SpanKind = 'tool' | 'llm' | 'retrieval' | 'reasoning' | 'unknown';
+export interface TraceTree {
+    traceId: string;
+    spans: Span[];
+    byId: Map<string, Span>;
+    parentToChildren: Map<string | null, Span[]>;
+    byKind: Map<SpanKind, Span[]>;
+    root: Span | null;
+}
+export interface RuleTaxonomy {
+    signalsAxis: 'interaction' | 'execution' | 'environment';
+    msClass: 'retry_loop' | 'tool_misuse' | 'context_loss' | 'goal_drift' | 'cascading_error' | 'silent_quality_degradation';
+}
+export interface Rule {
+    schemaVersion: 'diagnosis-rule/v1';
+    id: string;
+    severity: 'low' | 'medium' | 'high';
+    symptom: string;
+    taxonomy: RuleTaxonomy;
+    suggestedFix: {
+        target: string;
+        changeTemplate: string;
+    };
+    verifyWith: {
+        assertionTemplates: string[];
+    };
+    predicateRef: string;
+    params: Record<string, unknown>;
+    sourcePath: string;
+}
+export interface Hit {
+    evidenceSpans: string[];
+    excerpt: string;
+    bindings: Record<string, unknown>;
+}
+export type Predicate = (trace: TraceTree, params: Record<string, unknown>) => Hit[];
+export interface Finding {
+    ruleId: string;
+    judgmentKind: 'symbolic';
+    severity: 'low' | 'medium' | 'high';
+    symptom: string;
+    likelyCause: string;
+    evidence: {
+        spans: string[];
+        excerpt: string;
+    };
+    suggestedFix: {
+        target: string;
+        change: string;
+    };
+    confidence: 'low';
+    verifyWith: {
+        suggestedEvalCase: {
+            queryId: string | null;
+            query: string | null;
+            assertions: string[];
+        };
+    };
+}
+export interface SummaryRootCause {
+    findingIds: number[];
+    description: string;
+    targetForFix: string;
+}
+export interface SummaryFixPriority {
+    findingId: number;
+    reason: string;
+}
+export interface SummaryCrossLink {
+    findingIds: number[];
+    relation: string;
+}
+export interface Summary {
+    headline: string;
+    primaryRootCause: SummaryRootCause | null;
+    fixPriority: SummaryFixPriority[];
+    crossFindingLinks: SummaryCrossLink[];
+}
+export interface Report {
+    schemaVersion: 'trace-diagnose-report/v1';
+    trace: {
+        traceId: string;
+        agentId: string | null;
+        tenant: string | null;
+    };
+    run: {
+        diagnosedAt: string;
+        cliVersion: string;
+        mode: 'symbolic-only';
+        rulesApplied: string[];
+        rulesSkipped: {
+            ruleId: string;
+            reason: string;
+        }[];
+        synthesizerMode: 'template';
+    };
+    summary: Summary;
+    findings: Finding[];
+}
+export interface DiagnoseOpts {
+    out: string | null;
+    rulesDir: string | null;
+    noBuiltin: boolean;
+    noLlm: true;
+    agentProvider: string | null;
+    timeoutMs: number;
+    baseUrl: string;
+    token: string;
+    businessDomain: string;
+}

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

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "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-core/diagnose/builtin-rules/*.yaml dist/trace-core/diagnose/builtin-rules/",
     "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"
   }
 }