platform/packages/calculator/README.md

@blade-and-brawn/calculator

Turns a player's raw activity performances (e.g. squat weight, mile time) into per-attribute and overall "levels", by generating and interpolating strength/ performance standards across age, weight, and gender.

For the algorithm itself and the external standards it's based on, see docs/level-calculator.md at the repo root.

Exports

• LevelCalculator — takes a Standards instance; calculate(player, activityPerformances) returns a level per Attribute plus an overall player level.
• Standards — takes a StandardsConfig (raw StandardsData + generation StandardsParams) and builds the full interpolatable standards table (stretching to more levels, generating missing ages/weights, etc.).
• Typebox schemas for the above (models.ts), re-exported from the package root.

Usage

StandardsConfig normally comes from the database (see apps/api/src/services/calculator.ts), not a static file, since standards configs/datasets are editable from the admin portal:

import { LevelCalculator, Standards, type StandardsConfig } from "@blade-and-brawn/calculator";

const config: StandardsConfig = /* fetched from storage */;
const calculator = new LevelCalculator(new Standards(config));

const { player, attributes } = calculator.calculate(playerMetrics, activityPerformances);

Structure

• src/index.ts — LevelCalculator and Standards
• src/models.ts — typebox schemas and types
• src/avg-weights.ts + src/data/avg-weights.json — average bodyweight by age/gender, used when generating age-based standards