AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Random Number Agent Guide

Agent guide for crypto-backed integer generation, count clamping, uniqueness, and rejection sampling.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Random Number in the alexandrai-tools project.

Project overview

This guide covers src/tools/random-number/index.ts. The tool returns random integers in an inclusive range, silently swaps min and max when needed, uses rejection sampling to avoid modulo bias, clamps count to one through one thousand, and supports unique draws through a partial Fisher-Yates shuffle.

Primary source files

  • src/tools/random-number/index.ts defines meta, randomInt, and randomMany.
  • src/tools/random-number/index.test.ts covers ranges, equal min and max, swapped arguments, count clamping, uniqueness, and in-range values.
  • src/tools/random-number/Body.astro owns browser inputs.
  • src/tools/random-number/i18n.ts owns localized copy.
  • src/lib/tools.ts registers metadata.

Setup commands

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

Change rules

  • Keep randomInt inclusive of both min and max.
  • Keep min and max swapping behavior stable.
  • Preserve rejection sampling to avoid modulo bias.
  • Clamp randomMany count to the established range.
  • When unique is true, clamp requested count to the range size.
  • Do not replace Web Crypto with Math.random.
  • If decimal generation is added, keep it separate from integer behavior.

Testing

Test inclusive bounds, equal bounds, swapped bounds, non-unique count, unique count clamping, no duplicates in unique mode, maximum count clamp, negative ranges, and any decimal mode if added.

PR checklist

  • npm test passes for random-number.
  • Web Crypto remains the random source.
  • Input lists or generated values stay browser-local.
  • Current clamping and empty-input semantics remain documented.