@vellumai/assistant 0.8.9-staging.3 → 0.8.9-staging.4

package/src/plugins/defaults/memory-v3-shadow/__tests__/dense.test.ts

@@ -0,0 +1,181 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { makeMockLogger } from "../../../../__tests__/helpers/mock-logger.js";
+import type { AssistantConfig } from "../../../../config/types.js";
+
+mock.module("../../../../util/logger.js", () => ({
+  getLogger: () => makeMockLogger(),
+}));
+
+mock.module("../../../../memory/qdrant-client.js", () => ({
+  resolveQdrantUrl: () => "http://127.0.0.1:6333",
+}));
+
+// Stub the shared embedding backend. Records the queries it was asked to embed
+// and returns one deterministic vector so `denseLane` can issue the search.
+const embedState = {
+  calls: [] as string[][],
+  throws: null as Error | null,
+};
+mock.module("../../../../memory/embedding-backend.js", () => ({
+  embedWithBackend: async (_config: unknown, inputs: string[]) => {
+    embedState.calls.push(inputs);
+    if (embedState.throws) throw embedState.throws;
+    return {
+      provider: "local",
+      model: "test-model",
+      vectors: inputs.map(() => [0.1, 0.2, 0.3, 0.4]),
+    };
+  },
+}));
+
+// Mock the @qdrant/js-client-rest client. The mock records the query params and
+// returns whatever section points the test programmed (in descending score
+// order, matching Qdrant's behavior).
+type MockPoint = {
+  payload: { article: string; ordinal: number };
+  score: number;
+};
+
+const state = {
+  points: [] as MockPoint[],
+  queryThrows: null as Error | null,
+  queryCalls: [] as Array<{
+    collection: string;
+    query: unknown;
+    limit: number;
+  }>,
+};
+
+class MockQdrantClient {
+  constructor(_opts: unknown) {}
+  async query(name: string, params: { query: unknown; limit: number }) {
+    state.queryCalls.push({
+      collection: name,
+      query: params.query,
+      limit: params.limit,
+    });
+    if (state.queryThrows) throw state.queryThrows;
+    return { points: state.points };
+  }
+}
+
+mock.module("@qdrant/js-client-rest", () => ({
+  QdrantClient: MockQdrantClient,
+}));
+
+const { denseLane, OVERSAMPLE } = await import("../dense.js");
+const { SECTION_COLLECTION, _resetSectionDenseStoreForTests } =
+  await import("../section-dense-store.js");
+
+const CONFIG = {
+  memory: { qdrant: { vectorSize: 4, onDisk: true } },
+} as unknown as AssistantConfig;
+
+function point(article: string, ordinal: number, score: number): MockPoint {
+  return { payload: { article, ordinal }, score };
+}
+
+function resetState(): void {
+  embedState.calls.length = 0;
+  embedState.throws = null;
+  state.points = [];
+  state.queryThrows = null;
+  state.queryCalls.length = 0;
+  _resetSectionDenseStoreForTests();
+}
+
+describe("memory v3 dense lane", () => {
+  beforeEach(resetState);
+  afterEach(resetState);
+
+  test("targets the section collection at k * OVERSAMPLE depth", async () => {
+    state.points = [point("page-a", 0, 0.9)];
+
+    await denseLane(CONFIG, "some query", 5);
+
+    // Embedded the query once.
+    expect(embedState.calls).toEqual([["some query"]]);
+    // Oversampled the section search so dedupe still yields k articles.
+    expect(state.queryCalls).toHaveLength(1);
+    expect(state.queryCalls[0]!.collection).toBe(SECTION_COLLECTION);
+    expect(state.queryCalls[0]!.limit).toBe(5 * OVERSAMPLE);
+    expect(state.queryCalls[0]!.query).toEqual([0.1, 0.2, 0.3, 0.4]);
+  });
+
+  test("dedupes section points to distinct articles with their best section", async () => {
+    // page-a's best section is ordinal 2 (highest score); the later page-a
+    // section is ignored once the article is already represented.
+    state.points = [
+      point("page-a", 2, 0.95),
+      point("topic-x", 0, 0.9),
+      point("page-a", 1, 0.5),
+    ];
+
+    const hits = await denseLane(CONFIG, "query", 5);
+
+    expect(hits).toEqual([
+      { article: "page-a", section: 2 },
+      { article: "topic-x", section: 0 },
+    ]);
+  });
+
+  test("oversamples then truncates to k distinct articles", async () => {
+    state.points = [
+      point("page-a", 0, 0.99),
+      point("page-b", 0, 0.98),
+      point("page-c", 0, 0.97),
+      point("page-d", 0, 0.96),
+    ];
+
+    const hits = await denseLane(CONFIG, "query", 2);
+
+    expect(hits).toEqual([
+      { article: "page-a", section: 0 },
+      { article: "page-b", section: 0 },
+    ]);
+  });
+
+  test("ignores malformed payloads", async () => {
+    state.points = [
+      {
+        payload: {
+          article: 123,
+          ordinal: 0,
+        } as unknown as MockPoint["payload"],
+        score: 0.9,
+      },
+      point("topic-x", 1, 0.8),
+    ];
+
+    const hits = await denseLane(CONFIG, "query", 5);
+
+    expect(hits).toEqual([{ article: "topic-x", section: 1 }]);
+  });
+
+  test("a thrown Qdrant search degrades to []", async () => {
+    state.queryThrows = new Error("qdrant unreachable");
+
+    const hits = await denseLane(CONFIG, "query", 5);
+
+    expect(hits).toEqual([]);
+  });
+
+  test("a failed embedding degrades to []", async () => {
+    embedState.throws = new Error("embed backend down");
+
+    const hits = await denseLane(CONFIG, "query", 5);
+
+    expect(hits).toEqual([]);
+    // No Qdrant round-trip when embedding fails.
+    expect(state.queryCalls).toHaveLength(0);
+  });
+
+  test("non-positive k short-circuits without a search", async () => {
+    const hits = await denseLane(CONFIG, "query", 0);
+
+    expect(hits).toEqual([]);
+    expect(embedState.calls).toEqual([]);
+    expect(state.queryCalls).toHaveLength(0);
+  });
+});

package/src/plugins/defaults/memory-v3-shadow/__tests__/edge.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, test } from "bun:test";
+
+import type { PageIndexEntry } from "../../../../memory/v2/page-index.js";
+import { buildEdgeGraph, edgeExpand } from "../edge.js";
+import type { Slug } from "../types.js";
+
+/** Minimal page-index entry factory — only the fields the edge lane reads. */
+function entry(id: number, slug: Slug, edges: number[] = []): PageIndexEntry {
+  return { id, slug, summary: "", edges, leaves: [], modifiedAt: 0 };
+}
+
+/** Build a raw-page reader from a fixture map; missing slugs read as "". */
+function rawReader(pages: Record<string, string>) {
+  return async (slug: Slug): Promise<string> => pages[slug] ?? "";
+}
+
+/** Frontmatter helper: wrap a `links:` list around an optional body. */
+function withLinks(links: string[], body = "body"): string {
+  const block = links.map((l) => `  - "${l}"`).join("\n");
+  return `---\ntitle: x\nlinks:\n${block}\n---\n\n${body}`;
+}
+
+describe("buildEdgeGraph — links: frontmatter", () => {
+  test("parses target + description split on the first ' — '", async () => {
+    const articles = [entry(1, "page-a"), entry(2, "page-b")];
+    const graph = await buildEdgeGraph(
+      articles,
+      rawReader({
+        "page-a": withLinks(["page-b — the b page — with an extra dash"]),
+        "page-b": "no frontmatter",
+      }),
+    );
+    const out = graph.adjacency.get("page-a")!;
+    // Split on the FIRST ' — ' only: description keeps the trailing dash text.
+    expect(out.get("page-b")).toBe("the b page — with an extra dash");
+  });
+
+  test("drops unknown/dangling link targets", async () => {
+    const articles = [entry(1, "page-a"), entry(2, "page-b")];
+    const graph = await buildEdgeGraph(
+      articles,
+      rawReader({
+        "page-a": withLinks([
+          "page-b — known target",
+          "page-ghost — dangling target not in corpus",
+        ]),
+      }),
+    );
+    const out = graph.adjacency.get("page-a")!;
+    expect(out.has("page-b")).toBe(true);
+    expect(out.has("page-ghost")).toBe(false);
+    expect([...out.keys()]).toEqual(["page-b"]);
+  });
+
+  test("a page with no links: falls back to wikilinks and numeric edges", async () => {
+    const articles = [
+      entry(1, "page-a", [2]), // numeric edge → page-b
+      entry(2, "page-b"),
+      entry(3, "topic-x"),
+    ];
+    const graph = await buildEdgeGraph(
+      articles,
+      rawReader({
+        // No links: frontmatter; body has an inline wikilink to topic-x.
+        "page-a": "plain body referencing [[topic-x]] inline",
+      }),
+    );
+    const out = graph.adjacency.get("page-a")!;
+    expect(out.has("page-b")).toBe(true); // from numeric edge
+    expect(out.has("topic-x")).toBe(true); // from wikilink
+    // No curated descriptions on wikilink/numeric edges.
+    expect(out.get("page-b")).toBeUndefined();
+    expect(out.get("topic-x")).toBeUndefined();
+  });
+});
+
+describe("buildEdgeGraph — three-source union", () => {
+  test("links ∪ wikilinks ∪ numeric edges merge into one adjacency map", async () => {
+    const articles = [
+      entry(1, "page-a", [4]), // numeric edge → topic-y
+      entry(2, "page-b"),
+      entry(3, "topic-x"),
+      entry(4, "topic-y"),
+    ];
+    const graph = await buildEdgeGraph(
+      articles,
+      rawReader({
+        "page-a": withLinks(
+          ["page-b — authored neighbour"],
+          "and a [[topic-x]] wikilink in the body",
+        ),
+      }),
+    );
+    const out = graph.adjacency.get("page-a")!;
+    expect(new Set(out.keys())).toEqual(
+      new Set(["page-b", "topic-x", "topic-y"]),
+    );
+    expect(out.get("page-b")).toBe("authored neighbour"); // from links
+    expect(out.get("topic-x")).toBeUndefined(); // from wikilink
+    expect(out.get("topic-y")).toBeUndefined(); // from numeric edge
+  });
+
+  test("read failure still keeps numeric-edge fallback", async () => {
+    const articles = [entry(1, "page-a", [2]), entry(2, "page-b")];
+    const graph = await buildEdgeGraph(articles, async () => {
+      throw new Error("read failed");
+    });
+    const out = graph.adjacency.get("page-a")!;
+    expect(out.has("page-b")).toBe(true);
+  });
+});
+
+describe("buildEdgeGraph — hubs", () => {
+  test("marks articles with in-degree > hubDegree as hubs", async () => {
+    // hub receives 3 inbound edges; with hubDegree=2 it is a hub.
+    const articles = [
+      entry(1, "page-a"),
+      entry(2, "page-b"),
+      entry(3, "page-c"),
+      entry(4, "hub"),
+    ];
+    const graph = await buildEdgeGraph(
+      articles,
+      rawReader({
+        "page-a": withLinks(["hub — to hub"]),
+        "page-b": withLinks(["hub — to hub"]),
+        "page-c": withLinks(["hub — to hub"]),
+      }),
+      { hubDegree: 2 },
+    );
+    expect(graph.hubs.has("hub")).toBe(true);
+    expect(graph.hubs.has("page-a")).toBe(false);
+  });
+});
+
+describe("edgeExpand", () => {
+  /** Build a star/chain graph: page-a → b,c,d,e,f,g ; topic-x → b. */
+  async function fixtureGraph(hubDegree = 30) {
+    const articles = [
+      entry(1, "page-a"),
+      entry(2, "page-b"),
+      entry(3, "page-c"),
+      entry(4, "page-d"),
+      entry(5, "page-e"),
+      entry(6, "page-f"),
+      entry(7, "page-g"),
+      entry(8, "topic-x"),
+    ];
+    return buildEdgeGraph(
+      articles,
+      rawReader({
+        "page-a": withLinks([
+          "page-b — neighbour b",
+          "page-c — neighbour c",
+          "page-d — neighbour d",
+          "page-e — neighbour e",
+          "page-f — neighbour f",
+          "page-g — neighbour g",
+        ]),
+        "topic-x": withLinks(["page-b — also to b"]),
+      }),
+      { hubDegree },
+    );
+  }
+
+  test("carries the curated links description through expansion", async () => {
+    const graph = await fixtureGraph();
+    const out = edgeExpand(graph, ["page-a"]);
+    const b = out.find((n) => n.article === "page-b");
+    expect(b?.description).toBe("neighbour b");
+  });
+
+  test("respects perSeed", async () => {
+    const graph = await fixtureGraph();
+    const out = edgeExpand(graph, ["page-a"], { perSeed: 2 });
+    expect(out).toHaveLength(2);
+    expect(out.map((n) => n.article)).toEqual(["page-b", "page-c"]);
+  });
+
+  test("respects cap across seeds", async () => {
+    const graph = await fixtureGraph();
+    // Two seeds each could add many; cap=3 truncates the total.
+    const out = edgeExpand(graph, ["page-a", "topic-x"], {
+      perSeed: 6,
+      cap: 3,
+    });
+    expect(out).toHaveLength(3);
+  });
+
+  test("respects seedCount (only top-N seeds expanded)", async () => {
+    // seedCount=1: only the first seed expands; the second seed's unique
+    // neighbour is never reached.
+    const articles = [
+      entry(1, "seed-1"),
+      entry(2, "seed-2"),
+      entry(3, "only-via-2"),
+      entry(4, "via-1"),
+    ];
+    const g = await buildEdgeGraph(
+      articles,
+      rawReader({
+        "seed-1": withLinks(["via-1 — x"]),
+        "seed-2": withLinks(["only-via-2 — y"]),
+      }),
+    );
+    const out = edgeExpand(g, ["seed-1", "seed-2"], { seedCount: 1 });
+    expect(out.map((n) => n.article)).toEqual(["via-1"]);
+    expect(out.find((n) => n.article === "only-via-2")).toBeUndefined();
+  });
+
+  test("excludes hub neighbours from expansion", async () => {
+    // page-b has in-degree 2 (page-a + topic-x). At the default threshold it
+    // is not a hub; lowering hubDegree below 2 makes it one.
+    const nonHubGraph = await fixtureGraph();
+    expect(nonHubGraph.hubs.has("page-b")).toBe(false);
+
+    const hubGraph = await fixtureGraph(1); // page-b in-degree 2 > 1 → hub
+    expect(hubGraph.hubs.has("page-b")).toBe(true);
+    const out = edgeExpand(hubGraph, ["page-a"]);
+    expect(out.find((n) => n.article === "page-b")).toBeUndefined();
+    // non-hub neighbours still surface
+    expect(out.find((n) => n.article === "page-c")).toBeDefined();
+  });
+
+  test("respects the alive predicate", async () => {
+    const graph = await fixtureGraph();
+    const out = edgeExpand(graph, ["page-a"], {
+      alive: (slug) => slug !== "page-c",
+    });
+    expect(out.find((n) => n.article === "page-c")).toBeUndefined();
+    expect(out.find((n) => n.article === "page-b")).toBeDefined();
+  });
+
+  test("does not surface the seeds themselves", async () => {
+    const articles = [entry(1, "page-a"), entry(2, "page-b")];
+    const graph = await buildEdgeGraph(
+      articles,
+      rawReader({
+        "page-a": withLinks(["page-b — to b"]),
+        "page-b": withLinks(["page-a — back to a"]),
+      }),
+    );
+    const out = edgeExpand(graph, ["page-a", "page-b"]);
+    // page-a and page-b are both seeds; neither should be surfaced.
+    expect(out).toHaveLength(0);
+  });
+});