Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion backend/src/controllers/query.controller.ts
Original file line number Diff line number Diff line change
@@ -1,23 +1,31 @@
import { getAuth } from "@clerk/express";
import { journeyMatches } from "../services/journeyMatch.service.js";
import type { Request, Response } from "express";
import { understandQuery } from "../processors/query/understandQuery.processor.js";
import { retrieveContext } from "../processors/query/retrieveContext.processor.js";
import { aggregateContext } from "../processors/query/aggregateContext.processor.js";
import { resolveQueryInput } from "../processors/speech/resolveQueryInput.processor.js";

export async function queryController(req: Request, res: Response): Promise<void> {
res.set("Cache-Control", "private, no-store");
res.vary("Authorization");
try {
const query = req.body?.query;
const { query: resolvedQuery, transcribed } = await resolveQueryInput({ query, audioFile: req.file });
const structuredQuery = await understandQuery(resolvedQuery);
const context = await retrieveContext(structuredQuery);
const aggregatedContext = await aggregateContext(resolvedQuery, structuredQuery, context);

const scores = await journeyMatches(getAuth(req).userId, aggregatedContext.timelineFeed.map(journey => journey.username));
const timelineFeed = aggregatedContext.timelineFeed.map(journey => ({
...journey, journeyMatch: scores.get(journey.username) ?? null,
}));
res.json({
query: resolvedQuery,
transcribed,
structuredQuery,
context,
aggregatedContext
aggregatedContext: { ...aggregatedContext, timelineFeed }
});
} catch (error: unknown) {
const message = error instanceof Error ? error.message : String(error);
Expand Down
52 changes: 52 additions & 0 deletions backend/src/services/journeyMatch.scoring.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
export interface MatchGraph {
username: string;
goals: { topics?: string[]; subtopics?: string[] }[];
experiences: { id: string; title?: string; context?: string; challengeFaced?: string; outcome?: string; skills?: string[] }[];
transitions: { from: string; to: string }[];
}
export interface JourneyMatch {
percentage: number;
computedAt: string;
method: "weighted-graph-overlap-v1";
breakdown: { dimension: string; percentage: number; weight: number }[];
}
const stop = new Set("a an and are as at be been by did do for from had has have i in into is it its me my of on or our that the their them then there these they this to was we were what when which who will with you your".split(" "));
const normalize = (value: string) => value.normalize("NFKC").toLowerCase().trim().replace(/\s+/g, " ");
const terms = (text: string) => normalize(text.slice(0, 12000)).split(/[^\p{L}\p{N}+#.]+/u).map(x => x.replace(/^\.+|\.+$/g, "")).filter(x => /[\p{L}\p{N}]/u.test(x) && x.length > 2 && !stop.has(x));
const clean = (values: string[]) => new Set(values.filter(x => typeof x === "string").map(normalize).filter(x => /[\p{L}\p{N}]/u.test(x)));
export function graphFeatures(graph: MatchGraph) {
const experiences = graph.experiences.slice(0, 100);
const skills = clean(experiences.flatMap(e => (e.skills ?? []).slice(0, 30)));
const goals = clean(graph.goals.slice(0, 50).flatMap(g => [...(g.topics ?? []), ...(g.subtopics ?? [])]));
const experienceTerms = new Set(experiences.flatMap(e => terms([e.title, e.context, e.challengeFaced, e.outcome].filter(Boolean).join(" "))));
const nodes = new Map(experiences.map(e => [e.id, [...clean(e.skills ?? [])].slice(0, 12).map(s => "skill:" + s).concat(terms(e.title ?? "").slice(0, 8).map(s => "title:" + s))]));
const transitions = new Set<string>();
for (const edge of graph.transitions.slice(0, 200)) {
for (const from of nodes.get(edge.from) ?? []) {
for (const to of nodes.get(edge.to) ?? []) transitions.add(JSON.stringify([from, to]));
}
}
return { skills, goals, experienceTerms, transitions, meaningful: experiences.length > 0 && (skills.size > 0 || experienceTerms.size > 0) };
}
export function compareJourneys(owner: MatchGraph, other: MatchGraph, computedAt = new Date().toISOString()): JourneyMatch | null {
if (owner.username === other.username) return null;
const a = graphFeatures(owner), b = graphFeatures(other);
if (!a.meaningful || !b.meaningful) return null;
const dimensions = [
["Skills", a.skills, b.skills, 0.40],
["Goal topics", a.goals, b.goals, 0.25],
["Experience terms", a.experienceTerms, b.experienceTerms, 0.20],
["Directed transitions", a.transitions, b.transitions, 0.15],
] as const;
const available = dimensions.filter(([, left, right]) => left.size > 0 && right.size > 0);
const totalWeight = available.reduce((sum, [, , , weight]) => sum + weight, 0);
if (!totalWeight) return null;
let score = 0;
const breakdown = available.map(([dimension, left, right, weight]) => {
const intersection = [...left].filter(x => right.has(x)).length;
const similarity = intersection / new Set([...left, ...right]).size;
score += similarity * weight / totalWeight;
return { dimension, percentage: Math.round(similarity * 100), weight: weight / totalWeight };
});
return { percentage: Math.round(score * 100), computedAt, method: "weighted-graph-overlap-v1", breakdown };
}
89 changes: 89 additions & 0 deletions backend/src/services/journeyMatch.service.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
import type { Session } from "neo4j-driver";
import { compareJourneys, type MatchGraph, type JourneyMatch } from "./journeyMatch.scoring.js";

// Only project non-sensitive matching features; never return owner graph or proofs.
export async function journeyMatches(
clerkId: string | null,
usernames: string[],
createSession: () => Promise<Session> = async () => {
const { getSession } = await import("./neo4j.service.js");
return getSession({ defaultAccessMode: "READ" });
},
): Promise<Map<string, JourneyMatch>> {
const matches = new Map<string, JourneyMatch>();
if (!clerkId || !usernames.length) return matches;
let session: Session | undefined;
try {
session = await createSession();
const result = await session.run(`
MATCH (owner:User {clerkId: $clerkId})
WITH owner
MATCH (u:User)
WHERE u = owner OR u.username IN $usernames
WITH DISTINCT owner, u
LIMIT 21
CALL {
WITH u
MATCH (u)-[:HAS_GOAL]->(g:Goal)
WITH g ORDER BY g.id LIMIT 50
RETURN collect({topics: g.topics, subtopics: g.subtopics}) AS goals
}
CALL {
WITH u
MATCH (u)-[:HAS_EXPERIENCE]->(e:Experience)
WITH e ORDER BY e.startDate DESC, e.id LIMIT 100
RETURN collect(e) AS nodes
}
CALL {
WITH nodes
UNWIND nodes AS e
CALL {
WITH e
MATCH (e)-[:BUILT_SKILL]->(s:Skill)
WHERE s.name IS NOT NULL
WITH DISTINCT s.name AS skill
ORDER BY skill LIMIT 30
RETURN collect(skill) AS skills
}
RETURN collect({
id: e.id, title: e.title, context: e.context,
challengeFaced: e.challengeFaced, outcome: e.outcome,
skills: skills
}) AS experiences
}
CALL {
WITH nodes
UNWIND nodes AS e
MATCH (e)-[:TRANSITION]->(target:Experience)
WHERE target IN nodes
WITH DISTINCT e, target ORDER BY e.id, target.id LIMIT 200
RETURN collect({from: e.id, to: target.id}) AS transitions
}
RETURN u = owner AS isOwner, u.username AS username, goals, experiences, transitions
`, { clerkId, usernames: [...new Set(usernames)].slice(0, 20) }, { timeout: 5000 });
const rows = result.records.map(record => ({
isOwner: record.get("isOwner") as boolean,
graph: {
username: record.get("username") as string,
goals: record.get("goals"),
experiences: record.get("experiences"),
transitions: record.get("transitions"),
} as MatchGraph,
}));
const owner = rows.find(row => row.isOwner)?.graph;
if (!owner) return matches;
const computedAt = new Date().toISOString();
for (const row of rows) {
if (row.isOwner) continue;
const score = compareJourneys(owner, row.graph, computedAt);
if (score) matches.set(row.graph.username, score);
}
return matches;
} catch {
// Fail closed: search remains available, but never manufacture a percentage.
matches.clear();
return matches;
} finally {
try { await session?.close(); } catch { matches.clear(); }
}
}
71 changes: 71 additions & 0 deletions backend/tests/journeyMatch.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import { compareJourneys, graphFeatures, type MatchGraph } from "../src/services/journeyMatch.scoring.js";

const graph = (username: string): MatchGraph => ({
username, goals: [{ topics: ["Engineering"], subtopics: ["Open source"] }],
experiences: [
{ id: "1", title: "Build APIs", context: "Developed authentication", skills: ["TypeScript"] },
{ id: "2", title: "Review patches", context: "Maintained software", skills: ["Testing"] },
],
transitions: [{ from: "1", to: "2" }],
});
test("identical feature graphs have a legitimate 100, not an arbitrary cap", () => {
const match = compareJourneys(graph("a"), graph("b"), "2026-11-15T00:00:00Z");
assert.equal(match?.percentage, 100);
assert.equal(match?.computedAt, "2026-11-15T00:00:00Z");
assert.deepEqual(match?.breakdown.map(x => x.weight), [.4, .25, .2, .15]);
});
test("self comparisons and empty journeys do not produce scores", () => {
assert.equal(compareJourneys(graph("a"), graph("a")), null);
assert.equal(compareJourneys({ ...graph("a"), experiences: [] }, graph("b")), null);
assert.equal(compareJourneys(graph("a"), { ...graph("b"), experiences: [] }), null);
});
test("stopword-only experiences are insufficient even when goal topics match", () => {
assert.equal(compareJourneys({ ...graph("a"), experiences: [{ id: "1", title: "I am the" }] }, graph("b")), null);
});
test("disjoint meaningful graphs score zero", () => {
const b: MatchGraph = { username: "b", goals: [{ topics: ["Medicine"] }],
experiences: [{ id: "3", title: "Surgery clinic", skills: ["Diagnosis"] }], transitions: [] };
assert.equal(compareJourneys(graph("a"), b)?.percentage, 0);
});
test("missing dimensions are excluded and weights renormalized", () => {
const a: MatchGraph = { username: "a", goals: [], experiences: [{ id: "1", skills: ["TypeScript"] }], transitions: [] };
const b = { ...a, username: "b", experiences: [{ id: "2", skills: ["typescript", "Rust"] }] };
const score = compareJourneys(a, b);
assert.equal(score?.percentage, 50);
assert.deepEqual(score?.breakdown, [{ dimension: "Skills", percentage: 50, weight: 1 }]);
});
test("normalization, deduplication, and identity-independent edge features", () => {
const b = graph("b");
b.experiences[0]!.skills = [" TYPESCRIPT ", "typescript"];
b.experiences[0]!.id = "x"; b.experiences[1]!.id = "y";
b.transitions = [{ from: "x", to: "y" }];
assert.equal(compareJourneys(graph("a"), b)?.percentage, 100);
});
test("reversing an edge changes the structural match", () => {
const b = graph("b"); b.transitions = [{ from: "2", to: "1" }];
const result = compareJourneys(graph("a"), b);
assert.equal(result?.breakdown.find(x => x.dimension === "Directed transitions")?.percentage, 0);
assert.equal(result?.percentage, 85);
});
test("weights and percentages remain bounded, symmetric and reproducible", () => {
const a = graph("a"), b = graph("b");
b.experiences[0]!.skills = ["Python"];
const forward = compareJourneys(a, b, "now")!;
assert.deepEqual(compareJourneys(a, b, "now"), forward);
assert.equal(compareJourneys(b, a, "now")?.percentage, forward.percentage);
assert.ok(forward.percentage >= 0 && forward.percentage <= 100);
assert.ok(Math.abs(forward.breakdown.reduce((n, d) => n + d.weight, 0) - 1) < 1e-9);
});
test("graph feature extraction bounds experiences and transition edges", () => {
const a = graph("a");
a.experiences = Array.from({ length: 150 }, (_, i) => ({ id: String(i), skills: ["skill" + i] }));
assert.equal(graphFeatures(a).skills.size, 100);
});
test("punctuation-only experiences and skills do not produce scores", () => {
for (const value of ["...", "+++", "###", " "]) {
const a = { ...graph("a"), experiences: [{ id: "1", title: value, skills: [value] }] };
assert.equal(compareJourneys(a, { ...a, username: "b" }), null);
}
});
79 changes: 79 additions & 0 deletions backend/tests/journeyMatchService.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import type { Session } from "neo4j-driver";
import { journeyMatches } from "../src/services/journeyMatch.service.js";
import type { MatchGraph } from "../src/services/journeyMatch.scoring.js";
const graph = (username: string): MatchGraph => ({
username, goals: [{ topics: ["engineering"] }],
experiences: [{ id: "1", title: "Build APIs", skills: ["TypeScript"] }], transitions: [],
});
function record(isOwner: boolean, data: MatchGraph) {
const fields: Record<string, unknown> = { isOwner, ...data };
return { get: (key: string) => fields[key] };
}
const records = () => [record(true, graph("owner")), record(false, graph("candidate"))];
function fake(rows = records(), failRun = false, failClose = false) {
const state = { closed: 0, calls: [] as { query: string; params: any; options: any }[] };
const session = {
run: async (query: string, params: any, options: any) => {
state.calls.push({ query, params, options });
if (failRun) throw new Error("database down");
return { records: rows };
},
close: async () => { state.closed++; if (failClose) throw new Error("close failed"); },
} as unknown as Session;
return { state, factory: async () => session };
}
test("unauthenticated and empty searches never open a database session", async () => {
const factory = async (): Promise<Session> => { throw new Error("must not run"); };
assert.equal((await journeyMatches(null, ["candidate"], factory)).size, 0);
assert.equal((await journeyMatches("clerk-owner", [], factory)).size, 0);
});
test("owner lookup is parameterized, candidates bounded, and graph stays private", async () => {
const { factory, state } = fake();
const result = await journeyMatches("clerk-owner", Array.from({ length: 40 }, (_, i) => "user" + i), factory);
assert.equal(state.calls[0]!.params.clerkId, "clerk-owner");
assert.equal(state.calls[0]!.params.usernames.length, 20);
assert.equal(state.calls[0]!.options.timeout, 5000);
assert.match(state.calls[0]!.query, /MATCH \(owner:User \{clerkId: \$clerkId\}\)/);
assert.match(state.calls[0]!.query, /ORDER BY skill LIMIT 30/);
assert.equal(result.has("owner"), false);
assert.equal(result.get("candidate")?.percentage, 100);
assert.equal(state.closed, 1);
const serialized = JSON.stringify([...result.values()]);
for (const field of ["clerkId", "goals", "experiences", "transitions", "TypeScript", "proof"]) {
assert.equal(serialized.includes('"' + field + '"'), false);
}
});
test("candidate usernames are deduplicated", async () => {
const { factory, state } = fake();
await journeyMatches("owner", ["candidate", "candidate"], factory);
assert.deepEqual(state.calls[0]!.params.usernames, ["candidate"]);
});
test("missing owner and insufficient target data produce no score", async () => {
assert.equal((await journeyMatches("owner", ["candidate"], fake([record(false, graph("candidate"))]).factory)).size, 0);
const empty = { ...graph("candidate"), experiences: [] };
assert.equal((await journeyMatches("owner", ["candidate"], fake([record(true, graph("owner")), record(false, empty)]).factory)).size, 0);
});
test("session creation, read and close failures never fail the search or return a score", async () => {
assert.equal((await journeyMatches("owner", ["candidate"], async () => { throw new Error("connection"); })).size, 0);
for (const [read, close] of [[true, false], [false, true]]) {
const { factory, state } = fake(records(), read, close);
assert.equal((await journeyMatches("owner", ["candidate"], factory)).size, 0);
assert.equal(state.closed, 1);
}
});
test("a malformed later graph clears earlier partial scores", async () => {
const malformed = { ...graph("bad"), experiences: null } as unknown as MatchGraph;
const { factory } = fake([...records(), record(false, malformed)]);
assert.equal((await journeyMatches("owner", ["candidate", "bad"], factory)).size, 0);
});
test("scores are recomputed from each new database snapshot", async () => {
const a = await journeyMatches("owner", ["candidate"], fake().factory);
const changed = graph("candidate");
changed.goals = [{ topics: ["medicine"] }];
changed.experiences = [{ id: "2", title: "Clinical surgery", skills: ["Diagnosis"] }];
const b = await journeyMatches("owner", ["candidate"], fake([record(true, graph("owner")), record(false, changed)]).factory);
assert.equal(a.get("candidate")?.percentage, 100);
assert.equal(b.get("candidate")?.percentage, 0);
});
49 changes: 49 additions & 0 deletions docs/journey-matching.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Journey match scores

Search results may include `journeyMatch` on each returned journey. The backend uses the
verified Clerk identity, not an identity supplied in the request body. Existing text
and voice query requests already attach the Clerk bearer token.

## Meaning and calculation
Scores compare the signed-in user's saved Neo4j journey with the saved journey of
each search-result owner. Search relevance and journey similarity are different:
search chooses the candidates; this score compares the people’s recorded journeys.

This is deterministic weighted Jaccard feature overlap:
- Skills: 40%
- Goal topics and subtopics: 25%
- Normalized experience text terms: 20%
- Directed transition feature pairs (source skills/title terms to destination features): 15%

A dimension is omitted unless both journeys contain features for it. Remaining
weights are renormalized. Scores are rounded to whole percentages. Zero is valid;
100 means identical compared feature sets, not identical lives. This is not a
probability, semantic embedding model, graph-isomorphism proof, or guarantee of success.

Both journeys need at least one experience with meaningful text or skills.
Self, anonymous, missing-profile, insufficient-data, and database-error cases have
no score. The UI never substitutes a made-up match. Errors do not fail the underlying
search. The response includes a component breakdown and computation timestamp, but
does not expose the signed-in user's raw graph or proofs.

## Freshness and limits
Graphs are read on each search; save changes then search again to refresh.
"Real-time" means request-time calculation, not live background streaming.
Responses use `Cache-Control: private, no-store` and vary on Authorization.

To bound work, scoring reads at most 20 candidate users, 50 goals and 100 latest
experiences per user, 30 ordered skills per experience, and 200 directed edges
within those selected experiences. Query timeout is five seconds. Experience text
is limited to 12,000 characters per experience; transition features use up to 12
skills and eight title terms per endpoint. Therefore larger graphs can be truncated,
and this simple lexical model is not yet empirically calibrated.

## Validation
- `cd backend && npm ci && npm run build && npm test`
- `cd frontend && npm ci && npm run typecheck && npm test && npm run build`
- Regression coverage includes exact/disjoint/partial overlap, directionality,
normalization, punctuation-only input, missing data, weight normalization, privacy,
candidate caps, authentication gating and session/read/close failures.
- Deployment requires both backend and frontend updates. A source branch push is
not confirmation that either live service has been updated. No new secrets or
infrastructure are required.
Loading
Loading