Role Match, Combined Scoring & Individual Comparison

This page documents the second-generation algorithm features added on top of the V1 workstyle scoring engine:

  1. Role Match — how well a candidate’s experience and goals match a Role’s specification.
  2. Combined Score — blend of Role Match + Workstyle Match into a single 0–100 score.
  3. Individual Comparison — pairwise compatibility between two candidates’ answer sets.

These features power the new evaluation endpoints POST /evaluation/{id}/team-match and POST /evaluation/compare.

1. Role Match

Given a RoleSpecification, the algorithm scores each candidate by:

  1. Building a list of QueryElements — small criterion predicates with a priority (1–4+):

    • industry, function, skill, studyMajor → set match (any-overlap; percentage = |intersection| / |spec.ids|).
    • professionalYears, educationLevel → threshold-GTE (candidate’s orderBy ≥ spec’s orderBy).
    • location (goal-only) → set match.

  2. Awarding priority points (Java parity):

    Priority Points
    1 13
    2 7
    3 3
    4+ 1

    Each element contributes points × percentageMatch (earned) and points × 1.0 (max).

  3. Computing two scores:

    • experienceScore from elements built against UserExperience (industry/function/skill/professionalYears/educationLevel/studyMajor).
    • goalScore from elements built against UserGoal (industry/function/skill/location).

  4. Blending them: roleMatch = 0.95 × experienceScore + 0.05 × goalScore.

    • If only one side has criteria configured, that side’s score is used directly.

Result fields: score (0–100), scoreCategory, per-element breakdown.

Library: libs/algorithm/search/role-match.ts. Element helpers: libs/algorithm/search/query-elements.ts.

2. Combined Score

Blends Role Match and Workstyle Match. Implemented in libs/algorithm/search/combined-score.ts.

combined = (roleScore × roleWeight + workstyleScore × (100 − roleWeight)) / 100
  • roleWeight defaults to 50 (equal weighting).
  • If only one of the two scores is available, combined equals the available one.
  • Workstyle itself can blend team workstyle (70%) and management workstyle (30%) when both are present:
workstyleScore = 0.7 × teamWorkstyle + 0.3 × managementWorkstyle

Management workstyle is currently unimplemented (null); the team score is used as-is until manager scoring lands.

3. Individual ↔ Individual Comparison

Library: libs/algorithm/individual/individual-compare.ts.

Three modes:

Mode Symmetric Description
PAIRWISE (default) ❌ Treat user A as a 1-person team; score B as the candidate.
MUTUAL ✅ Run PAIRWISE in both directions; report the average plus both raw scores.
SIMULATED_TEAM ✅ Same calculation as MUTUAL, framed as 2-person team cohesion.

Output mirrors the workstyle dimension result: score, scoreCategory, full dimensions[], and (for symmetric modes) reverseScore + reverseDimensions.

4. New Database Entities

Seeded by libs/seeder/seed-algorithm.ts from mock/data/{roles,experiences,lookups}.ts. Mongoose schemas are in libs/algorithm/db/schemas/.

Collection Purpose
roles Role { id, organisationId, title, teamId, roleSpecificationId, criteriaWeight }
rolespecifications Per-criterion IDs + priorities + thresholds
userexperiences Per-user industry/function/skill/years/education/major
usergoals Per-user target industry/function/skill/location
industries, workfunctions, skills Lookup tables
professionalyears, educationlevels, studymajors Lookups with orderBy for threshold matching
locations Lookup with countryId

All use numeric _id (matches the algorithm’s userId / roleId conventions).

5. New Endpoints

Endpoint Purpose
POST /evaluation/{id}/team-match Combined Role + Workstyle score for one evaluation
POST /evaluation/compare Pairwise / mutual comparison between two evaluations

Both endpoints are computed on demand and do not persist results — call them as often as you need.

See Swagger and the UI integration guides:

6. Algorithm Constants Reference

Constant Value Where
Priority points P1 / P2 / P3 / P4+ 13 / 7 / 3 / 1 query-elements.ts::priorityPoints
Experience weight (role match) 0.95 role-match.ts
Goal weight (role match) 0.05 role-match.ts
Team workstyle weight 0.70 combined-score.ts
Management workstyle weight 0.30 combined-score.ts
Default roleWeight 50 combined-score.ts
Score category buckets <33 LOW, 33–65 MEDIUM, ≥66 HIGH score-category.ts
next Introduction