Spoke

factor-models

Versioned latent-factor models — build → validate → score → publish above calculus + psychometrics.

Character

You own culture / capability composites but leadership keeps asking whether the weights from last refresh still apply—and you cannot show the validation gate behind each scorecard.

Problem

External. Vendors mint black-box factor scores without immutable version ids tying training windows to disclosures.

Internal. Governance teams expect subgroup fairness artefacts; you stitch spreadsheets because no substrate stores validation rows next to inference.

Philosophical. Latent constructs should behave like audited software artefacts, not orphaned notebook tabs.

Guide

factor-models treats latent spaces as Postgres-backed assets with modelId × versionId pinning. Scores persist only once validation reports pass—so consumers can quote (modelId, factor, percentile) while weights evolve cleanly.

Abstract

Background. People analytics needs defensible composites above raw pulses; ad-hoc weight tweaking erodes fairness reviews.

Methodology. Canonical pipeline: declare models, accumulate factor weights per versionId, memoise deterministic scores after validation artefacts land, and optionally audit subgroup slices using consumer-supplied segmentation keys (HTTP-only contracts).

Scope. Does not replace IRT (reincarnation) or causal claims (program-evaluation); merges only indicator streams you supply.

Contribution. MCP + HTTP parity, immutable validation tables, deterministic scoring—engineering-grade latent indices.

Evidence / Provenance. PAT-D5-B README + demo seed seeds/2026-05-22-factor-models-demo.sql.

Plan

01
Author models + validations
Mutate models/versions behind the service key; ensure validation_reports captures each gate before promotion.
02
Publish currentVersionId
Flip currentVersionId only after passing validations so downstream decks reference stable semver-like rows.
03
Score indicators
POST score routes with memoisation—replay identical payloads to prove audit-friendly determinism during reviews.
04
Compose fairness externally
Segment comparisons stay consumer-owned; ingest cohort keys resolved via segmentation-studio without cross-importing its DB.

Call to Action

Direct. Exercise the PAT-D5 README curls against a seeded tenant.

Transitional. Read session report PAT-D5-B before wiring production tenants.

Spoke I/O (visual language v1)

Every toolbox spoke shares the same abstract choreography: typed inputs on the left, distilled verbs in the center, typed outputs on the right, and (when relevant) cross-spoke HTTP composition along the bottom rail. Source package: @people-analytics-toolbox/spoke-illustrations.

Try it now

Copy this curl. Paste in any terminal. Public read — no auth needed.

factor-models.models.get

GET

Fetch a seeded demo model once migration + seed.sql applied; swap UUID/tenant when you have real rows.

curl -sS "https://people-analytics-toolbox.vercel.app/api/spokes/factor-models/models/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa?tenantId=pat-d5-b-demo"

Vendor the contract

The Zod contract is the source of truth. Vendor a copy into your consumer app — you keep it; we don't break it underneath you. Re-vendor when the version bumps.

// Vendor canonical types:
// src/spokes/factor-models/contracts/types.ts

Source path: src/spokes/factor-models/contracts/types.ts · GitHub

Try in Dev Console Read the explainer Browse registry entry on /operator Back to all spokes

Failure

Quarterly composites drift silently; fairness investigations cite yesterday’s workbook, not reproducible artefacts.

Success

Factor scores cite explicit version ids plus validation dossiers—you can defend leadership and regulator scrutiny with Postgres truth.