recallnest 2.3.0 → 2.6.0

package/src/__tests__/post-retrieval-filter.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "bun:test";
+
+import { filterByRelevance, type FilterConfig } from "../post-retrieval-filter.js";
+import type { LLMClient } from "../llm-client.js";
+import type { RetrievalResult } from "../retriever.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeResult(id: string, text: string, score: number): RetrievalResult {
+  return {
+    entry: {
+      id,
+      text,
+      vector: [],
+      category: "events",
+      scope: "test",
+      importance: 0.5,
+      timestamp: Date.now(),
+    },
+    score,
+    sources: {},
+  };
+}
+
+function makeMockLLM(response: boolean[] | null, shouldThrow = false): LLMClient {
+  return {
+    chatJson: async () => {
+      if (shouldThrow) throw new Error("LLM failure");
+      return response;
+    },
+  } as unknown as LLMClient;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("filterByRelevance", () => {
+  it("returns empty array for empty results", async () => {
+    const llm = makeMockLLM([]);
+    const out = await filterByRelevance([], "some query", llm);
+    expect(out).toEqual([]);
+  });
+
+  it("returns original results when query is empty", async () => {
+    const results = [makeResult("a", "hello", 0.8)];
+    const llm = makeMockLLM([true]);
+    const out = await filterByRelevance(results, "", llm);
+    expect(out).toEqual(results);
+  });
+
+  it("returns all when LLM marks all as relevant", async () => {
+    const results = [
+      makeResult("a", "TypeScript project setup", 0.9),
+      makeResult("b", "Docker deployment notes", 0.85),
+    ];
+    const llm = makeMockLLM([true, true]);
+    const out = await filterByRelevance(results, "project setup", llm);
+    expect(out).toHaveLength(2);
+    expect(out[0].entry.id).toBe("a");
+    expect(out[1].entry.id).toBe("b");
+  });
+
+  it("filters out items LLM marks as irrelevant", async () => {
+    const results = [
+      makeResult("a", "TypeScript project setup", 0.9),
+      makeResult("b", "Favorite pizza recipe", 0.85),
+      makeResult("c", "Docker deployment notes", 0.8),
+    ];
+    const llm = makeMockLLM([true, false, true]);
+    const out = await filterByRelevance(results, "project deployment", llm);
+    expect(out).toHaveLength(2);
+    expect(out[0].entry.id).toBe("a");
+    expect(out[1].entry.id).toBe("c");
+  });
+
+  it("drops items below minScoreForFilter without LLM call", async () => {
+    const results = [
+      makeResult("a", "High score item", 0.9),
+      makeResult("b", "Low score item", 0.3),
+      makeResult("c", "Very low score", 0.1),
+    ];
+    // LLM only sees 1 item (the one above threshold)
+    const llm = makeMockLLM([true]);
+    const out = await filterByRelevance(results, "test query", llm);
+    expect(out).toHaveLength(1);
+    expect(out[0].entry.id).toBe("a");
+  });
+
+  it("returns all candidates when all are below minScoreForFilter", async () => {
+    const results = [
+      makeResult("a", "Low score A", 0.3),
+      makeResult("b", "Low score B", 0.2),
+    ];
+    const llm = makeMockLLM([]);
+    const out = await filterByRelevance(results, "test query", llm);
+    expect(out).toHaveLength(0);
+  });
+
+  it("truncates to maxItems", async () => {
+    const results = Array.from({ length: 15 }, (_, i) =>
+      makeResult(`item-${i}`, `Memory item ${i}`, 0.9 - i * 0.01),
+    );
+    // LLM receives only 5 items, marks all as relevant
+    const cfg: Partial<FilterConfig> = { maxItems: 5 };
+    const llm = makeMockLLM([true, true, true, true, true]);
+    const out = await filterByRelevance(results, "test query", llm, cfg);
+    expect(out).toHaveLength(5);
+    expect(out[0].entry.id).toBe("item-0");
+    expect(out[4].entry.id).toBe("item-4");
+  });
+
+  it("returns candidates on LLM failure (graceful fallback)", async () => {
+    const results = [
+      makeResult("a", "Important memory", 0.9),
+      makeResult("b", "Another memory", 0.85),
+    ];
+    const llm = makeMockLLM(null, true);
+    const out = await filterByRelevance(results, "test query", llm);
+    // Should return all candidates, not lose data
+    expect(out).toHaveLength(2);
+    expect(out[0].entry.id).toBe("a");
+  });
+
+  it("returns candidates when LLM returns non-array", async () => {
+    const results = [
+      makeResult("a", "Important memory", 0.9),
+    ];
+    const llm = makeMockLLM(null);
+    const out = await filterByRelevance(results, "test query", llm);
+    expect(out).toHaveLength(1);
+  });
+
+  it("uses l0_abstract from metadata when available", async () => {
+    const result = makeResult("a", "Very long raw text that should not be used", 0.9);
+    result.entry.metadata = JSON.stringify({ l0_abstract: "Short summary" });
+    const calls: string[] = [];
+    const llm = {
+      chatJson: async (_sys: string, user: string) => {
+        calls.push(user);
+        return [true];
+      },
+    } as unknown as LLMClient;
+
+    await filterByRelevance([result], "test", llm);
+    expect(calls[0]).toContain("Short summary");
+    expect(calls[0]).not.toContain("Very long raw text");
+  });
+
+  it("handles custom minScoreForFilter", async () => {
+    const results = [
+      makeResult("a", "High", 0.9),
+      makeResult("b", "Medium", 0.6),
+      makeResult("c", "Low", 0.4),
+    ];
+    const cfg: Partial<FilterConfig> = { minScoreForFilter: 0.65 };
+    const llm = makeMockLLM([true]);
+    const out = await filterByRelevance(results, "test", llm, cfg);
+    expect(out).toHaveLength(1);
+    expect(out[0].entry.id).toBe("a");
+  });
+
+  it("handles shorter LLM verdict array than candidates", async () => {
+    const results = [
+      makeResult("a", "Memory A", 0.9),
+      makeResult("b", "Memory B", 0.85),
+      makeResult("c", "Memory C", 0.8),
+    ];
+    // LLM returns fewer verdicts than items
+    const llm = makeMockLLM([true, false]);
+    const out = await filterByRelevance(results, "test", llm);
+    // Only first item passes (index 0 = true, index 1 = false, index 2 = out of bounds)
+    expect(out).toHaveLength(1);
+    expect(out[0].entry.id).toBe("a");
+  });
+});

package/src/__tests__/ppr-traversal.test.ts

@@ -0,0 +1,256 @@
+import { describe, expect, it } from "bun:test";
+import {
+  buildGraph,
+  pprTraverse,
+  pprFromTriples,
+  edgeWeight,
+  DEFAULT_PPR_CONFIG,
+} from "../ppr-traversal.js";
+import type { KGTriple, NeighborhoodResult } from "../kg-store.js";
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function makeTriple(
+  subject: string,
+  predicate: string,
+  object: string,
+  confidence = 0.9,
+  id?: string,
+): KGTriple {
+  return {
+    id: id ?? `${subject}-${predicate}-${object}`,
+    scope: "test",
+    subject,
+    predicate,
+    object,
+    confidence,
+    source_memory_id: `mem-${subject}-${object}`,
+    source_text: `${subject} ${predicate} ${object}`,
+    timestamp: Date.now(),
+  };
+}
+
+function makeNeighborhood(triples: KGTriple[]): NeighborhoodResult[] {
+  const entities = new Set<string>();
+  for (const t of triples) {
+    entities.add(t.subject);
+    entities.add(t.object);
+  }
+  return [...entities].map(entity => ({
+    entity,
+    triples: triples.filter(t => t.subject === entity || t.object === entity),
+    hops: 0,
+  }));
+}
+
+// ============================================================================
+// edgeWeight
+// ============================================================================
+
+describe("edgeWeight", () => {
+  it("returns known weights for standard predicates", () => {
+    expect(edgeWeight("created_by")).toBe(0.95);
+    expect(edgeWeight("uses")).toBe(0.90);
+    expect(edgeWeight("related_to")).toBe(0.50);
+  });
+
+  it("returns default weight for unknown predicates", () => {
+    expect(edgeWeight("unknown_predicate")).toBe(0.60);
+  });
+});
+
+// ============================================================================
+// buildGraph
+// ============================================================================
+
+describe("buildGraph", () => {
+  it("builds undirected graph from neighborhood", () => {
+    const triples = [
+      makeTriple("Alice", "uses", "Python"),
+      makeTriple("Alice", "works_with", "Bob"),
+    ];
+    const neighborhood = makeNeighborhood(triples);
+    const graph = buildGraph(neighborhood);
+
+    expect(graph.nodes.size).toBe(3); // Alice, Python, Bob
+    expect(graph.adj.get("Alice")?.length).toBe(2); // -> Python, -> Bob
+    expect(graph.adj.get("Python")?.length).toBe(1); // -> Alice
+    expect(graph.adj.get("Bob")?.length).toBe(1); // -> Alice
+  });
+
+  it("deduplicates triples by id", () => {
+    const t = makeTriple("Alice", "uses", "Python", 0.9, "same-id");
+    const neighborhood: NeighborhoodResult[] = [
+      { entity: "Alice", triples: [t], hops: 0 },
+      { entity: "Python", triples: [t], hops: 1 },
+    ];
+    const graph = buildGraph(neighborhood);
+
+    // Should only have 1 edge per direction despite appearing in 2 neighborhood entries
+    expect(graph.adj.get("Alice")?.length).toBe(1);
+    expect(graph.adj.get("Python")?.length).toBe(1);
+  });
+
+  it("handles empty neighborhood", () => {
+    const graph = buildGraph([]);
+    expect(graph.nodes.size).toBe(0);
+    expect(graph.adj.size).toBe(0);
+  });
+});
+
+// ============================================================================
+// pprTraverse — convergence
+// ============================================================================
+
+describe("pprTraverse", () => {
+  it("converges on a simple chain A -> B -> C", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("B", "uses", "C"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"]);
+
+    // A should have highest score (it's the seed)
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].entity).toBe("A");
+
+    // B should score higher than C (closer to seed)
+    const bResult = results.find(r => r.entity === "B");
+    const cResult = results.find(r => r.entity === "C");
+    expect(bResult).toBeDefined();
+    expect(cResult).toBeDefined();
+    expect(bResult!.score).toBeGreaterThan(cResult!.score);
+  });
+
+  it("respects hop limits", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("B", "uses", "C"),
+      makeTriple("C", "uses", "D"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"], { hopLimit: 1 });
+
+    // With hopLimit=1, only A and B should be reachable
+    const entities = results.map(r => r.entity);
+    expect(entities).toContain("A");
+    expect(entities).toContain("B");
+    expect(entities).not.toContain("C");
+    expect(entities).not.toContain("D");
+  });
+
+  it("handles multiple seed entities", () => {
+    const triples = [
+      makeTriple("A", "uses", "C"),
+      makeTriple("B", "uses", "C"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A", "B"]);
+
+    // C should be reachable from both seeds
+    const cResult = results.find(r => r.entity === "C");
+    expect(cResult).toBeDefined();
+    expect(cResult!.hops).toBe(1);
+  });
+
+  it("returns empty for empty graph", () => {
+    const graph = buildGraph([]);
+    const results = pprTraverse(graph, ["A"]);
+    expect(results).toEqual([]);
+  });
+
+  it("returns empty when seeds not in graph", () => {
+    const triples = [makeTriple("X", "uses", "Y")];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["NotInGraph"]);
+    expect(results).toEqual([]);
+  });
+
+  it("respects topK limit", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("A", "uses", "C"),
+      makeTriple("A", "uses", "D"),
+      makeTriple("A", "uses", "E"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"], { topK: 2 });
+    expect(results.length).toBe(2);
+  });
+
+  it("computes shortest paths correctly", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("B", "uses", "C"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"]);
+
+    const aResult = results.find(r => r.entity === "A");
+    const bResult = results.find(r => r.entity === "B");
+    const cResult = results.find(r => r.entity === "C");
+
+    expect(aResult?.hops).toBe(0);
+    expect(aResult?.path).toEqual(["A"]);
+    expect(bResult?.hops).toBe(1);
+    expect(bResult?.path).toEqual(["A", "B"]);
+    expect(cResult?.hops).toBe(2);
+    expect(cResult?.path).toEqual(["A", "B", "C"]);
+  });
+
+  it("edge weights affect scores — stronger predicates yield higher scores", () => {
+    // Two separate subgraphs from same seed
+    const triples = [
+      makeTriple("A", "created_by", "B", 1.0), // weight 0.95
+      makeTriple("A", "related_to", "C", 1.0), // weight 0.50
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"]);
+
+    const bResult = results.find(r => r.entity === "B");
+    const cResult = results.find(r => r.entity === "C");
+    expect(bResult).toBeDefined();
+    expect(cResult).toBeDefined();
+    // B should score higher due to stronger edge weight
+    expect(bResult!.score).toBeGreaterThan(cResult!.score);
+  });
+
+  it("all scores sum to approximately 1.0 (probability distribution)", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("B", "uses", "C"),
+      makeTriple("C", "uses", "A"), // cycle
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"], { maxIterations: 50 });
+
+    const totalScore = results.reduce((sum, r) => sum + r.score, 0);
+    // PPR scores approximate a probability distribution
+    expect(totalScore).toBeGreaterThan(0.8);
+    expect(totalScore).toBeLessThan(1.2);
+  });
+});
+
+// ============================================================================
+// pprFromTriples (convenience)
+// ============================================================================
+
+describe("pprFromTriples", () => {
+  it("works with raw triples", () => {
+    const triples = [
+      makeTriple("Alice", "uses", "Python"),
+      makeTriple("Alice", "works_at", "Google"),
+    ];
+    const results = pprFromTriples(triples, ["Alice"]);
+
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].entity).toBe("Alice");
+
+    const entities = results.map(r => r.entity);
+    expect(entities).toContain("Python");
+    expect(entities).toContain("Google");
+  });
+});