@rubytech/create-realagent 1.0.693 → 1.0.696

package/payload/platform/lib/graph-search/src/__tests__/bm25-only.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from "vitest";
+import { bm25Only } from "../index.js";
+
+/**
+ * Stub Session records every `run()` call — we assert on the Cypher text and
+ * params to pin down the clause-composition invariants from the task brief.
+ * No real Neo4j is contacted; this is pure unit coverage of the SQL-building
+ * decision layer.
+ */
+function makeStubSession(records: Array<Record<string, unknown>> = []) {
+  const calls: Array<{ query: string; params: Record<string, unknown> }> = [];
+  const session = {
+    run(query: string, params: Record<string, unknown>) {
+      calls.push({ query, params });
+      return Promise.resolve({
+        records: records.map((r) => ({
+          get: (k: string) => r[k],
+        })),
+      });
+    },
+  } as unknown as import("neo4j-driver").Session;
+  return { session, calls };
+}
+
+describe("bm25Only Cypher composition", () => {
+  it("omits scope clause when allowedScopes is not set", async () => {
+    const { session, calls } = makeStubSession();
+    await bm25Only(session, { query: "foo", accountId: "acc-1", limit: 10 });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].query).not.toContain("node.scope");
+    expect(calls[0].params).not.toHaveProperty("allowedScopes");
+  });
+
+  it("adds scope clause only when allowedScopes is set", async () => {
+    const { session, calls } = makeStubSession();
+    await bm25Only(session, {
+      query: "foo",
+      accountId: "acc-1",
+      limit: 10,
+      allowedScopes: ["public", "account"],
+    });
+    expect(calls[0].query).toContain("node.scope IS NULL OR node.scope IN $allowedScopes");
+    expect(calls[0].params.allowedScopes).toEqual(["public", "account"]);
+  });
+
+  it("omits agent clause when agentSlug is not set", async () => {
+    const { session, calls } = makeStubSession();
+    await bm25Only(session, { query: "foo", accountId: "acc-1", limit: 10 });
+    expect(calls[0].query).not.toContain("node.agents");
+    expect(calls[0].params).not.toHaveProperty("agentSlug");
+  });
+
+  it("adds agent clause when agentSlug is set", async () => {
+    const { session, calls } = makeStubSession();
+    await bm25Only(session, {
+      query: "foo",
+      accountId: "acc-1",
+      limit: 10,
+      agentSlug: "support",
+    });
+    expect(calls[0].query).toContain("$agentSlug IN node.agents");
+    expect(calls[0].params.agentSlug).toBe("support");
+  });
+
+  it("omits keyword clause when keywords is not set", async () => {
+    const { session, calls } = makeStubSession();
+    await bm25Only(session, { query: "foo", accountId: "acc-1", limit: 10 });
+    expect(calls[0].query).not.toContain("node.keywords IS NULL");
+    expect(calls[0].params).not.toHaveProperty("keywords");
+  });
+
+  it("adds keyword clause with ANY (default) when keywords is set", async () => {
+    const { session, calls } = makeStubSession();
+    await bm25Only(session, {
+      query: "foo",
+      accountId: "acc-1",
+      limit: 10,
+      keywords: ["Alpha", "Beta"],
+    });
+    expect(calls[0].query).toContain("ANY(kw IN $keywords WHERE kw IN node.keywords)");
+    expect(calls[0].params.keywords).toEqual(["alpha", "beta"]);
+  });
+
+  it("uses ALL when keywordMatch='all'", async () => {
+    const { session, calls } = makeStubSession();
+    await bm25Only(session, {
+      query: "foo",
+      accountId: "acc-1",
+      limit: 10,
+      keywords: ["a"],
+      keywordMatch: "all",
+    });
+    expect(calls[0].query).toContain("ALL(kw IN $keywords WHERE kw IN node.keywords)");
+  });
+
+  it("always applies notTrashed filter", async () => {
+    const { session, calls } = makeStubSession();
+    await bm25Only(session, { query: "foo", accountId: "acc-1", limit: 10 });
+    expect(calls[0].query).toContain("NOT `node`:Trashed");
+    expect(calls[0].query).toContain("`node`.deletedAt IS NULL");
+  });
+
+  it("escapes Lucene special chars in query param", async () => {
+    const { session, calls } = makeStubSession();
+    await bm25Only(session, { query: "foo:bar (x)", accountId: "acc-1", limit: 10 });
+    expect(calls[0].params.query).toBe("foo\\:bar \\(x\\)");
+  });
+
+  it("returns [] when the fulltext index does not exist", async () => {
+    const session = {
+      run() {
+        return Promise.reject(new Error("There is no such fulltext index"));
+      },
+    } as unknown as import("neo4j-driver").Session;
+    const hits = await bm25Only(session, { query: "foo", accountId: "acc-1", limit: 10 });
+    expect(hits).toEqual([]);
+  });
+
+  it("rethrows non-index errors", async () => {
+    const session = {
+      run() {
+        return Promise.reject(new Error("ServiceUnavailable: database offline"));
+      },
+    } as unknown as import("neo4j-driver").Session;
+    await expect(
+      bm25Only(session, { query: "foo", accountId: "acc-1", limit: 10 }),
+    ).rejects.toThrow("ServiceUnavailable");
+  });
+});

package/payload/platform/lib/graph-search/src/__tests__/escape-and-normalise.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import { escapeLucene, normaliseBm25Scores } from "../index.js";
+
+describe("escapeLucene", () => {
+  it("escapes Lucene operators in field:value syntax", () => {
+    expect(escapeLucene("foo:bar")).toBe("foo\\:bar");
+  });
+
+  it("escapes boolean-grouping parens and OR", () => {
+    expect(escapeLucene("(a OR b)")).toBe("\\(a OR b\\)");
+  });
+
+  it("escapes wildcard characters", () => {
+    expect(escapeLucene("bar*")).toBe("bar\\*");
+  });
+
+  it("escapes backslash", () => {
+    expect(escapeLucene("a\\b")).toBe("a\\\\b");
+  });
+
+  it("preserves non-special characters", () => {
+    expect(escapeLucene("hello world 123")).toBe("hello world 123");
+  });
+
+  it("escapes a mix of specials in one pass", () => {
+    expect(escapeLucene("a+b-c&d|e!f")).toBe("a\\+b\\-c\\&d\\|e\\!f");
+  });
+});
+
+describe("normaliseBm25Scores", () => {
+  it("returns empty array for empty input", () => {
+    expect(normaliseBm25Scores([])).toEqual([]);
+  });
+
+  it("maps [min..max] to [0..1] via min-max", () => {
+    expect(normaliseBm25Scores([1, 2, 3])).toEqual([0, 0.5, 1]);
+  });
+
+  it("returns 1.0 for all values when range is zero (all scores equal)", () => {
+    expect(normaliseBm25Scores([5, 5, 5])).toEqual([1, 1, 1]);
+  });
+
+  it("returns 1.0 for single-element input (range is zero)", () => {
+    expect(normaliseBm25Scores([42])).toEqual([1]);
+  });
+
+  it("handles non-integer scores", () => {
+    const result = normaliseBm25Scores([0.5, 1.5, 2.5]);
+    expect(result[0]).toBeCloseTo(0);
+    expect(result[1]).toBeCloseTo(0.5);
+    expect(result[2]).toBeCloseTo(1);
+  });
+});

package/payload/platform/lib/graph-search/src/__tests__/hybrid.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { hybrid, clearIndexCache } from "../index.js";
+
+/**
+ * Hybrid tests cover the two decisions that make this lib non-trivial:
+ *   1. overlapping vector+BM25 nodeIds combine as 0.7*vec + 0.3*bm25_norm
+ *   2. degradeOnEmbedFailure=true with a failing embed returns bm25-only
+ *      and annotates mode="bm25"
+ * Deeper integration (index discovery, expand, keyword subscriptions) is
+ * covered by the downstream MCP tool tests against a real Neo4j.
+ */
+
+interface StubRun {
+  match: (query: string) => boolean;
+  records: Array<Record<string, unknown>>;
+}
+
+function record(fields: Record<string, unknown>) {
+  return { get: (k: string) => fields[k] };
+}
+
+function makeStubSession(scripted: StubRun[]) {
+  const calls: Array<{ query: string; params: Record<string, unknown> }> = [];
+  const session = {
+    run(query: string, params: Record<string, unknown>) {
+      calls.push({ query, params });
+      const hit = scripted.find((s) => s.match(query));
+      if (!hit) return Promise.resolve({ records: [] });
+      return Promise.resolve({ records: hit.records.map(record) });
+    },
+  } as unknown as import("neo4j-driver").Session;
+  return { session, calls };
+}
+
+beforeEach(() => {
+  clearIndexCache();
+});
+
+describe("hybrid — score combination", () => {
+  it("combines overlapping nodeIds as 0.7*vec + 0.3*bm25_norm (expand skipped)", async () => {
+    const session = makeStubSession([
+      {
+        match: (q) => q.includes("SHOW INDEXES"),
+        records: [{ name: "vec_knowledge", labelsOrTypes: ["KnowledgeDocument"] }],
+      },
+      {
+        match: (q) => q.includes("db.index.vector.queryNodes"),
+        records: [
+          {
+            nodeId: "n1",
+            nodeLabels: ["KnowledgeDocument"],
+            node: { properties: { title: "A" } },
+            score: 0.9,
+          },
+          {
+            nodeId: "n2",
+            nodeLabels: ["KnowledgeDocument"],
+            node: { properties: { title: "B" } },
+            score: 0.5,
+          },
+        ],
+      },
+      {
+        match: (q) => q.includes("db.index.fulltext.queryNodes"),
+        records: [
+          {
+            nodeId: "n1",
+            nodeLabels: ["KnowledgeDocument"],
+            node: { properties: { title: "A" } },
+            score: 10,
+          },
+          {
+            nodeId: "n3",
+            nodeLabels: ["KnowledgeDocument"],
+            node: { properties: { title: "C" } },
+            score: 5,
+          },
+        ],
+      },
+    ]).session;
+
+    const embed = async () => [0.1, 0.2, 0.3];
+    const res = await hybrid(session, embed, {
+      query: "test",
+      accountId: "acc-1",
+      limit: 10,
+      expandHops: 0,
+    });
+
+    expect(res.mode).toBe("hybrid");
+    // bm25 normalised: [10,5] -> [1,0]; n1: 0.7*0.9 + 0.3*1 = 0.93
+    //                  n2 (vec only): 0.7*0.5 + 0.3*0 = 0.35
+    //                  n3 (bm25 only): 0.7*0 + 0.3*0 = 0
+    const n1 = res.results.find((r) => r.nodeId === "n1");
+    const n2 = res.results.find((r) => r.nodeId === "n2");
+    const n3 = res.results.find((r) => r.nodeId === "n3");
+    expect(n1?.score).toBeCloseTo(0.93);
+    expect(n2?.score).toBeCloseTo(0.35);
+    expect(n3?.score).toBeCloseTo(0);
+    // Ranking: n1 > n2 > n3
+    expect(res.results.map((r) => r.nodeId)).toEqual(["n1", "n2", "n3"]);
+  });
+});
+
+describe("hybrid — embed degrade", () => {
+  const failingEmbed = async () => {
+    throw new Error("Ollama unreachable");
+  };
+
+  it("throws when degradeOnEmbedFailure is false (default)", async () => {
+    const { session } = makeStubSession([
+      { match: () => true, records: [] },
+    ]);
+    await expect(
+      hybrid(session, failingEmbed, { query: "x", accountId: "a", limit: 5 }),
+    ).rejects.toThrow("Ollama unreachable");
+  });
+
+  it("returns bm25-only result with mode='bm25' when degradeOnEmbedFailure is true", async () => {
+    const { session } = makeStubSession([
+      {
+        match: (q) => q.includes("db.index.fulltext.queryNodes"),
+        records: [
+          {
+            nodeId: "n1",
+            nodeLabels: ["KnowledgeDocument"],
+            node: { properties: { title: "hit" } },
+            score: 3,
+          },
+        ],
+      },
+    ]);
+
+    const res = await hybrid(session, failingEmbed, {
+      query: "x",
+      accountId: "a",
+      limit: 5,
+      degradeOnEmbedFailure: true,
+    });
+
+    expect(res.mode).toBe("bm25");
+    expect(res.embedError).toContain("Ollama unreachable");
+    expect(res.results).toHaveLength(1);
+    expect(res.results[0]?.nodeId).toBe("n1");
+    // score is raw BM25 score (no hybrid combine in degrade path)
+    expect(res.results[0]?.score).toBe(3);
+    // related[] is [] in degrade path (no expand)
+    expect(res.results[0]?.related).toEqual([]);
+  });
+
+  it("returns empty results with mode='bm25' when embed fails and index is missing", async () => {
+    const session = {
+      run: (q: string) => {
+        if (q.includes("db.index.fulltext.queryNodes")) {
+          return Promise.reject(new Error("There is no such fulltext index"));
+        }
+        return Promise.resolve({ records: [] });
+      },
+    } as unknown as import("neo4j-driver").Session;
+
+    const res = await hybrid(session, failingEmbed, {
+      query: "x",
+      accountId: "a",
+      limit: 5,
+      degradeOnEmbedFailure: true,
+    });
+    expect(res.mode).toBe("bm25");
+    expect(res.results).toEqual([]);
+  });
+});
+
+describe("hybrid — label filter short-circuit", () => {
+  it("returns empty results when requested labels have no vector index", async () => {
+    const { session } = makeStubSession([
+      {
+        match: (q) => q.includes("SHOW INDEXES"),
+        records: [{ name: "vec_knowledge", labelsOrTypes: ["KnowledgeDocument"] }],
+      },
+    ]);
+    const embed = async () => [0.1];
+    const res = await hybrid(session, embed, {
+      query: "x",
+      accountId: "a",
+      limit: 5,
+      labels: ["UnknownLabel"],
+    });
+    expect(res.results).toEqual([]);
+    expect(res.mode).toBe("hybrid");
+  });
+});