Readme and comments and reward pdated

readme was outdated
env rewards got a penalty for standing still while it should move instead of 0 reward

ml/MetricsOverlay.py

@@ -1,5 +1,9 @@
 """
-ml/MetricsOverlay.py - Camera-Facing (Billboard) 3D Floating Text Overlay
+ml/MetricsOverlay.py - 3D HUD overlay for live simulation telemetry.
+
+This file provides a small PyBullet HUD renderer that draws live robot metrics in the
+simulation scene. It is used during GUI runs to show the current phase, command vector,
+reward information, and basic motion statistics without leaving the 3D view.
 """
 from typing import List, Tuple, Optional, Dict
 import numpy as np

ml/callbacks.py

@@ -1,6 +1,9 @@
 """
-ml/callbacks.py - Stable-Baselines3 Custom Callbacks for Logging & Curriculum Advancement
-Fully compatible with SubprocVecEnv and DummyVecEnv.
+ml/callbacks.py - Stable-Baselines3 callbacks for training diagnostics.
+
+These callbacks extend SB3 training with two responsibilities: logging reward-component
+statistics for TensorBoard/console output, and checking whether the curriculum should
+advance to a harder set of commands based on recent training performance.
 """
 
 import numpy as np

ml/env.py

@@ -1,5 +1,10 @@
 """
-ml/env.py - Gymnasium Environment for JackBot Hexapod RL Training
+ml/env.py - Gymnasium environment for JackBot RL training and evaluation.
+
+This file defines JackBotEnv, the main training/evaluation environment used by PPO.
+It wraps the PyBullet simulation and Robot interfaces into a Gymnasium-compatible
+step/reset loop, manages command sampling, curriculum progression, and reward
+calculation, and exposes metrics that the training callbacks can log.
 """
 import time
 import math
@@ -363,7 +368,10 @@ class JackBotEnv(gym.Env):
             target_speed = math.hypot(target_vx, target_vy)
 
             if not is_moving:
-                total_reward = 0.0
+                # If the command says move but the robot stays effectively still,
+                # give a real penalty instead of a neutral reward.
+                stillness_penalty = -0.10
+                total_reward = stillness_penalty
             else:
                 lin_vel_error = (filtered_vx - target_vx)**2 + (filtered_vy - target_vy)**2
                 r_lin_vel = math.exp(-25.0 * lin_vel_error)
@@ -371,7 +379,7 @@ class JackBotEnv(gym.Env):
 
                 if target_speed > 0.08 and raw_speed < 0.03:
                     r_lin_vel = 0.0
-                    stillness_penalty = -0.1  # Softened from -0.25
+                    stillness_penalty = -0.05
 
                 w_lin_vel, w_ang_vel, w_height, w_stability, w_smoothness = 0.55, 0.15, 0.10, 0.12, 0.08
                 total_reward = (
@@ -381,7 +389,7 @@ class JackBotEnv(gym.Env):
 
         step_reward = float(total_reward / 10.0)
         alive_bonus = 0.01
-        final_reward = max(0.0, step_reward + jitter_penalty + alive_bonus)
+        final_reward = step_reward + jitter_penalty + alive_bonus
 
         self.last_reward_components = {
             "height": float(r_height),

ml/pretrain_bc.py

@@ -1,5 +1,10 @@
 """
-ml/pretrain_bc.py - Behavioral Cloning from Kinematics Teacher
+ml/pretrain_bc.py - Behavioral Cloning teacher-data pipeline.
+
+This script collects observation/action pairs from the kinematics solver, then uses
+those pairs as training data for a PPO policy. In practice it serves as a teacher-
+student pretraining step: the kinematics controller generates sample trajectories, and
+this file teaches the policy to imitate those behavior patterns before PPO training.
 """
 import sys
 import time

ml/run_eval.py

@@ -1,6 +1,10 @@
 """
-ml/run_eval.py - Phase-by-Phase Policy Evaluator for JackBot
-Evaluates a trained model across all curriculum phases with fixed command vectors.
+ml/run_eval.py - Evaluate a saved JackBot policy across fixed command phases.
+
+This script loads a trained PPO checkpoint, instantiates the Gymnasium environment in
+non-random mode, and runs deterministic evaluation episodes for several command
+regimes. It is used to measure whether a policy can survive, move, and maintain
+stability under forward, turning, lateral, and omni-direction commands.
 """
 
 import argparse

ml/run_eval_training.py

@@ -1,5 +1,10 @@
 """
-ml/run_eval_training.py - Benchmark reward system across all curriculum phases.
+ml/run_eval_training.py - Run a kinematics-mode reward benchmark.
+
+This script repeatedly resets the JackBot environment in kinematics mode and applies
+fixed command vectors for each curriculum phase. It is intended as a lightweight
+benchmark to inspect reward components, movement quality, and survival behavior without
+requiring an already-trained PPO model.
 """
 import time
 import numpy as np

ml/run_train.py

@@ -1,4 +1,9 @@
-"""Minimal training launcher for quick experiments.
+"""PPO training launcher for JackBot.
+
+This script is the main entry point for training a policy in the JackBot Gymnasium
+environment. It creates a vectorized environment, optionally loads a pretrained base
+model, runs Stable-Baselines3 PPO for a configured number of timesteps, and saves
+checkpoints plus evaluation artifacts during training.
 
 Usage:
     python ml/run_train.py --total-timesteps 1500000 --gui