Merge remote-tracking branch 'origin/graph/gitgram-serving' into merge/graphrag-serving-2026-10-27

This commit is contained in:
caelum0x 2026-10-27 18:54:33 +03:00
commit 87f50d813e
12 changed files with 1816 additions and 1 deletions

View File

@ -6,6 +6,30 @@ import { analyzeNeedCoverage } from '../services/talentGapAnalysisService';
import prisma from '../utils/prisma';
import { normalizePublicHttpUrl } from '../utils/publicHttpUrl';
import { runTalentMutation, type TalentMutationResult } from '../services/talentMutationService';
import { explainTalentMatch, defaultRagAsk } from '../services/talentGraphRag';
import type { TalentGraphView } from '../services/talentGraphEdges';
/**
* Run a grounded GraphRAG explanation and translate the module's plain errors
* into the API's typed errors. The LLM seam (`ask`) is injected here so the
* controller stays a thin adapter over the testable service; until a real client
* is wired, `defaultRagAsk` surfaces a clear 503 rather than a fake answer.
*/
async function runGroundedExplain(
developerId: string,
query: unknown,
loadView?: (id: string) => Promise<TalentGraphView | null>,
) {
const cleanedQuery = boundedText(query, 'query', 2000);
try {
return await explainTalentMatch(developerId, cleanedQuery, { ask: defaultRagAsk, loadView });
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
if (message.includes('No LLM client')) throw Errors.serviceUnavailable('Talent GraphRAG');
if (message.includes('No talent graph view')) throw Errors.userNotFound(developerId);
throw Errors.badRequest(message);
}
}
const PILOT_STATUSES = ['PLANNED', 'ACTIVE', 'REVIEW', 'COMPLETED', 'CANCELLED'] as const;
type PilotStatus = (typeof PILOT_STATUSES)[number];
@ -93,6 +117,33 @@ export const talentGraphController = {
res.json({ data: graph, meta: { proofSchemaVersion: 1 } });
}),
// GraphRAG serving: grounded "why/how does this developer match?" over the
// authenticated user's own assembled talent graph. Non-breaking — a new route
// that reuses getTalentGraph via the RAG service's default view loader.
explainMine: asyncHandler(async (req: AuthRequest, res: Response) => {
const result = await runGroundedExplain(req.userId!, req.body?.query);
res.setHeader('Cache-Control', 'no-store, private');
res.json({ data: result });
}),
// Grounded explanation over a public developer's privacy-safe dossier. Reuses
// getTalentGraph in publicView mode as the injected view loader.
explainPublic: asyncHandler(async (req: AuthRequest, res: Response) => {
const user = await prisma.user.findUnique({
where: { username: req.params.username },
select: { id: true, isPrivate: true },
});
if (!user || user.isPrivate) throw Errors.userNotFound(req.params.username);
const result = await runGroundedExplain(
user.id,
req.body?.query,
async (id) => (await getTalentGraph(id, { publicView: true })) as TalentGraphView | null,
);
res.setHeader('Cache-Control', 'no-store');
res.json({ data: result });
}),
listOpportunities: asyncHandler(async (req: AuthRequest, res: Response) => {
const opportunities = await prisma.talentOpportunity.findMany({
where: { status: { in: ['OPEN', 'MATCHING', 'PILOT'] } },

View File

@ -28,7 +28,9 @@ function requireMutationOrigin(req: Request, _res: Response, next: NextFunction)
}
router.get('/me', authenticate, talentGraphController.getMine);
router.post('/me/explain', authenticate, requireMutationOrigin, interactionLimiter, talentGraphController.explainMine);
router.get('/public/:username', talentGraphController.getPublic);
router.post('/public/:username/explain', optionalAuth, requireMutationOrigin, interactionLimiter, talentGraphController.explainPublic);
router.get('/opportunities', optionalAuth, talentGraphController.listOpportunities);
router.post('/opportunities', authenticate, requireMutationOrigin, interactionLimiter, talentGraphController.createOpportunity);
router.get('/opportunities/:id/matches', optionalAuth, talentGraphController.getOpportunityMatches);

View File

@ -0,0 +1,133 @@
/**
* Edge extraction from the assembled talent graph.
*
* `getTalentGraph` (talentGraphService.ts) already assembles a developer's
* projects, collaborators and evidence on read, but returns them as nested view
* objects — not as typed, provenanced edges. This module is the extraction step
* of the graph pipeline: it turns that view into flat candidate edges
* (`TalentEdgeInput`) which the ontology's `validateEdges` then vets against
* domain/range before anything is persisted. Extract → validate → serve.
*
* It REUSES rather than rebuilds:
* - the shapes produced by `getTalentGraph` (structural subset below),
* - `canonicalizeSkill` from skillTaxonomyService for skill-node identity,
* - the ontology's `EvidenceSource` union, aligned with `TalentEvidence.kind`.
*
* Pure and dependency-light: takes an already-fetched graph view, does no I/O.
*/
import { canonicalizeSkill } from './skillTaxonomyService';
import { EVIDENCE_SOURCES, type EvidenceSource, type TalentEdgeInput } from './talentGraphOntology';
type EvidenceLevel = 'verified' | 'linked' | 'recorded';
/** Confidence for an edge derived from a project at a given verification tier. */
const CONFIDENCE_BY_LEVEL: Readonly<Record<EvidenceLevel, number>> = {
verified: 1,
linked: 0.75,
recorded: 0.5,
};
const SOURCE_SET: ReadonlySet<string> = new Set(EVIDENCE_SOURCES);
/** Structural subset of one project as returned by `getTalentGraph`. */
export interface GraphProjectView {
readonly id: string;
readonly url: string | null;
readonly topics: readonly string[];
readonly verificationLevel: EvidenceLevel;
readonly lastVerifiedAt: Date;
readonly evidence: readonly { readonly kind: string; readonly sourceUrl: string | null }[];
}
/** Structural subset of one collaborator as returned by `getTalentGraph`. */
export interface GraphCollaboratorView {
readonly id: string;
readonly sharedProjects: readonly { readonly id: string; readonly url: string }[];
}
/** Structural subset of the whole graph view `deriveTalentEdges` consumes. */
export interface TalentGraphView {
readonly profile: { readonly id: string };
readonly projects: readonly GraphProjectView[];
readonly collaborators: readonly GraphCollaboratorView[];
}
/**
* Pick the provenance source for a project-derived edge from its strongest
* evidence record, falling back to `project_record` when the evidence carries no
* recognized kind. Keeps edge provenance traceable to the same evidence the
* dossier shows the user.
*/
function projectSource(project: GraphProjectView): EvidenceSource {
const known = project.evidence.find((item) => SOURCE_SET.has(item.kind));
return (known?.kind as EvidenceSource) ?? 'project_record';
}
/**
* Extract candidate edges from a talent graph view. The output is intentionally
* untrusted `TalentEdgeInput[]`: run it through `validateEdges` to get the vetted,
* de-duplicated edge set. Emits three relation families:
* - developer —contributed_to→ repo (one per project)
* - developer —has_skill→ skill (one per canonicalized project topic)
* - developer —collaborated_with→ developer (one per collaborator, symmetric)
*/
export function deriveTalentEdges(graph: TalentGraphView): TalentEdgeInput[] {
const developerId = graph.profile.id;
const edges: TalentEdgeInput[] = [];
if (!developerId) return edges;
for (const project of graph.projects) {
const source = projectSource(project);
const confidence = CONFIDENCE_BY_LEVEL[project.verificationLevel];
edges.push({
type: 'contributed_to',
from: { id: developerId, type: 'developer' },
to: { id: project.id, type: 'repo' },
provenance: {
source,
observedAt: project.lastVerifiedAt,
confidence,
sourceUrl: project.url,
},
});
const seenSkills = new Set<string>();
for (const topic of project.topics) {
const skill = canonicalizeSkill(topic);
if (!skill || seenSkills.has(skill)) continue;
seenSkills.add(skill);
edges.push({
type: 'has_skill',
from: { id: developerId, type: 'developer' },
to: { id: skill, type: 'skill' },
provenance: {
source,
observedAt: project.lastVerifiedAt,
// A skill inferred from a repo topic is weaker than the contribution
// itself; cap it at the "recorded" tier.
confidence: Math.min(confidence, CONFIDENCE_BY_LEVEL.recorded),
sourceUrl: project.url,
},
});
}
}
for (const collaborator of graph.collaborators) {
if (!collaborator.id || collaborator.id === developerId) continue;
const shared = collaborator.sharedProjects[0];
edges.push({
type: 'collaborated_with',
from: { id: developerId, type: 'developer' },
to: { id: collaborator.id, type: 'developer' },
provenance: {
source: 'github_sync',
observedAt: new Date(),
confidence: CONFIDENCE_BY_LEVEL.recorded,
sourceUrl: shared?.url ?? null,
},
});
}
return edges;
}

View File

@ -0,0 +1,291 @@
/**
* Talent-graph ontology + edge validation.
*
* A graph is a PRODUCT WITH A SCHEMA, not a pile of triples. Before this rung the
* talent graph was assembled implicitly inside `getTalentGraph` — projects,
* collaborators and skills were derived on read, but no typed contract said which
* relationships are *legal*. This module promotes that implicit structure to an
* explicit ontology and adds the single guardrail that removes hallucinated
* structure: every candidate edge is validated against its edge type's
* domain/range, and type-incompatible edges are rejected with a reason.
*
* Entities (node types): developer, repo, org, skill, contribution.
* Relations (edge types): contributed_to, member_of, has_skill, collaborated_with.
*
* Discipline applied here (not recited):
* - Model types BEFORE writing edges (TALENT_ONTOLOGY below).
* - Provenance on EVERY fact: source, observedAt, confidence, sourceUrl.
* - Validate edges against domain/range; reject type-incompatible ones.
* - Incremental & pure: no Prisma, no I/O — unit-testable in isolation, mirroring
* skillTaxonomyService / talentGapAnalysisService.
*
* The evidence `source` union is deliberately aligned with the `kind` field of
* `TalentEvidence` in talentGraphService.ts (plus `profile_interest`) so edges
* derived from that service carry provenance the rest of the graph already speaks.
*/
export const TALENT_NODE_TYPES = ['developer', 'repo', 'org', 'skill', 'contribution'] as const;
export type TalentNodeType = (typeof TALENT_NODE_TYPES)[number];
export const TALENT_EDGE_TYPES = ['contributed_to', 'member_of', 'has_skill', 'collaborated_with'] as const;
export type TalentEdgeType = (typeof TALENT_EDGE_TYPES)[number];
/**
* Provenance sources. Kept in lock-step with `TalentEvidence['kind']` in
* talentGraphService.ts, extended with `profile_interest` for the weakest signal
* (a self-declared interest with no repository/pilot evidence behind it).
*/
export const EVIDENCE_SOURCES = [
'repository_claim',
'github_sync',
'github_activity',
'project_record',
'institutional_pilot',
'profile_interest',
] as const;
export type EvidenceSource = (typeof EVIDENCE_SOURCES)[number];
/**
* Domain/range contract for one edge type. `domain` is the set of legal source
* node types, `range` the set of legal target node types. `symmetric` marks
* undirected relations (collaborated_with) so A→B and B→A collapse to one edge.
* `reflexiveAllowed` guards self-loops (a developer cannot collaborate with self).
*/
export interface EdgeTypeDefinition {
readonly type: TalentEdgeType;
readonly domain: readonly TalentNodeType[];
readonly range: readonly TalentNodeType[];
readonly symmetric: boolean;
readonly reflexiveAllowed: boolean;
}
export const TALENT_ONTOLOGY: Readonly<Record<TalentEdgeType, EdgeTypeDefinition>> = {
contributed_to: {
type: 'contributed_to',
domain: ['developer'],
range: ['repo'],
symmetric: false,
reflexiveAllowed: false,
},
member_of: {
type: 'member_of',
domain: ['developer'],
range: ['org'],
symmetric: false,
reflexiveAllowed: false,
},
has_skill: {
type: 'has_skill',
domain: ['developer'],
range: ['skill'],
symmetric: false,
reflexiveAllowed: false,
},
collaborated_with: {
type: 'collaborated_with',
domain: ['developer'],
range: ['developer'],
symmetric: true,
reflexiveAllowed: false,
},
};
export interface NodeRef {
readonly id: string;
readonly type: TalentNodeType;
}
export interface EdgeProvenance {
readonly source: EvidenceSource;
readonly observedAt: Date;
/** Confidence in (0, 1]. Verified evidence is 1; weaker signals score lower. */
readonly confidence: number;
readonly sourceUrl: string | null;
}
/** An accepted, well-typed edge. `key` is its canonical dedup identity. */
export interface TalentEdge {
readonly type: TalentEdgeType;
readonly from: NodeRef;
readonly to: NodeRef;
readonly provenance: EdgeProvenance;
readonly key: string;
}
/**
* Untrusted edge input, exactly as it might arrive from an extractor, a GitHub
* sync, or an LLM. Every field is loosely typed on purpose — validation is what
* narrows it. Never trust external data.
*/
export interface TalentEdgeInput {
readonly type: string;
readonly from: { readonly id: string; readonly type: string };
readonly to: { readonly id: string; readonly type: string };
readonly provenance: {
readonly source: string;
readonly observedAt: Date | string | number;
readonly confidence: number;
readonly sourceUrl?: string | null;
};
}
export type EdgeRejectionCode =
| 'unknown_edge_type'
| 'missing_from_id'
| 'missing_to_id'
| 'unknown_from_type'
| 'unknown_to_type'
| 'domain_violation'
| 'range_violation'
| 'self_reference'
| 'unknown_source'
| 'invalid_confidence'
| 'invalid_observed_at';
export interface EdgeRejection {
readonly code: EdgeRejectionCode;
readonly message: string;
}
export type EdgeValidation =
| { readonly valid: true; readonly edge: TalentEdge }
| { readonly valid: false; readonly rejections: readonly EdgeRejection[] };
export interface EdgeBatchResult {
readonly accepted: readonly TalentEdge[];
readonly rejected: readonly { readonly input: TalentEdgeInput; readonly rejections: readonly EdgeRejection[] }[];
}
const NODE_TYPE_SET: ReadonlySet<string> = new Set(TALENT_NODE_TYPES);
const SOURCE_SET: ReadonlySet<string> = new Set(EVIDENCE_SOURCES);
function isTalentEdgeType(value: string): value is TalentEdgeType {
return Object.prototype.hasOwnProperty.call(TALENT_ONTOLOGY, value);
}
function coerceDate(value: Date | string | number): Date | null {
const date = value instanceof Date ? value : new Date(value);
return Number.isNaN(date.getTime()) ? null : date;
}
/**
* Canonical identity of an edge. For symmetric edge types the two endpoints are
* sorted so that A—B and B—A share one key; for directed edges the order is kept.
*/
export function edgeKey(type: TalentEdgeType, from: NodeRef, to: NodeRef): string {
const left = `${from.type}:${from.id}`;
const right = `${to.type}:${to.id}`;
const [a, b] = TALENT_ONTOLOGY[type].symmetric && right < left ? [right, left] : [left, right];
return `${type}|${a}|${b}`;
}
/**
* Validate a single untrusted edge against the ontology. Returns the normalized,
* accepted edge, or ALL the reasons it was rejected (validation is comprehensive
* rather than fail-fast so callers can surface every problem at once).
*/
export function validateEdge(input: TalentEdgeInput): EdgeValidation {
const rejections: EdgeRejection[] = [];
const type = typeof input.type === 'string' ? input.type.trim() : '';
const fromId = typeof input.from?.id === 'string' ? input.from.id.trim() : '';
const toId = typeof input.to?.id === 'string' ? input.to.id.trim() : '';
const fromType = typeof input.from?.type === 'string' ? input.from.type.trim() : '';
const toType = typeof input.to?.type === 'string' ? input.to.type.trim() : '';
if (!isTalentEdgeType(type)) {
rejections.push({ code: 'unknown_edge_type', message: `Unknown edge type "${input.type}"` });
}
if (!fromId) rejections.push({ code: 'missing_from_id', message: 'Edge is missing a source node id' });
if (!toId) rejections.push({ code: 'missing_to_id', message: 'Edge is missing a target node id' });
if (!NODE_TYPE_SET.has(fromType)) {
rejections.push({ code: 'unknown_from_type', message: `Unknown source node type "${fromType}"` });
}
if (!NODE_TYPE_SET.has(toType)) {
rejections.push({ code: 'unknown_to_type', message: `Unknown target node type "${toType}"` });
}
// Domain/range only make sense once the edge type is known.
if (isTalentEdgeType(type)) {
const def = TALENT_ONTOLOGY[type];
if (NODE_TYPE_SET.has(fromType) && !def.domain.includes(fromType as TalentNodeType)) {
rejections.push({
code: 'domain_violation',
message: `${type} requires a source of type [${def.domain.join(', ')}], got "${fromType}"`,
});
}
if (NODE_TYPE_SET.has(toType) && !def.range.includes(toType as TalentNodeType)) {
rejections.push({
code: 'range_violation',
message: `${type} requires a target of type [${def.range.join(', ')}], got "${toType}"`,
});
}
if (!def.reflexiveAllowed && fromId && toId && fromType === toType && fromId === toId) {
rejections.push({
code: 'self_reference',
message: `${type} cannot connect a node to itself (${fromType}:${fromId})`,
});
}
}
const source = typeof input.provenance?.source === 'string' ? input.provenance.source.trim() : '';
if (!SOURCE_SET.has(source)) {
rejections.push({ code: 'unknown_source', message: `Unknown provenance source "${source}"` });
}
const confidence = input.provenance?.confidence;
if (typeof confidence !== 'number' || !Number.isFinite(confidence) || confidence <= 0 || confidence > 1) {
rejections.push({ code: 'invalid_confidence', message: 'Provenance confidence must be a number in (0, 1]' });
}
const observedAt = input.provenance?.observedAt === undefined ? null : coerceDate(input.provenance.observedAt);
if (!observedAt) {
rejections.push({ code: 'invalid_observed_at', message: 'Provenance observedAt must be a valid date' });
}
if (rejections.length > 0) return { valid: false, rejections };
const edgeType = type as TalentEdgeType;
const from: NodeRef = { id: fromId, type: fromType as TalentNodeType };
const to: NodeRef = { id: toId, type: toType as TalentNodeType };
const provenance: EdgeProvenance = {
source: source as EvidenceSource,
observedAt: observedAt as Date,
confidence: confidence as number,
sourceUrl: input.provenance.sourceUrl ?? null,
};
return {
valid: true,
edge: { type: edgeType, from, to, provenance, key: edgeKey(edgeType, from, to) },
};
}
/**
* Validate a batch of untrusted edges, partitioning into accepted and rejected.
* Accepted edges are de-duplicated by canonical `key` (first writer wins); when a
* duplicate carries higher confidence the stronger provenance is kept.
*
* This is the "single validation step that removes hallucinated structure": feed
* it raw extraction output, persist only `accepted`, and inspect `rejected` to
* see exactly which type-incompatible triples were dropped and why.
*/
export function validateEdges(inputs: readonly TalentEdgeInput[]): EdgeBatchResult {
const acceptedByKey = new Map<string, TalentEdge>();
const rejected: EdgeBatchResult['rejected'] = [];
for (const input of inputs) {
const result = validateEdge(input);
if (!result.valid) {
(rejected as { input: TalentEdgeInput; rejections: readonly EdgeRejection[] }[]).push({
input,
rejections: result.rejections,
});
continue;
}
const existing = acceptedByKey.get(result.edge.key);
if (!existing || result.edge.provenance.confidence > existing.provenance.confidence) {
acceptedByKey.set(result.edge.key, result.edge);
}
}
return { accepted: Array.from(acceptedByKey.values()), rejected };
}

View File

@ -0,0 +1,212 @@
/**
* Talent GraphRAG serving layer — grounded "why does this developer match?" query.
*
* This is the top of the GraphRAG vertical slice. It composes the pieces that
* were each built to be pure and testable:
* load view → buildTalentSubgraph (retrieve) → serializeTalentSubgraphForLLM
* → ask the LLM under a grounding contract → enforce grounding on the reply.
*
* Grounding is enforced on OUR side, not trusted from the model: the LLM is asked
* to cite edges by their canonical key, and we intersect its citations with the
* keys that actually exist in the retrieved subgraph. Any cited key that is not
* in the subgraph is a hallucinated reference and is dropped; the returned
* `evidence` therefore only ever references facts that were truly retrieved.
*
* The LLM call is injected via `deps.ask` so the retrieval + serialization +
* grounding logic is fully unit-testable without a live API. `deps.loadView` is
* likewise injectable; a default wires it to the existing `getTalentGraph`
* dossier assembler, keeping the seam while reusing the read path.
*/
import logger from '../utils/logger';
import { getTalentGraph } from './talentGraphService';
import type { TalentGraphView } from './talentGraphEdges';
import type {
EvidenceSource,
NodeRef,
TalentEdge,
TalentEdgeType,
} from './talentGraphOntology';
import {
buildTalentSubgraph,
type TalentSubgraph,
} from './talentSubgraphRetrieval';
import { serializeTalentSubgraphForLLM } from './talentSubgraphSerializer';
import {
buildRagPrompt,
parseRagResponse,
type RagAsk,
} from './talentGraphRagPrompt';
const DEFAULT_DEPTH = 2;
const MAX_QUERY_LENGTH = 2000;
/** A single cited fact returned to the caller — a projection of a subgraph edge. */
export interface EdgeReference {
readonly key: string;
readonly type: TalentEdgeType;
readonly from: NodeRef;
readonly to: NodeRef;
readonly source: EvidenceSource;
readonly confidence: number;
readonly observedAt: string;
readonly sourceUrl: string | null;
}
/** The grounded answer plus the evidence it is allowed to stand on. */
export interface ExplainTalentMatchResult {
readonly developerId: string;
readonly query: string;
readonly answer: string;
readonly evidence: readonly EdgeReference[];
readonly retrieval: {
readonly depth: number;
readonly nodeCount: number;
readonly edgeCount: number;
};
/**
* Keys the model cited that were NOT in the subgraph. Always empty in a
* well-behaved run; surfaced (not hidden) so grounding violations are
* observable rather than silently absorbed.
*/
readonly droppedCitations: readonly string[];
}
/** Injectable dependencies for {@link explainTalentMatch}. */
export interface ExplainTalentMatchDeps {
/** The LLM seam. Required — there is no implicit network call. */
readonly ask: RagAsk;
/** How to obtain the assembled view. Defaults to {@link getTalentGraph}. */
readonly loadView?: (developerId: string) => Promise<TalentGraphView | null>;
/** k-hop retrieval depth. Defaults to {@link DEFAULT_DEPTH}. */
readonly depth?: number;
}
/** Default view loader: reuse the existing dossier assembler on the read path. */
async function defaultLoadView(developerId: string): Promise<TalentGraphView | null> {
return (await getTalentGraph(developerId)) as TalentGraphView | null;
}
function toEdgeReference(edge: TalentEdge): EdgeReference {
return {
key: edge.key,
type: edge.type,
from: edge.from,
to: edge.to,
source: edge.provenance.source,
confidence: edge.provenance.confidence,
observedAt: edge.provenance.observedAt.toISOString(),
sourceUrl: edge.provenance.sourceUrl,
};
}
/**
* Enforce grounding: partition the model's cited keys into those present in the
* subgraph (kept as evidence, de-duplicated, in subgraph order) and those that
* are not (dropped as hallucinations). This is the guardrail that guarantees the
* returned evidence only references retrieved facts.
*/
function groundCitations(
subgraph: TalentSubgraph,
citedKeys: readonly string[],
): { evidence: EdgeReference[]; dropped: string[] } {
const edgesByKey = new Map(subgraph.edges.map((edge) => [edge.key, edge]));
const seen = new Set<string>();
const dropped: string[] = [];
for (const key of citedKeys) {
if (!edgesByKey.has(key)) {
if (!dropped.includes(key)) dropped.push(key);
}
}
// Preserve deterministic subgraph edge order for cited, in-subgraph keys.
const citedSet = new Set(citedKeys);
const evidence: EdgeReference[] = [];
for (const edge of subgraph.edges) {
if (citedSet.has(edge.key) && !seen.has(edge.key)) {
seen.add(edge.key);
evidence.push(toEdgeReference(edge));
}
}
return { evidence, dropped };
}
function normalizeQuery(query: string): string {
const cleaned = typeof query === 'string' ? query.trim() : '';
if (!cleaned) throw new Error('A non-empty query is required to explain a talent match');
if (cleaned.length > MAX_QUERY_LENGTH) {
throw new Error(`Query must be at most ${MAX_QUERY_LENGTH} characters`);
}
return cleaned;
}
/**
* Explain, grounded in the retrieved subgraph, why/how a developer matches a
* query. Retrieves the k-hop neighborhood, serializes it, asks the injected LLM
* under the grounding contract, then enforces that the returned evidence only
* references retrieved edges.
*
* @throws if inputs are invalid, the developer has no assembled view, or the LLM
* reply cannot be parsed. Errors are explicit — never silently swallowed.
*/
export async function explainTalentMatch(
rootDeveloperId: string,
query: string,
deps: ExplainTalentMatchDeps,
): Promise<ExplainTalentMatchResult> {
const developerId = typeof rootDeveloperId === 'string' ? rootDeveloperId.trim() : '';
if (!developerId) throw new Error('explainTalentMatch requires a non-empty rootDeveloperId');
if (!deps || typeof deps.ask !== 'function') {
throw new Error('explainTalentMatch requires deps.ask (the injectable LLM call)');
}
const cleanedQuery = normalizeQuery(query);
const depth = deps.depth ?? DEFAULT_DEPTH;
const loadView = deps.loadView ?? defaultLoadView;
const view = await loadView(developerId);
if (!view) throw new Error(`No talent graph view found for developer "${developerId}"`);
const subgraph = buildTalentSubgraph(view, developerId, depth);
const context = serializeTalentSubgraphForLLM(subgraph);
const prompt = buildRagPrompt(cleanedQuery, context);
const raw = await deps.ask(prompt);
const parsed = parseRagResponse(raw);
const { evidence, dropped } = groundCitations(subgraph, parsed.citedEdgeKeys);
if (dropped.length > 0) {
logger.warn('talent-graphrag dropped hallucinated citations not present in the subgraph', {
event: 'talent_graph.rag.hallucinated_citation',
developerId,
droppedCount: dropped.length,
dropped,
});
}
return {
developerId,
query: cleanedQuery,
answer: parsed.answer,
evidence,
retrieval: {
depth: subgraph.depth,
nodeCount: subgraph.nodes.length,
edgeCount: subgraph.edges.length,
},
droppedCitations: dropped,
};
}
/**
* Default LLM seam. There is no LLM client wired into gitgram-ai yet, so this
* default fails loudly rather than pretending to answer — production wiring
* should replace it with a real client (e.g. via `deps.ask`) while keeping this
* exact signature. Kept as a named export so the controller can depend on the
* seam and tests can substitute their own `ask`.
*/
export const defaultRagAsk: RagAsk = async () => {
throw new Error(
'No LLM client is configured for talent GraphRAG. Provide deps.ask to explainTalentMatch.',
);
};

View File

@ -0,0 +1,97 @@
/**
* Grounded prompt construction + response parsing for talent GraphRAG.
*
* This file owns the *grounding contract* between our retrieval layer and the
* LLM: the system instruction that forbids outside knowledge, the user prompt
* that carries the serialized subgraph and the query, and the strict parser that
* turns the model's reply back into a typed answer + cited edge keys. Keeping the
* contract in one small module makes the grounding rules auditable and lets the
* parser be unit-tested without any live API.
*/
/** The instruction that pins the model to the retrieved subgraph only. */
export const GROUNDING_SYSTEM_PROMPT = [
'You are a talent-graph analyst. You answer ONLY using the facts in the',
'provided subgraph context. Never use outside knowledge, and never invent',
'developers, repositories, skills, organizations, or relationships that are',
'not present in the EDGES list.',
'',
'Every claim in your answer must be supported by one or more edges, cited by',
'their [key]. If the subgraph does not contain enough information to answer,',
'say so plainly and cite no edges.',
'',
'Respond with a single JSON object and nothing else, of the exact shape:',
'{"answer": string, "citedEdgeKeys": string[]}',
'where each citedEdgeKeys entry is an edge [key] copied verbatim from EDGES.',
].join('\n');
/** A request handed to an injected LLM. `context` is the serialized subgraph. */
export interface RagAskRequest {
readonly system: string;
readonly query: string;
readonly context: string;
}
/** The injectable LLM seam: raw prompt in, raw model text out. */
export type RagAsk = (request: RagAskRequest) => Promise<string>;
/** Parsed, still-untrusted model reply before grounding is enforced. */
export interface ParsedRagResponse {
readonly answer: string;
readonly citedEdgeKeys: readonly string[];
}
/**
* Build the user-facing prompt body. The query is included verbatim but clearly
* fenced from the context so a hostile query cannot masquerade as graph facts.
*/
export function buildRagPrompt(query: string, context: string): RagAskRequest {
const cleanedQuery = typeof query === 'string' ? query.trim() : '';
if (!cleanedQuery) throw new Error('A non-empty query is required to explain a talent match');
return {
system: GROUNDING_SYSTEM_PROMPT,
query: cleanedQuery,
context,
};
}
/**
* Parse a raw LLM reply into a typed response. Tolerant of a leading/trailing
* code fence but otherwise strict: the payload must be a JSON object with a
* string `answer` and an array of string `citedEdgeKeys`. Anything else is a
* hard error — we never guess at a malformed model reply. Grounding (checking the
* cited keys actually exist in the subgraph) happens in the caller.
*/
export function parseRagResponse(raw: string): ParsedRagResponse {
if (typeof raw !== 'string' || raw.trim() === '') {
throw new Error('LLM returned an empty response');
}
const stripped = raw
.trim()
.replace(/^```(?:json)?\s*/i, '')
.replace(/\s*```$/i, '')
.trim();
let parsed: unknown;
try {
parsed = JSON.parse(stripped);
} catch {
throw new Error('LLM response was not valid JSON');
}
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
throw new Error('LLM response must be a JSON object');
}
const record = parsed as Record<string, unknown>;
if (typeof record.answer !== 'string') {
throw new Error('LLM response is missing a string "answer"');
}
if (!Array.isArray(record.citedEdgeKeys) || record.citedEdgeKeys.some((key) => typeof key !== 'string')) {
throw new Error('LLM response "citedEdgeKeys" must be an array of strings');
}
return {
answer: record.answer.trim(),
citedEdgeKeys: record.citedEdgeKeys as string[],
};
}

View File

@ -1,6 +1,9 @@
import prisma from '../utils/prisma';
import logger from '../utils/logger';
import { normalizePublicHttpUrl } from '../utils/publicHttpUrl';
import { canonicalizeSkill, canonicalizeSkills, expandSkillQueryTokens } from './skillTaxonomyService';
import { deriveTalentEdges, type TalentGraphView } from './talentGraphEdges';
import { validateEdges, type EdgeBatchResult } from './talentGraphOntology';
import type { PrismaClient } from '@prisma/client';
type EvidenceLevel = 'verified' | 'linked' | 'recorded';
@ -56,6 +59,38 @@ function projectKey(owner: string | null, name: string, fullName: string | null)
return (fullName || (owner ? `${owner}/${name}` : name)).toLowerCase();
}
/**
* Non-breaking validation gate for the assembled talent graph.
*
* `getTalentGraph` assembles a read-only dossier; it does not persist edges. This
* gate realizes the ontology guardrail on that read path: it derives typed,
* provenanced candidate edges from the assembled view and vets them with
* `validateEdges` (domain/range, provenance, symmetric dedup). It is WARN-ONLY —
* it never mutates, drops, or reshapes the response. Ontology-invalid
* ("hallucinated") structure is surfaced as a single structured warning (reason
* codes + endpoint types) so violations are observable via logs/metrics without
* changing any success-path output existing consumers depend on. Returns the
* batch result so callers and tests can inspect what the gate saw.
*/
export function auditTalentGraphEdges(view: TalentGraphView): EdgeBatchResult {
const result = validateEdges(deriveTalentEdges(view));
if (result.rejected.length > 0) {
logger.warn('talent-graph edge validation rejected ontology-invalid edges', {
event: 'talent_graph.edge_validation.rejected',
developerId: view.profile.id,
acceptedCount: result.accepted.length,
rejectedCount: result.rejected.length,
rejections: result.rejected.map((entry) => ({
edgeType: entry.input.type,
fromType: entry.input.from?.type,
toType: entry.input.to?.type,
codes: entry.rejections.map((rejection) => rejection.code),
})),
});
}
return result;
}
export async function getTalentGraph(userId: string, options: { publicView?: boolean } = {}) {
const [user, syncedProjects, managedRepositories] = await Promise.all([
prisma.user.findUnique({
@ -356,7 +391,7 @@ export async function getTalentGraph(userId: string, options: { publicView?: boo
(a, b) => b.sharedProjects.length - a.sharedProjects.length,
);
return {
const graph = {
profile: {
id: user.id,
username: user.username,
@ -377,6 +412,21 @@ export async function getTalentGraph(userId: string, options: { publicView?: boo
collaborators: talentCollaborators,
generatedAt: new Date(),
};
// Realize the ontology guardrail on the read path. Warn-only and defensive:
// the gate observes ontology-invalid structure but never changes `graph`, and a
// failure here must never break a dossier read.
try {
auditTalentGraphEdges(graph);
} catch (error) {
logger.error('talent-graph edge validation gate failed', {
event: 'talent_graph.edge_validation.error',
developerId: user.id,
error: error instanceof Error ? error.message : String(error),
});
}
return graph;
}
export async function findTalentMatches(requiredSkills: string[], limit = 12, db: TalentMatchDb = prisma) {

View File

@ -0,0 +1,177 @@
/**
* k-hop subgraph retrieval for the talent GraphRAG serving layer.
*
* GraphRAG serves *structure*, not prose: before an LLM can ground an answer we
* must first retrieve the bounded neighborhood of facts that are relevant to a
* developer. This module is the retrieval half. It REUSES the existing graph
* pipeline rather than rebuilding it:
* assembled view → deriveTalentEdges → validateEdges → k-hop subgraph
* so every fact that reaches the LLM has already been vetted against the
* ontology's domain/range and carries provenance (source, confidence, observedAt).
*
* Two entry points:
* - `buildSubgraphFromEdges` — the pure BFS core over an already-validated edge
* set. Traversal is undirected (a neighborhood, not a reachability query) so a
* developer's repos, skills, orgs and collaborators are all gathered, but never
* beyond `depth` hops. This is the unit-testable heart of retrieval.
* - `buildTalentSubgraph` — the view-based wrapper that runs the extract→validate
* pipeline before delegating to the BFS core.
*
* Pure and dependency-light: no Prisma, no I/O, immutable output.
*/
import {
deriveTalentEdges,
type TalentGraphView,
} from './talentGraphEdges';
import {
validateEdges,
type NodeRef,
type TalentEdge,
type TalentNodeType,
} from './talentGraphOntology';
/** A node that appears in a retrieved subgraph, tagged with its BFS distance. */
export interface SubgraphNode {
readonly id: string;
readonly type: TalentNodeType;
/** Hops from the root developer. The root itself is 0. */
readonly distance: number;
}
/** A bounded, validated neighborhood of the talent graph around one developer. */
export interface TalentSubgraph {
readonly root: NodeRef;
readonly depth: number;
readonly nodes: readonly SubgraphNode[];
readonly edges: readonly TalentEdge[];
}
const MAX_DEPTH = 6;
function nodeKey(type: TalentNodeType, id: string): string {
return `${type}:${id}`;
}
/**
* Validate the requested traversal depth at the boundary. Retrieval must always
* terminate, so depth is a non-negative integer capped at MAX_DEPTH. Never trust
* a caller-supplied bound.
*/
function normalizeDepth(depth: number): number {
if (typeof depth !== 'number' || !Number.isInteger(depth) || depth < 0) {
throw new RangeError('Subgraph depth must be a non-negative integer');
}
return Math.min(depth, MAX_DEPTH);
}
/**
* Retrieve the k-hop neighborhood around `root` from a set of already-validated
* edges. Undirected BFS assigns each reachable node its shortest hop distance;
* nodes farther than `depth` are excluded, and an edge is kept only when BOTH of
* its endpoints made it into the node set. This is what stops "wrong hops":
* facts hanging off a node one step beyond the frontier never enter the context.
*
* The root is always present (distance 0) even when it has no edges, so callers
* always get a well-formed subgraph. Termination is guaranteed: each node is
* enqueued at most once.
*/
export function buildSubgraphFromEdges(
edges: readonly TalentEdge[],
root: NodeRef,
depth: number,
): TalentSubgraph {
if (!root || typeof root.id !== 'string' || root.id.trim() === '') {
throw new Error('Subgraph retrieval requires a root node with a non-empty id');
}
const maxDepth = normalizeDepth(depth);
const rootRef: NodeRef = { id: root.id, type: root.type };
// Adjacency list over an undirected view of the (directed) edge set.
const adjacency = new Map<string, { neighbor: NodeRef }[]>();
const addAdjacency = (from: NodeRef, to: NodeRef) => {
const key = nodeKey(from.type, from.id);
const list = adjacency.get(key) ?? [];
list.push({ neighbor: to });
adjacency.set(key, list);
};
for (const edge of edges) {
addAdjacency(edge.from, edge.to);
addAdjacency(edge.to, edge.from);
}
// BFS from the root, recording the shortest distance to every node.
const distances = new Map<string, SubgraphNode>();
const rootKey = nodeKey(rootRef.type, rootRef.id);
distances.set(rootKey, { id: rootRef.id, type: rootRef.type, distance: 0 });
let frontier: NodeRef[] = [rootRef];
for (let hop = 1; hop <= maxDepth && frontier.length > 0; hop += 1) {
const next: NodeRef[] = [];
for (const node of frontier) {
for (const { neighbor } of adjacency.get(nodeKey(node.type, node.id)) ?? []) {
const key = nodeKey(neighbor.type, neighbor.id);
if (distances.has(key)) continue;
distances.set(key, { id: neighbor.id, type: neighbor.type, distance: hop });
next.push(neighbor);
}
}
frontier = next;
}
// Keep only edges whose BOTH endpoints are inside the retrieved node set.
const included = (node: NodeRef) => distances.has(nodeKey(node.type, node.id));
const keptEdges = edges.filter((edge) => included(edge.from) && included(edge.to));
const nodes = Array.from(distances.values());
return {
root: rootRef,
depth: maxDepth,
nodes: sortNodes(nodes),
edges: sortEdges(keptEdges),
};
}
/**
* View-based retrieval entry point. Runs the existing extract→validate pipeline
* (`deriveTalentEdges` + `validateEdges`) so only ontology-valid, provenance-
* carrying edges are traversed, then returns the k-hop subgraph around the given
* developer. `rootDeveloperId` is validated against the view's own profile to keep
* the seam honest — you can only build a subgraph for the developer the view
* describes.
*/
export function buildTalentSubgraph(
view: TalentGraphView,
rootDeveloperId: string,
depth: number,
): TalentSubgraph {
if (!view || typeof view !== 'object') {
throw new Error('buildTalentSubgraph requires an assembled talent graph view');
}
const developerId = typeof rootDeveloperId === 'string' ? rootDeveloperId.trim() : '';
if (!developerId) {
throw new Error('buildTalentSubgraph requires a non-empty rootDeveloperId');
}
if (view.profile?.id !== developerId) {
throw new Error(
`rootDeveloperId "${developerId}" does not match the view profile "${view.profile?.id ?? ''}"`,
);
}
const { accepted } = validateEdges(deriveTalentEdges(view));
return buildSubgraphFromEdges(accepted, { id: developerId, type: 'developer' }, depth);
}
/** Deterministic node ordering: by distance, then type, then id. */
function sortNodes(nodes: readonly SubgraphNode[]): SubgraphNode[] {
return [...nodes].sort(
(a, b) =>
a.distance - b.distance ||
a.type.localeCompare(b.type) ||
a.id.localeCompare(b.id),
);
}
/** Deterministic edge ordering by canonical key. */
function sortEdges(edges: readonly TalentEdge[]): TalentEdge[] {
return [...edges].sort((a, b) => a.key.localeCompare(b.key));
}

View File

@ -0,0 +1,101 @@
/**
* Deterministic serialization of a retrieved talent subgraph into LLM-ready
* context.
*
* The grounding contract of GraphRAG is only as strong as the context window is
* faithful: the LLM may answer ONLY from what we hand it, so the serialized block
* must (a) be deterministic — identical subgraph in, byte-identical text out, so
* prompts are cacheable and tests are stable — and (b) expose the citation handle
* (each edge's canonical `key`) the model is required to cite, alongside the
* provenance (source, confidence, observedAt) that makes each fact auditable.
*
* Nodes are grouped by ontology type in a fixed order; edges are rendered as
* subject–predicate–object triples with their provenance and citation key. No
* prose, no I/O — pure formatting.
*/
import {
TALENT_NODE_TYPES,
type TalentEdge,
type TalentNodeType,
} from './talentGraphOntology';
import type { SubgraphNode, TalentSubgraph } from './talentSubgraphRetrieval';
/** Human-facing labels for each node type, kept stable for prompt determinism. */
const NODE_TYPE_LABELS: Readonly<Record<TalentNodeType, string>> = {
developer: 'Developers',
repo: 'Repositories',
org: 'Organizations',
skill: 'Skills',
contribution: 'Contributions',
};
/** Verb phrasing for each edge type so triples read naturally but stay stable. */
const EDGE_TYPE_PHRASES: Readonly<Record<string, string>> = {
contributed_to: 'contributed to',
member_of: 'is a member of',
has_skill: 'has skill',
collaborated_with: 'collaborated with',
};
function formatConfidence(value: number): string {
return value.toFixed(2);
}
function formatNodeLine(node: SubgraphNode): string {
return ` - ${node.type}:${node.id} (depth ${node.distance})`;
}
function formatEdgeLine(edge: TalentEdge): string {
const phrase = EDGE_TYPE_PHRASES[edge.type] ?? edge.type;
const provenance =
`source=${edge.provenance.source}` +
`, confidence=${formatConfidence(edge.provenance.confidence)}` +
`, observedAt=${edge.provenance.observedAt.toISOString()}` +
`, sourceUrl=${edge.provenance.sourceUrl ?? 'none'}`;
return (
` - [${edge.key}] ${edge.from.type}:${edge.from.id} ` +
`${phrase} ${edge.to.type}:${edge.to.id} {${provenance}}`
);
}
/**
* Render the subgraph as a deterministic text block for the LLM context window.
* Structure:
* ROOT: <type>:<id> (depth <k>)
* NODES
* <grouped by type, sorted>
* EDGES (facts — cite by [key])
* <sorted by key, one triple per line with provenance>
*
* The input is assumed already ordered by the retrieval layer; grouping here is a
* stable re-projection, so the output is a pure function of the subgraph.
*/
export function serializeTalentSubgraphForLLM(subgraph: TalentSubgraph): string {
if (!subgraph || typeof subgraph !== 'object') {
throw new Error('serializeTalentSubgraphForLLM requires a subgraph');
}
const lines: string[] = [];
lines.push(`ROOT: ${subgraph.root.type}:${subgraph.root.id} (depth ${subgraph.depth})`);
lines.push('NODES');
if (subgraph.nodes.length === 0) {
lines.push(' (none)');
} else {
for (const type of TALENT_NODE_TYPES) {
const ofType = subgraph.nodes.filter((node) => node.type === type);
if (ofType.length === 0) continue;
lines.push(` ${NODE_TYPE_LABELS[type]}:`);
for (const node of ofType) lines.push(` ${formatNodeLine(node)}`);
}
}
lines.push('EDGES (facts — cite by [key]):');
if (subgraph.edges.length === 0) {
lines.push(' (none)');
} else {
for (const edge of subgraph.edges) lines.push(formatEdgeLine(edge));
}
return lines.join('\n');
}

View File

@ -0,0 +1,171 @@
/**
* Tests for the talent-graph validation GATE (not just the ontology library).
*
* The ontology unit tests (talentGraphOntology.test.ts) prove validateEdge /
* validateEdges are correct in isolation. These tests prove that the gate is
* actually WIRED into the service read path — `getTalentGraph` runs the assembled
* graph through `auditTalentGraphEdges` — and that it is non-breaking:
* - valid edges pass through with no warning and the response shape is unchanged,
* - an ontology-invalid edge (here: unparseable provenance timestamp from a
* corrupt DB row) triggers exactly one structured warning while the dossier is
* still returned intact (warn-only, nothing dropped, nothing reshaped).
*
* Prisma and the logger are mocked globally by tests/setup.ts.
*/
import { auditTalentGraphEdges, getTalentGraph } from '../../src/services/talentGraphService';
import type { TalentGraphView } from '../../src/services/talentGraphEdges';
import { mockPrisma } from '../setup';
import logger from '../../src/utils/logger';
const warn = logger.warn as jest.Mock;
function makeView(overrides: Partial<TalentGraphView> = {}): TalentGraphView {
return {
profile: { id: 'dev-1' },
projects: [
{
id: 'repo-1',
url: 'https://github.com/acme/repo-1',
topics: ['typescript'],
verificationLevel: 'verified',
lastVerifiedAt: new Date('2026-01-01T00:00:00Z'),
evidence: [{ kind: 'repository_claim', sourceUrl: 'https://github.com/acme/repo-1' }],
},
],
collaborators: [],
...overrides,
};
}
describe('auditTalentGraphEdges (the gate)', () => {
it('accepts well-typed edges from a clean view and emits no warning', () => {
const result = auditTalentGraphEdges(makeView());
expect(result.rejected).toHaveLength(0);
// developer→repo contribution + developer→skill has_skill.
expect(result.accepted.length).toBeGreaterThanOrEqual(2);
expect(warn).not.toHaveBeenCalled();
});
it('rejects an ontology-invalid edge and emits one structured warning (warn-only)', () => {
// A corrupt DB timestamp flows into edge provenance as an unparseable date.
const corrupt = makeView({
projects: [
{
id: 'repo-1',
url: 'https://github.com/acme/repo-1',
topics: [],
verificationLevel: 'verified',
lastVerifiedAt: new Date('not-a-real-date'),
evidence: [{ kind: 'repository_claim', sourceUrl: null }],
},
],
});
const result = auditTalentGraphEdges(corrupt);
expect(result.rejected.length).toBeGreaterThan(0);
expect(result.rejected[0].rejections.map((r) => r.code)).toContain('invalid_observed_at');
expect(warn).toHaveBeenCalledTimes(1);
const [message, meta] = warn.mock.calls[0];
expect(message).toMatch(/edge validation rejected/i);
expect(meta).toMatchObject({
event: 'talent_graph.edge_validation.rejected',
developerId: 'dev-1',
rejectedCount: result.rejected.length,
});
expect(meta.rejections[0].codes).toContain('invalid_observed_at');
});
});
describe('getTalentGraph invokes the gate on the real read path', () => {
const userId = 'dev-real-1';
function seedUser() {
mockPrisma.user.__rows = [
{
id: userId,
username: 'dev-real',
displayName: 'Dev Real',
avatar: null,
avatarUrl: null,
bio: null,
githubId: null,
githubUsername: null,
createdAt: new Date('2025-01-01T00:00:00Z'),
isPrivate: false,
},
];
// Unused-but-queried tables must resolve to empty sets.
mockPrisma.repositoryManager.__rows = [];
mockPrisma.repositoryActivity.__rows = [];
// The talent* models are not part of the shared prisma mock; stub the reads
// getTalentGraph performs so the assembly runs without touching a real DB.
mockPrisma.talentPilot = { findMany: jest.fn().mockResolvedValue([]) };
mockPrisma.talentPublicProof = { findMany: jest.fn().mockResolvedValue([]) };
}
function seedProject(updatedAt: Date) {
mockPrisma.project.__rows = [
{
id: 'proj-1',
userId,
owner: 'acme',
name: 'repo-1',
fullName: 'acme/repo-1',
description: 'a project',
url: 'https://github.com/acme/repo-1',
repoUrl: 'https://github.com/acme/repo-1',
language: 'TypeScript',
tags: ['typescript'],
stars: 3,
forks: 1,
githubId: null,
updatedAt,
},
];
}
it('runs the gate and returns the unchanged dossier shape for clean data (no warning)', async () => {
seedUser();
seedProject(new Date('2026-02-01T00:00:00Z'));
const graph = await getTalentGraph(userId);
// Success-path response shape is exactly what consumers depend on.
expect(graph).not.toBeNull();
expect(graph).toEqual(
expect.objectContaining({
profile: expect.objectContaining({ id: userId }),
summary: expect.objectContaining({ projectCount: 1 }),
projects: expect.any(Array),
collaborators: expect.any(Array),
generatedAt: expect.any(Date),
}),
);
expect(graph!.projects).toHaveLength(1);
// Clean data => the gate found nothing to warn about.
expect(warn).not.toHaveBeenCalled();
});
it('emits a gate warning when the assembled graph carries an ontology-invalid edge, still returning the dossier', async () => {
seedUser();
// Corrupt persisted timestamp -> invalid edge provenance on the read path.
seedProject(new Date('totally-invalid'));
const graph = await getTalentGraph(userId);
// Warn-only: the dossier is still returned intact, nothing dropped.
expect(graph).not.toBeNull();
expect(graph!.projects).toHaveLength(1);
// The gate actually ran inside getTalentGraph and flagged the violation.
expect(warn).toHaveBeenCalledTimes(1);
const [, meta] = warn.mock.calls[0];
expect(meta).toMatchObject({
event: 'talent_graph.edge_validation.rejected',
developerId: userId,
});
});
});

View File

@ -0,0 +1,227 @@
/**
* Unit tests for the talent-graph ontology + edge validation and extraction.
*
* These are pure (no Prisma, no I/O), mirroring skillTaxonomyService /
* talentGapAnalysisService tests. They pin the load-bearing behavior of this
* rung: edges are validated against the ontology's domain/range so
* type-incompatible ("hallucinated") structure is rejected, provenance is
* required on every fact, symmetric edges de-duplicate, and edges extracted from
* a graph view all pass validation.
*/
import {
validateEdge,
validateEdges,
edgeKey,
TALENT_ONTOLOGY,
type TalentEdgeInput,
} from '../../src/services/talentGraphOntology';
import { deriveTalentEdges, type TalentGraphView } from '../../src/services/talentGraphEdges';
function makeInput(overrides: Partial<TalentEdgeInput> = {}): TalentEdgeInput {
return {
type: 'contributed_to',
from: { id: 'dev-1', type: 'developer' },
to: { id: 'repo-1', type: 'repo' },
provenance: {
source: 'repository_claim',
observedAt: new Date('2026-01-01T00:00:00Z'),
confidence: 1,
sourceUrl: 'https://github.com/acme/repo-1',
},
...overrides,
};
}
describe('validateEdge', () => {
it('accepts a well-typed developer→repo contribution and normalizes it', () => {
const result = validateEdge(makeInput());
expect(result.valid).toBe(true);
if (!result.valid) return;
expect(result.edge.type).toBe('contributed_to');
expect(result.edge.from).toEqual({ id: 'dev-1', type: 'developer' });
expect(result.edge.to).toEqual({ id: 'repo-1', type: 'repo' });
expect(result.edge.provenance.confidence).toBe(1);
expect(result.edge.provenance.observedAt).toBeInstanceOf(Date);
expect(result.edge.key).toBe('contributed_to|developer:dev-1|repo:repo-1');
});
it('rejects an unknown edge type', () => {
const result = validateEdge(makeInput({ type: 'founded' }));
expect(result.valid).toBe(false);
if (result.valid) return;
expect(result.rejections.map((r) => r.code)).toContain('unknown_edge_type');
});
it('rejects a domain violation (repo cannot be the source of contributed_to)', () => {
const result = validateEdge(
makeInput({ from: { id: 'repo-1', type: 'repo' }, to: { id: 'repo-2', type: 'repo' } }),
);
expect(result.valid).toBe(false);
if (result.valid) return;
expect(result.rejections.map((r) => r.code)).toContain('domain_violation');
});
it('rejects a range violation (has_skill must target a skill, not a repo)', () => {
const result = validateEdge(
makeInput({ type: 'has_skill', to: { id: 'repo-1', type: 'repo' } }),
);
expect(result.valid).toBe(false);
if (result.valid) return;
expect(result.rejections.map((r) => r.code)).toContain('range_violation');
});
it('rejects an unknown node type', () => {
const result = validateEdge(
makeInput({ type: 'member_of', to: { id: 'x', type: 'company' } }),
);
expect(result.valid).toBe(false);
if (result.valid) return;
expect(result.rejections.map((r) => r.code)).toContain('unknown_to_type');
});
it('rejects a self-referential collaborated_with edge', () => {
const result = validateEdge(
makeInput({
type: 'collaborated_with',
from: { id: 'dev-1', type: 'developer' },
to: { id: 'dev-1', type: 'developer' },
}),
);
expect(result.valid).toBe(false);
if (result.valid) return;
expect(result.rejections.map((r) => r.code)).toContain('self_reference');
});
it('rejects missing endpoint ids', () => {
const result = validateEdge(makeInput({ from: { id: ' ', type: 'developer' } }));
expect(result.valid).toBe(false);
if (result.valid) return;
expect(result.rejections.map((r) => r.code)).toContain('missing_from_id');
});
it('rejects out-of-range and non-finite confidence', () => {
for (const confidence of [0, 1.5, -0.2, Number.NaN]) {
const result = validateEdge(
makeInput({ provenance: { source: 'github_sync', observedAt: new Date(), confidence, sourceUrl: null } }),
);
expect(result.valid).toBe(false);
if (result.valid) continue;
expect(result.rejections.map((r) => r.code)).toContain('invalid_confidence');
}
});
it('rejects an unknown provenance source and an invalid date together', () => {
const result = validateEdge(
makeInput({ provenance: { source: 'psychic_intuition', observedAt: 'not-a-date', confidence: 0.5 } }),
);
expect(result.valid).toBe(false);
if (result.valid) return;
const codes = result.rejections.map((r) => r.code);
expect(codes).toContain('unknown_source');
expect(codes).toContain('invalid_observed_at');
});
it('coerces an ISO-string observedAt into a Date', () => {
const result = validateEdge(
makeInput({ provenance: { source: 'github_activity', observedAt: '2026-02-01T12:00:00Z', confidence: 0.75, sourceUrl: null } }),
);
expect(result.valid).toBe(true);
if (!result.valid) return;
expect(result.edge.provenance.observedAt.toISOString()).toBe('2026-02-01T12:00:00.000Z');
});
});
describe('edgeKey', () => {
it('is order-independent for symmetric edges and directed for others', () => {
const a = { id: 'dev-a', type: 'developer' as const };
const b = { id: 'dev-b', type: 'developer' as const };
expect(edgeKey('collaborated_with', a, b)).toBe(edgeKey('collaborated_with', b, a));
const dev = { id: 'dev-a', type: 'developer' as const };
const repo = { id: 'repo-1', type: 'repo' as const };
expect(edgeKey('contributed_to', dev, repo)).not.toBe(edgeKey('contributed_to', repo as never, dev as never));
});
it('every ontology edge type has a coherent domain/range', () => {
for (const def of Object.values(TALENT_ONTOLOGY)) {
expect(def.domain.length).toBeGreaterThan(0);
expect(def.range.length).toBeGreaterThan(0);
}
});
});
describe('validateEdges (batch)', () => {
it('partitions accepted from rejected and dedups symmetric edges keeping strongest confidence', () => {
const inputs: TalentEdgeInput[] = [
makeInput(),
// duplicate symmetric collaboration in both directions, second stronger
makeInput({
type: 'collaborated_with',
from: { id: 'dev-1', type: 'developer' },
to: { id: 'dev-2', type: 'developer' },
provenance: { source: 'github_sync', observedAt: new Date(), confidence: 0.5, sourceUrl: null },
}),
makeInput({
type: 'collaborated_with',
from: { id: 'dev-2', type: 'developer' },
to: { id: 'dev-1', type: 'developer' },
provenance: { source: 'github_sync', observedAt: new Date(), confidence: 0.9, sourceUrl: null },
}),
// hallucinated / type-incompatible: a skill cannot contribute to a repo
makeInput({ from: { id: 'skill-x', type: 'skill' } }),
];
const { accepted, rejected } = validateEdges(inputs);
// one contribution + one deduped collaboration
expect(accepted).toHaveLength(2);
const collab = accepted.find((e) => e.type === 'collaborated_with');
expect(collab?.provenance.confidence).toBe(0.9);
expect(rejected).toHaveLength(1);
expect(rejected[0].rejections.map((r) => r.code)).toContain('domain_violation');
});
});
describe('deriveTalentEdges', () => {
const view: TalentGraphView = {
profile: { id: 'dev-1' },
projects: [
{
id: 'repo-1',
url: 'https://github.com/acme/repo-1',
topics: ['reactjs', 'k8s', 'reactjs'], // alias + duplicate → one skill
verificationLevel: 'verified',
lastVerifiedAt: new Date('2026-01-01T00:00:00Z'),
evidence: [{ kind: 'repository_claim', sourceUrl: 'https://github.com/acme/repo-1' }],
},
],
collaborators: [
{ id: 'dev-2', sharedProjects: [{ id: 'repo-1', url: 'https://github.com/acme/repo-1' }] },
{ id: 'dev-1', sharedProjects: [] }, // self — must be skipped
],
};
it('emits contributed_to, canonicalized+deduped has_skill, and collaborated_with edges', () => {
const edges = deriveTalentEdges(view);
const byType = edges.reduce<Record<string, TalentEdgeInput[]>>((acc, e) => {
(acc[e.type] ??= []).push(e);
return acc;
}, {});
expect(byType.contributed_to).toHaveLength(1);
expect(byType.has_skill.map((e) => e.to.id).sort()).toEqual(['kubernetes', 'react']);
// self-collaborator dev-1 skipped, only dev-2 remains
expect(byType.collaborated_with).toHaveLength(1);
expect(byType.collaborated_with[0].to.id).toBe('dev-2');
});
it('produces edges that all pass ontology validation', () => {
const { accepted, rejected } = validateEdges(deriveTalentEdges(view));
expect(rejected).toHaveLength(0);
expect(accepted.length).toBeGreaterThan(0);
// skill edges are capped at the recorded tier even for a verified project
const skillEdge = accepted.find((e) => e.type === 'has_skill');
expect(skillEdge?.provenance.confidence).toBe(0.5);
});
});

View File

@ -0,0 +1,303 @@
/**
* Unit tests for the talent GraphRAG serving layer.
*
* Pure (no Prisma, no network): the LLM call and the view loader are both
* injected. These tests pin the three load-bearing guarantees of the layer:
* 1. Retrieval correctness — the k-hop subgraph contains the right nodes at the
* right depth, takes no wrong hops, and always terminates.
* 2. Deterministic serialization — identical subgraph in, byte-identical text.
* 3. Grounding — the answer's evidence only ever references edges that were
* actually retrieved; hallucinated citations are dropped.
*/
import { validateEdge, type TalentEdge } from '../../src/services/talentGraphOntology';
import {
buildSubgraphFromEdges,
buildTalentSubgraph,
} from '../../src/services/talentSubgraphRetrieval';
import { serializeTalentSubgraphForLLM } from '../../src/services/talentSubgraphSerializer';
import { parseRagResponse } from '../../src/services/talentGraphRagPrompt';
import {
explainTalentMatch,
type ExplainTalentMatchDeps,
} from '../../src/services/talentGraphRag';
import type { TalentGraphView } from '../../src/services/talentGraphEdges';
// --- helpers ---------------------------------------------------------------
function edge(
type: string,
from: { id: string; type: string },
to: { id: string; type: string },
confidence = 1,
source = 'repository_claim',
): TalentEdge {
const result = validateEdge({
type,
from,
to,
provenance: { source, observedAt: new Date('2026-01-01T00:00:00Z'), confidence, sourceUrl: null },
});
if (!result.valid) throw new Error(`test edge invalid: ${result.rejections.map((r) => r.code).join(',')}`);
return result.edge;
}
const DEV = (id: string) => ({ id, type: 'developer' as const });
const REPO = (id: string) => ({ id, type: 'repo' as const });
/** A multi-hop edge set: dev-1 is the root; repo-2 sits two hops away. */
function multiHopEdges(): TalentEdge[] {
return [
edge('contributed_to', DEV('dev-1'), REPO('repo-1')),
edge('has_skill', DEV('dev-1'), { id: 'react', type: 'skill' }),
edge('member_of', DEV('dev-1'), { id: 'org-1', type: 'org' }),
edge('collaborated_with', DEV('dev-1'), DEV('dev-2'), 0.5, 'github_sync'),
// dev-2's own contribution — reachable only at depth 2 from dev-1
edge('contributed_to', DEV('dev-2'), REPO('repo-2')),
];
}
// --- retrieval correctness -------------------------------------------------
describe('buildSubgraphFromEdges (k-hop retrieval)', () => {
it('depth 0 returns only the root, no edges', () => {
const sub = buildSubgraphFromEdges(multiHopEdges(), DEV('dev-1'), 0);
expect(sub.nodes).toHaveLength(1);
expect(sub.nodes[0]).toMatchObject({ id: 'dev-1', type: 'developer', distance: 0 });
expect(sub.edges).toHaveLength(0);
});
it('depth 1 includes direct neighbors but takes no wrong hops', () => {
const sub = buildSubgraphFromEdges(multiHopEdges(), DEV('dev-1'), 1);
const nodeIds = sub.nodes.map((n) => `${n.type}:${n.id}`).sort();
expect(nodeIds).toEqual([
'developer:dev-1',
'developer:dev-2',
'org:org-1',
'repo:repo-1',
'skill:react',
]);
// repo-2 is two hops away — it must NOT appear, and neither must its edge.
expect(nodeIds).not.toContain('repo:repo-2');
expect(sub.edges.some((e) => e.to.id === 'repo-2' || e.from.id === 'repo-2')).toBe(false);
// every edge kept has both endpoints inside the node set
const present = new Set(nodeIds);
for (const e of sub.edges) {
expect(present.has(`${e.from.type}:${e.from.id}`)).toBe(true);
expect(present.has(`${e.to.type}:${e.to.id}`)).toBe(true);
}
});
it('depth 2 expands to the second hop and includes the bridging edge', () => {
const sub = buildSubgraphFromEdges(multiHopEdges(), DEV('dev-1'), 2);
const repo2 = sub.nodes.find((n) => n.id === 'repo-2');
expect(repo2).toBeDefined();
expect(repo2?.distance).toBe(2);
expect(sub.edges.some((e) => e.from.id === 'dev-2' && e.to.id === 'repo-2')).toBe(true);
});
it('terminates on cycles and caps runaway depth', () => {
const cyclic = [
edge('collaborated_with', DEV('dev-1'), DEV('dev-2'), 0.5, 'github_sync'),
edge('collaborated_with', DEV('dev-2'), DEV('dev-3'), 0.5, 'github_sync'),
edge('collaborated_with', DEV('dev-3'), DEV('dev-1'), 0.5, 'github_sync'),
];
const sub = buildSubgraphFromEdges(cyclic, DEV('dev-1'), 1000);
// three developers, each visited once; depth is capped, not 1000
expect(sub.nodes).toHaveLength(3);
expect(sub.depth).toBeLessThanOrEqual(6);
});
it('rejects a negative or non-integer depth at the boundary', () => {
expect(() => buildSubgraphFromEdges(multiHopEdges(), DEV('dev-1'), -1)).toThrow();
expect(() => buildSubgraphFromEdges(multiHopEdges(), DEV('dev-1'), 1.5)).toThrow();
});
it('rejects an empty root id', () => {
expect(() => buildSubgraphFromEdges(multiHopEdges(), DEV(' '), 1)).toThrow();
});
});
// --- view-based retrieval --------------------------------------------------
const VIEW: TalentGraphView = {
profile: { id: 'dev-1' },
projects: [
{
id: 'repo-1',
url: 'https://github.com/acme/repo-1',
topics: ['reactjs', 'k8s'],
verificationLevel: 'verified',
lastVerifiedAt: new Date('2026-01-01T00:00:00Z'),
evidence: [{ kind: 'repository_claim', sourceUrl: 'https://github.com/acme/repo-1' }],
},
],
collaborators: [
{ id: 'dev-2', sharedProjects: [{ id: 'repo-1', url: 'https://github.com/acme/repo-1' }] },
],
};
describe('buildTalentSubgraph (view-based)', () => {
it('retrieves the developer neighborhood from an assembled view', () => {
const sub = buildTalentSubgraph(VIEW, 'dev-1', 1);
const types = sub.nodes.map((n) => n.type);
expect(types).toContain('developer'); // root + collaborator
expect(types).toContain('repo');
expect(types).toContain('skill');
// canonicalized skills present
expect(sub.nodes.some((n) => n.type === 'skill' && n.id === 'react')).toBe(true);
expect(sub.nodes.some((n) => n.type === 'skill' && n.id === 'kubernetes')).toBe(true);
// every edge carries provenance
for (const e of sub.edges) {
expect(e.provenance.confidence).toBeGreaterThan(0);
expect(e.provenance.observedAt).toBeInstanceOf(Date);
expect(typeof e.provenance.source).toBe('string');
}
});
it('rejects a rootDeveloperId that does not match the view profile', () => {
expect(() => buildTalentSubgraph(VIEW, 'someone-else', 1)).toThrow();
});
});
// --- deterministic serialization ------------------------------------------
describe('serializeTalentSubgraphForLLM', () => {
it('is deterministic: the same subgraph produces byte-identical text', () => {
// Serialization is a pure function of the subgraph, so a single retrieved
// subgraph must serialize identically every time (cacheable prompts). We
// build once and serialize twice; edge order is fixed by the retrieval layer.
const sub = buildSubgraphFromEdges(multiHopEdges(), DEV('dev-1'), 2);
expect(serializeTalentSubgraphForLLM(sub)).toBe(serializeTalentSubgraphForLLM(sub));
});
it('orders edges canonically regardless of input edge order', () => {
const forward = buildSubgraphFromEdges(multiHopEdges(), DEV('dev-1'), 2);
const shuffled = buildSubgraphFromEdges([...multiHopEdges()].reverse(), DEV('dev-1'), 2);
expect(serializeTalentSubgraphForLLM(forward)).toBe(serializeTalentSubgraphForLLM(shuffled));
});
it('exposes edge citation keys and provenance in the context', () => {
const sub = buildTalentSubgraph(VIEW, 'dev-1', 2);
const text = serializeTalentSubgraphForLLM(sub);
expect(text).toContain('ROOT: developer:dev-1');
expect(text).toContain('EDGES (facts — cite by [key]):');
for (const e of sub.edges) {
expect(text).toContain(`[${e.key}]`);
}
expect(text).toMatch(/source=/);
expect(text).toMatch(/confidence=/);
});
it('renders an empty subgraph without crashing', () => {
const empty = buildSubgraphFromEdges([], DEV('dev-1'), 1);
const text = serializeTalentSubgraphForLLM(empty);
expect(text).toContain('ROOT: developer:dev-1');
expect(text).toContain('(none)');
});
});
// --- response parsing ------------------------------------------------------
describe('parseRagResponse', () => {
it('parses a clean JSON object', () => {
const parsed = parseRagResponse('{"answer":"ok","citedEdgeKeys":["k1","k2"]}');
expect(parsed.answer).toBe('ok');
expect(parsed.citedEdgeKeys).toEqual(['k1', 'k2']);
});
it('tolerates a ```json code fence', () => {
const parsed = parseRagResponse('```json\n{"answer":"x","citedEdgeKeys":[]}\n```');
expect(parsed.answer).toBe('x');
});
it('throws on non-JSON, wrong shape, or non-string citations', () => {
expect(() => parseRagResponse('not json')).toThrow();
expect(() => parseRagResponse('[]')).toThrow();
expect(() => parseRagResponse('{"answer":1,"citedEdgeKeys":[]}')).toThrow();
expect(() => parseRagResponse('{"answer":"x","citedEdgeKeys":[1]}')).toThrow();
expect(() => parseRagResponse('')).toThrow();
});
});
// --- grounding (the core guarantee) ---------------------------------------
describe('explainTalentMatch (grounding)', () => {
const loadView: ExplainTalentMatchDeps['loadView'] = async () => VIEW;
it('returns an answer whose evidence only references retrieved edges', async () => {
// Discover the real edge keys the subgraph will contain.
const sub = buildTalentSubgraph(VIEW, 'dev-1', 2);
const realKey = sub.edges[0].key;
const hallucinatedKey = 'collaborated_with|developer:ghost|developer:phantom';
const ask: ExplainTalentMatchDeps['ask'] = async (req) => {
// sanity: the grounding contract and the serialized context were passed
expect(req.system).toMatch(/ONLY using the facts/i);
expect(req.context).toContain('ROOT: developer:dev-1');
return JSON.stringify({
answer: 'dev-1 matches because of contributed repositories and skills.',
citedEdgeKeys: [realKey, hallucinatedKey],
});
};
const result = await explainTalentMatch('dev-1', 'Why does this developer match React work?', {
ask,
loadView,
depth: 2,
});
const subgraphKeys = new Set(sub.edges.map((e) => e.key));
// INVARIANT: every cited piece of evidence exists in the retrieved subgraph
for (const ev of result.evidence) {
expect(subgraphKeys.has(ev.key)).toBe(true);
}
expect(result.evidence.map((e) => e.key)).toContain(realKey);
// the hallucinated citation was dropped, not returned as evidence
expect(result.evidence.map((e) => e.key)).not.toContain(hallucinatedKey);
expect(result.droppedCitations).toContain(hallucinatedKey);
// evidence carries provenance for auditability
expect(result.evidence[0].source).toBeDefined();
expect(result.evidence[0].confidence).toBeGreaterThan(0);
expect(result.retrieval.edgeCount).toBe(sub.edges.length);
});
it('de-duplicates repeated citations and preserves the answer text', async () => {
const sub = buildTalentSubgraph(VIEW, 'dev-1', 2);
const key = sub.edges[0].key;
const ask: ExplainTalentMatchDeps['ask'] = async () =>
JSON.stringify({ answer: 'grounded answer', citedEdgeKeys: [key, key, key] });
const result = await explainTalentMatch('dev-1', 'why match', { ask, loadView, depth: 2 });
expect(result.answer).toBe('grounded answer');
expect(result.evidence.filter((e) => e.key === key)).toHaveLength(1);
expect(result.droppedCitations).toHaveLength(0);
});
it('returns no evidence when the model cites nothing', async () => {
const ask: ExplainTalentMatchDeps['ask'] = async () =>
JSON.stringify({ answer: 'insufficient information in the subgraph', citedEdgeKeys: [] });
const result = await explainTalentMatch('dev-1', 'why match', { ask, loadView });
expect(result.evidence).toHaveLength(0);
expect(result.answer).toMatch(/insufficient/);
});
it('validates inputs and surfaces a missing view', async () => {
const ask: ExplainTalentMatchDeps['ask'] = async () => '{"answer":"x","citedEdgeKeys":[]}';
await expect(explainTalentMatch('', 'q', { ask, loadView })).rejects.toThrow(/rootDeveloperId/);
await expect(explainTalentMatch('dev-1', ' ', { ask, loadView })).rejects.toThrow(/query/);
await expect(
explainTalentMatch('dev-1', 'q', { ask, loadView: async () => null }),
).rejects.toThrow(/No talent graph view/);
});
it('requires an injected ask function', async () => {
await expect(
explainTalentMatch('dev-1', 'q', { loadView } as unknown as ExplainTalentMatchDeps),
).rejects.toThrow(/deps.ask/);
});
it('propagates a malformed LLM reply as an explicit error', async () => {
const ask: ExplainTalentMatchDeps['ask'] = async () => 'garbage not json';
await expect(explainTalentMatch('dev-1', 'q', { ask, loadView })).rejects.toThrow(/JSON/);
});
});