@saibolla/ada 0.1.2

package/skills/stable-baselines3/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: stable-baselines3
+description: Production-ready reinforcement learning algorithms (PPO, SAC, DQN, TD3, DDPG, A2C) with scikit-learn-like API. Use for standard RL experiments, quick prototyping, and well-documented algorithm implementations. Best for single-agent RL with Gymnasium environments. For high-performance parallel training, multi-agent systems, or custom vectorized environments, use pufferlib instead.
+license: MIT license
+metadata:
+    skill-author: K-Dense Inc.
+---
+
+# Stable Baselines3
+
+## Overview
+
+Stable Baselines3 (SB3) is a PyTorch-based library providing reliable implementations of reinforcement learning algorithms. This skill provides comprehensive guidance for training RL agents, creating custom environments, implementing callbacks, and optimizing training workflows using SB3's unified API.
+
+## Core Capabilities
+
+### 1. Training RL Agents
+
+**Basic Training Pattern:**
+
+```python
+import gymnasium as gym
+from stable_baselines3 import PPO
+
+# Create environment
+env = gym.make("CartPole-v1")
+
+# Initialize agent
+model = PPO("MlpPolicy", env, verbose=1)
+
+# Train the agent
+model.learn(total_timesteps=10000)
+
+# Save the model
+model.save("ppo_cartpole")
+
+# Load the model (without prior instantiation)
+model = PPO.load("ppo_cartpole", env=env)
+```
+
+**Important Notes:**
+- `total_timesteps` is a lower bound; actual training may exceed this due to batch collection
+- Use `model.load()` as a static method, not on an existing instance
+- The replay buffer is NOT saved with the model to save space
+
+**Algorithm Selection:**
+Use `references/algorithms.md` for detailed algorithm characteristics and selection guidance. Quick reference:
+- **PPO/A2C**: General-purpose, supports all action space types, good for multiprocessing
+- **SAC/TD3**: Continuous control, off-policy, sample-efficient
+- **DQN**: Discrete actions, off-policy
+- **HER**: Goal-conditioned tasks
+
+See `scripts/train_rl_agent.py` for a complete training template with best practices.
+
+### 2. Custom Environments
+
+**Requirements:**
+Custom environments must inherit from `gymnasium.Env` and implement:
+- `__init__()`: Define action_space and observation_space
+- `reset(seed, options)`: Return initial observation and info dict
+- `step(action)`: Return observation, reward, terminated, truncated, info
+- `render()`: Visualization (optional)
+- `close()`: Cleanup resources
+
+**Key Constraints:**
+- Image observations must be `np.uint8` in range [0, 255]
+- Use channel-first format when possible (channels, height, width)
+- SB3 normalizes images automatically by dividing by 255
+- Set `normalize_images=False` in policy_kwargs if pre-normalized
+- SB3 does NOT support `Discrete` or `MultiDiscrete` spaces with `start!=0`
+
+**Validation:**
+```python
+from stable_baselines3.common.env_checker import check_env
+
+check_env(env, warn=True)
+```
+
+See `scripts/custom_env_template.py` for a complete custom environment template and `references/custom_environments.md` for comprehensive guidance.
+
+### 3. Vectorized Environments
+
+**Purpose:**
+Vectorized environments run multiple environment instances in parallel, accelerating training and enabling certain wrappers (frame-stacking, normalization).
+
+**Types:**
+- **DummyVecEnv**: Sequential execution on current process (for lightweight environments)
+- **SubprocVecEnv**: Parallel execution across processes (for compute-heavy environments)
+
+**Quick Setup:**
+```python
+from stable_baselines3.common.env_util import make_vec_env
+
+# Create 4 parallel environments
+env = make_vec_env("CartPole-v1", n_envs=4, vec_env_cls=SubprocVecEnv)
+
+model = PPO("MlpPolicy", env, verbose=1)
+model.learn(total_timesteps=25000)
+```
+
+**Off-Policy Optimization:**
+When using multiple environments with off-policy algorithms (SAC, TD3, DQN), set `gradient_steps=-1` to perform one gradient update per environment step, balancing wall-clock time and sample efficiency.
+
+**API Differences:**
+- `reset()` returns only observations (info available in `vec_env.reset_infos`)
+- `step()` returns 4-tuple: `(obs, rewards, dones, infos)` not 5-tuple
+- Environments auto-reset after episodes
+- Terminal observations available via `infos[env_idx]["terminal_observation"]`
+
+See `references/vectorized_envs.md` for detailed information on wrappers and advanced usage.
+
+### 4. Callbacks for Monitoring and Control
+
+**Purpose:**
+Callbacks enable monitoring metrics, saving checkpoints, implementing early stopping, and custom training logic without modifying core algorithms.
+
+**Common Callbacks:**
+- **EvalCallback**: Evaluate periodically and save best model
+- **CheckpointCallback**: Save model checkpoints at intervals
+- **StopTrainingOnRewardThreshold**: Stop when target reward reached
+- **ProgressBarCallback**: Display training progress with timing
+
+**Custom Callback Structure:**
+```python
+from stable_baselines3.common.callbacks import BaseCallback
+
+class CustomCallback(BaseCallback):
+    def _on_training_start(self):
+        # Called before first rollout
+        pass
+
+    def _on_step(self):
+        # Called after each environment step
+        # Return False to stop training
+        return True
+
+    def _on_rollout_end(self):
+        # Called at end of rollout
+        pass
+```
+
+**Available Attributes:**
+- `self.model`: The RL algorithm instance
+- `self.num_timesteps`: Total environment steps
+- `self.training_env`: The training environment
+
+**Chaining Callbacks:**
+```python
+from stable_baselines3.common.callbacks import CallbackList
+
+callback = CallbackList([eval_callback, checkpoint_callback, custom_callback])
+model.learn(total_timesteps=10000, callback=callback)
+```
+
+See `references/callbacks.md` for comprehensive callback documentation.
+
+### 5. Model Persistence and Inspection
+
+**Saving and Loading:**
+```python
+# Save model
+model.save("model_name")
+
+# Save normalization statistics (if using VecNormalize)
+vec_env.save("vec_normalize.pkl")
+
+# Load model
+model = PPO.load("model_name", env=env)
+
+# Load normalization statistics
+vec_env = VecNormalize.load("vec_normalize.pkl", vec_env)
+```
+
+**Parameter Access:**
+```python
+# Get parameters
+params = model.get_parameters()
+
+# Set parameters
+model.set_parameters(params)
+
+# Access PyTorch state dict
+state_dict = model.policy.state_dict()
+```
+
+### 6. Evaluation and Recording
+
+**Evaluation:**
+```python
+from stable_baselines3.common.evaluation import evaluate_policy
+
+mean_reward, std_reward = evaluate_policy(
+    model,
+    env,
+    n_eval_episodes=10,
+    deterministic=True
+)
+```
+
+**Video Recording:**
+```python
+from stable_baselines3.common.vec_env import VecVideoRecorder
+
+# Wrap environment with video recorder
+env = VecVideoRecorder(
+    env,
+    "videos/",
+    record_video_trigger=lambda x: x % 2000 == 0,
+    video_length=200
+)
+```
+
+See `scripts/evaluate_agent.py` for a complete evaluation and recording template.
+
+### 7. Advanced Features
+
+**Learning Rate Schedules:**
+```python
+def linear_schedule(initial_value):
+    def func(progress_remaining):
+        # progress_remaining goes from 1 to 0
+        return progress_remaining * initial_value
+    return func
+
+model = PPO("MlpPolicy", env, learning_rate=linear_schedule(0.001))
+```
+
+**Multi-Input Policies (Dict Observations):**
+```python
+model = PPO("MultiInputPolicy", env, verbose=1)
+```
+Use when observations are dictionaries (e.g., combining images with sensor data).
+
+**Hindsight Experience Replay:**
+```python
+from stable_baselines3 import SAC, HerReplayBuffer
+
+model = SAC(
+    "MultiInputPolicy",
+    env,
+    replay_buffer_class=HerReplayBuffer,
+    replay_buffer_kwargs=dict(
+        n_sampled_goal=4,
+        goal_selection_strategy="future",
+    ),
+)
+```
+
+**TensorBoard Integration:**
+```python
+model = PPO("MlpPolicy", env, tensorboard_log="./tensorboard/")
+model.learn(total_timesteps=10000)
+```
+
+## Workflow Guidance
+
+**Starting a New RL Project:**
+
+1. **Define the problem**: Identify observation space, action space, and reward structure
+2. **Choose algorithm**: Use `references/algorithms.md` for selection guidance
+3. **Create/adapt environment**: Use `scripts/custom_env_template.py` if needed
+4. **Validate environment**: Always run `check_env()` before training
+5. **Set up training**: Use `scripts/train_rl_agent.py` as starting template
+6. **Add monitoring**: Implement callbacks for evaluation and checkpointing
+7. **Optimize performance**: Consider vectorized environments for speed
+8. **Evaluate and iterate**: Use `scripts/evaluate_agent.py` for assessment
+
+**Common Issues:**
+
+- **Memory errors**: Reduce `buffer_size` for off-policy algorithms or use fewer parallel environments
+- **Slow training**: Consider SubprocVecEnv for parallel environments
+- **Unstable training**: Try different algorithms, tune hyperparameters, or check reward scaling
+- **Import errors**: Ensure `stable_baselines3` is installed: `uv pip install stable-baselines3[extra]`
+
+## Resources
+
+### scripts/
+- `train_rl_agent.py`: Complete training script template with best practices
+- `evaluate_agent.py`: Agent evaluation and video recording template
+- `custom_env_template.py`: Custom Gym environment template
+
+### references/
+- `algorithms.md`: Detailed algorithm comparison and selection guide
+- `custom_environments.md`: Comprehensive custom environment creation guide
+- `callbacks.md`: Complete callback system reference
+- `vectorized_envs.md`: Vectorized environment usage and wrappers
+
+## Installation
+
+```bash
+# Basic installation
+uv pip install stable-baselines3
+
+# With extra dependencies (Tensorboard, etc.)
+uv pip install stable-baselines3[extra]
+```
+

package/skills/stable-baselines3/references/algorithms.md

@@ -0,0 +1,333 @@
+# Stable Baselines3 Algorithm Reference
+
+This document provides detailed characteristics of all RL algorithms in Stable Baselines3 to help select the right algorithm for specific tasks.
+
+## Algorithm Comparison Table
+
+| Algorithm | Type | Action Space | Sample Efficiency | Training Speed | Use Case |
+|-----------|------|--------------|-------------------|----------------|----------|
+| **PPO** | On-Policy | All | Medium | Fast | General-purpose, stable |
+| **A2C** | On-Policy | All | Low | Very Fast | Quick prototyping, multiprocessing |
+| **SAC** | Off-Policy | Continuous | High | Medium | Continuous control, sample-efficient |
+| **TD3** | Off-Policy | Continuous | High | Medium | Continuous control, deterministic |
+| **DDPG** | Off-Policy | Continuous | High | Medium | Continuous control (use TD3 instead) |
+| **DQN** | Off-Policy | Discrete | Medium | Medium | Discrete actions, Atari games |
+| **HER** | Off-Policy | All | Very High | Medium | Goal-conditioned tasks |
+| **RecurrentPPO** | On-Policy | All | Medium | Slow | Partial observability (POMDP) |
+
+## Detailed Algorithm Characteristics
+
+### PPO (Proximal Policy Optimization)
+
+**Overview:** General-purpose on-policy algorithm with good performance across many tasks.
+
+**Strengths:**
+- Stable and reliable training
+- Works with all action space types (Discrete, Box, MultiDiscrete, MultiBinary)
+- Good balance between sample efficiency and training speed
+- Excellent for multiprocessing with vectorized environments
+- Easy to tune
+
+**Weaknesses:**
+- Less sample-efficient than off-policy methods
+- Requires many environment interactions
+
+**Best For:**
+- General-purpose RL tasks
+- When stability is important
+- When you have cheap environment simulations
+- Tasks with continuous or discrete actions
+
+**Hyperparameter Guidance:**
+- `n_steps`: 2048-4096 for continuous, 128-256 for Atari
+- `learning_rate`: 3e-4 is a good default
+- `n_epochs`: 10 for continuous, 4 for Atari
+- `batch_size`: 64
+- `gamma`: 0.99 (0.995-0.999 for long episodes)
+
+### A2C (Advantage Actor-Critic)
+
+**Overview:** Synchronous variant of A3C, simpler than PPO but less stable.
+
+**Strengths:**
+- Very fast training (simpler than PPO)
+- Works with all action space types
+- Good for quick prototyping
+- Memory efficient
+
+**Weaknesses:**
+- Less stable than PPO
+- Requires careful hyperparameter tuning
+- Lower sample efficiency
+
+**Best For:**
+- Quick experimentation
+- When training speed is critical
+- Simple environments
+
+**Hyperparameter Guidance:**
+- `n_steps`: 5-256 depending on task
+- `learning_rate`: 7e-4
+- `gamma`: 0.99
+
+### SAC (Soft Actor-Critic)
+
+**Overview:** Off-policy algorithm with entropy regularization, state-of-the-art for continuous control.
+
+**Strengths:**
+- Excellent sample efficiency
+- Very stable training
+- Automatic entropy tuning
+- Good exploration through stochastic policy
+- State-of-the-art for robotics
+
+**Weaknesses:**
+- Only supports continuous action spaces (Box)
+- Slower wall-clock time than on-policy methods
+- More complex hyperparameters
+
+**Best For:**
+- Continuous control (robotics, physics simulations)
+- When sample efficiency is critical
+- Expensive environment simulations
+- Tasks requiring good exploration
+
+**Hyperparameter Guidance:**
+- `learning_rate`: 3e-4
+- `buffer_size`: 1M for most tasks
+- `learning_starts`: 10000
+- `batch_size`: 256
+- `tau`: 0.005 (target network update rate)
+- `train_freq`: 1 with `gradient_steps=-1` for best performance
+
+### TD3 (Twin Delayed DDPG)
+
+**Overview:** Improved DDPG with double Q-learning and delayed policy updates.
+
+**Strengths:**
+- High sample efficiency
+- Deterministic policy (good for deployment)
+- More stable than DDPG
+- Good for continuous control
+
+**Weaknesses:**
+- Only supports continuous action spaces (Box)
+- Less exploration than SAC
+- Requires careful tuning
+
+**Best For:**
+- Continuous control tasks
+- When deterministic policies are preferred
+- Sample-efficient learning
+
+**Hyperparameter Guidance:**
+- `learning_rate`: 1e-3
+- `buffer_size`: 1M
+- `learning_starts`: 10000
+- `batch_size`: 100
+- `policy_delay`: 2 (update policy every 2 critic updates)
+
+### DDPG (Deep Deterministic Policy Gradient)
+
+**Overview:** Early off-policy continuous control algorithm.
+
+**Strengths:**
+- Continuous action space support
+- Off-policy learning
+
+**Weaknesses:**
+- Less stable than TD3 or SAC
+- Sensitive to hyperparameters
+- Generally outperformed by TD3
+
+**Best For:**
+- Legacy compatibility
+- **Recommendation:** Use TD3 instead for new projects
+
+### DQN (Deep Q-Network)
+
+**Overview:** Classic off-policy algorithm for discrete action spaces.
+
+**Strengths:**
+- Sample-efficient for discrete actions
+- Experience replay enables reuse of past data
+- Proven success on Atari games
+
+**Weaknesses:**
+- Only supports discrete action spaces
+- Can be unstable without proper tuning
+- Overestimation bias
+
+**Best For:**
+- Discrete action tasks
+- Atari games and similar environments
+- When sample efficiency matters
+
+**Hyperparameter Guidance:**
+- `learning_rate`: 1e-4
+- `buffer_size`: 100K-1M depending on task
+- `learning_starts`: 50000 for Atari
+- `batch_size`: 32
+- `exploration_fraction`: 0.1
+- `exploration_final_eps`: 0.05
+
+**Variants:**
+- **QR-DQN**: Distributional RL version for better value estimates
+- **Maskable DQN**: For environments with action masking
+
+### HER (Hindsight Experience Replay)
+
+**Overview:** Not a standalone algorithm but a replay buffer strategy for goal-conditioned tasks.
+
+**Strengths:**
+- Dramatically improves learning in sparse reward settings
+- Learns from failures by relabeling goals
+- Works with any off-policy algorithm (SAC, TD3, DQN)
+
+**Weaknesses:**
+- Only for goal-conditioned environments
+- Requires specific observation structure (Dict with "observation", "achieved_goal", "desired_goal")
+
+**Best For:**
+- Goal-conditioned tasks (robotics manipulation, navigation)
+- Sparse reward environments
+- Tasks where goal is clear but reward is binary
+
+**Usage:**
+```python
+from stable_baselines3 import SAC, HerReplayBuffer
+
+model = SAC(
+    "MultiInputPolicy",
+    env,
+    replay_buffer_class=HerReplayBuffer,
+    replay_buffer_kwargs=dict(
+        n_sampled_goal=4,
+        goal_selection_strategy="future",  # or "episode", "final"
+    ),
+)
+```
+
+### RecurrentPPO
+
+**Overview:** PPO with LSTM policy for handling partial observability.
+
+**Strengths:**
+- Handles partial observability (POMDP)
+- Can learn temporal dependencies
+- Good for memory-required tasks
+
+**Weaknesses:**
+- Slower training than standard PPO
+- More complex to tune
+- Requires sequential data
+
+**Best For:**
+- Partially observable environments
+- Tasks requiring memory (e.g., navigation without full map)
+- Time-series problems
+
+## Algorithm Selection Guide
+
+### Decision Tree
+
+1. **What is your action space?**
+   - **Continuous (Box)** → Consider PPO, SAC, or TD3
+   - **Discrete** → Consider PPO, A2C, or DQN
+   - **MultiDiscrete/MultiBinary** → Use PPO or A2C
+
+2. **Is sample efficiency critical?**
+   - **Yes (expensive simulations)** → Use off-policy: SAC, TD3, DQN, or HER
+   - **No (cheap simulations)** → Use on-policy: PPO, A2C
+
+3. **Do you need fast wall-clock training?**
+   - **Yes** → Use PPO or A2C with vectorized environments
+   - **No** → Any algorithm works
+
+4. **Is the task goal-conditioned with sparse rewards?**
+   - **Yes** → Use HER with SAC or TD3
+   - **No** → Continue with standard algorithms
+
+5. **Is the environment partially observable?**
+   - **Yes** → Use RecurrentPPO
+   - **No** → Use standard algorithms
+
+### Quick Recommendations
+
+- **Starting out / General tasks:** PPO
+- **Continuous control / Robotics:** SAC
+- **Discrete actions / Atari:** DQN or PPO
+- **Goal-conditioned / Sparse rewards:** SAC + HER
+- **Fast prototyping:** A2C
+- **Sample efficiency critical:** SAC, TD3, or DQN
+- **Partial observability:** RecurrentPPO
+
+## Training Configuration Tips
+
+### For On-Policy Algorithms (PPO, A2C)
+
+```python
+# Use vectorized environments for speed
+env = make_vec_env(env_id, n_envs=8, vec_env_cls=SubprocVecEnv)
+
+model = PPO(
+    "MlpPolicy",
+    env,
+    n_steps=2048,  # Collect this many steps per environment before update
+    batch_size=64,
+    n_epochs=10,
+    learning_rate=3e-4,
+    gamma=0.99,
+)
+```
+
+### For Off-Policy Algorithms (SAC, TD3, DQN)
+
+```python
+# Fewer environments, but use gradient_steps=-1 for efficiency
+env = make_vec_env(env_id, n_envs=4)
+
+model = SAC(
+    "MlpPolicy",
+    env,
+    buffer_size=1_000_000,
+    learning_starts=10000,
+    batch_size=256,
+    train_freq=1,
+    gradient_steps=-1,  # Do 1 gradient step per env step (4 with 4 envs)
+    learning_rate=3e-4,
+)
+```
+
+## Common Pitfalls
+
+1. **Using DQN with continuous actions** - DQN only works with discrete actions
+2. **Not using vectorized environments with PPO/A2C** - Wastes potential speedup
+3. **Using too few environments** - On-policy methods need many samples
+4. **Using too large replay buffer** - Can cause memory issues
+5. **Not tuning learning rate** - Critical for stable training
+6. **Ignoring reward scaling** - Normalize rewards for better learning
+7. **Wrong policy type** - Use "CnnPolicy" for images, "MultiInputPolicy" for dict observations
+
+## Performance Benchmarks
+
+Approximate expected performance (mean reward) on common benchmarks:
+
+### Continuous Control (MuJoCo)
+- **HalfCheetah-v3**: PPO ~1800, SAC ~12000, TD3 ~9500
+- **Hopper-v3**: PPO ~2500, SAC ~3600, TD3 ~3600
+- **Walker2d-v3**: PPO ~3000, SAC ~5500, TD3 ~5000
+
+### Discrete Control (Atari)
+- **Breakout**: PPO ~400, DQN ~300
+- **Pong**: PPO ~20, DQN ~20
+- **Space Invaders**: PPO ~1000, DQN ~800
+
+*Note: Performance varies significantly with hyperparameters and training time.*
+
+## Additional Resources
+
+- **RL Baselines3 Zoo**: Collection of pre-trained agents and hyperparameters: https://github.com/DLR-RM/rl-baselines3-zoo
+- **Hyperparameter Tuning**: Use Optuna for systematic tuning
+- **Custom Policies**: Extend base policies for custom network architectures
+- **Contribution Repo**: SB3-Contrib for experimental algorithms (QR-DQN, TQC, etc.)