From fd507e5efedb843628ba447159af1592b9da2aac Mon Sep 17 00:00:00 2001 From: caelum0x Date: Tue, 25 Aug 2026 12:29:47 +0300 Subject: [PATCH 1/3] feat(graph): typed talent-graph ontology + edge validation & extraction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Promote the talent graph's implicit structure to an explicit schema and add the single guardrail that removes hallucinated structure: validate every candidate edge against its edge type's domain/range and reject type-incompatible ones. - talentGraphOntology.ts: node types (developer, repo, org, skill, contribution) and edge types (contributed_to, member_of, has_skill, collaborated_with) with domain/range, symmetry and reflexivity rules. validateEdge / validateEdges vet untrusted edges, require provenance (source, observedAt, confidence) on every fact, dedup symmetric edges, and return typed rejection reasons. Pure, no I/O. - talentGraphEdges.ts: extraction step — turns getTalentGraph's view into provenanced candidate edges, reusing canonicalizeSkill and the evidence source union aligned with TalentEvidence.kind. - tests: 15 unit tests covering domain/range rejection, provenance validation, symmetric dedup, and extract-then-validate soundness. --- .../backend/src/services/talentGraphEdges.ts | 133 ++++++++ .../src/services/talentGraphOntology.ts | 291 ++++++++++++++++++ .../tests/unit/talentGraphOntology.test.ts | 227 ++++++++++++++ 3 files changed, 651 insertions(+) create mode 100644 gitgram/backend/src/services/talentGraphEdges.ts create mode 100644 gitgram/backend/src/services/talentGraphOntology.ts create mode 100644 gitgram/backend/tests/unit/talentGraphOntology.test.ts diff --git a/gitgram/backend/src/services/talentGraphEdges.ts b/gitgram/backend/src/services/talentGraphEdges.ts new file mode 100644 index 00000000..0dbb029b --- /dev/null +++ b/gitgram/backend/src/services/talentGraphEdges.ts @@ -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> = { + verified: 1, + linked: 0.75, + recorded: 0.5, +}; + +const SOURCE_SET: ReadonlySet = 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(); + 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; +} diff --git a/gitgram/backend/src/services/talentGraphOntology.ts b/gitgram/backend/src/services/talentGraphOntology.ts new file mode 100644 index 00000000..a2a82b7f --- /dev/null +++ b/gitgram/backend/src/services/talentGraphOntology.ts @@ -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> = { + 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 = new Set(TALENT_NODE_TYPES); +const SOURCE_SET: ReadonlySet = 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(); + 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 }; +} diff --git a/gitgram/backend/tests/unit/talentGraphOntology.test.ts b/gitgram/backend/tests/unit/talentGraphOntology.test.ts new file mode 100644 index 00000000..874c14bf --- /dev/null +++ b/gitgram/backend/tests/unit/talentGraphOntology.test.ts @@ -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 { + 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>((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); + }); +}); From b46c487206afb0420cfd64f43456a5c98b78a750 Mon Sep 17 00:00:00 2001 From: caelum0x Date: Tue, 25 Aug 2026 18:35:08 +0300 Subject: [PATCH 2/3] feat(graph): wire talent-graph validation gate into the service path (warn-only) --- .../src/services/talentGraphService.ts | 52 +++++- .../tests/unit/talentGraphGate.test.ts | 171 ++++++++++++++++++ 2 files changed, 222 insertions(+), 1 deletion(-) create mode 100644 gitgram/backend/tests/unit/talentGraphGate.test.ts diff --git a/gitgram/backend/src/services/talentGraphService.ts b/gitgram/backend/src/services/talentGraphService.ts index d4d81b7f..ca95abfe 100644 --- a/gitgram/backend/src/services/talentGraphService.ts +++ b/gitgram/backend/src/services/talentGraphService.ts @@ -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) { diff --git a/gitgram/backend/tests/unit/talentGraphGate.test.ts b/gitgram/backend/tests/unit/talentGraphGate.test.ts new file mode 100644 index 00000000..baa1bf3f --- /dev/null +++ b/gitgram/backend/tests/unit/talentGraphGate.test.ts @@ -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 { + 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, + }); + }); +}); From 76e7064cbe92dc43703a542916e9101a25521db2 Mon Sep 17 00:00:00 2001 From: caelum0x Date: Tue, 25 Aug 2026 19:32:13 +0300 Subject: [PATCH 3/3] feat(graph): GraphRAG serving layer (subgraph retrieval + grounded query) --- .../src/controllers/talentGraphController.ts | 51 +++ gitgram/backend/src/routes/talentGraph.ts | 2 + .../backend/src/services/talentGraphRag.ts | 212 ++++++++++++ .../src/services/talentGraphRagPrompt.ts | 97 ++++++ .../src/services/talentSubgraphRetrieval.ts | 177 ++++++++++ .../src/services/talentSubgraphSerializer.ts | 101 ++++++ .../backend/tests/unit/talentGraphRag.test.ts | 303 ++++++++++++++++++ 7 files changed, 943 insertions(+) create mode 100644 gitgram/backend/src/services/talentGraphRag.ts create mode 100644 gitgram/backend/src/services/talentGraphRagPrompt.ts create mode 100644 gitgram/backend/src/services/talentSubgraphRetrieval.ts create mode 100644 gitgram/backend/src/services/talentSubgraphSerializer.ts create mode 100644 gitgram/backend/tests/unit/talentGraphRag.test.ts diff --git a/gitgram/backend/src/controllers/talentGraphController.ts b/gitgram/backend/src/controllers/talentGraphController.ts index 58315e92..97cc9578 100644 --- a/gitgram/backend/src/controllers/talentGraphController.ts +++ b/gitgram/backend/src/controllers/talentGraphController.ts @@ -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, +) { + 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'] } }, diff --git a/gitgram/backend/src/routes/talentGraph.ts b/gitgram/backend/src/routes/talentGraph.ts index 3dabaaed..41e9c92b 100644 --- a/gitgram/backend/src/routes/talentGraph.ts +++ b/gitgram/backend/src/routes/talentGraph.ts @@ -27,7 +27,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); diff --git a/gitgram/backend/src/services/talentGraphRag.ts b/gitgram/backend/src/services/talentGraphRag.ts new file mode 100644 index 00000000..6a69bec5 --- /dev/null +++ b/gitgram/backend/src/services/talentGraphRag.ts @@ -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; + /** 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 { + 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(); + 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 { + 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.', + ); +}; diff --git a/gitgram/backend/src/services/talentGraphRagPrompt.ts b/gitgram/backend/src/services/talentGraphRagPrompt.ts new file mode 100644 index 00000000..294515c3 --- /dev/null +++ b/gitgram/backend/src/services/talentGraphRagPrompt.ts @@ -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; + +/** 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; + 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[], + }; +} diff --git a/gitgram/backend/src/services/talentSubgraphRetrieval.ts b/gitgram/backend/src/services/talentSubgraphRetrieval.ts new file mode 100644 index 00000000..7345b309 --- /dev/null +++ b/gitgram/backend/src/services/talentSubgraphRetrieval.ts @@ -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(); + 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(); + 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)); +} diff --git a/gitgram/backend/src/services/talentSubgraphSerializer.ts b/gitgram/backend/src/services/talentSubgraphSerializer.ts new file mode 100644 index 00000000..aec07b7e --- /dev/null +++ b/gitgram/backend/src/services/talentSubgraphSerializer.ts @@ -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> = { + 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> = { + 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: : (depth ) + * NODES + * + * EDGES (facts — cite by [key]) + * + * + * 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'); +} diff --git a/gitgram/backend/tests/unit/talentGraphRag.test.ts b/gitgram/backend/tests/unit/talentGraphRag.test.ts new file mode 100644 index 00000000..c1680031 --- /dev/null +++ b/gitgram/backend/tests/unit/talentGraphRag.test.ts @@ -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/); + }); +});