Skip to content

Architecture

This package supports the relationship-level HCT model.

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

Overview

The unit of training is a worker-firm relationship expanded into yearly person-period rows. The model computes a match-quality score from the worker and firm embeddings and feeds that score 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.

Inputs

The worker tower receives:

  • pre-match employer history
  • optional history job category and seniority features
  • static employee-side features
  • configured relationship-state features such as tenure, seniority, job category, and calendar year

The company tower receives:

  • company identity
  • configured company categorical features
  • optional about-text embedding features

The relationship state is configured under training_features.relationship and is appended to the employee representation before the employee head. This lets match quality evolve over configured relationship-period features while keeping the pre-match history fixed within a relationship.

Losses And Metrics

Training combines:

  • separation hazard BCE as the primary loss
  • optional masked future wage-growth MSE as a secondary loss
  • optional sampled destination softmax on switch rows as an auxiliary loss

Evaluation reports configured hazard, wage, destination, match-quality movement, and pair-residual diagnostics. Destination recall/MRR/NDCG are computed only for separations with a known next employer, with the incumbent excluded.

Artifacts

Direct training modes write to training_modes.<mode>:

  • checkpoints in training_modes.<mode>.ckpt_dir
  • training/evaluation CSV or parquet outputs in training_modes.<mode>.eval_output_dir
  • training and evaluation plots in training_modes.<mode>.img_dir

Grouped cross-validation writes the same per-trial artifact structure under cross_validation_search.trial_root/<trial_name>/ and writes grouped summaries under cross_validation_search.summary_output_dir.