Skip to content

Model

The package implements a relationship-level Human Capital Transformer (HCT). Each worker-firm relationship is represented by annual person-period rows. The model learns a worker representation from pre-match employment history and employee features, a firm representation from firm features, and their compatibility as match quality.

Main entrypoints:

  • training/train.py
  • training/cross_validate.py
  • scoring/score_matches.py

Core modules:

  • data/relationship_dataset.py
  • data/history_events.py
  • runtime/company_runtime.py
  • runtime/model_runtime.py
  • models/hct.py
  • models/company_tower.py
  • models/employee_tower.py
  • evaluation/model_eval.py

Match quality and separation

The model computes match quality from worker and firm embeddings and feeds it into a separation-hazard equation:

match_score = cosine(employee_vec, company_vec)
hazard_prob = sigmoid(
  baseline_logits(tenure, optional calendar_year)
  + optional_firm_hazard_logits
  + optional_worker_hazard_logits
  + optional_relationship_hazard_logits
  - beta * match_score
)

If model.use_weighted_match_score: true, the cosine uses learned positive per-dimension weights and remains bounded by [-1, 1]. beta is constrained positive, so higher match quality lowers the predicted separation hazard, conditional on the configured baseline and any enabled additive hazard heads.

The baseline is a separate logistic module trained alongside the towers. Its controls are configured by model.relationship.hazard_baseline.controls; the currently supported controls are tenure and calendar_year. Additive firm, worker, and relationship hazard heads are controlled by model.relationship.additive_hazard_heads.enabled and are disabled in the base sample configs.

The independent hazard baseline captures tenure and, when configured, calendar year. Optional additive firm, worker, and relationship hazard heads capture residual separation propensity not explained by match quality. The base configs disable those additive heads.

See Inputs for what enters each tower and Objectives for the fitted outcomes.