# Pokemon Data Tools

This directory contains tools for downloading and processing Pokemon data from the PokeAPI.

## Pokemon Downloader (`pokemon_downloader.py`)

A comprehensive tool for downloading generation-specific Pokemon data from the PokeAPI.

### Features

- **Type Effectiveness**: Downloads type matchup charts for each generation
- **Pokemon Data**: Downloads Pokemon species data including stats, types, and abilities
- **Moves Data**: Downloads move information filtered by generation availability
- **Progress Tracking**: Uses progress bars and detailed logging
- **Error Handling**: Robust error handling with retry logic
- **Flexible Output**: Configurable output directory structure

### Usage

#### Basic Usage

```bash
# Download all data for all generations
python pokemon_downloader.py --all-generations --all-data-types

# Download specific generations and data types
python pokemon_downloader.py --generations generation-i,generation-ii --data-types types,pokemon

# Download only type effectiveness for Generation I
python pokemon_downloader.py --generations generation-i --data-types types
```

#### Command Line Options

- `--generations`: Comma-separated list of generations (generation-i, generation-ii, etc.)
- `--all-generations`: Download data for all available generations
- `--data-types`: Comma-separated list of data types (types, pokemon, moves)
- `--all-data-types`: Download all data types
- `--output-dir`: Output directory (default: data)

#### Examples

```bash
# Download Pokemon and moves for Generation I and II
python tools/data/pokemon_downloader.py \
    --generations generation-i,generation-ii \
    --data-types pokemon,moves \
    --output-dir data

# Download all type effectiveness data
python tools/data/pokemon_downloader.py \
    --all-generations \
    --data-types types
```

### Output Structure

The tool creates the following directory structure:

```
data/
├── types/
│   ├── generation-i.json
│   ├── generation-ii.json
│   └── ...
├── pokemon/
│   ├── generation-i.json
│   ├── generation-ii.json
│   └── ...
└── moves/
    ├── generation-i.json
    ├── generation-ii.json
    └── ...
```

### Data Formats

#### Type Effectiveness (`types/generation-X.json`)

```json
{
  "fire": {
    "double_damage_from": ["water", "ground", "rock"],
    "double_damage_to": ["grass", "ice", "bug", "steel"],
    "half_damage_from": ["fire", "water", "rock", "dragon"],
    "half_damage_to": ["fire", "water", "rock", "dragon"],
    "no_damage_from": ["fire"],
    "no_damage_to": ["fire"]
  }
}
```

#### Pokemon Data (`pokemon/generation-X.json`)

```json
[
  {
    "id": 1,
    "name": "bulbasaur",
    "types": ["grass", "poison"],
    "stats": {
      "hp": 45,
      "attack": 49,
      "defense": 49,
      "special-attack": 65,
      "special-defense": 65,
      "speed": 45
    },
    "abilities": [...],
    "species": {
      "generation": "generation-i",
      "is_legendary": false,
      "is_mythical": false
    }
  }
]
```

#### Moves Data (`moves/generation-X.json`)

```json
[
  {
    "id": 1,
    "name": "pound",
    "power": 40,
    "pp": 35,
    "accuracy": 100,
    "type": "normal",
    "damage_class": "physical",
    "generation": "generation-i"
  }
]
```

### Dependencies

The tool requires the following Python packages (available in `tools/requirements.txt`):

- `requests` - HTTP requests to PokeAPI
- `tqdm` - Progress bars
- `argparse` - Command line argument parsing (built-in)

### API Rate Limiting

The tool includes:
- Retry logic with exponential backoff
- Respectful request timing
- User-agent identification
- Error handling for rate limits

### New Features (Latest Update)

**Efficient Moves Download:**
- Downloads all moves once and saves to `data/all_moves.json`
- Subsequent generations filter from this master file instead of re-downloading
- Dramatically reduces API calls and download time

**Smart Caching:**
- Checks if data files already exist and contain expected amount of data
- Skips re-downloading if files are present and valid
- Supports partial downloads (e.g., if some Pokemon are missing, only downloads missing ones)

**File Structure:**
```
data/
├── all_moves.json          # Complete moves database (all generations)
├── types/
│   ├── generation-i.json   # Type effectiveness for each generation
│   ├── generation-ii.json
│   └── ...
├── pokemon/
│   ├── generation-i.json   # Pokemon data for each generation
│   ├── generation-ii.json
│   └── ...
└── moves/
    ├── generation-i.json   # Moves available in each generation
    ├── generation-ii.json  # (filtered from all_moves.json)
    └── ...
```

### Performance Improvements

- **Moves**: Downloads all 900+ moves once, then filters per generation
- **Caching**: Checks file existence and validity before downloading
- **Batch Processing**: Downloads complete datasets efficiently
- **Resume Support**: Can continue interrupted downloads

### Usage Examples with Caching

```bash
# First run - downloads all data
python tools/data/pokemon_downloader.py --all-generations --all-data-types

# Subsequent runs - uses cached data (much faster!)
python tools/data/pokemon_downloader.py --all-generations --all-data-types

# Only downloads missing data
python tools/data/pokemon_downloader.py --generations generation-v --data-types pokemon
```

### Notes

- Some Pokemon and moves appear in multiple generations
- Type effectiveness is consistent across generations in the base game
- The tool respects the PokeAPI fair use policy
- Data is cached locally to avoid repeated API calls
- `all_moves.json` contains the complete moves database for efficient filtering