# aaqibzahid/pokemon-battlestate-analytics architecture

> Architecture diagram of the GitHub repository aaqibzahid/pokemon-battlestate-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaqibzahid/pokemon-battlestate-analytics
- Repository: https://github.com/aaqibzahid/pokemon-battlestate-analytics

## Overview

Pokemon BattleState Analytics benchmarks real-time win-probability estimates from Pokémon Showdown replays. Its main workflow collects replay URLs, downloads logs, parses events, reconstructs turn-by-turn battle states, derives observable features, splits by battle, trains baselines, and evaluates predictions. The Streamlit app and replay-prediction module are an additional user-facing branch. Edges follow README pipeline documentation and SOURCE INDEX references; unsampled implementation details and UI call paths are not asserted.

Main entry points: [`src/battletrace/pipeline/evaluate_models.py`](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/pipeline/evaluate_models.py) (Evaluation pipeline), [`src/battletrace/pipeline/build_dataset.py`](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/pipeline/build_dataset.py) (Dataset builder), [`src/battletrace/state/state_machine.py`](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/state/state_machine.py) (State machine), [`src/battletrace/parsing/parser.py`](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/parsing/parser.py) (Log parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Replay ingestion"]
  node_collector["Replay collector<br/>[collect_replays.py]"]
  node_urls["Replay URL list<br/>[replay_urls.txt]"]
  node_downloader["Log downloader<br/>[download_logs.py]"]
  node_rawlogs["Raw battle logs"]
end

subgraph group_reconstruct["Battle reconstruction"]
  node_builder["Dataset builder<br/>[build_dataset.py]"]
  node_parser["Log parser<br/>[parser.py]"]
  node_protocol["Protocol definitions<br/>[protocol.py]"]
  node_events["Battle events<br/>[events.py]"]
  node_state_machine["State machine<br/>[state_machine.py]"]
  node_battle_state["Battle state<br/>[battle_state.py]"]
  node_snapshot["Turn snapshots<br/>[snapshot.py]"]
  node_states["Reconstructed states"]
end

subgraph group_modeling["Features and models"]
  node_feature_extractor["Feature extraction"]
  node_features["Feature dataset"]
  node_splits["Battle-level splits"]
  node_trainer["Training pipeline<br/>[train_baselines.py]"]
  node_baselines["Classical baselines<br/>[baselines.py]"]
  node_heuristic["Heuristic baseline<br/>[heuristics.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation_runner["Evaluation pipeline<br/>[evaluate_models.py]"]
  node_metrics["Probability metrics<br/>[metrics.py]"]
  node_calibration["Calibration analysis<br/>[calibration.py]"]
  node_turnwise["Turn-wise analysis<br/>[turnwise_eval.py]"]
  node_reports["Evaluation reports"]
end

subgraph group_product["User experience"]
  node_app["Streamlit app<br/>[streamlit_app.py]"]
  node_predict_replay["Replay prediction<br/>[predict_replay.py]"]
end

node_showdown(("Showdown API"))
node_user(("Analyst"))

node_showdown -->|"provides replays"| node_collector
node_collector -->|"writes URLs"| node_urls
node_urls -->|"supplies URLs"| node_downloader
node_downloader -->|"downloads logs"| node_rawlogs
node_rawlogs -->|"provides logs"| node_builder
node_builder -->|"parses logs"| node_parser
node_parser -->|"uses definitions"| node_protocol
node_parser -->|"creates events"| node_events
node_builder -->|"reconstructs states"| node_state_machine
node_state_machine -->|"dispatches events"| node_events
node_state_machine -->|"updates state"| node_battle_state
node_state_machine -->|"emits snapshots"| node_snapshot
node_builder -->|"writes states"| node_states
node_states -->|"supplies snapshots"| node_feature_extractor
node_feature_extractor -->|"derives features"| node_features
node_features -->|"splits by battle"| node_splits
node_splits -->|"supplies partitions"| node_trainer
node_trainer -->|"trains models"| node_baselines
node_trainer -->|"trains baseline"| node_heuristic
node_features -->|"evaluates predictions"| node_evaluation_runner
node_evaluation_runner -->|"evaluates models"| node_baselines
node_evaluation_runner -->|"evaluates model"| node_heuristic
node_evaluation_runner -->|"computes metrics"| node_metrics
node_evaluation_runner -->|"computes calibration"| node_calibration
node_evaluation_runner -->|"computes turnwise"| node_turnwise
node_evaluation_runner -->|"writes results"| node_reports
node_user -->|"uses interface"| node_app
node_app -.->|"uses predictor"| node_predict_replay

click node_collector "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/ingest/collect_replays.py"
click node_urls "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/data/raw/replay_urls.txt"
click node_downloader "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/ingest/download_logs.py"
click node_builder "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/pipeline/build_dataset.py"
click node_parser "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/parsing/parser.py"
click node_protocol "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/parsing/protocol.py"
click node_events "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/parsing/events.py"
click node_state_machine "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/state/state_machine.py"
click node_battle_state "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/state/battle_state.py"
click node_snapshot "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/state/snapshot.py"
click node_states "https://github.com/aaqibzahid/pokemon-battlestate-analytics/tree/main/data/processed"
click node_feature_extractor "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/features/extract_features.py"
click node_features "https://github.com/aaqibzahid/pokemon-battlestate-analytics/tree/main/data/processed"
click node_splits "https://github.com/aaqibzahid/pokemon-battlestate-analytics/tree/main/data/processed/splits"
click node_trainer "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/pipeline/train_baselines.py"
click node_baselines "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/models/baselines.py"
click node_heuristic "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/models/heuristics.py"
click node_evaluation_runner "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/pipeline/evaluate_models.py"
click node_metrics "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/evaluation/metrics.py"
click node_calibration "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/evaluation/calibration.py"
click node_turnwise "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/evaluation/turnwise_eval.py"
click node_reports "https://github.com/aaqibzahid/pokemon-battlestate-analytics/tree/main/reports/metrics"
click node_app "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/app/streamlit_app.py"
click node_predict_replay "https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/demo/predict_replay.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_collector,node_urls,node_downloader,node_rawlogs toneBlue
class node_builder,node_parser,node_protocol,node_events,node_state_machine,node_battle_state,node_snapshot,node_states toneAmber
class node_feature_extractor,node_features,node_splits,node_trainer,node_baselines,node_heuristic,node_showdown toneMint
class node_evaluation_runner,node_metrics,node_calibration,node_turnwise,node_reports toneRose
class node_app,node_predict_replay,node_user toneIndigo
```

## Components

### Replay ingestion

- [Replay collector](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/ingest/collect_replays.py): `src/battletrace/ingest/collect_replays.py`
- [Replay URL list](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/data/raw/replay_urls.txt): `data/raw/replay_urls.txt`
- [Log downloader](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/ingest/download_logs.py): `src/battletrace/ingest/download_logs.py`
- **Raw battle logs**

### Battle reconstruction

- [Dataset builder](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/pipeline/build_dataset.py): `src/battletrace/pipeline/build_dataset.py`
- [Log parser](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/parsing/parser.py): `src/battletrace/parsing/parser.py`
- [Protocol definitions](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/parsing/protocol.py): `src/battletrace/parsing/protocol.py`
- [Battle events](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/parsing/events.py): `src/battletrace/parsing/events.py`
- [State machine](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/state/state_machine.py): `src/battletrace/state/state_machine.py`
- [Battle state](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/state/battle_state.py): `src/battletrace/state/battle_state.py`
- [Turn snapshots](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/state/snapshot.py): `src/battletrace/state/snapshot.py`
- [Reconstructed states](https://github.com/aaqibzahid/pokemon-battlestate-analytics/tree/main/data/processed): `data/processed`

### Features and models

- [Feature extraction](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/features/extract_features.py): `src/battletrace/features/extract_features.py`
- [Feature dataset](https://github.com/aaqibzahid/pokemon-battlestate-analytics/tree/main/data/processed): `data/processed`
- [Battle-level splits](https://github.com/aaqibzahid/pokemon-battlestate-analytics/tree/main/data/processed/splits): `data/processed/splits`
- [Training pipeline](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/pipeline/train_baselines.py): `src/battletrace/pipeline/train_baselines.py`
- [Classical baselines](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/models/baselines.py): `src/battletrace/models/baselines.py`
- [Heuristic baseline](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/models/heuristics.py): `src/battletrace/models/heuristics.py`

### Evaluation

- [Evaluation pipeline](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/pipeline/evaluate_models.py): `src/battletrace/pipeline/evaluate_models.py`
- [Probability metrics](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/evaluation/metrics.py): `src/battletrace/evaluation/metrics.py`
- [Calibration analysis](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/evaluation/calibration.py): `src/battletrace/evaluation/calibration.py`
- [Turn-wise analysis](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/evaluation/turnwise_eval.py): `src/battletrace/evaluation/turnwise_eval.py`
- [Evaluation reports](https://github.com/aaqibzahid/pokemon-battlestate-analytics/tree/main/reports/metrics): `reports/metrics`

### User experience

- [Streamlit app](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Replay prediction](https://github.com/aaqibzahid/pokemon-battlestate-analytics/blob/main/src/battletrace/demo/predict_replay.py): `src/battletrace/demo/predict_replay.py`

### Other components

- **Showdown API**
- **Analyst**

## Connections

- Showdown API → Replay collector: provides replays (evidence: `README.md`)
- Replay collector → Replay URL list: writes URLs (evidence: `README.md`)
- Replay URL list → Log downloader: supplies URLs (evidence: `README.md`)
- Log downloader → Raw battle logs: downloads logs (evidence: `README.md`)
- Raw battle logs → Dataset builder: provides logs (evidence: `README.md`)
- Dataset builder → Log parser: parses logs (evidence: `src/battletrace/pipeline/build_dataset.py`)
- Log parser → Protocol definitions: uses definitions (evidence: `src/battletrace/parsing/parser.py`)
- Log parser → Battle events: creates events (evidence: `src/battletrace/parsing/parser.py`)
- Dataset builder → State machine: reconstructs states (evidence: `src/battletrace/pipeline/build_dataset.py`)
- State machine → Battle events: dispatches events (evidence: `src/battletrace/state/state_machine.py`)
- State machine → Battle state: updates state (evidence: `src/battletrace/state/state_machine.py`)
- State machine → Turn snapshots: emits snapshots (evidence: `src/battletrace/state/state_machine.py`)
- Dataset builder → Reconstructed states: writes states (evidence: `README.md`)
- Reconstructed states → Feature extraction: supplies snapshots (evidence: `README.md`)
- Feature extraction → Feature dataset: derives features (evidence: `README.md`)
- Feature dataset → Battle-level splits: splits by battle (evidence: `README.md`)
- Battle-level splits → Training pipeline: supplies partitions (evidence: `README.md`)
- Training pipeline → Classical baselines: trains models (evidence: `src/battletrace/pipeline/train_baselines.py`)
- Training pipeline → Heuristic baseline: trains baseline (evidence: `src/battletrace/pipeline/train_baselines.py`)
- Feature dataset → Evaluation pipeline: evaluates predictions (evidence: `README.md`)
- Evaluation pipeline → Classical baselines: evaluates models (evidence: `src/battletrace/pipeline/evaluate_models.py`)
- Evaluation pipeline → Heuristic baseline: evaluates model (evidence: `src/battletrace/pipeline/evaluate_models.py`)
- Evaluation pipeline → Probability metrics: computes metrics (evidence: `src/battletrace/pipeline/evaluate_models.py`)
- Evaluation pipeline → Calibration analysis: computes calibration (evidence: `src/battletrace/pipeline/evaluate_models.py`)
- Evaluation pipeline → Turn-wise analysis: computes turnwise (evidence: `src/battletrace/pipeline/evaluate_models.py`)
- Evaluation pipeline → Evaluation reports: writes results (evidence: `README.md`)
- Analyst → Streamlit app: uses interface (evidence: `README.md`)
- Streamlit app → Replay prediction: uses predictor (evidence: `app/streamlit_app.py`)
