@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/dist/trace-ai/scan/batched-rubric.js

@@ -0,0 +1,159 @@
+import yaml from "js-yaml";
+import { z } from "zod";
+import { AgentProviderError } from "../../agent-providers/types.js";
+import { render as renderPrompt, languageInstructionFor, } from "../../agent-providers/prompt-template.js";
+function chunkArray(arr, size) {
+    const out = [];
+    for (let i = 0; i < arr.length; i += size)
+        out.push(arr.slice(i, i + size));
+    return out;
+}
+function buildTracesYaml(chunk) {
+    return yaml.dump(chunk.map((t) => ({ trace_id: t.traceId, spans: t.spans, inputs: t.inputs })), { lineWidth: 120 });
+}
+/**
+ * Takes the single-verdict raw JSON Schema object (from rule YAML's `output_schema`
+ * block) and returns a wrapper schema that:
+ *   1. Injects `trace_id` into the item's `required` array and `properties` map.
+ *   2. Wraps the augmented item inside `{ trace_results: array<augmented-item> }`.
+ *
+ * This ensures the prompt's `output_schema` block instructs the LLM to emit
+ * `trace_id` on every verdict, matching the zod schema used for validation.
+ */
+function wrapSchemaForBatch(single) {
+    const required = Array.isArray(single.required)
+        ? [...single.required, "trace_id"]
+        : ["trace_id"];
+    const properties = {
+        ...(single.properties ?? {}),
+        trace_id: { type: "string", description: "Echo back the trace_id from input" },
+    };
+    return {
+        type: "object",
+        required: ["trace_results"],
+        properties: {
+            trace_results: {
+                type: "array",
+                items: { ...single, type: "object", required, properties },
+            },
+        },
+    };
+}
+/**
+ * Stage-2 batched rubric evaluator. Splits flagged traces into chunks of K
+ * (default 10), one LLM call per chunk, then validates each per-trace verdict
+ * against the rule's output schema PLUS two ground-truth checks:
+ *   - trace_id must echo back one of this chunk's input trace_ids
+ *   - first_violating_step_id must be a real span_id in THAT trace's spans
+ * Failures isolate to the affected trace; chunk-wide LLM failures skip the
+ * whole chunk with agent-error:<kind>.
+ */
+export async function runBatchedRubric(opts) {
+    const { rule, traces, agentId, provider, promptRegistry, chunkSize, artifacts } = opts;
+    const verdicts = [];
+    const skipped = [];
+    if (artifacts) {
+        await artifacts.writeStageTwoWorkQueue(rule.ruleId, traces.map((t) => t.traceId));
+    }
+    const tpl = promptRegistry.get(rule.promptTemplateRef);
+    const chunks = chunkArray(traces, chunkSize);
+    for (let chunkIdx = 0; chunkIdx < chunks.length; chunkIdx++) {
+        const chunk = chunks[chunkIdx];
+        const traceIdSet = new Set(chunk.map((t) => t.traceId));
+        const spansByTraceId = new Map(chunk.map((t) => [t.traceId, new Set(t.spans)]));
+        const prompt = renderPrompt(tpl, {
+            rule_id: rule.ruleId,
+            batch_size: chunk.length,
+            agent_id: agentId,
+            judge_question: rule.judgeQuestion,
+            traces_yaml: buildTracesYaml(chunk),
+            output_schema: wrapSchemaForBatch(rule.outputSchemaRaw),
+            language_instruction: languageInstructionFor(opts.lang ?? "en"),
+        });
+        if (artifacts)
+            await artifacts.writeStageTwoPrompt(rule.ruleId, chunkIdx, prompt);
+        // rule.outputSchema is the SINGLE-verdict shape (zod converted from rule YAML's
+        // output_schema block). The Stage-2 batched prompt asks the LLM to return
+        // { trace_results: [<verdict>, ...] }, so we wrap before validation.
+        // We also extend each array item with trace_id (the LLM echoes back the
+        // trace_id from the input; the raw prompt schema enforces this via
+        // wrapSchemaForBatch above, so the zod schema must match).
+        const batchedOutputSchema = z.object({
+            trace_results: z.array(rule.outputSchema.and(z.object({ trace_id: z.string() }))),
+        });
+        let response;
+        try {
+            const resp = await provider.invoke({
+                prompt,
+                outputSchema: batchedOutputSchema,
+                tier: "fast",
+                timeoutMs: opts.timeoutMs,
+                correlationId: `stage-2/${rule.ruleId}/chunk-${chunkIdx}`,
+            });
+            response = resp.output;
+        }
+        catch (e) {
+            const kind = e instanceof AgentProviderError ? e.kind : "transport";
+            for (const t of chunk)
+                skipped.push({ traceId: t.traceId, reason: `agent-error:${kind}` });
+            if (artifacts)
+                await artifacts.writeStageTwoResponse(rule.ruleId, chunkIdx, { error: String(e) });
+            continue;
+        }
+        if (artifacts)
+            await artifacts.writeStageTwoResponse(rule.ruleId, chunkIdx, response);
+        const parseErrors = [];
+        const items = response.trace_results ?? [];
+        const seenInChunk = new Set(); // NEW: defend against LLM emitting same trace_id twice
+        for (const item of items) {
+            const itm = item;
+            const traceId = typeof itm.trace_id === "string" ? itm.trace_id : undefined;
+            if (!traceId || !traceIdSet.has(traceId)) {
+                // Unrecognized trace_id: silently discard — the "missing in trace_results"
+                // loop below will create a schema_violation entry for the actual input trace.
+                continue;
+            }
+            if (seenInChunk.has(traceId)) {
+                // LLM violated "no duplicates" — drop the duplicate verdict, record parse-error.
+                // The first occurrence has already been accepted; we keep that one as the verdict.
+                parseErrors.push({ traceId, reason: "schema_violation: duplicate trace_id in trace_results" });
+                continue;
+            }
+            seenInChunk.add(traceId);
+            const first = typeof itm.first_violating_step_id === "string" ? itm.first_violating_step_id : undefined;
+            if (!first || !spansByTraceId.get(traceId).has(first)) {
+                parseErrors.push({
+                    traceId,
+                    reason: `schema_violation: first_violating_step_id '${first}' not in trace's spans`,
+                });
+                continue;
+            }
+            verdicts.push({
+                traceId,
+                category: String(itm.category ?? "other"),
+                reasoning: String(itm.reasoning ?? ""),
+                severity: itm.severity ?? "low",
+                firstViolatingStepId: first,
+                evidenceSpanIds: Array.isArray(itm.evidence_span_ids)
+                    ? itm.evidence_span_ids.map(String)
+                    : [first],
+            });
+        }
+        // Any trace_id in this chunk's input that didn't appear in trace_results → schema_violation.
+        const verdictTraceIds = new Set(items.map((i) => i.trace_id));
+        for (const t of chunk) {
+            if (!verdictTraceIds.has(t.traceId)) {
+                parseErrors.push({
+                    traceId: t.traceId,
+                    reason: "schema_violation: missing in trace_results",
+                });
+            }
+        }
+        for (const pe of parseErrors)
+            skipped.push({ traceId: pe.traceId, reason: `agent-error:${pe.reason}` });
+        if (parseErrors.length > 0 && artifacts) {
+            await artifacts.writeStageTwoParseErrors(rule.ruleId, chunkIdx, parseErrors);
+        }
+    }
+    return { verdicts, skipped };
+}

package/dist/trace-ai/scan/cross-trace-synthesizer.d.ts

@@ -0,0 +1,24 @@
+import type { AgentProvider } from "../../agent-providers/types.js";
+import { PromptTemplateRegistry, type AgentOutputLang } from "../../agent-providers/prompt-template.js";
+import { ScanSummaryShape } from "./scan-summary-schema.js";
+import type { AggregatesBlock } from "./aggregator.js";
+import type { SamplerOutput } from "./sampler.js";
+import { ArtifactWriter } from "./artifacts/writer.js";
+export interface CrossTraceSynthesizerResult {
+    summary: import("zod").infer<typeof ScanSummaryShape> | null;
+    /** Non-null when summary is null (schema_violation / transport / etc.). */
+    fallbackReason?: string;
+}
+export interface RunCrossTraceSynthesizerOpts {
+    agentId: string;
+    aggregates: AggregatesBlock;
+    samples: SamplerOutput;
+    nTotal: number;
+    provider: AgentProvider;
+    promptRegistry: PromptTemplateRegistry;
+    promptRef?: string;
+    lang?: AgentOutputLang;
+    artifacts?: ArtifactWriter;
+    timeoutMs?: number;
+}
+export declare function runCrossTraceSynthesizer(opts: RunCrossTraceSynthesizerOpts): Promise<CrossTraceSynthesizerResult>;

package/dist/trace-ai/scan/cross-trace-synthesizer.js

@@ -0,0 +1,93 @@
+import yaml from "js-yaml";
+import { AgentProviderError } from "../../agent-providers/types.js";
+import { render as renderPrompt, languageInstructionFor } from "../../agent-providers/prompt-template.js";
+import { ScanSummaryShape } from "./scan-summary-schema.js";
+const SUMMARY_OUTPUT_SCHEMA_DESCRIPTION = {
+    type: "object",
+    required: ["headline", "primary_root_cause", "fix_priority", "cross_rule_links"],
+    properties: {
+        headline: { type: "string", maxLength: 160 },
+        primary_root_cause: {
+            anyOf: [
+                { type: "null" },
+                {
+                    type: "object",
+                    required: ["rule_ids", "description", "target_for_fix"],
+                    properties: {
+                        rule_ids: { type: "array", items: { type: "string" }, minItems: 1 },
+                        description: { type: "string" },
+                        target_for_fix: { type: "string" },
+                    },
+                },
+            ],
+        },
+        fix_priority: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["rule_id", "affected_trace_count", "reason"],
+                properties: {
+                    rule_id: { type: "string" },
+                    affected_trace_count: { type: "integer", minimum: 0 },
+                    reason: { type: "string" },
+                },
+            },
+        },
+        cross_rule_links: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["rule_ids", "relation"],
+                properties: {
+                    rule_ids: { type: "array", items: { type: "string" }, minItems: 2 },
+                    relation: { type: "string" },
+                },
+            },
+        },
+    },
+};
+function formatRatio(k, n) {
+    if (n === 0)
+        return "0%";
+    return `${Math.round((k / n) * 100)}%`;
+}
+export async function runCrossTraceSynthesizer(opts) {
+    const { agentId, aggregates, samples, nTotal, provider, promptRegistry, artifacts } = opts;
+    const ref = opts.promptRef ?? "builtin:cross-trace-synthesizer-v1";
+    const sampleCount = samples.samples.length;
+    if (artifacts)
+        await artifacts.writeStageFourInputs(aggregates, samples);
+    const tpl = promptRegistry.get(ref);
+    const prompt = renderPrompt(tpl, {
+        n_total: nTotal,
+        sample_count: sampleCount,
+        sample_ratio: formatRatio(sampleCount, nTotal),
+        agent_id: agentId,
+        aggregates: yaml.dump(aggregates, { lineWidth: 120 }),
+        samples_yaml: yaml.dump(samples, { lineWidth: 120 }),
+        output_schema: SUMMARY_OUTPUT_SCHEMA_DESCRIPTION,
+        language_instruction: languageInstructionFor(opts.lang ?? "en"),
+    });
+    if (artifacts)
+        await artifacts.writeStageFourPrompt(prompt);
+    try {
+        const resp = await provider.invoke({
+            prompt,
+            outputSchema: ScanSummaryShape,
+            tier: "std",
+            timeoutMs: opts.timeoutMs,
+            correlationId: `stage-4/${agentId}`,
+        });
+        if (artifacts)
+            await artifacts.writeStageFourResponse(resp.output);
+        return { summary: resp.output };
+    }
+    catch (e) {
+        const kind = e instanceof AgentProviderError ? e.kind : "transport";
+        if (artifacts) {
+            await artifacts.writeStageFourResponse({ error: String(e) });
+            await artifacts.writeStageFourParseErrors([{ reason: `agent-error:${kind}`, detail: String(e) }]);
+        }
+        return { summary: null, fallbackReason: `agent-error:${kind}` };
+    }
+}

package/dist/trace-ai/scan/index.d.ts

@@ -0,0 +1,31 @@
+import "../diagnose/builtin-rules/register.js";
+export interface RunBatchOpts {
+    traces: string[];
+    out: string;
+    rulesDir: string | null;
+    noBuiltin: boolean;
+    noArtifacts: boolean;
+    lang?: "en" | "zh";
+    /**
+     * Output format. The YAML report is always written (it's the resume
+     * ground truth via ReportSchema.safeParse). Markdown is written when
+     * format ∈ {'markdown', 'both'}. Default: 'both'.
+     */
+    format?: "yaml" | "markdown" | "both";
+    timeoutMs: number;
+    maxParallel: number;
+    baseUrl: string;
+    token: string;
+    businessDomain: string;
+}
+export interface RunBatchResult {
+    scanSummaryPath: string;
+    perTraceReportPaths: string[];
+    tracesDiagnosed: number;
+    tracesReused: number;
+}
+/**
+ * Orchestrator: walks N conv_ids through the batch pipeline.
+ * Single-agent enforced; --no-llm rejected by CLI (not here).
+ */
+export declare function runBatch(opts: RunBatchOpts): Promise<RunBatchResult>;