@jeffober/thatch 0.1.17 → 0.1.19

package/src/tool-defs.ts

@@ -2,6 +2,17 @@ import { z } from "zod";
 import type { ThatchDB, DedupCandidate } from "./db";
 import type { EmbeddingModel } from "./embeddings";
 
+// Near-duplicate thresholds for matcher/prediction dedup at creation time.
+// Matches the thatch_find_duplicates threshold (0.85).
+const MATCHER_DEDUP_COSINE = 0.85;
+const PREDICTION_DEDUP_COSINE = 0.85;
+
+// Minimum matcher cosine to consider a prediction relevant. Matches the
+// auto-fire threshold in index.ts (PREDICTION_THRESHOLD). The query tool
+// should not return predictions from near-zero-similarity matchers that
+// would never fire in the auto-fire.
+const PREDICTION_QUERY_THRESHOLD = 0.45;
+
 /**
  * Shared context passed to every tool's execute function. Framework-agnostic —
  * neither opencode nor MCP specific. The plugin wires real defaults; tests and
@@ -367,6 +378,194 @@ const extractionDoneDef: ToolDef = {
   },
 };
 
+// ---------------------------------------------------------------------------
+// Prediction engine: user decision model
+// ---------------------------------------------------------------------------
+
+const predictionQueryDef: ToolDef = {
+  name: "prediction_query",
+  description:
+    "Query the user decision model for scored predictions matching a " +
+    "context. Returns predictions with confidence and evidence count. " +
+    "Use when facing a judgment call about scope, appropriateness, or " +
+    "methodology and the auto-injected prediction block did not already " +
+    "cover the situation.",
+  args: {
+    context: z.string().describe(
+      "The situation or context to match against. Describe the decision being faced.",
+    ),
+    store: z.string().optional().describe(
+      "Store to search. Defaults to the project store and global together.",
+    ),
+  },
+  async execute(args, ctx) {
+    const stores = args.store
+      ? [args.store as string]
+      : [ctx.defaultStore, "global"];
+    const embedding = await ctx.model.queryEmbed(args.context as string);
+    const matchers = ctx.db.findMatchers(stores, embedding, { limit: 5 })
+      .filter((m) => m.score >= PREDICTION_QUERY_THRESHOLD);
+    if (matchers.length === 0) return "No matching predictions found.";
+    const scored = ctx.db.scorePredictions(matchers);
+    if (scored.length === 0) return "No matching predictions found.";
+    return scored.map((s) => {
+      const verb = s.evidence_count === 0 ? "you may prefer" : "you tend to";
+      return `[${s.confidence.toFixed(2)} conf, ${s.evidence_count} tests] ` +
+        `When ${s.matcher_description}: ${verb} ${s.statement}`;
+    }).join("\n");
+  },
+};
+
+const predictionUpdateDef: ToolDef = {
+  name: "prediction_update",
+  description:
+    "Create, reinforce, or weaken a prediction in the user decision " +
+    "model. Use when the user corrects you, answers a question, or " +
+    "provides a clear signal about their preferences or decision-making " +
+    "strategy. The tool handles matcher and prediction lookup, dedup, " +
+    "and confidence adjustment automatically.",
+  args: {
+    matcher: z.string().describe(
+      "Description of the situation. What decision was being made?",
+    ),
+    prediction: z.string().describe(
+      "The user's preference or tendency in this situation.",
+    ),
+    signal: z.enum(["confirm", "disconfirm", "soft", "create"]).describe(
+      "What happened: confirm (user confirmed the prediction), " +
+      "disconfirm (user pushed back), soft (weak disconfirm, user " +
+      "partially disagreed), create (new observation).",
+    ),
+    rationale: z.string().describe(
+      "Why this prediction was formed or updated. What did the user say or do?",
+    ),
+    store: z.string().optional().describe(
+      "Store to write to. Defaults to the project store.",
+    ),
+  },
+  async execute(args, ctx) {
+    const store = (args.store as string) || ctx.defaultStore;
+    const matcherText = args.matcher as string;
+    const predictionText = args.prediction as string;
+    const signal = args.signal as "confirm" | "disconfirm" | "soft" | "create";
+    const rationale = args.rationale as string;
+
+    const matcherEmbed = await ctx.model.passageEmbed(matcherText);
+    const predEmbed = await ctx.model.passageEmbed(predictionText);
+
+    // All read-modify-write mutations run inside a transaction so a
+    // failure mid-sequence (FK violation, I/O error) rolls back the
+    // entire operation rather than leaving orphans (matcher without
+    // prediction, prediction without edge, edge without confidence).
+    return ctx.db.transaction(() => {
+      // Dedup matchers: find an existing matcher above the cosine threshold
+      // rather than always creating a new one.
+      let matcherId = ctx.db.findNearestMatcher(store, matcherEmbed, MATCHER_DEDUP_COSINE)?.id;
+      if (!matcherId) matcherId = ctx.db.createMatcher(store, matcherText, matcherEmbed, ctx.model.name);
+
+      // Store-wide dedup: search the entire store for a near-identical
+      // prediction, not just this matcher's edges. If found, link this
+      // matcher to the existing prediction via an edge rather than
+      // creating a second row with the same statement.
+      let predictionId = ctx.db.findNearestPrediction(store, predEmbed, PREDICTION_DEDUP_COSINE)?.id;
+
+      if (!predictionId) {
+        // No near-identical prediction exists; create one and link it.
+        predictionId = ctx.db.createPrediction(store, predictionText, rationale, predEmbed, ctx.model.name);
+        ctx.db.createEdge(matcherId, predictionId, 1.0);
+
+        // When the signal is confirm/disconfirm/soft (not create), apply
+        // it immediately so the first signal isn't lost. The prediction
+        // starts at p0 with 0 evidence; without this, the agent's
+        // "confirm" would be discarded and the prediction would have
+        // 0 confirms.
+        if (signal !== "create") {
+          ctx.db.adjustConfidence(predictionId, signal === "soft" ? "soft" : signal === "confirm" ? "confirm" : "disconfirm");
+          ctx.db.addProvenance(predictionId, signal, rationale);
+          const updated = ctx.db.getPrediction(predictionId);
+          return `[created + ${signal}] "${updated?.statement ?? predictionText}" confidence=${(updated?.confidence ?? 0).toFixed(2)} (${updated?.confirm_count ?? 0}/${updated?.disconfirm_count ?? 0})`;
+        }
+        ctx.db.addProvenance(predictionId, "create", rationale);
+        return `[created] ${store} :: "${predictionText}" for "${matcherText}"`;
+      }
+
+      // Ensure an edge links this matcher to the existing prediction.
+      // createEdge uses ON CONFLICT DO NOTHING, so existing edge weights
+      // are preserved.
+      ctx.db.createEdge(matcherId, predictionId, 1.0);
+
+      // "create" on an existing prediction means the agent re-observed
+      // the same preference in a new context. Link the edge and record
+      // provenance, but do NOT adjust confidence — "create" is
+      // confidence-neutral, not a disconfirm.
+      if (signal === "create") {
+        ctx.db.addProvenance(predictionId, "create", rationale);
+        const existing = ctx.db.getPrediction(predictionId);
+        return `[linked] "${existing?.statement ?? predictionText}" for "${matcherText}" confidence=${(existing?.confidence ?? 0).toFixed(2)} (${existing?.confirm_count ?? 0}/${existing?.disconfirm_count ?? 0})`;
+      }
+
+      // Signal is confirm, disconfirm, or soft. Map the tool's 4-value
+      // enum to adjustConfidence's 3-value enum.
+      ctx.db.adjustConfidence(predictionId, signal === "soft" ? "soft" : signal === "confirm" ? "confirm" : "disconfirm");
+      ctx.db.addProvenance(predictionId, signal, rationale);
+      const updated = ctx.db.getPrediction(predictionId);
+      return `[${signal}] "${updated?.statement ?? predictionText}" confidence=${(updated?.confidence ?? 0).toFixed(2)} (${updated?.confirm_count ?? 0}/${updated?.disconfirm_count ?? 0})`;
+    });
+  },
+};
+
+const predictionListDef: ToolDef = {
+  name: "prediction_list",
+  description:
+    "List all predictions in the user decision model with their matchers, " +
+    "confidence, and evidence count. For inspection and debugging.",
+  args: {
+    store: z.string().optional().describe(
+      "Which store to list. Defaults to the project store.",
+    ),
+  },
+  async execute(args, ctx) {
+    const store = (args.store as string) || ctx.defaultStore;
+    const predictions = ctx.db.listPredictions(store);
+    if (predictions.length === 0) return `No predictions in "${store}".`;
+    return predictions.map((p) => {
+      const matchers = p.matchers.map((m) => `    - "${m.description}" (w:${m.weight})`).join("\n");
+      const provenance = ctx.db.getProvenance(p.id);
+      const provLines = provenance.map((pr) => `    - [${pr.created_at.slice(0, 10)}] ${pr.signal}: ${pr.detail ?? ""}`).join("\n");
+      return `[${p.confidence.toFixed(2)} conf, ${p.evidence_count} tests] ${p.statement}` +
+        (p.rationale ? `\n  rationale: ${p.rationale}` : "") +
+        (matchers ? `\n  matchers:\n${matchers}` : "") +
+        (provLines ? `\n  provenance:\n${provLines}` : "");
+    }).join("\n\n");
+  },
+};
+
+const predictionDeleteDef: ToolDef = {
+  name: "prediction_delete",
+  description:
+    "Delete a prediction from the user decision model. Useful when a " +
+    "prediction was created in error or is no longer relevant. Edges " +
+    "and provenance are deleted automatically (cascade).",
+  args: {
+    statement: z.string().describe(
+      "The prediction statement to delete. Use prediction_list to find the exact text; matching is semantic (cosine >= 0.85).",
+    ),
+    store: z.string().optional().describe(
+      "Store to delete from. Defaults to the project store.",
+    ),
+  },
+  async execute(args, ctx) {
+    const store = (args.store as string) || ctx.defaultStore;
+    const statementText = args.statement as string;
+    const predEmbed = await ctx.model.passageEmbed(statementText);
+    const prediction = ctx.db.findNearestPrediction(store, predEmbed, PREDICTION_DEDUP_COSINE);
+    if (!prediction) return `No prediction matching "${statementText}" found in "${store}".`;
+    const deleted = ctx.db.deletePrediction(prediction.id);
+    if (!deleted) return `Failed to delete prediction "${prediction.statement}".`;
+    return `[deleted] "${prediction.statement}" from "${store}"`;
+  },
+};
+
 /**
  * All tool definitions, in the order they should be presented to the agent.
  * The opencode plugin wraps each in `tool()`; the MCP server exposes them
@@ -382,4 +581,8 @@ export const TOOL_DEFS: ToolDef[] = [
   findDuplicatesDef,
   markCheckedDef,
   extractionDoneDef,
+  predictionQueryDef,
+  predictionUpdateDef,
+  predictionListDef,
+  predictionDeleteDef,
 ];