AGENTS.md

Guidance for coding agents working on AlexandrAI Tools BAC Calculator in the alexandrai-tools project.

Project overview

This guide covers src/tools/bac-calculator. calcBac estimates blood alcohol content from standard drinks, volume, ABV, weight, sex, and elapsed hours using Widmark distribution ratios, subtracts a fixed hourly metabolism amount, rounds to three decimals, and clamps negative output to zero. The module also includes fluid-ounce to millilitre and pound to kilogram conversion helpers.

Primary source files

• src/tools/bac-calculator/index.ts defines meta, Sex, Widmark ratios, calcBac, flOzToMl, and lbToKg.
• src/tools/bac-calculator/index.test.ts covers a known scenario, metabolism clamping, sex ratio differences, zero input guards, fluid-ounce conversion, and pound conversion.
• src/tools/bac-calculator/Body.astro owns user inputs and result presentation.
• src/tools/bac-calculator/i18n.ts owns localized labels and warning copy.
• src/lib/tools.ts registers the tool metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

• Return zero for non-positive drinks, drink volume, ABV, or body weight.
• Use sex-specific Widmark ratios from the R map.
• Clamp elapsed hours at zero before subtracting metabolism.
• Round BAC to three decimals.
• Clamp final BAC to zero or greater.
• Keep unit conversions pure and separately tested.
• Keep safety copy clear: this is informational and must not imply legal or driving clearance.

Testing

Test known BAC scenarios, male and female ratio differences, elapsed-time clamping, all zero guards, negative inputs if UI can send them, unit conversions, rounding boundaries, and safety warning copy.

PR checklist

• npm test passes for bac-calculator.
• Calculator formulas, units, and rounding rules are documented.
• Health and fitness outputs keep informational safety scope.
• UI labels, validation, and pure helper tests stay aligned.