lootqdm 0.1.0

Turn your training loop into an idle RPG.

lootqdm

Turn your training loop into an idle RPG.

lootqdm replaces bland training progress bars with an idle RPG experience. XP bars, loot drops, quests, achievements, level-ups, critical batches — all in your terminal.

╭─ 🗡️ LOOTQDM ─────────────────────────────────────────────────────────╮
│  mnist_run · dark_dungeon                    ⚙        00:12:34       │
├───────────────────────────────────┬──────────────────────────────────┤
│                                   │                                  │
│  PROGRESS                         │  STATS                           │
│                                   │                                  │
│  Epoch  3/10  █████████░░░  80%   │  ⚔  DMG  (loss)       0.0234   │
│  Batch 128/500 ███████░░░░  56%   │  🎯 CRIT (acc)        94.2%    │
│  ETA 00:08:22  ·  1284 it/s       │  💧 MANA (lr)         1e-4     │
│                                   │  📉 loss  ▇▆▅▄▃▃▂▂▁▁           │
│  🩸 ██████████░░  2340/3000 LV 7  │  🔥 GPU   78%  · 4.2 GB       │
│                                   │                                  │
├───────────────────────────────────┼──────────────────────────────────┤
│                                   │                                  │
│  LOOT & EVENTS                    │  QUESTS                          │
│                                   │                                  │
│  ⚜️  LEGENDARY Cursed Crown! +500 │  📜 acc ≥ 0.95  ▰▰▰▰▱  94%    │
│  💠 Rare Void Shard  +50 XP       │  📜 loss < 0.01 ▰▰▱▱▱  42%    │
│  💥 CRITICAL BATCH!  +20 XP       │  ✅ First epoch  ✓              │
│  🪙 Rusty Coin  +5 XP             │  ✅ New best acc  ✓             │
│                                   │                                  │
╰───────────────────────────────────┴──────────────────────────────────╯

Install

pip install lootqdm

Quick Start

Minimal

from lootqdm import GameUI

with GameUI(total_steps=1000) as ui:
    for i in range(1000):
        loss = 0.9 / (i + 1)
        ui.step({"loss": loss, "lr": 1e-3})

Wrap an iterable

from lootqdm import GameUI

with GameUI(total_steps=len(dataloader)) as ui:
    for batch in ui.wrap(dataloader):
        loss = train_step(batch)
        ui.step({"loss": loss.item()})

PyTorch

from lootqdm import GameUI
from lootqdm.integrations.torch import LootqdmCallback

epochs = 10
with GameUI(
    total_steps=len(loader) * epochs,
    total_epochs=epochs,
    theme="neon_cyber",
    run_name="mnist",
) as ui:
    ui.quest("Low Loss", "loss", 0.1, "<=")
    cb = LootqdmCallback(ui)

    for epoch in range(epochs):
        for batch_x, batch_y in loader:
            loss, acc = train_step(batch_x, batch_y)
            cb.on_batch_end(loss=loss, acc=acc)
        cb.on_epoch_end(val_acc=validate())

Keras

from lootqdm import GameUI
from lootqdm.integrations.keras import LootqdmKerasCallback

with GameUI(
    total_steps=steps_per_epoch * epochs,
    total_epochs=epochs,
    theme="cozy_pastel",
) as ui:
    model.fit(x, y, callbacks=[LootqdmKerasCallback(ui)], verbose=0)

Themes

Pick a vibe. Four built-in themes:

Theme	Mood	Icons
dark_dungeon	Roguelike, gritty	🩸 🗡️ 🪙 💠 ⚜️
cozy_pastel	Cottagecore, soft	🌱 🧺 🍓 🫐 🧁
neon_cyber	Synthwave, flashy	⚡ 🧬 📀 🧪 💎
retro_crt	Old terminal, ASCII	+XP LV [C] [R] [L]

GameUI(total_steps=1000, theme="cozy_pastel")

Quests

Set metric-based goals. Progress bars track them live:

with GameUI(total_steps=1000) as ui:
    ui.quest("Low Loss", "loss", 0.05, "<=")
    ui.quest("High Accuracy", "acc", 0.95, ">=")
    # quests check on epoch_end()

Loot System

Every 50 steps, a loot drop is rolled:

Rarity	Chance	XP	Example (dark_dungeon)
Common	70%	+5	🪙 Rusty Coin
Uncommon	20%	+15	🔧 Iron Buckle
Rare	8%	+50	💠 Cursed Relic
Epic	1.9%	+150	🔮 Bloodstone Amulet
Legendary	0.1%	+500	⚜️ Cursed Crown

Random Events

• 💥 Critical Batch (3% per step) — bonus XP burst
• 🦇 Lucky Batch (1% per step) — mystery bonus

Achievements

Unlocked automatically:

• First epoch complete
• New best metric (per metric key)
• NaN survived (with warning)
• Level milestones (5, 10, 25, 50, 100)

Stat Mapping

Metrics are auto-translated to game stats:

ML Metric	Game Stat	Icon
loss	DMG	⚔
acc / accuracy	CRIT	🎯
lr	MANA	💧
val_loss	vDMG	🛡
val_acc	vCRIT	🎯

Custom mappings:

from lootqdm import StatMapper

mapper = StatMapper(mappings={
    "f1_score": ("F1 PWR", "⚔"),
    "bleu": ("BLEU", "📝"),
})

API Reference

GameUI

GameUI(
    total_steps=1000,       # Total training steps
    total_epochs=10,        # Number of epochs
    theme="dark_dungeon",   # Theme: dark_dungeon, cozy_pastel, neon_cyber, retro_crt
    refresh_rate=10,        # Max FPS for terminal refresh
    emoji=True,             # Enable emoji icons
    persist=True,           # Save profile to ~/.lootqdm/
    run_name="my_run",      # Display name for the run
)

Method	Description
step(metrics, n=1)	Advance by n steps with optional metrics dict
epoch_end(metrics)	Signal end of epoch; triggers quest checks
log(message, rarity)	Add message to the loot feed
quest(name, metric, target, compare)	Register a quest goal
wrap(iterable, metrics_fn)	Wrap iterable with auto step tracking
pytorch_step(**metrics)	Convenience for step(metrics) via kwargs

Persistence

Profile persists across runs at ~/.lootqdm/profile.json:

• Lifetime XP, total runs, level, achievements, loot log
• Set persist=False to disable

TTY Fallback

When not in a terminal (CI, pipes, LOOTQDM_PLAIN=1), lootqdm automatically falls back to plain logging output. No crashes, no garbled text.

Examples

Run the included examples:

# Simple loop with all 4 themes
python examples/basic_loop.py

# PyTorch (falls back to simulation if torch not installed)
python examples/pytorch_mnist.py

# Keras (falls back to simulation if tensorflow not installed)
python examples/keras_callback.py

Development

git clone https://github.com/lootqdm/lootqdm.git
cd lootqdm
pip install -e ".[dev]"
pytest

License

MIT