@kweaver-ai/kweaver-sdk 0.7.3 → 0.8.1

package/dist/commands/trace.d.ts

@@ -0,0 +1,14 @@
+export interface ParsedTraceArgs {
+    subcommand: "diagnose" | "rules-validate" | "help";
+    conversationId?: string;
+    rulePath?: string;
+    out: string | null;
+    rulesDir: string | null;
+    noBuiltin: boolean;
+    noLlm: boolean;
+    baseUrl: string | null;
+    token: string | null;
+    businessDomain: string | null;
+}
+export declare function parseTraceArgs(argv: string[]): ParsedTraceArgs;
+export declare function runTraceCommand(rest: string[]): Promise<number>;

package/dist/commands/trace.js

@@ -0,0 +1,168 @@
+import yargs from "yargs";
+import { diagnose, TraceNotFoundError } from "../trace-core/diagnose/index.js";
+import { RuleLoadError } from "../trace-core/diagnose/rule-loader.js";
+import { RuleProbeError } from "../trace-core/diagnose/signal-probe.js";
+import { RuleSchema } from "../trace-core/diagnose/schemas.js";
+import { ensureValidToken } from "../auth/oauth.js";
+import yaml from "js-yaml";
+import fs from "node:fs/promises";
+export function parseTraceArgs(argv) {
+    if (argv.length === 0) {
+        return defaults("help");
+    }
+    const head = argv[0];
+    if (head !== "diagnose") {
+        return defaults("help");
+    }
+    if (argv[1] === "rules" && argv[2] === "validate") {
+        return { ...defaults("rules-validate"), rulePath: argv[3] };
+    }
+    // diagnose <traceId> [flags...]
+    const parsed = yargs(argv.slice(1))
+        .option("out", { type: "string", default: undefined })
+        .option("rules", { type: "string", default: undefined })
+        .option("builtin", { type: "boolean", default: true }) // --no-builtin sets this to false
+        .option("llm", { type: "boolean", default: false }) // PR-A: forced false (--no-llm)
+        .option("token", { type: "string" })
+        .option("base-url", { type: "string" })
+        .option("business-domain", { alias: "bd", type: "string" })
+        .help(false)
+        .parseSync();
+    return {
+        subcommand: "diagnose",
+        conversationId: String(parsed._[0] ?? ""),
+        out: parsed.out ?? null,
+        rulesDir: parsed.rules ?? null,
+        noBuiltin: !parsed.builtin,
+        noLlm: !parsed.llm,
+        baseUrl: parsed.baseUrl ?? null,
+        token: parsed.token ?? null,
+        businessDomain: parsed.businessDomain ?? null,
+    };
+}
+function defaults(sub) {
+    return {
+        subcommand: sub,
+        out: null,
+        rulesDir: null,
+        noBuiltin: false,
+        noLlm: true,
+        baseUrl: null,
+        token: null,
+        businessDomain: null,
+    };
+}
+function printHelp() {
+    process.stdout.write(`kweaver trace — trace diagnosis commands
+
+Subcommands:
+  trace diagnose <conversation_id>            Diagnose the trace produced by a conversation; emit YAML report
+                                              (the id is the conversation_id returned by 'agent chat' /
+                                              'agent sessions'; spans are fetched from agent-observability)
+    --out <file>                              Write report to file (default: stdout)
+    --rules <dir>                             Override <cwd>/diagnosis-rules/
+    --no-builtin                              Disable the 5 builtin baseline rules
+    --no-llm                                  PR-A: always on; PR-B will allow disabling
+
+  trace diagnose rules validate <rule.yaml>   Validate a rule yaml file (exit 0 ok, 6 fail)
+
+Auth flags (any subcommand): --token, --base-url, --business-domain (-bd).
+`);
+}
+export async function runTraceCommand(rest) {
+    const args = parseTraceArgs(rest);
+    if (args.subcommand === "help") {
+        printHelp();
+        return 0;
+    }
+    if (args.subcommand === "rules-validate") {
+        return await runRulesValidate(args.rulePath ?? "");
+    }
+    // diagnose
+    if (!args.conversationId) {
+        process.stderr.write("error: missing <conversation_id>\n");
+        return 2;
+    }
+    let baseUrl = args.baseUrl ?? process.env.KWEAVER_BASE_URL ?? "";
+    let token = args.token ?? process.env.KWEAVER_TOKEN ?? "";
+    const bd = args.businessDomain ?? process.env.KWEAVER_BUSINESS_DOMAIN ?? "bd_public";
+    // Fall back to the active platform from `~/.kweaver/` (same as agent trace),
+    // so users don't need to pass --base-url / --token explicitly. Tokens are
+    // auto-refreshed for OAuth platforms; "__NO_AUTH__" is returned for no-auth.
+    if (!baseUrl || !token) {
+        try {
+            const t = await ensureValidToken();
+            if (!baseUrl)
+                baseUrl = t.baseUrl;
+            if (!token)
+                token = t.accessToken;
+        }
+        catch (e) {
+            process.stderr.write(`error: missing --base-url / --token, and no active platform in ~/.kweaver/ — ${e.message}\n`);
+            return 5;
+        }
+    }
+    if (!baseUrl || !token) {
+        process.stderr.write("error: missing --base-url / --token (or KWEAVER_BASE_URL / KWEAVER_TOKEN env)\n");
+        return 5;
+    }
+    try {
+        await diagnose(args.conversationId, {
+            out: args.out,
+            rulesDir: args.rulesDir,
+            noBuiltin: args.noBuiltin,
+            noLlm: true,
+            agentProvider: null,
+            timeoutMs: 60000,
+            baseUrl,
+            token,
+            businessDomain: bd,
+        });
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof TraceNotFoundError) {
+            process.stderr.write(`error: ${e.message}; check time window / tenant\n`);
+            return 4;
+        }
+        if (e instanceof RuleLoadError) {
+            process.stderr.write(`error: ${e.message}\n`);
+            return 6;
+        }
+        if (e instanceof RuleProbeError) {
+            process.stderr.write(`error: ${e.message}\n`);
+            return 6;
+        }
+        process.stderr.write(`error: ${e.message}\n`);
+        return 1;
+    }
+}
+async function runRulesValidate(rulePath) {
+    if (!rulePath) {
+        process.stderr.write("error: missing <rule.yaml> path\n");
+        return 2;
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(rulePath, "utf8");
+    }
+    catch (e) {
+        process.stderr.write(`error: cannot read ${rulePath}: ${e.message}\n`);
+        return 6;
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (e) {
+        process.stderr.write(`error: yaml parse error: ${e.message}\n`);
+        return 6;
+    }
+    const result = RuleSchema.safeParse(parsed);
+    if (!result.success) {
+        process.stderr.write(`error: schema validation failed:\n${result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n")}\n`);
+        return 6;
+    }
+    process.stdout.write(`ok: ${rulePath} validates against diagnosis-rule/v1\n`);
+    return 0;
+}

package/dist/index.d.ts

@@ -29,6 +29,10 @@ export type { ListKnowledgeNetworksOptions, GetKnowledgeNetworkOptions, CreateKn
 export { listKnowledgeNetworks, getKnowledgeNetwork, createKnowledgeNetwork, updateKnowledgeNetwork, deleteKnowledgeNetwork, listObjectTypes, listRelationTypes, listActionTypes, } from "./api/knowledge-networks.js";
 export type { OntologyQueryBaseOptions, ObjectTypeQueryOptions, ObjectTypePropertiesOptions, SubgraphOptions, ActionTypeQueryOptions, ActionTypeExecuteOptions, ActionExecutionGetOptions, ActionLogsListOptions, ActionLogGetOptions, ActionLogCancelOptions, } from "./api/ontology-query.js";
 export { objectTypeQuery, objectTypeProperties, subgraph, actionTypeQuery, actionTypeExecute, actionExecutionGet, actionLogsList, actionLogGet, actionLogCancel, } from "./api/ontology-query.js";
+export type { MetricQueryDataOptions, MetricDryRunOptions } from "./api/ontology-query-metrics.js";
+export { metricQueryData, metricDryRun } from "./api/ontology-query-metrics.js";
+export type { ListMetricsOptions, CreateMetricsOptions, SearchMetricsOptions, ValidateMetricsOptions, GetMetricOptions, UpdateMetricOptions, DeleteMetricOptions, GetMetricsByIdsOptions, DeleteMetricsByIdsOptions, } from "./api/bkn-metrics.js";
+export { listMetrics, createMetrics, searchMetrics, validateMetrics, getMetric, updateMetric, deleteMetric, getMetrics, deleteMetrics, } from "./api/bkn-metrics.js";
 export type { SendChatRequestOptions, SendChatRequestStreamCallbacks, ChatResult, ProgressItem, AgentInfo, } from "./api/agent-chat.js";
 export { sendChatRequest, sendChatRequestStream, fetchAgentInfo, buildChatUrl, buildAgentInfoUrl, extractText, } from "./api/agent-chat.js";
 export type { ListAgentsOptions, GetAgentOptions, GetAgentByKeyOptions, CreateAgentOptions, UpdateAgentOptions, DeleteAgentOptions, PublishAgentOptions, UnpublishAgentOptions, } from "./api/agent-list.js";
@@ -52,11 +56,16 @@ export { ContextLoaderResource } from "./resources/context-loader.js";
 export { SkillsResource } from "./resources/skills.js";
 export { ToolboxesResource } from "./resources/toolboxes.js";
 export type { InvokeToolArgs } from "./resources/toolboxes.js";
+export { ModelsResource, LlmModelsSubresource, SmallModelsSubresource, ModelInvocationSubresource, } from "./resources/models.js";
 export type { SkillStatus, SkillSummary, SkillInfo, SkillFileSummary, SkillContentIndex, SkillFileReadResult, RegisterSkillResult, DeleteSkillResult, UpdateSkillStatusResult, SkillListResult, ListSkillsOptions, ListSkillMarketOptions, GetSkillOptions, RegisterSkillContentOptions, RegisterSkillZipOptions, UpdateSkillStatusOptions, ReadSkillFileOptions, DownloadSkillOptions, DownloadedSkillArchive, } from "./api/skills.js";
 export { listSkills, listSkillMarket, getSkill, deleteSkill, updateSkillStatus, registerSkillContent, registerSkillZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, installSkillArchive, } from "./api/skills.js";
 export type { ViewField, DataView, CreateDataViewOptions, GetDataViewOptions, ListDataViewsOptions, DeleteDataViewOptions, FindDataViewOptions, QueryDataViewOptions, DataViewQueryResult, } from "./api/dataviews.js";
 export { parseDataView, createDataView, getDataView, listDataViews, deleteDataView, findDataView, queryDataView, } from "./api/dataviews.js";
 export { DataViewsResource } from "./resources/dataviews.js";
+export type { MfManagerBaseOptions, ListLlmModelsOptions, GetLlmModelOptions, AddLlmModelOptions, EditLlmModelOptions, DeleteLlmModelsOptions, TestLlmModelOptions, ListSmallModelsOptions, GetSmallModelOptions, AddSmallModelOptions, EditSmallModelOptions, DeleteSmallModelsOptions, TestSmallModelOptions, } from "./api/models.js";
+export { MF_MODEL_MANAGER_PATH_PREFIX, assertSmallModelConfigAdapterExclusive, assertSmallModelEditBody, listLlmModels, getLlmModel, addLlmModel, editLlmModel, deleteLlmModels, testLlmModel, listSmallModels, getSmallModel, addSmallModel, editSmallModel, deleteSmallModels, testSmallModel, } from "./api/models.js";
+export type { MfApiBaseOptions, ChatMessage, ModelChatCompletionsOptions, ModelChatResult, ModelEmbeddingOptions, ModelRerankOptions, } from "./api/model-invocation.js";
+export { MF_MODEL_API_PATH_PREFIX, consumeOpenAiSseText, modelChatCompletions, modelEmbedding, modelEmbeddings, modelRerank, } from "./api/model-invocation.js";
 export type { BusinessDomain, ListBusinessDomainsOptions } from "./api/business-domains.js";
 export { listBusinessDomains } from "./api/business-domains.js";
 export type { CreateToolboxOptions, DeleteToolboxOptions, SetToolboxStatusOptions, UploadToolOptions, SetToolStatusesOptions, ListToolboxesOptions, ListToolsOptions, InvokeToolOptions, } from "./api/toolboxes.js";

package/dist/index.js

@@ -27,6 +27,8 @@
  */
 export { listKnowledgeNetworks, getKnowledgeNetwork, createKnowledgeNetwork, updateKnowledgeNetwork, deleteKnowledgeNetwork, listObjectTypes, listRelationTypes, listActionTypes, } from "./api/knowledge-networks.js";
 export { objectTypeQuery, objectTypeProperties, subgraph, actionTypeQuery, actionTypeExecute, actionExecutionGet, actionLogsList, actionLogGet, actionLogCancel, } from "./api/ontology-query.js";
+export { metricQueryData, metricDryRun } from "./api/ontology-query-metrics.js";
+export { listMetrics, createMetrics, searchMetrics, validateMetrics, getMetric, updateMetric, deleteMetric, getMetrics, deleteMetrics, } from "./api/bkn-metrics.js";
 export { sendChatRequest, sendChatRequestStream, fetchAgentInfo, buildChatUrl, buildAgentInfoUrl, extractText, } from "./api/agent-chat.js";
 export { listAgents, getAgent, getAgentByKey, createAgent, updateAgent, deleteAgent, publishAgent, unpublishAgent, } from "./api/agent-list.js";
 export { listConversations, listMessages } from "./api/conversations.js";
@@ -41,9 +43,12 @@ export { ConversationsResource } from "./resources/conversations.js";
 export { ContextLoaderResource } from "./resources/context-loader.js";
 export { SkillsResource } from "./resources/skills.js";
 export { ToolboxesResource } from "./resources/toolboxes.js";
+export { ModelsResource, LlmModelsSubresource, SmallModelsSubresource, ModelInvocationSubresource, } from "./resources/models.js";
 export { listSkills, listSkillMarket, getSkill, deleteSkill, updateSkillStatus, registerSkillContent, registerSkillZip, getSkillContentIndex, fetchSkillContent, readSkillFile, fetchSkillFile, downloadSkill, installSkillArchive, } from "./api/skills.js";
 export { parseDataView, createDataView, getDataView, listDataViews, deleteDataView, findDataView, queryDataView, } from "./api/dataviews.js";
 export { DataViewsResource } from "./resources/dataviews.js";
+export { MF_MODEL_MANAGER_PATH_PREFIX, assertSmallModelConfigAdapterExclusive, assertSmallModelEditBody, listLlmModels, getLlmModel, addLlmModel, editLlmModel, deleteLlmModels, testLlmModel, listSmallModels, getSmallModel, addSmallModel, editSmallModel, deleteSmallModels, testSmallModel, } from "./api/models.js";
+export { MF_MODEL_API_PATH_PREFIX, consumeOpenAiSseText, modelChatCompletions, modelEmbedding, modelEmbeddings, modelRerank, } from "./api/model-invocation.js";
 export { listBusinessDomains } from "./api/business-domains.js";
 export { createToolbox, deleteToolbox, setToolboxStatus, uploadTool, setToolStatuses, listToolboxes, listTools, executeTool, debugTool, } from "./api/toolboxes.js";
 // ── HTTP utilities ────────────────────────────────────────────────────────────

package/dist/resources/datasources.js

@@ -1,4 +1,5 @@
-import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, listTables, listTablesWithColumns, scanMetadata, } from "../api/datasources.js";
+import { testDatasource, createDatasource, listDatasources, getDatasource, deleteDatasource, listTables, } from "../api/datasources.js";
+import { listTablesWithColumns, scanMetadata } from "../api/vega.js";
 export class DataSourcesResource {
     ctx;
     constructor(ctx) {

package/dist/resources/models.d.ts

@@ -0,0 +1,40 @@
+import type { ClientContext } from "../client.js";
+import { type ListLlmModelsOptions, type ListSmallModelsOptions, type MfManagerBaseOptions } from "../api/models.js";
+import { type MfApiBaseOptions, type ModelChatCompletionsOptions, type ModelEmbeddingOptions, type ModelRerankOptions } from "../api/model-invocation.js";
+type Base = MfManagerBaseOptions;
+export declare class LlmModelsSubresource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    list(opts: Omit<ListLlmModelsOptions, keyof Base> & Partial<MfManagerBaseOptions>): Promise<unknown>;
+    get(modelId: string, opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+    add(body: Record<string, unknown>, opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+    edit(body: Record<string, unknown>, opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+    delete(modelIds: string[], opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+    test(body: Record<string, unknown>, opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+}
+export declare class SmallModelsSubresource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    list(opts: Omit<ListSmallModelsOptions, keyof Base> & Partial<MfManagerBaseOptions>): Promise<unknown>;
+    get(modelId: string, opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+    add(body: Record<string, unknown>, opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+    edit(body: Record<string, unknown>, opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+    delete(modelIds: string[], opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+    test(body: Record<string, unknown>, opts?: Partial<Pick<MfManagerBaseOptions, "mfManagerBaseUrl" | "businessDomain">>): Promise<unknown>;
+}
+export declare class ModelInvocationSubresource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    chat(opts: Omit<ModelChatCompletionsOptions, "baseUrl" | "accessToken" | "businessDomain"> & Partial<Pick<MfApiBaseOptions, "mfApiBaseUrl" | "businessDomain">>): Promise<import("../api/model-invocation.js").ModelChatResult>;
+    embedding(opts: Omit<ModelEmbeddingOptions, "baseUrl" | "accessToken" | "businessDomain"> & Partial<Pick<MfApiBaseOptions, "mfApiBaseUrl" | "businessDomain">>): Promise<unknown>;
+    embeddings(opts: Omit<ModelEmbeddingOptions, "baseUrl" | "accessToken" | "businessDomain"> & Partial<Pick<MfApiBaseOptions, "mfApiBaseUrl" | "businessDomain">>): Promise<unknown>;
+    rerank(opts: Omit<ModelRerankOptions, "baseUrl" | "accessToken" | "businessDomain"> & Partial<Pick<MfApiBaseOptions, "mfApiBaseUrl" | "businessDomain">>): Promise<unknown>;
+}
+/** Model factory: mf-model-manager (CRUD) + mf-model-api (invoke chat / embedding / rerank). */
+export declare class ModelsResource {
+    readonly llm: LlmModelsSubresource;
+    readonly small: SmallModelsSubresource;
+    readonly invocation: ModelInvocationSubresource;
+    constructor(ctx: ClientContext);
+}
+export {};

package/dist/resources/models.js

@@ -0,0 +1,88 @@
+import { addLlmModel, addSmallModel, deleteLlmModels, deleteSmallModels, editLlmModel, editSmallModel, getLlmModel, getSmallModel, listLlmModels, listSmallModels, testLlmModel, testSmallModel, } from "../api/models.js";
+import { modelChatCompletions, modelEmbedding, modelEmbeddings, modelRerank, } from "../api/model-invocation.js";
+export class LlmModelsSubresource {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    list(opts) {
+        return listLlmModels({ ...this.ctx.base(), ...opts });
+    }
+    get(modelId, opts = {}) {
+        return getLlmModel({ ...this.ctx.base(), modelId, ...opts });
+    }
+    add(body, opts = {}) {
+        return addLlmModel({ ...this.ctx.base(), body, ...opts });
+    }
+    edit(body, opts = {}) {
+        return editLlmModel({ ...this.ctx.base(), body, ...opts });
+    }
+    delete(modelIds, opts = {}) {
+        return deleteLlmModels({ ...this.ctx.base(), modelIds, ...opts });
+    }
+    test(body, opts = {}) {
+        return testLlmModel({ ...this.ctx.base(), body, ...opts });
+    }
+}
+export class SmallModelsSubresource {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    list(opts) {
+        return listSmallModels({ ...this.ctx.base(), ...opts });
+    }
+    get(modelId, opts = {}) {
+        return getSmallModel({ ...this.ctx.base(), modelId, ...opts });
+    }
+    add(body, opts = {}) {
+        return addSmallModel({ ...this.ctx.base(), body, ...opts });
+    }
+    edit(body, opts = {}) {
+        return editSmallModel({ ...this.ctx.base(), body, ...opts });
+    }
+    delete(modelIds, opts = {}) {
+        return deleteSmallModels({ ...this.ctx.base(), modelIds, ...opts });
+    }
+    test(body, opts = {}) {
+        return testSmallModel({ ...this.ctx.base(), body, ...opts });
+    }
+}
+export class ModelInvocationSubresource {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    chat(opts) {
+        const { baseUrl, accessToken, businessDomain } = this.ctx.base();
+        return modelChatCompletions({
+            baseUrl,
+            accessToken,
+            businessDomain,
+            ...opts,
+        });
+    }
+    embedding(opts) {
+        const { baseUrl, accessToken, businessDomain } = this.ctx.base();
+        return modelEmbedding({ baseUrl, accessToken, businessDomain, ...opts });
+    }
+    embeddings(opts) {
+        const { baseUrl, accessToken, businessDomain } = this.ctx.base();
+        return modelEmbeddings({ baseUrl, accessToken, businessDomain, ...opts });
+    }
+    rerank(opts) {
+        const { baseUrl, accessToken, businessDomain } = this.ctx.base();
+        return modelRerank({ baseUrl, accessToken, businessDomain, ...opts });
+    }
+}
+/** Model factory: mf-model-manager (CRUD) + mf-model-api (invoke chat / embedding / rerank). */
+export class ModelsResource {
+    llm;
+    small;
+    invocation;
+    constructor(ctx) {
+        this.llm = new LlmModelsSubresource(ctx);
+        this.small = new SmallModelsSubresource(ctx);
+        this.invocation = new ModelInvocationSubresource(ctx);
+    }
+}

package/dist/templates/model/llm-basic.json

@@ -0,0 +1,13 @@
+{
+  "__template_note": "Shape aligned with mf-model-manager POST /llm/add: nested model_config (required). model_series must be one of: tome, qwen, openai, internlm, deepseek, qianxun, claude, chatglm, llama, others, baidu, baidu_tianchen. model_type: llm | rlm | vu. Optional: model_parameters (int>0), quota (bool). openai series: api_key required by backend validation. baidu/baidu_tianchen need extra keys inside model_config per vendor.",
+  "model_name": "example-llm",
+  "model_series": "others",
+  "model_type": "llm",
+  "max_model_len": 8192,
+  "model_config": {
+    "api_url": "https://example.com/v1/chat/completions",
+    "api_model": "example-deployment",
+    "api_key": ""
+  },
+  "quota": false
+}

package/dist/templates/model/manifest.json

@@ -0,0 +1,16 @@
+{
+  "llm": [
+    {
+      "id": "basic",
+      "file": "llm-basic.json",
+      "summary": "Minimal POST /llm/add body — model_config nested + model_series / max_model_len / model_type"
+    }
+  ],
+  "small": [
+    {
+      "id": "basic",
+      "file": "small-basic.json",
+      "summary": "Minimal model_config stub for embedding/reranker registration — extend or merge with CLI flags"
+    }
+  ]
+}

package/dist/templates/model/small-basic.json

@@ -0,0 +1,6 @@
+{
+  "__template_note": "Fragment for small-model model_config only (POST /small-model/add). Backend requires api_url + api_model inside model_config. Root fields model_name, model_type (embedding|reranker), batch_size, and for embedding also max_tokens + embedding_dim are supplied via CLI flags or separate JSON root — not repeated here.",
+  "api_url": "https://example.com/v1/embeddings",
+  "api_model": "example-embedding-model",
+  "api_key": ""
+}

package/dist/trace-core/diagnose/builtin-rules/excessive-tool-calls-per-turn.d.ts

@@ -0,0 +1,2 @@
+import type { Predicate } from "../types.js";
+export declare const predicate: Predicate;

package/dist/trace-core/diagnose/builtin-rules/excessive-tool-calls-per-turn.js

@@ -0,0 +1,15 @@
+// PR-A approximation: counts tool calls across the entire trace, not per user turn.
+// Real per-turn scoping requires turn segmentation by gen_ai.conversation.id round trips,
+// which is deferred to PR-B (where the synthesizer can also use turn boundaries for narratives).
+// For single-turn traces (the common case in PR-A) this approximation matches the rule semantics.
+export const predicate = (trace, params) => {
+    const max = params.max_tool_calls_per_turn ?? 10;
+    const tools = trace.byKind.get("tool") ?? [];
+    if (tools.length <= max)
+        return [];
+    return [{
+            evidenceSpans: tools.map((t) => t.spanId),
+            excerpt: `tool calls per turn exceeded threshold: ${tools.length} > ${max}`,
+            bindings: { count: tools.length, max_calls: max },
+        }];
+};

package/dist/trace-core/diagnose/builtin-rules/excessive-tool-calls-per-turn.yaml

@@ -0,0 +1,16 @@
+schema_version: diagnosis-rule/v1
+id: excessive_tool_calls_per_turn
+severity: medium
+symptom: excessive_tool_calls_per_user_turn
+taxonomy:
+  signals_axis: execution
+  ms_class: tool_misuse
+suggested_fix:
+  target: decision_agent.prompt
+  change_template: "constrain plan to at most {{max_calls}} tool calls per user turn; observed {{count}}"
+verify_with:
+  assertion_templates:
+    - "tool_call_count_per_turn <= {{max_calls}}"
+predicate: builtin:excessive_tool_calls_per_turn
+params:
+  max_tool_calls_per_turn: 10

package/dist/trace-core/diagnose/builtin-rules/llm-response-truncated-no-continue.d.ts

@@ -0,0 +1,2 @@
+import type { Predicate } from "../types.js";
+export declare const predicate: Predicate;

package/dist/trace-core/diagnose/builtin-rules/llm-response-truncated-no-continue.js

@@ -0,0 +1,44 @@
+function finishReason(s) {
+    // OTel GenAI 1.x emits an array (`finish_reasons`); older spans / fixtures
+    // use the singular string form. Accept both; first non-empty entry wins.
+    const arr = s.attributes["gen_ai.response.finish_reasons"];
+    if (Array.isArray(arr)) {
+        for (const r of arr) {
+            if (typeof r === "string" && r.length > 0)
+                return r;
+        }
+    }
+    const a = s.attributes["gen_ai.response.finish_reason"] ?? s.attributes["llm.finish_reason"];
+    return typeof a === "string" ? a : "";
+}
+function conversationId(s) {
+    const v = s.attributes["gen_ai.conversation.id"];
+    return typeof v === "string" ? v : "";
+}
+export const predicate = (trace) => {
+    const llms = (trace.byKind.get("llm") ?? [])
+        .slice()
+        .sort((a, b) => Number(BigInt(a.startTimeUnixNano) - BigInt(b.startTimeUnixNano)));
+    const hits = [];
+    for (let i = 0; i < llms.length; i++) {
+        const s = llms[i];
+        if (finishReason(s) !== "length")
+            continue;
+        const convId = conversationId(s);
+        let hasContinuation = false;
+        for (let j = i + 1; j < llms.length; j++) {
+            if (conversationId(llms[j]) === convId) {
+                hasContinuation = true;
+                break;
+            }
+        }
+        if (!hasContinuation) {
+            hits.push({
+                evidenceSpans: [s.spanId],
+                excerpt: `LLM response truncated (finish_reason=length) with no continuation span in conversation '${convId}'`,
+                bindings: { conversation_id: convId },
+            });
+        }
+    }
+    return hits;
+};

package/dist/trace-core/diagnose/builtin-rules/llm-response-truncated-no-continue.yaml

@@ -0,0 +1,15 @@
+schema_version: diagnosis-rule/v1
+id: llm_response_truncated_no_continue
+severity: medium
+symptom: llm_output_truncated_with_no_continuation
+taxonomy:
+  signals_axis: execution
+  ms_class: context_loss
+suggested_fix:
+  target: decision_agent.prompt
+  change_template: "after finish_reason=length, send a continuation request or split the task earlier"
+verify_with:
+  assertion_templates:
+    - "if(llm.finish_reason == 'length'): next_step in [continuation, split_task]"
+predicate: builtin:llm_response_truncated_no_continue
+params: {}

package/dist/trace-core/diagnose/builtin-rules/register.d.ts

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

package/dist/trace-core/diagnose/builtin-rules/register.js

@@ -0,0 +1,11 @@
+import { registerPredicate } from "../predicate-registry.js";
+import { predicate as toolLoopNoStateChange } from "./tool-loop-no-state-change.js";
+import { predicate as toolErrorSwallowed } from "./tool-error-swallowed.js";
+import { predicate as retrievalEmptyNoFallback } from "./retrieval-empty-no-fallback.js";
+import { predicate as llmResponseTruncatedNoContinue } from "./llm-response-truncated-no-continue.js";
+import { predicate as excessiveToolCallsPerTurn } from "./excessive-tool-calls-per-turn.js";
+registerPredicate("tool_loop_no_state_change", toolLoopNoStateChange);
+registerPredicate("tool_error_swallowed", toolErrorSwallowed);
+registerPredicate("retrieval_empty_no_fallback", retrievalEmptyNoFallback);
+registerPredicate("llm_response_truncated_no_continue", llmResponseTruncatedNoContinue);
+registerPredicate("excessive_tool_calls_per_turn", excessiveToolCallsPerTurn);

package/dist/trace-core/diagnose/builtin-rules/retrieval-empty-no-fallback.d.ts

@@ -0,0 +1,2 @@
+import type { Predicate } from "../types.js";
+export declare const predicate: Predicate;

package/dist/trace-core/diagnose/builtin-rules/retrieval-empty-no-fallback.js

@@ -0,0 +1,29 @@
+function resultCount(s) {
+    const v = s.attributes["gen_ai.retrieval.result_count"];
+    return typeof v === "number" ? v : null;
+}
+export const predicate = (trace) => {
+    const ordered = trace.spans
+        .slice()
+        .sort((a, b) => Number(BigInt(a.startTimeUnixNano) - BigInt(b.startTimeUnixNano)));
+    const hits = [];
+    for (let i = 0; i < ordered.length; i++) {
+        const s = ordered[i];
+        if (s.kind !== "retrieval")
+            continue;
+        if (resultCount(s) !== 0)
+            continue;
+        const next = ordered[i + 1];
+        if (!next)
+            continue;
+        if (next.kind === "llm") {
+            hits.push({
+                evidenceSpans: [s.spanId, next.spanId],
+                excerpt: `retrieval returned 0 results; next step was LLM generation with no fallback path`,
+                bindings: {},
+            });
+        }
+        // retrieval (retry/rewrite) or tool (alt source) → no hit
+    }
+    return hits;
+};

package/dist/trace-core/diagnose/builtin-rules/retrieval-empty-no-fallback.yaml

@@ -0,0 +1,15 @@
+schema_version: diagnosis-rule/v1
+id: retrieval_empty_no_fallback
+severity: medium
+symptom: empty_retrieval_result_no_fallback_path
+taxonomy:
+  signals_axis: execution
+  ms_class: cascading_error
+suggested_fix:
+  target: decision_agent.prompt
+  change_template: "when retrieval returns 0 results, branch to query rewrite, alternate source, or explicit 'no answer' before generating"
+verify_with:
+  assertion_templates:
+    - "if(retrieval.result_count == 0): next_step in [retry, rewrite, alt_source, no_answer]"
+predicate: builtin:retrieval_empty_no_fallback
+params: {}

package/dist/trace-core/diagnose/builtin-rules/tool-error-swallowed.d.ts

@@ -0,0 +1,2 @@
+import type { Predicate } from "../types.js";
+export declare const predicate: Predicate;

package/dist/trace-core/diagnose/builtin-rules/tool-error-swallowed.js

@@ -0,0 +1,45 @@
+function getPrompt(s) {
+    const v = s.attributes["gen_ai.prompt"] ?? s.attributes["llm.prompt"];
+    return typeof v === "string" ? v : "";
+}
+function getErrorMessage(s) {
+    const v = s.attributes["error.message"];
+    return typeof v === "string" ? v : "";
+}
+function getToolName(s) {
+    const v = s.attributes["gen_ai.tool.name"];
+    return typeof v === "string" ? v : s.name;
+}
+export const predicate = (trace) => {
+    const allSpans = trace.spans
+        .slice()
+        .sort((a, b) => Number(BigInt(a.startTimeUnixNano) - BigInt(b.startTimeUnixNano)));
+    const hits = [];
+    for (let i = 0; i < allSpans.length; i++) {
+        const s = allSpans[i];
+        if (s.kind !== "tool" || s.status !== "error")
+            continue;
+        const errMsg = getErrorMessage(s);
+        const toolName = getToolName(s);
+        // find next LLM span
+        let next;
+        for (let j = i + 1; j < allSpans.length; j++) {
+            if (allSpans[j].kind === "llm") {
+                next = allSpans[j];
+                break;
+            }
+        }
+        if (!next)
+            continue;
+        const prompt = getPrompt(next).toLowerCase();
+        const errInPrompt = errMsg.length > 0 && prompt.includes(errMsg.toLowerCase());
+        if (!errInPrompt) {
+            hits.push({
+                evidenceSpans: [s.spanId, next.spanId],
+                excerpt: `tool '${toolName}' errored ('${errMsg}') but next LLM prompt did not propagate the error`,
+                bindings: { tool_name: toolName, error_message: errMsg },
+            });
+        }
+    }
+    return hits;
+};