@inventure71/paddockjs 4.1.0 → 4.2.0

package/examples/train-basic-policy.mjs

@@ -1,276 +0,0 @@
-#!/usr/bin/env node
-
-import { createPaddockEnvironment, createProgressReward } from '@inventure71/paddockjs/environment';
-import { TRAINING_DEMO_DRIVERS, TRAINING_DEMO_ENTRIES } from './trainingData.mjs';
-
-const DEFAULT_OPTIONS = Object.freeze({
-  generations: 4,
-  candidates: 5,
-  episodes: 1,
-  steps: 240,
-  frameSkip: 4,
-  seed: 71,
-  traffic: false,
-  evalOnly: false,
-});
-
-const INITIAL_POLICY = Object.freeze({
-  steeringHeading: -1.2,
-  steeringOffset: -0.35,
-  steeringRayBalance: 0.45,
-  throttleBias: 0.72,
-  throttleFrontClearance: 0.28,
-  throttleSpeedDamping: 0.18,
-  brakeBias: 0,
-  brakeFrontDanger: 0.65,
-  brakeOffTrack: 0.2,
-});
-
-const POLICY_KEYS = Object.keys(INITIAL_POLICY);
-
-main();
-
-function main() {
-  const options = parseCliArgs(process.argv.slice(2));
-  if (options.help) {
-    printHelp();
-    return;
-  }
-
-  const driverId = TRAINING_DEMO_DRIVERS[0].id;
-  const rng = createSeededRandom(options.seed);
-  const reward = createProgressReward();
-  const evaluate = (policy, seedOffset = 0) => evaluatePolicy({
-    policy,
-    driverId,
-    reward,
-    options,
-    seedOffset,
-  });
-
-  if (options.evalOnly) {
-    const baseline = evaluate(INITIAL_POLICY);
-    printSummary({ options, driverId, bestPolicy: INITIAL_POLICY, best: baseline });
-    return;
-  }
-
-  let bestPolicy = { ...INITIAL_POLICY };
-  let best = evaluate(bestPolicy);
-
-  console.log(formatGenerationLine(0, best));
-
-  for (let generation = 1; generation <= options.generations; generation += 1) {
-    const mutationScale = 0.45 / Math.sqrt(generation);
-    const candidates = [{ policy: bestPolicy, scoreSeedOffset: generation * 1000 }];
-
-    for (let index = 1; index < options.candidates; index += 1) {
-      candidates.push({
-        policy: mutatePolicy(bestPolicy, rng, mutationScale),
-        scoreSeedOffset: generation * 1000 + index * 100,
-      });
-    }
-
-    for (const candidate of candidates) {
-      const score = evaluate(candidate.policy, candidate.scoreSeedOffset);
-      if (score.averageReward > best.averageReward) {
-        best = score;
-        bestPolicy = candidate.policy;
-      }
-    }
-
-    console.log(formatGenerationLine(generation, best));
-  }
-
-  printSummary({ options, driverId, bestPolicy, best });
-}
-
-function evaluatePolicy({ policy, driverId, reward, options, seedOffset = 0 }) {
-  let totalReward = 0;
-  let totalDistanceMeters = 0;
-  let totalCollisions = 0;
-  let totalOffTrackSteps = 0;
-  let completedEpisodes = 0;
-
-  for (let episode = 0; episode < options.episodes; episode += 1) {
-    const env = createTrainingEnvironment({ driverId, reward, options, episode, seedOffset });
-    let result = env.reset();
-    let episodeReward = 0;
-
-    for (let step = 0; step < options.steps && !result.done; step += 1) {
-      const observation = result.observation[driverId];
-      const action = chooseAction(policy, observation);
-      result = env.step({ [driverId]: action });
-      episodeReward += result.reward?.[driverId] ?? 0;
-      totalCollisions += result.events.filter((event) => event.type === 'collision').length;
-      if (result.observation[driverId]?.object?.self?.onTrack === false) totalOffTrackSteps += 1;
-    }
-
-    const car = result.state.snapshot.cars.find((entry) => entry.id === driverId);
-    totalReward += episodeReward;
-    totalDistanceMeters += Number(car?.distanceMeters ?? 0);
-    completedEpisodes += 1;
-    env.destroy();
-  }
-
-  return {
-    averageReward: totalReward / Math.max(1, completedEpisodes),
-    averageDistanceMeters: totalDistanceMeters / Math.max(1, completedEpisodes),
-    collisions: totalCollisions,
-    offTrackSteps: totalOffTrackSteps,
-  };
-}
-
-function createTrainingEnvironment({ driverId, reward, options, episode, seedOffset }) {
-  const drivers = options.traffic ? TRAINING_DEMO_DRIVERS.slice(0, 8) : TRAINING_DEMO_DRIVERS.slice(0, 1);
-  return createPaddockEnvironment({
-    drivers,
-    entries: TRAINING_DEMO_ENTRIES,
-    controlledDrivers: [driverId],
-    seed: options.seed + seedOffset + episode,
-    trackSeed: options.seed + 2026 + seedOffset + episode,
-    totalLaps: 3,
-    frameSkip: options.frameSkip,
-    scenario: {
-      participants: options.traffic ? 'all' : 'controlled-only',
-      nonControlled: 'ai',
-    },
-    episode: {
-      maxSteps: options.steps,
-      endOnRaceFinish: true,
-    },
-    rules: {
-      standingStart: false,
-    },
-    reward,
-  });
-}
-
-function chooseAction(policy, observation) {
-  const self = observation.object.self;
-  const frontRay = getRayDistance(observation, 0);
-  const leftRay = getRayDistance(observation, -60);
-  const rightRay = getRayDistance(observation, 60);
-  const frontDanger = clamp01((35 - frontRay) / 35);
-  const rayBalanceMeters = rightRay - leftRay;
-
-  const steering = clamp(
-    policy.steeringHeading * self.trackHeadingErrorRadians +
-      policy.steeringOffset * (self.trackOffsetMeters / 12) +
-      policy.steeringRayBalance * (rayBalanceMeters / 120),
-    -1,
-    1,
-  );
-  const throttle = clamp01(
-    policy.throttleBias +
-      policy.throttleFrontClearance * (frontRay / 120) -
-      policy.throttleSpeedDamping * (self.speedKph / 320) -
-      (self.onTrack ? 0 : 0.35),
-  );
-  const brake = clamp01(
-    policy.brakeBias +
-      policy.brakeFrontDanger * frontDanger +
-      (self.onTrack ? 0 : policy.brakeOffTrack),
-  );
-
-  return { steering, throttle, brake };
-}
-
-function getRayDistance(observation, angleDegrees) {
-  const ray = observation.object.rays.find((entry) => entry.angleDegrees === angleDegrees);
-  return Number(ray?.track?.distanceMeters ?? ray?.lengthMeters ?? 120);
-}
-
-function mutatePolicy(policy, rng, scale) {
-  return Object.fromEntries(POLICY_KEYS.map((key) => [
-    key,
-    policy[key] + randomNormal(rng) * scale,
-  ]));
-}
-
-function parseCliArgs(argv) {
-  const options = { ...DEFAULT_OPTIONS };
-
-  for (const arg of argv) {
-    const [name, rawValue] = arg.split('=');
-    if (name === '--help' || name === '-h') options.help = true;
-    else if (name === '--eval-only') options.evalOnly = true;
-    else if (name === '--traffic') options.traffic = true;
-    else if (name === '--no-traffic') options.traffic = false;
-    else if (name === '--generations') options.generations = parsePositiveInt(rawValue, name);
-    else if (name === '--candidates') options.candidates = parsePositiveInt(rawValue, name);
-    else if (name === '--episodes') options.episodes = parsePositiveInt(rawValue, name);
-    else if (name === '--steps') options.steps = parsePositiveInt(rawValue, name);
-    else if (name === '--frame-skip') options.frameSkip = parsePositiveInt(rawValue, name);
-    else if (name === '--seed') options.seed = parsePositiveInt(rawValue, name);
-    else throw new Error(`Unknown option: ${name}`);
-  }
-
-  return options;
-}
-
-function parsePositiveInt(value, optionName) {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new Error(`${optionName} requires a positive integer value.`);
-  }
-  return parsed;
-}
-
-function createSeededRandom(seed) {
-  let state = seed >>> 0;
-  return function random() {
-    state += 0x6D2B79F5;
-    let value = state;
-    value = Math.imul(value ^ (value >>> 15), value | 1);
-    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
-    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
-function randomNormal(rng) {
-  const a = Math.max(Number.EPSILON, rng());
-  const b = Math.max(Number.EPSILON, rng());
-  return Math.sqrt(-2 * Math.log(a)) * Math.cos(2 * Math.PI * b);
-}
-
-function clamp(value, min, max) {
-  return Math.min(max, Math.max(min, value));
-}
-
-function clamp01(value) {
-  return clamp(value, 0, 1);
-}
-
-function formatGenerationLine(generation, score) {
-  return [
-    `generation=${generation}`,
-    `reward=${score.averageReward.toFixed(2)}`,
-    `distanceMeters=${score.averageDistanceMeters.toFixed(1)}`,
-    `collisions=${score.collisions}`,
-    `offTrackSteps=${score.offTrackSteps}`,
-  ].join(' ');
-}
-
-function printSummary({ options, driverId, bestPolicy, best }) {
-  console.log(JSON.stringify({
-    driverId,
-    options,
-    best,
-    bestPolicy,
-  }, null, 2));
-}
-
-function printHelp() {
-  console.log(`Usage: node examples/train-basic-policy.mjs [options]
-
-Options:
-  --generations=N   Random-search generations. Default: ${DEFAULT_OPTIONS.generations}
-  --candidates=N    Candidate policies per generation. Default: ${DEFAULT_OPTIONS.candidates}
-  --episodes=N      Episodes per policy evaluation. Default: ${DEFAULT_OPTIONS.episodes}
-  --steps=N         Maximum manual environment steps per episode. Default: ${DEFAULT_OPTIONS.steps}
-  --frame-skip=N    Simulator frames advanced by each step(action). Default: ${DEFAULT_OPTIONS.frameSkip}
-  --seed=N          Deterministic random seed. Default: ${DEFAULT_OPTIONS.seed}
-  --traffic         Keep built-in AI traffic on track during training.
-  --eval-only       Evaluate the starter policy without training.
-`);
-}

package/examples/trainingData.mjs

@@ -1,133 +0,0 @@
-export const TRAINING_DEMO_DRIVERS = [
-  {
-    id: 'budget',
-    code: 'BUD',
-    icon: 'BB',
-    name: 'Budget Buddy',
-    color: '#ff2d55',
-    tire: 'M',
-    raceData: ['AI finance coach', 'Python + LLM', 'Budget guardrails'],
-  },
-  {
-    id: 'noir',
-    code: 'NOI',
-    icon: 'NN',
-    name: 'Neural Noir',
-    color: '#ffb000',
-    tire: 'M',
-    raceData: ['Procedural mystery', 'Gemini storytelling', 'Unreal loop'],
-  },
-  {
-    id: 'vinyl',
-    code: 'HOL',
-    icon: 'HV',
-    name: 'HoloVinyl',
-    color: '#00c2a8',
-    tire: 'H',
-    raceData: ['Touchless DJ control', 'Computer vision', 'Hand tracking'],
-  },
-  {
-    id: 'drsorriso',
-    code: 'DRS',
-    icon: 'DR',
-    name: 'DrSorrisoDonations',
-    color: '#e10600',
-    tire: 'S',
-    raceData: ['Donation intake', 'Database workflow', 'Automation tool'],
-  },
-  {
-    id: 'victoria',
-    code: 'VIC',
-    icon: 'VI',
-    name: 'VictorIA',
-    color: '#00a3ff',
-    tire: 'M',
-    raceData: ['Game AI sandbox', 'Robotics ideas', 'Vision systems'],
-  },
-  {
-    id: 'reminderz',
-    code: 'REM',
-    icon: 'RZ',
-    name: 'ReminderZ',
-    color: '#a3e635',
-    tire: 'H',
-    raceData: ['Knowledge workflow', 'Personal graph', 'Capture tool'],
-  },
-  {
-    id: 'clipclop',
-    code: 'CLP',
-    icon: 'CC',
-    name: 'ClipClop',
-    color: '#f97316',
-    tire: 'S',
-    raceData: ['Mac + Android sync', 'Local clipboard', 'Productivity app'],
-  },
-  {
-    id: 'core',
-    code: 'COR',
-    icon: 'AI',
-    name: 'Core Conflict',
-    color: '#38bdf8',
-    tire: 'M',
-    raceData: ['Runtime AI agents', 'Multiplayer state', 'Game systems'],
-  },
-];
-
-export const TRAINING_DEMO_ENTRIES = [
-  {
-    driverId: 'budget',
-    driverNumber: 71,
-    timingName: 'Budget',
-    driver: { pace: 52, racecraft: 74, aggression: 38, riskTolerance: 47, patience: 81, consistency: 86 },
-    vehicle: { id: 'budget-bb01', name: 'BB-01 Ledger', power: 48, braking: 72, aero: 55, dragEfficiency: 66, mechanicalGrip: 63, weightControl: 58, tireCare: 82 },
-  },
-  {
-    driverId: 'noir',
-    driverNumber: 13,
-    timingName: 'Noir',
-    driver: { pace: 68, racecraft: 83, aggression: 61, riskTolerance: 72, patience: 57, consistency: 64 },
-    vehicle: { id: 'noir-nn13', name: 'NN-13 Shadow', power: 64, braking: 60, aero: 73, dragEfficiency: 57, mechanicalGrip: 69, weightControl: 54, tireCare: 51 },
-  },
-  {
-    driverId: 'vinyl',
-    driverNumber: 33,
-    timingName: 'HoloVinyl',
-    driver: { pace: 71, racecraft: 66, aggression: 52, riskTolerance: 59, patience: 62, consistency: 58 },
-    vehicle: { id: 'vinyl-hv33', name: 'HV-33 Groove', power: 70, braking: 49, aero: 58, dragEfficiency: 74, mechanicalGrip: 52, weightControl: 68, tireCare: 46 },
-  },
-  {
-    driverId: 'drsorriso',
-    driverNumber: 55,
-    timingName: 'DrSorriso',
-    driver: { pace: 46, racecraft: 69, aggression: 44, riskTolerance: 43, patience: 76, consistency: 73 },
-    vehicle: { id: 'sorriso-ds55', name: 'DS-55 Intake', power: 54, braking: 67, aero: 62, dragEfficiency: 49, mechanicalGrip: 71, weightControl: 45, tireCare: 69 },
-  },
-  {
-    driverId: 'victoria',
-    driverNumber: 11,
-    timingName: 'VictorIA',
-    driver: { pace: 78, racecraft: 79, aggression: 58, riskTolerance: 65, patience: 55, consistency: 68 },
-    vehicle: { id: 'victoria-vi11', name: 'VI-11 Vector', power: 76, braking: 58, aero: 65, dragEfficiency: 63, mechanicalGrip: 61, weightControl: 60, tireCare: 48 },
-  },
-  {
-    driverId: 'reminderz',
-    driverNumber: 7,
-    timingName: 'ReminderZ',
-    driver: { pace: 41, racecraft: 61, aggression: 34, riskTolerance: 39, patience: 85, consistency: 80 },
-    vehicle: { id: 'reminderz-rz07', name: 'RZ-07 Recall', power: 42, braking: 76, aero: 50, dragEfficiency: 72, mechanicalGrip: 58, weightControl: 63, tireCare: 88 },
-  },
-  {
-    driverId: 'clipclop',
-    driverNumber: 14,
-    timingName: 'ClipClop',
-    driver: { pace: 73, racecraft: 88, aggression: 76, riskTolerance: 78, patience: 48, consistency: 61 },
-    vehicle: { id: 'clipclop-cc14', name: 'CC-14 Sync', power: 68, braking: 63, aero: 59, dragEfficiency: 61, mechanicalGrip: 78, weightControl: 56, tireCare: 44 },
-  },
-  {
-    driverId: 'core',
-    driverNumber: 91,
-    timingName: 'Core',
-    driver: { pace: 82, racecraft: 85, aggression: 67, riskTolerance: 74, patience: 53, consistency: 72 },
-    vehicle: { id: 'core-ai91', name: 'AI-91 Core', power: 80, braking: 61, aero: 72, dragEfficiency: 59, mechanicalGrip: 75, weightControl: 51, tireCare: 50 },
-  },
-];