This workplace-learning recommender filters resources for feasibility before ranking them against confirmed competency gaps and work context. It exposes contributions from need priority, gap coverage, task fit, quality, effort, and other declared factors, then checks coverage and sensitivity to weights. The output is a reasoned recommendation based on supplied metadata, not a validated estimate of learning impact.
Review scope: 34 existing unittest checks passed. The bundled demonstration executed successfully in this review.
Explainable workplace-learning recommendations with hard eligibility checks, context-aware scoring, coverage control, and ranking sensitivity.
Area: Learning & Development · Workplace Learning · Recommendation Systems
Status: working research prototype
Author: Devis Saputra
A workplace-learning recommender should not simply return the most popular or highest-rated course.
A useful recommendation has to answer several different questions:
- Is there a confirmed development need?
- Is the resource appropriate for the learner's current level?
- Are prerequisites met?
- Is it actually available?
- Does it fit the current task, role, and learning goal?
- Does it fit the learner's time and modality constraints?
- Has the learner just seen or completed it?
- Is the recommendation list covering several important needs or repeating the same skill?
This repository implements a transparent baseline for those questions.
It does not infer employee capability, motivation, personality, career intent, or hidden preferences.
The recommender separates eligibility from ranking.
The system expects upstream competency evidence with statuses such as:
gapmetexceeds_targetunknown_evidenceinsufficient_evidence
Only sufficiently supported confirmed gaps enter recommendation ranking.
Missing evidence is not converted into a zero skill level.
The data model is compatible in spirit with the separate competency_gap_intelligence project, but this repository has no runtime dependency on it.
The request can include:
- role
- role tags
- current task tags
- learning-goal tags
- preferred modalities
- language
- available hours
- completed resources
- recent resource exposures
- an explicit recommendation date
These values are supplied deliberately. The baseline does not infer them from hidden monitoring.
Each resource can declare:
- target skills
- entry level
- target level
- quality
- quality source
- modality
- effort hours
- competency prerequisites
- task tags
- role tags
- goal tags
- language
- availability
- last-updated date
A resource is excluded before scoring when it is:
- unavailable
- already completed
- incompatible with the selected language
- longer than the available time budget
- unrelated to any confirmed gap
- above the learner's current entry level
- unable to advance beyond the current level
- blocked by an unmet prerequisite
This avoids a common recommender failure: allowing an unsuitable course to survive because a high quality score compensates for a hard mismatch.
Eligible resources receive ten normalized component scores:
| Component | Meaning |
|---|---|
| Need priority | relative priority of the confirmed competency gap |
| Gap coverage | how much of the remaining level gap the resource can cover |
| Task fit | overlap with the current task tags |
| Role fit | overlap with the role tags |
| Goal fit | overlap with the learning-goal tags |
| Quality | externally supplied resource-quality signal |
| Modality fit | match with declared modality preferences |
| Effort fit | fit within the available learning time |
| Freshness | how recently the resource itself was updated |
| Novelty | how recently the learner saw the same resource |
All component weights are explicit and normalized.
The default weights are a design baseline, not an empirically validated optimum.
The original prototype used a recently_seen count and called it recency.
That has been replaced by two different signals.
Freshness comes from the resource's last_updated date.
Novelty comes from the learner's supplied days-since-exposure history.
A resource can therefore be new to the learner but old in the catalog, or recently updated but already seen yesterday.
A raw ranker can easily return five Python courses because Python happens to have the highest gap.
select_with_coverage() first gives different confirmed skill needs an opportunity to appear.
A second pass fills remaining positions while respecting max_per_skill.
This is a simple deterministic coverage heuristic, not a learned diversification model.
Every returned recommendation includes:
- matched skill
- total score
- every component score
- gap coverage
- resource metadata
- a plain-language explanation generated from the actual score components
The explanation does not claim contextual fit that was never measured.
ranking_sensitivity() reruns recommendation with alternative weight configurations.
It reports:
- ranking by scenario
- best and worst rank
- whether the rank stayed stable
- whether the resource appears in every scenario
This makes it easier to see when a recommendation depends heavily on one arbitrary weighting choice.
The bundled synthetic example includes:
- four confirmed development gaps
- one competency above target
- one competency with unknown evidence
- explicit role/task/goal context
- modality and time constraints
- ten learning resources
- an unmet prerequisite
- an unavailable resource
- an over-budget resource
- a stale catalog resource
- recent exposure history
- component-level explanations
- skill-coverage diagnostics
- alternative scoring-weight scenarios
The example is synthetic and is not evidence that any recommendation improves workplace learning.
data/needs.json
Synthetic development needs and proficiency scale.
data/context.json
Synthetic workplace-learning context and constraints.
data/resources.json
Structured resource catalog used by the demo.
data/sample.csv
Compact tabular view of the synthetic resource catalog.
data/README.md
Schema, governance, and interpretation guidance.
git clone https://github.com/devissaputra/workplace_learning_recommender.git
cd workplace_learning_recommender
python scripts/run_demo.py
python -m unittest discover -s tests -vThe current baseline uses only the Python standard library.
validate_scale(...)
Validates the proficiency scale.
validate_needs(...)
Separates confirmed gaps from met, unknown, or insufficient evidence.
validate_context(...)
Validates explicit role, task, goal, preference, time, language, completion, and exposure context.
validate_resources(...)
Validates structured resource metadata.
eligibility_report(...)
Returns eligible resources and explicit exclusion reasons.
score_resources(...)
Calculates the ten decomposed score components for eligible resources.
select_with_coverage(...)
Limits list concentration and gives distinct skill gaps a chance to appear.
recommend(...)
Returns recommendations, explanations, exclusions, and diagnostics.
recommendation_diagnostics(...)
Reports skill coverage and concentration.
ranking_sensitivity(...)
Tests recommendation order under alternative scoring weights.
The current prototype can calculate:
- eligibility
- normalized component scores
- skill coverage
- maximum single-skill share
- exclusion reasons
- ranking sensitivity
It does not currently claim empirical:
- nDCG
- precision or recall
- novelty preference
- learner satisfaction
- training effectiveness
- job-performance improvement
Those require relevance labels or real outcome data.
A credible study should examine:
- Eligibility precision — were filtered items truly unsuitable?
- Ranking relevance — do experts and learners prefer the ranked resources?
- Coverage and concentration — are important needs represented without excessive repetition?
- Explanation usefulness — can people understand and challenge the reasons?
- Rejection reasons — why are suggestions postponed, rejected, or corrected?
- Learning impact — do accepted resources improve independent competency evidence?
Clicks and completions alone are not proof of learning.
The repository is informed by workplace-learning recommender research on:
- multi-stakeholder learning goals
- task-oriented workplace recommendation
- explainable employee-training recommendation
- learner control and privacy
- adult-learning participation constraints
See docs/related_work.md for references and scope boundaries.
Workplace learning recommendations can become coercive if a system blurs the distinction between learner choice and employer requirements.
This prototype should not be used alone for:
- hiring
- termination
- promotion
- pay
- discipline
- forced ranking
- psychological profiling
- covert monitoring
- automatic career-path assignment
See docs/ethics_and_risks.md for the workplace-specific risk review.
The current baseline:
- depends on externally supplied competency needs
- depends on hand-authored resource metadata
- uses simple tag overlap rather than semantic embeddings
- uses heuristic freshness and novelty functions
- uses hand-selected default weights
- does not model resource cost
- does not learn preferences from behavior
- does not model mentoring, peer learning, stretch assignments, job aids, or workflow redesign
- does not estimate causal learning impact
- does not prove that a resource will close a competency gap
A recommendation is a reviewable development suggestion, not an objective prescription.
.
├── .github/workflows/ci.yml
├── assets/
│ ├── architecture.svg
│ ├── data_flow.svg
│ ├── demo_snapshot.svg
│ └── evaluation_dashboard.svg
├── data/
│ ├── README.md
│ ├── context.json
│ ├── needs.json
│ ├── resources.json
│ └── sample.csv
├── docs/
│ ├── ethics_and_risks.md
│ ├── related_work.md
│ └── research_protocol.md
├── reports/model_card.md
├── scripts/run_demo.py
├── src/workplace_learning_recommender/
│ ├── __init__.py
│ └── core.py
├── tests/test_core.py
├── .gitignore
├── CITATION.cff
├── LICENSE
├── pyproject.toml
├── requirements.txt
└── README.md
A stronger empirical version would:
- validate the resource catalog with L&D experts
- collect independent resource-relevance judgments
- compare with gap-only, quality-only, popularity, and random baselines
- test explanations with learners and managers
- collect recommendation rejection and correction reasons
- evaluate accessibility and language coverage
- test preference-control designs
- compare transparent scoring with semantic or learned recommenders
- measure whether accepted resources improve independent competency evidence
- examine whether recommendation quality differs systematically across worker contexts
CITATION.cff contains the software citation.
Code and original SVG visuals use the MIT License. External datasets, frameworks, and resource catalogs retain their own licenses and governance requirements.