### Training and Evaluation Setup

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Instructions on configuring weights and biases logging and running training scripts for Metamon agents, including examples for training from scratch.

```APIDOC
## Training and Evaluation

### Description
Metamon leverages the `amago` library for training and evaluation of RL and IL models. This section provides guidance on setting up `wandb` for logging and details how to execute training scripts for various agent configurations.

### Configuring `wandb` Logging (Optional)
To enable `wandb` logging for tracking experiments, set the following environment variables:

```bash
cd metamon/rl/
export METAMON_WANDB_PROJECT="my_wandb_project_name"
export METAMON_WANDB_ENTITY="my_wandb_username"
```

### Training from Scratch
The `train.py` script in `metamon/rl/` handles offline RL training on battle datasets, including optional self-play data. Use `python train.py --help` to see all available command-line options.

#### Example: Training a Small IL Agent
To retrain the "`SmallIL`" model, use a command similar to this:

```bash
python -m metamon.rl.train --run_name AnyNameHere --model_gin_config small_agent.gin --train_gin_config il.gin --save_dir ~/my_checkpoint_path/ --log
```

For training a "`SmallRL`" agent, replace `--train_gin_config il.gin` with `--train_gin_config exp_rl.gin`. Pre-trained agent configurations can be found in `rl/pretrained.py`.

Larger training runs can take several days and optionally utilize multiple GPUs. Refer to the `amago` documentation for multi-GPU setup details. A configuration example for a smaller RNN can be found in `small_rnn.gin`.
```

--------------------------------

### Verify Metamon Installation

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Runs test battles using the Metamon environment to confirm that the installation and server setup are functioning correctly.

```bash
python -m metamon.env
```

--------------------------------

### Install Pokémon Showdown Dependencies

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Installs the necessary Node.js dependencies for the Pokémon Showdown server used by Metamon.

```shell
cd server/pokemon-showdown
npm install
```

--------------------------------

### Start Pokémon Showdown Server

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Starts the local Pokémon Showdown server in the background, disabling security features for easier integration with Metamon.

```shell
# in the background (`screen`, etc.)
node pokemon-showdown start --no-security
```

--------------------------------

### Metamon Installation

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Installs Metamon and its dependencies from a cloned Git repository using pip, making the package available in the active Python environment.

```shell
git clone --recursive git@github.com:UT-Austin-RPL/metamon.git
cd metamon
pip install -e .
```

--------------------------------

### Run Metamon IL Training

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Provides a command-line interface for training IL (Imitation Learning) agents using Metamon. This command starts the IL training process, allowing agents to learn from expert demonstrations.

```bash
python -m metamon.il.train
```

--------------------------------

### Conda Environment Setup

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Sets up a dedicated Conda environment for Metamon with Python 3.10, ensuring dependency isolation for the project.

```shell
conda create -n metamon python==3.10
conda activate metamon
```

--------------------------------

### Load Reconstructed Human Demonstrations

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Loads a dataset of reconstructed human demonstrations from replay files. This PyTorch dataset converts examples to the specified observation, action, and reward formats on-the-fly, enabling training on offline data.

```python
from metamon.data import ParsedReplayDataset
# pytorch dataset. examples are converted to 
# the chosen obs/actions/rewards on-the-fly.offline_dset = ParsedReplayDataset(
    observation_space=obs_space,
    action_space=action_space,
    reward_function=reward_func,
    formats=["gen1ou"],
)
obs_seq, action_seq, reward_seq, done_seq = offline_dset[0]
```

--------------------------------

### Tokenization and Observation Spaces

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Details on tokenizing text observations into fixed-length integer IDs using predefined vocabularies. Includes examples of creating tokenized observation spaces and lists available tokenizer versions.

```APIDOC
## Tokenization and Observation Spaces

### Description
Text features often have inconsistent lengths. Metamon addresses this by translating them into integer IDs using a list of known vocabulary words. The built-in observation spaces are designed to ensure that the "tokenized" version always has a fixed length.

### Available Tokenizers

| Tokenizer Name             | Description                                                                    |
|----------------------------|--------------------------------------------------------------------------------|
| `allreplays-v3`            | Legacy version for pre-release models.                                         |
| `DefaultObservationSpace-v0` | Updated post-release vocabulary as of `metamon-parsed-replays` dataset `v2`. |
| `DefaultObservationSpace-v1` | Updated vocabulary as of `metamon-parsed-replays` dataset `v3-beta` (adds ~1k words for Gen 9). |

### Code Example
```python
from metamon.interface import TokenizedObservationSpace, DefaultObservationSpace
from metamon.tokenizer import get_toknenizer

base_obs = DefaultObservationSpace()
tokenized_space = TokenizedObservationSpace(
    base_obs_space=base_obs,
    tokenizer=get_tokenizer("DefaultObservationSpace-v0"),
)
```
```

--------------------------------

### Sample Revealed Team Format (Text)

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

An example of the 'partially revealed' team format used by Metamon. It includes placeholders like '$missing_ev$' and '$missing_move$' for elements not yet known.

```text
Tyranitar @ Custap Berry
Ability: Sand Stream
EVs: $missing_ev$ HP / $missing_ev$ Atk / $missing_ev$ Def / $missing_ev$ SpA / $missing_ev$ SpD / $missing_ev$ Spe
$missing_nature$ Nature
IVs: 31 HP / 31 Atk / 31 Def / 31 SpA / 31 SpD / 31 Spe
- Stealth Rock
- Stone Edge
- Pursuit
- $missing_move$
```

--------------------------------

### Train Toy IL Model with Transformer Embedding

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Starts a toy IL (behavior cloning with RNNs) training process. Requires specifying a run name, model configuration, and GPU. This is a deprecated module for early learning-based baselines.

```shell
cd metamon/il/
python train.py --run_name any_name_will_do --model_config configs/transformer_embedding.gin  --gpu 0
```

--------------------------------

### Get Metamon Baselines

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Retrieve specific baseline opponents by name or list all available baseline opponent names using the metamon.baselines module. These functions are essential for selecting and interacting with pre-defined AI opponents.

```python
from metamon.baselines import get_baseline, get_all_baseline_names

opponent = get_baseline(name)  # Get specific baseline
available = get_all_all_baseline_names()  # List all available baselines
```

--------------------------------

### Get Metamon Teams by Format and Set Name

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Python function to retrieve Metamon team sets for a specified battle format and set name. Different set names ('competitive', 'paper_variety', 'paper_replays', 'modern_replays') offer varying team compositions and origins.

```python
metamon.env.get_metamon_teams(battle_format : str, set_name : str)
```

--------------------------------

### Get Usage Statistics for Pokemon Battles

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Retrieves usage statistics for Pokemon battles within a specified date range for a given format. These stats record the frequency of team choices (items, moves, abilities) and are used for rule changes and predicting team details. Data can be retrieved using the `get_usage_stats` function.

```python
from metamon.backend.team_prediction.usage_stats import get_usage_stats
from datetime import date
usage_stats = get_usage_stats("gen1ou",
    start_date=date(2017, 12, 1),
    end_date=date(2018, 3, 30)
)
alakazam_info: dict = usage_stats["Alakazam"] # non alphanum chars and case are flexible
```

--------------------------------

### Run Metamon RL Training

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Provides a command-line interface for training RL agents using Metamon. This command initiates the training process, potentially using pretrained models or custom configurations.

```bash
python -m metamon.rl.train
```

--------------------------------

### Initialize Metamon Environment Components

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Sets up the necessary components for a Metamon environment, including Pokémon teams, observation space, reward function, and action space. These are fundamental for creating any Metamon-based RL environment.

```python
from metamon.env import get_metamon_teams
from metamon.interface import DefaultObservationSpace, DefaultShapedReward, DefaultActionSpace

team_set = get_metamon_teams("gen1ou", "competitive")
obs_space = DefaultObservationSpace()
reward_fn = DefaultShapedReward()
action_space = DefaultActionSpace()
```

--------------------------------

### Train Model from Scratch with Metamon and Amago (Bash)

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Illustrates how to initiate training for a Metamon agent using the amago library. This command specifies run name, model configuration, training configuration, save directory, and enables logging. It's suitable for both offline RL and self-play data.

```bash
python -m metamon.rl.train --run_name AnyNameHere --model_gin_config small_agent.gin --train_gin_config il.gin --save_dir ~/my_checkpoint_path/ --log
```

--------------------------------

### Configure PokéAgent Challenge Environment

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Shows how to use `metamon.env.PokeAgentLadder` to interact with the PokéAgent Challenge ladder. It requires providing player username and password for authentication, similar to `QueueOnLocalLadder`.

```python
from metamon.env import PokeAgentLadder

# Assuming obs_space, action_space, reward_fn, team_set are initialized
env = PokeAgentLadder(
    battle_format="gen1ou", # Example format
    player_username="PAC_YourUsername",
    player_password="your_password",
    num_battles=5, # Example number of battles
    observation_space=obs_space,
    action_space=action_space,
    reward_function=reward_fn,
    player_team_set=team_set,
)
```

--------------------------------

### Metamon Battle Backend Integration (Python)

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Demonstrates how to switch the battle backend to 'metamon' in Metamon environments. This utilizes the poke-env library for communication with Pokémon Showdown.

```python
env = make("pokemon-showdown", battle_backend="metamon")
```

--------------------------------

### Download Parsed Replays Dataset (CLI)

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Command-line interface command to download the 'parsed-replays' dataset. This dataset is crucial for RL training and contains reconstructed battle trajectories.

```python
python -m metamon.data.download parsed-replays
```

--------------------------------

### Initialize Tokenized Observation Space in Python

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Demonstrates how to create a tokenized observation space using Metamon's interface. It involves initializing a base observation space and then wrapping it with TokenizedObservationSpace, specifying a tokenizer.

```python
from metamon.interface import TokenizedObservationSpace, DefaultObservationSpace
from metamon.tokenizer import get_toknenizer

base_obs = DefaultObservationSpace()
tokenized_space = TokenizedObservationSpace(
    base_obs_space=base_obs,
    tokenizer=get_tokenizer("DefaultObservationSpace-v0"),
)
```

--------------------------------

### Action Spaces

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Explains the UniversalAction space and different ActionSpace implementations for converting policy outputs into discrete actions, including support for different Pokémon generations.

```APIDOC
## Action Spaces

### Description
Metamon utilizes a fixed `UniversalAction` space comprising 13 discrete choices. These choices cover Pokémon moves, switches, and generation-specific gimmicks. The `ActionSpace` class provides an interface to convert the output of a reinforcement learning policy into this universal action format, supporting various game generations.

### UniversalAction Space Breakdown
- `{0, 1, 2, 3}`: Use the active Pokémon's moves in alphabetical order.
- `{4, 5, 6, 7, 8}`: Switch to the other Pokémon in the party in alphabetical order.
- `{9, 10, 11, 12}`: Wildcards for generation-specific gimmicks (currently Gen 9), applying moves with terastallization.

### Available Action Spaces

| Action Space             | Description                                                                                   |
|--------------------------|-----------------------------------------------------------------------------------------------|
| `DefaultActionSpace`     | Standard discrete space of 13 actions, supporting Gen 9.                                      |
| `MinimalActionSpace`     | The original space of 9 choices (4 moves + 5 switches), sufficient for Gen 1-4.               |

New action spaces can be added to `metamon.interface.ALL_ACTION_SPACES`. A text action space for LLM-Agents is planned for future development.
```

--------------------------------

### Deploy Pretrained Agents on PokéAgent Challenge Ladder

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Deploys a specified pretrained RL agent onto the PokéAgent Challenge ladder. This requires providing account credentials (username and password) along with battle parameters.

```bash
python -m metamon.rl.evaluate --eval_type pokeagent --agent SyntheticRLV2 --gens 1 --formats ou --total_battles 10 --username <your username> --password <your password> --team_set competitive
```

--------------------------------

### Configure Wandb Logging in Shell

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Provides shell commands to configure Weights & Biases (wandb) logging for Metamon projects. This involves navigating to the rl directory and setting environment variables for the project name and entity.

```shell
cd metamon/rl/
export METAMON_WANDB_PROJECT="my_wandb_project_name"
export METAMON_WANDB_ENTITY="my_wandb_username"
```

--------------------------------

### Download Metamon Teams

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Command to download pre-collected Showdown team files from Hugging Face. These files are used as pretraining data for Metamon.

```bash
python -m metamon.data.download teams
```

--------------------------------

### Configure Metamon Cache Directory

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Sets the METAMON_CACHE_DIR environment variable in the user's bash profile to specify a location for Metamon to download and store large datasets.

```shell
# add to ~/.bashrc
export METAMON_CACHE_DIR=/path/to/plenty/of/disk/space
```

--------------------------------

### Compare Metamon Baselines

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Compare the performance of different baseline opponents through automated battles. This command-line interface allows specifying battle format, players, opponents, and the number of battles to conduct.

```bash
python -m metamon.baselines.compete --battle_format gen2ou --player GymLeader --opponent RandomBaseline --battles 10
```

--------------------------------

### Battle Against Built-in Baselines with Gymnasium

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Creates an environment to battle against predefined baselines. It integrates with the standard `gymnasium` API for environment interaction, allowing users to reset the environment and take steps using sampled actions.

```python
from metamon.env import BattleAgainstBaseline
from metamon.baselines import get_baseline

env = BattleAgainstBaseline(
    battle_format="gen1ou",
    observation_space=obs_space,
    action_space=action_space,
    reward_function=reward_fn,
    team_set=team_set,
    opponent_type=get_baseline("Gen1BossAI"),
)

# standard `gymnasium` environment
obs, info = env.reset()
next_obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
```

--------------------------------

### Use Custom Team Directory with Metamon

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Python class to initialize a TeamSet using a local directory of Showdown team files. Team files must have the extension corresponding to their battle format (e.g., '.gen3nu_team').

```python
from metamon.env import TeamSet

team_set = TeamSet("/path/to/your/team/dir", battle_format: str) # e.g. gen3ou
```

--------------------------------

### Save and Load Agent Experience Trajectories

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Demonstrates how to save an agent's experience (trajectories) to a specified path using `QueueOnLocalLadder` and then load this data using `ParsedReplayDataset`. It includes refreshing the dataset to include newly saved files.

```python
from metamon.env import QueueOnLocalLadder
from metamon.data import ParsedReplayDataset

env = QueueOnLocalLadder(
    .., # rest of args
    save_trajectories_to="my_data_path",
)

online_dset = ParsedReplayDataset(
    dset_root="my_data_path",
    observation_space=obs_space,
    action_space=action_space,
    reward_function=reward_func,
)
terminated = False
while not terminated:
    *_, terminated, _, _ = env.step(env.action_space.sample())
# find completed battles before loading examples
online_dset.refresh_files()
```

--------------------------------

### Queue Battles on Local Showdown Server

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Enables queuing for battles on a local Pokémon Showdown server. This allows interaction with other online players, including humans and other AI projects, by specifying battle format, player credentials, and the number of battles.

```python
from metamon.env import QueueOnLocalLadder

env = QueueOnLocalLadder(
    battle_format="gen1ou",
    player_username="my_scary_username",
    num_battles=10,
    observation_space=obs_space,
    action_space=action_space,
    reward_function=reward_fn,
    player_team_set=team_set,
)
```

--------------------------------

### Metamon Project Citation (BibTeX)

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

The BibTeX entry for citing the Metamon project, including authors, title, year, and publication details.

```bibtex
@misc{grigsby2025metamon,
      title={Human-Level Competitive Pok'emon via Scalable Offline Reinforcement Learning with Transformers},
      author={Jake Grigsby and Yuqi Xie and Justin Sasek and Steven Zheng and Yuke Zhu},
      year={2025},
      eprint={2504.04395},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2504.04395},
}
```

--------------------------------

### Finetune HuggingFace Model with Custom Data

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Finetunes an existing HuggingFace model to a new dataset, training objective, or reward function. Allows inheritance of base model architecture with modifications to training configurations and reward functions. Note that optimal finetuning settings may differ from original training.

```bash
python -m metamon.rl.finetune_from_hf --finetune_from_model SmallRL --run_name MyCustomSmallRL --save_dir ~/metamon_finetunes/ --custom_replay_dir /my/custom/parsed_replay_dataset --custom_replay_sample_weight .25 --epochs 10 --steps_per_epoch 10000 --log --formats gen9ou --eval_gens 9
```

--------------------------------

### Evaluate Pretrained Models on Local Ladder

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Evaluates a specified pretrained RL agent by having it battle on the local Showdown server. Users need to provide a unique username and specify the team set for the battles.

```bash
python -m metamon.rl.evaluate --eval_type ladder --agent SyntheticRLV2 --gens 1 --formats ou --total_battles 50 --username <pick unique username> --team_set competitive
```

--------------------------------

### Download Usage Stats Data

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Downloads usage statistics data using a Python module. The data is stored on HuggingFace and can be useful for various purposes related to battle data analysis.

```shell
python -m metamon.data.download usage-stats
```

--------------------------------

### Download Revealed Teams Data (Shell)

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

This command downloads the revealed teams data used by the Metamon project. It utilizes a Python module within the metamon package to fetch the dataset.

```shell
python -m metamon.data.download revealed-teams
```

--------------------------------

### Evaluate Pretrained Models Against Heuristic Baselines

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Evaluates a specified pretrained RL agent against a set of heuristic baselines. This command allows users to test model performance on predefined benchmarks over a set number of battles.

```bash
python -m metamon.rl.evaluate --eval_type heuristic --agent SyntheticRLV2 --gens 1 --formats ou --total_battles 100
```

--------------------------------

### Reward Functions

Source: https://github.com/ut-austin-rpl/metamon/blob/main/README.md

Details various reward function implementations that assign scalar rewards based on state transitions, including win/loss bonuses and shaping terms for in-game events.

```APIDOC
## Reward Functions

### Description
Reward functions calculate a scalar reward based on consecutive states (R(s, s')). Metamon provides several implementations tailored for different training objectives, ranging from simple win/loss rewards to more detailed shaping based on game events.

### Available Reward Functions

| Reward Function             | Description                                                                                                                                    |
|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `DefaultShapedReward`       | Shaped reward used in the paper. Provides +/- 100 for win/loss, with additional shaping for damage dealt, health recovered, and status effects. |
| `BinaryReward`              | Simplifies the reward by removing minor shaping terms, offering only +/- 100 for win/loss.                                                      |
| `AggresiveShapedReward`      | Modifies `DefaultShapedReward` to provide +200 for winning and 0 for losing, focusing on decisive outcomes.                                   |

New reward functions can be incorporated by adding them to `metamon.interface.ALL_REWARD_FUNCTIONS` or by creating a new class that inherits from `metamon.interface.RewardFunction`.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.