WikifitaGitHub live67e8de5
pesquisa · kaggle/pokemon_tcg_glossary

Pokémon TCG AI Battle — Glossary and Nomenclature

Canonical vocabulary used across the training, inference, data, and tournament pages: TBPTT, KV cache, opt/gstep, chunk, decisions, sweep, top-elo, aux heads, scratch registers, sources.

Baixar raw

Pokémon TCG AI Battle — Glossary

Purpose

Single source of truth for the terms every other Pokémon TCG page uses. When a page uses chunk, opt_step, row_group, sweep, source='remote', aux_valid, substep, or TBPTT, it means exactly what this page defines. Terms that are project-invented (not standard ML vocabulary) are marked with [project].

Data and dataset

  • row — one classified decision by one side of one match. Columns include full observation, action label y, action mask, aux targets, and metadata like episode_id/side/step_id/decision_id. Encoded once by the builder from Kaggle replay JSON.
  • episode — one Kaggle match. Identified by episode_id. Each episode contributes one row per decision × 2 sides (when bc_both_sides=true).
  • side — 0 or 1, which player the row is played by. Recurrence and TBPTT chunks group by (episode_id, side) — the two sides of the same episode are independent lanes for memory purposes.
  • step_id / decision_id / substep — within an episode-side lane, step_id is the raw engine step, decision_id groups substeps that belong to the same multi-select decision, and substep is the order inside that decision. Autoregressive multi-select in inference recomputes logits at each substep.
  • new_episode — boolean row flag that the trainer uses to reset persistent scratch memory when TBPTT is on.
  • terminal / outcome / reward — terminal marks the final row of an episode; outcome ∈ {-1, 0, 1} is the sign of the reward; reward is a normalized float that feeds aux_return.
  • aux_valid — bit mask on each row saying whether the aux heads have a valid target for that row. Aux losses are masked by it.
  • aux_ko / aux_prize_delta / aux_terminal / aux_return — the four auxiliary training targets (see pokemon_tcg_training_pipeline).
  • day [project] — the calendar date of a batch of Kaggle replays. Datasets are day-partitioned: one Parquet file per day. Days are catalogued in sqlite:days.
  • competition day — a monotonic integer day-index counted from the start of the Kaggle competition. Used as a scalar feature so the model has a coarse temporal anchor.
  • manifest — a data/bc_data/<date>.manifest.json sidecar recording provenance for the corresponding Parquet file (source zip SHA256, aux-target contract, encoder version).

Parquet and storage

  • row group — pyarrow's physical read unit inside a Parquet file. Each of our daily Parquet files carries ~23 row groups of ~35k rows each. Loading, cache retention, and SSD spill all operate at row-group granularity, not row granularity. See pokemon_tcg_parquet_dataset.
  • column chunk — one column's data inside one row group. Streaming reads project only the columns the training step actually needs.
  • fixed_size_list — the Parquet type used for all vector-valued columns (unit_attr, opt_attr, action_mask, etc.) so the reader can decode a whole batch without per-row length tracking.

KV cache

  • KV cache [project] — the in-process cache of decoded Parquet row groups the trainer holds resident between microbatches. Named after key/value caches in inference but semantically closer to a page cache over parquet blocks. See pokemon_tcg_kv_cache_hierarchical.
  • hot tier / transient tier [project] — the two RAM tiers inside the cache. Hot is pinned (never evicted while resident capacity allows); transient is LRU. Row groups get promoted from transient to hot after _HOT_PROMOTION_HITS=2 hits.
  • SSD spill [project] — the disk tier. When a row group is evicted from RAM, its decoded arrays get written to <checkpoint_dir>/.cache_spill/ as an .npz and can be re-hydrated without redecoding the source Parquet.
  • in_opt_step() [project] — reentrant context manager the trainer wraps around the forward+backward pass so pressure-driven eviction is suppressed during a single microbatch. Prevents an activation peak from evicting the row group the current microbatch is still reading.

Training accounting

  • microbatch — one (forward → loss → backward) cycle over one temporal batch. Does not step the optimizer on its own.
  • optimizer step / opt_step — one (clip → optimizer.update → mx.eval) cycle after gradients from all microbatches in the accumulation group have been added in FP32. With accum_steps=1 (current default), microbatch and opt_step are 1:1.
  • gstep — the global optimizer-step counter, monotonically incremented across epochs. Used to seed tensorboard tags and index the LR schedule. See pokemon_tcg_tbptt_training_contract.
  • scheduler_phase_step — the checkpoint-relative position inside the current LR schedule phase. Restored on --scheduler-state resume.
  • chunk (TBPTT chunk) — the number of decisions per (episode_id, side) lane the trainer feeds through one forward pass before applying stop_gradient at the boundary. Typical values: 8, 16, 32. --tbptt-chunk 0 disables TBPTT (shuffled training).
  • row budget — the maximum encoded rows packed into one TBPTT temporal batch. Set by --batch. Lanes are packed until either the row budget or the max-chunk-length constraint is hit.
  • temporal batch — one packed batch of ordered (episode_id, side) lanes ready for a microbatch.
  • run vs global — "run" scopes to the current invocation (e.g. run_optimizer_steps); "global" is the running total including any resumed history. The scheduler counts run-local optimizer steps; provenance counts global.

Scheduler and optimizer

  • Muon — an optimizer variant for hidden 2D weight matrices (attention QKV, FFN projections). The MLX training pipeline routes matrix parameters to Muon and everything else (embeddings, output heads, biases, layer norms, scalars) to AdamW.
  • AdamW — decoupled-weight-decay Adam. Used for the non-matrix parameters.
  • muon_adamw — the value of the --optimizer flag; there is currently no alternative topology.
  • structured_weight_decay — a higher decay applied specifically to the verb heads (type_query, type_bias) so rare verbs collapse toward the shared opt_head fallback. Only takes effect when --structured true (off in the current BC baseline).
  • warmup — the linear ramp of LR from 0 to peak over --warmup-steps optimizer steps. Applied at the start of each scheduler phase.
  • lr_min_ratio — LR floor at the end of decay = lr × lr_min_ratio. Orbit-style: LR holds at floor after decay completes.

Model

  • d_model / nhead / nlayers / ff_dim — Transformer hyperparameters. Current baseline: 128 / 4 / 3 (config default) or 4 (current train_config.json) / 512.
  • entity/action Transformer — the architectural family: state tokens describe entities on the board and option tokens describe legal actions; option scoring is a bilinear projection. Distinct from causal language decoders.
  • scratch registers — a small number of learned tokens inserted between the state and option token streams. When TBPTT is on, they carry inter-decision memory across chunks (write-in from previous chunk, read-out into next). See pokemon_tcg_agent_architecture.
  • static card features — the frozen per-card feature table read from EN_Card_Data.csv. Included via a learned linear projection; the table itself is a buffer, not a trainable parameter.
  • split heads — dedicated VALUE_TOK and SUBMIT_TOK tokens with their own output heads, separate from the shared option scoring head. On by default.
  • structured head — verb-conditioned action scoring (per-OptionType query and bias). Off in the current BC baseline; docstring only.
  • aux heads — four Linear(d_model, 1) heads applied to the CLS output that predict ko, prize_delta, terminal, and normalized return. Trained with fixed loss weights; see pokemon_tcg_training_pipeline.
  • CLS / VALUE_TOK / SUBMIT_TOK — three reserved token positions at the head of the sequence.
  • padding_id=0 — card and attack ID zero mean "no card / no attack"; embedded to a zero vector, not a learned "absence" embedding.
  • additive attention mask — mask contract used inside MHA: 0 for valid keys, a large finite negative sentinel for padded keys. The current trainer/inference path is FP32; the sentinel is also representable in historical FP16 artifacts. Not a boolean.
  • MHA bias — the multi-head attention projections carry a bias term (matching the PyTorch reference). Explicitly instantiated on the MLX side.

Inference and action semantics

  • autoregressive multi-select — inference algorithm: for a multi-select decision, the model chooses one legal option, updates the picked-set, recomputes logits with the mask reflecting the new picked-set, chooses the next option, until legal SUBMIT or max_count. See pokemon_tcg_torch_inference.
  • SUBMIT_ACTION — the reserved option index (== MAX_OPTIONS = 192) meaning "stop this multi-select and commit the buffered set."
  • would_ko — a per-option ternary feature: would_ko rate, expected prizes taken, P(ends game). Computed by the offline dataset builder from the search agent; used as pure input features (not a learned head). Toggled by --bc-would-ko at build time.
  • PyTorch artifact — the arena-side runtime. Historical packaging used the filename model/bc_model/bc_best_torch_fp16.pt, but the current converter validates strict FP32 tensors. Inference is torch-only; see pokemon_tcg_current_state_reconciliation.

Sources and SQLite

  • source='remote' — Elo/coverage rows populated from Kaggle replay observations. This is what the pipeline has coverage for out of the box.
  • source='local' — Elo/coverage rows populated from local synchronous tournaments. Requires local tournaments to have run first.
  • deck source codes — replay, arena, starter, submission, public_agent, builder, custom. Provenance of a deck row in decks.
  • datasets (SQLite table) — one row per day-partitioned Parquet file, with path, schema_version, rows, sha256, aux_targets. The trainer resolves training days by looking up this table.
  • schema_version — currently 2.0.0 (day-partitioned Elo tables, source enum, first-class agents/decks/datasets). The old single-snapshot card_elo/deck_elo are backwards-compat views over card_elo_daily/deck_elo_daily. See pokemon_tcg_sqlite_schema_current.

Tournament and evaluation

  • sweep [project] — for a per-run tournament, our agent is rotated through a set of top decks against a fixed opponent set. Only our agent/deck.csv is swapped; opponent decks are static.
  • sweep source — remote or local; the Elo tier the sweep pulls its top decks from. Default remote (from deck_elo_daily, source='remote').
  • round-robin — the intra-suite phase where the 10 trained checkpoints are matched pairwise (45 unique pairs); --no-sweep --skip-baselines. Same deck for all so the comparison is apples-to-apples. See pokemon_tcg_tournament_system.
  • baselines — the built-in random and first opponents always prepended by tournament.py unless --skip-baselines. random picks a uniformly random legal option; first always picks the first.

Cross-references