Andreas/mtg_python_deckbuilder
1
0
Fork 0
mirror of https://github.com/mwisnowski/mtg_python_deckbuilder.git synced 2025-12-16 07:30:13 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
mtg_python_deckbuilder/README.md

29 KiB
Raw Blame History

# 🃏 MTG Python Deckbuilder

License: MIT Python 3.11+ Docker

A web-first Commander/EDH deckbuilder with a shared core for CLI, headless, and Docker workflows. It builds curated decks, enforces bracket policies, understands owned cards, and ships a modern FastAPI + HTMX UI.

  • Web UI priority: All homepage actions map to the sections below.
  • Shared logic: Web, CLI, and headless runs use the same builder engine and exports.
  • Deterministic outputs: Random modes respect seeds, include/exclude lists, and bracket rules.
  • Data-aware UX: Owned library, themes, commanders, diagnostics, and logs live side-by-side.

Table of contents

Quick start

Pick the path that fits your setup. All commands target Windows PowerShell.

Option 1 — Docker Compose (recommended web experience)

docker compose up --build --no-deps -d web

The Web UI starts on http://localhost:8080. First boot seeds data, refreshes decks, and tags cards automatically (see env defaults in docker-compose.yml). Use docker compose stop web / docker compose start web to pause or resume.

Option 2 — Docker Hub image

docker run --rm -p 8080:8080 `
  -v "${PWD}/deck_files:/app/deck_files" `
  -v "${PWD}/logs:/app/logs" `
  -v "${PWD}/csv_files:/app/csv_files" `
  -v "${PWD}/config:/app/config" `
  -v "${PWD}/owned_cards:/app/owned_cards" `
  mwisnowski/mtg-python-deckbuilder:latest

Brings up the same web UI using the prebuilt image. All volumes persist on the host.

Option 3 — Run from source

python -m venv .venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn code.web.app:app --host 127.0.0.1 --port 8080

CLI entry point: python code/main.py. Headless convenience runner: python code/headless_runner.py --config config/deck.json.

For deeper Docker notes (including headless runs, impersonating CLI via compose, and maintenance scripts) see DOCKER.md.

Homepage guide

Every tile on the homepage connects to a workflow. Use these sections as your tour.

Build a Deck

Start here for interactive deck creation.

  • Pick commander, themes (primary/secondary/tertiary), bracket, and optional deck name in the unified modal.
  • Locks, Replace, Compare, and Permalinks live in Step 5.
  • Exports (CSV, TXT, compliance JSON, summary JSON) land in deck_files/ and reuse your chosen deck name when set.
  • ALLOW_MUST_HAVES=1 (default) enables include/exclude enforcement.
  • WEB_AUTO_ENFORCE=1 re-runs bracket enforcement automatically after each build.

Run a JSON Config

Execute saved configs without manual input.

  • Place JSON configs under config/ (see config/deck.json for a template).
  • Launch via homepage button or by running the container with APP_MODE=cli and DECK_MODE=headless.
  • Respect include/exclude, owned, and theme overrides defined in the config file or env vars.

Initial Setup

Refresh data and caches when formats shift.

  • Runs card downloads, CSV regeneration, tagging, and commander catalog rebuilds.
  • Controlled by SHOW_SETUP=1 (on by default in compose).
  • Force a rebuild manually: 
    docker compose run --rm --entrypoint bash web -lc "python -m code.file_setup.setup"
  • Rebuild only the commander catalog: 
    docker compose run --rm --entrypoint bash web -lc "python -m code.scripts.refresh_commander_catalog"

Owned Library

Keep track of cards you own.

  • Upload .txt or .csv lists; the app enriches and deduplicates entries.
  • Owned-only and Prefer-owned build modes live in the New Deck modal.
  • owned_cards/ is persisted via volume mounting (OWNED_CARDS_DIR=/app/owned_cards).
  • Enable virtualization for large libraries with WEB_VIRTUALIZE=1.

Browse Commanders

Explore the curated commander catalog.

  • Powered by csv_files/commander_cards.csv.
  • Toggle the tile with SHOW_COMMANDERS=1.
  • Refresh via Initial Setup or the commander catalog script above.
  • MDFC merges and compatibility snapshots are handled automatically; use --compat-snapshot on the refresh script to emit an unmerged snapshot.

Browse Themes

Investigate theme synergies and diagnostics.

  • ENABLE_THEMES=1 keeps the tile visible (default).
  • Extra tooling (/themes/metrics, uncapped synergies, editorial quality) is gated by WEB_THEME_PICKER_DIAGNOSTICS=1.
  • Rebuild the merged catalog as needed: 
    docker compose run --rm --entrypoint bash web -lc "python -m code.scripts.build_theme_catalog"
  • Advanced editorial knobs (EDITORIAL_*, SPLASH_ADAPTIVE, etc.) live in .env.example and are summarized in the env table below.

Finished Decks

Review, compare, and export previous builds.

  • Reads from the deck_files/ volume.
  • Compare view can diff two builds, copy summaries, and download text lists.
  • Locks, replace history, and compliance metadata persist per deck.

Random Build

Spin up surprise decks with deterministic fallbacks.

  • Enable backend endpoints with RANDOM_MODES=1 and the UI tile with RANDOM_UI=1.
  • Fine-tune with RANDOM_MAX_ATTEMPTS, RANDOM_TIMEOUT_MS, RANDOM_PRIMARY_THEME, RANDOM_SEED, and RANDOM_AUTO_FILL.
  • Random flows honor include/exclude lists, owned filters, and bracket enforcement.

Diagnostics

Peek at health & performance.

  • Enabled via SHOW_DIAGNOSTICS=1.
  • /diagnostics summarizes system status, feature flags, and theme metrics.
  • /healthz offers a lightweight probe ({status, version, uptime_seconds}).
  • Press v inside virtualized lists (when WEB_VIRTUALIZE=1) to view grid diagnostics.

View Logs

Tail and download logs without leaving the browser.

  • Enabled via SHOW_LOGS=1.
  • /logs shows recent entries, filtering, and copy-to-clipboard.
  • Raw files live under the mounted logs/ directory.
  • /status/logs?tail=N returns JSON payloads for automation.

CLI & headless flows

The CLI and headless runners share the builder core.

  • Launch menu-driven CLI: python code/main.py.
  • Run headless (non-interactive) builds: python code/headless_runner.py --config config/deck.json.
  • In Docker, set APP_MODE=cli (and optionally DECK_MODE=headless) to switch the container entrypoint to the CLI.
  • Config precedence is CLI prompts > environment variables > JSON config > defaults.

Data, exports, and volumes

Host path Container path Purpose
deck_files/ /app/deck_files CSV/TXT exports, compliance JSON, summary JSON
logs/ /app/logs Application logs, taxonomy snapshots
csv_files/ /app/csv_files Card datasets, commander catalog, tagging metadata
config/ /app/config JSON configs, bracket policies, themes, card lists
owned_cards/ /app/owned_cards Uploaded owned-card libraries

Exports follow a stable naming scheme and include a .summary.json sidecar containing deck metadata, resolved themes, and lock history.

Environment variables

Most defaults are defined in docker-compose.yml and documented in .env.example. Highlights:

Core modes & networking

Variable Default Purpose
APP_MODE web Switch between Web UI (web) and CLI (cli).
DECK_MODE (unset) headless auto-runs the builder in CLI mode.
DECK_CONFIG /app/config/deck.json Points the headless runner at a config file or folder.
HOST / PORT / WORKERS 0.0.0.0 / 8080 / 1 Uvicorn settings for the web server.

Homepage visibility & UX

Variable Default Purpose
SHOW_SETUP 1 Show the Initial Setup tile.
SHOW_LOGS 1 Enable the logs viewer tile and endpoints.
SHOW_DIAGNOSTICS 1 Unlock diagnostics views and overlays.
SHOW_COMMANDERS 1 Enable the commander browser.
ENABLE_THEMES 1 Keep the theme browser and selector active.
WEB_VIRTUALIZE 1 Opt into virtualized lists for large datasets.
ALLOW_MUST_HAVES 1 Enforce include/exclude (must-have) lists.
THEME dark Default UI theme (system, light, or dark).

Random build tuning

Variable Default Purpose
RANDOM_MODES (unset) Expose random build endpoints.
RANDOM_UI (unset) Show the Random Build homepage tile.
RANDOM_MAX_ATTEMPTS 5 Retry budget when constraints are tight.
RANDOM_TIMEOUT_MS 5000 Per-attempt timeout in milliseconds.
RANDOM_PRIMARY_THEME / RANDOM_SECONDARY_THEME / RANDOM_TERTIARY_THEME (blank) Override selected themes.
RANDOM_SEED (blank) Deterministic seed for reproducible builds.
RANDOM_AUTO_FILL 1 Allow auto-fill of missing theme slots.

Automation & performance

Variable Default Purpose
WEB_AUTO_SETUP 1 Auto-run setup when artifacts are missing or stale.
WEB_AUTO_REFRESH_DAYS 7 Refresh cards.csv if older than N days.
WEB_TAG_PARALLEL 1 Enable parallel tagging workers.
WEB_TAG_WORKERS 4 Worker count for tagging (compose default).
WEB_AUTO_ENFORCE 0 Auto-apply bracket enforcement after builds.
WEB_THEME_PICKER_DIAGNOSTICS 1 Enable theme diagnostics endpoints.

Paths & overrides

Variable Default Purpose
CSV_FILES_DIR /app/csv_files Alternate dataset location (useful for tests).
DECK_EXPORTS /app/deck_files Override where exports land.
OWNED_CARDS_DIR / CARD_LIBRARY_DIR /app/owned_cards Override owned library path.
CARD_INDEX_EXTRA_CSV (blank) Inject extra CSV data into the card index.

Refer to .env.example for advanced editorial, taxonomy, and experimentation knobs (EDITORIAL_*, SPLASH_ADAPTIVE, WEB_THEME_FILTER_PREWARM, etc.). Document any newly introduced variables in the README, DOCKER guide, compose files, and .env.example.

Project layout

code/                 FastAPI app, deckbuilding engine, CLI, scripts, and tests
├─ web/               Web UI (FastAPI + Jinja2 + HTMX)
├─ deck_builder/      Core builder logic and services
├─ tagging/           Tag pipelines and utilities
├─ locks/             Card locking utilities
├─ scripts/           Maintenance and editorial tools
├─ tests/             Pytest suite (web, CLI, random, tagging)
config/               JSON configs, bracket policies, themes, card lists
csv_files/            Card datasets, commander catalog, theme outputs
owned_cards/          User-supplied owned lists
logs/                 Application logs and taxonomy snapshots
deck_files/           Generated deck exports (CSV/TXT/JSON)

Development setup

  1. Create and activate the virtual environment: 
    python -m venv .venv
.\venv\Scripts\Activate.ps1
  2. Install dependencies: 
    pip install -r requirements.txt -r requirements-dev.txt
  3. Run the web app locally: 
    uvicorn code.web.app:app --host 127.0.0.1 --port 8080
  4. Run tests (prefer targeted files—no wildcards): 
    C:/Users/Matt/mtg_python/mtg_python_deckbuilder/.venv/Scripts/python.exe -m pytest -q code/tests/test_random_determinism.py code/tests/test_permalinks_and_locks.py
    Use tasks.json entries such as pytest-fast-random or pytest-fast-locks for quick feedback.
  5. Linting and type checks follow pyproject.toml / mypy.ini defaults. Keep changes minimal and well-typed.

When adding features, favor the web UI first, keep public builder APIs stable, and update documentation (CHANGELOG → RELEASE_NOTES_TEMPLATE → DOCKER → README) in that order.

Troubleshooting

  • Blank page after start: Visit /healthz, check /logs, ensure SHOW_LOGS=1, and inspect host logs/ for stack traces.
  • Stale data: Run Initial Setup or delete csv_files/.tagging_complete.json to force reseeding.
  • Owned-only build fails: Confirm owned files were uploaded correctly and that owned_cards/ is mounted.
  • Random build stalls: Lower RANDOM_MAX_ATTEMPTS, increase RANDOM_TIMEOUT_MS, and verify selected themes exist via /themes/.
  • Commander list outdated: Rerun the commander refresh script or Initial Setup.

Contributing

Pull requests are welcome—follow the conventional commit style, keep diffs focused, add or update tests when behavior changes, and document new env vars or workflows. Review CONTRIBUTING_EDITORIAL.md for editorial tooling guidance.

License & attribution

Licensed under the MIT License. Card data and imagery are provided by Scryfall; please respect their API terms.

Further reading