@kweaver-ai/kweaver-sdk 0.7.3 → 0.8.1

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/dist/utils/trace-views.d.ts

@@ -0,0 +1,44 @@
+import type { TraceSpan, TracesByConversationResult } from "../api/conversations.js";
+export interface SpanNode {
+    span: TraceSpan;
+    children: SpanNode[];
+}
+/**
+ * Build a parent-child forest from a flat span array.
+ *
+ * Spans whose parentSpanId is missing or points to a span that is not in the set
+ * are treated as roots. Multiple traceIds in one conversation produce multiple roots.
+ * Children are sorted by startTime ascending.
+ */
+export declare function buildSpanTree(spans: TraceSpan[]): SpanNode[];
+/**
+ * Tree view: indented call topology with duration, status, service, and inline metadata.
+ */
+export declare function formatTreeView(spans: TraceSpan[]): string;
+/**
+ * Perf view: aggregated duration and call count per category.
+ */
+export declare function formatPerfView(spans: TraceSpan[]): string;
+/**
+ * Evidence view: ordered chain of execute_tool spans with arguments, hit count, and score.
+ */
+export declare function formatEvidenceView(spans: TraceSpan[]): string;
+export interface ReasoningOptions {
+    /** When true, print every message at full length. Default truncates large bodies. */
+    full?: boolean;
+}
+/**
+ * Reasoning view: walks the LLM's chat history (input messages of the chat span +
+ * the assistant's final output) so the user can read the agent's actual thought
+ * process — system / user / assistant / tool_call / tool result / final answer.
+ */
+export declare function formatReasoningView(spans: TraceSpan[], opts?: ReasoningOptions): string;
+export type TraceView = "tree" | "perf" | "evidence" | "reasoning" | "all";
+export interface FormatOptions {
+    /** Pass through to formatReasoningView — disables per-message truncation. */
+    full?: boolean;
+}
+/**
+ * Render one or more views over a trace result. Returns concatenated text suitable for stdout.
+ */
+export declare function formatTraceResult(result: TracesByConversationResult, view: TraceView, opts?: FormatOptions): string;