mtg_python_deckbuilder/README.md

# 🃏 MTG Python Deckbuilder

A powerful, intelligent command-line tool for building and analyzing Magic: The Gathering Commander/EDH decks. Features advanced theme detection, automated card suggestions, and seamless integration with popular online deck builders.

✨ Features

🏗️ Intelligent Deck Building

• Commander Selection: Search and select from comprehensive commander database
• Theme Detection: Automatically identify deck themes and suggest synergistic cards
• Color Identity Filtering: Respect Commander color identity rules automatically
• Power Bracket System: Build decks targeting specific power levels (1-4)
• Smart Card Suggestions: AI-driven recommendations based on deck strategy

📊 Advanced Analysis

• Mana Curve Optimization: Automatically balance your deck's mana curve
• Land Base Calculator: Intelligent land recommendations based on color requirements
• Synergy Detection: Identify and maximize card synergies within themes
• Type Balance: Ensure proper creature/spell/land ratios

🔄 Seamless Workflow

• Instant Export: Deck lists displayed immediately for copy/paste to Moxfield, EDHREC, etc.
• Dual Format Export: Both CSV (detailed) and TXT (simple) formats
• File Persistence: All decks saved locally for future reference
• Interactive Menus: User-friendly CLI with intuitive navigation

🐳 Multiple Deployment Options

• Docker Support: Run anywhere with zero Python setup required
• Cross-Platform: Windows, macOS, and Linux support
• Python Package: Traditional pip installation available
• From Source: Full development environment setup

🚀 Quick Start

Option 1: Docker Hub (Fastest)

Prerequisites: Docker installed

# Create a directory for your decks
mkdir mtg-decks && cd mtg-decks

# Option A: Use the helper script (easiest)
curl -O https://raw.githubusercontent.com/mwisnowski/mtg_python_deckbuilder/main/run-from-dockerhub.sh
chmod +x run-from-dockerhub.sh
./run-from-dockerhub.sh

# Option B: Manual command
docker run -it --rm \
  -v "$(pwd)/deck_files":/app/deck_files \
  -v "$(pwd)/logs":/app/logs \
  -v "$(pwd)/csv_files":/app/csv_files \
  mwisnowski/mtg-python-deckbuilder:latest

# Windows PowerShell equivalent
# Download: Invoke-WebRequest -Uri "https://raw.githubusercontent.com/mwisnowski/mtg_python_deckbuilder/main/run-from-dockerhub.bat" -OutFile "run-from-dockerhub.bat"
# Then run: .\run-from-dockerhub.bat
docker run -it --rm `
  -v "${PWD}/deck_files:/app/deck_files" `
  -v "${PWD}/logs:/app/logs" `
  -v "${PWD}/csv_files:/app/csv_files" `
  mwisnowski/mtg-python-deckbuilder:latest

Option 2: Docker from Source

Prerequisites: Docker installed

# Clone the repository
git clone https://github.com/mwisnowski/mtg_python_deckbuilder.git
cd mtg_python_deckbuilder

# Linux/macOS - One-command start
./quick-start.sh

# Windows PowerShell
.\run-docker.ps1 compose

# Manual Docker Compose
docker-compose run --rm mtg-deckbuilder-interactive

Option 3: From Source

git clone https://github.com/mwisnowski/mtg_python_deckbuilder.git
cd mtg_python_deckbuilder
pip install -r requirements.txt
python code/main.py

📋 System Requirements

Component	Requirement
Python	3.11+ (if running from source)
Docker	Latest version (for containerized deployment)
Memory	2GB+ RAM for card database processing
Storage	500MB+ for card data and deck storage
Network	Internet connection for initial card data download

🎯 Usage

First Run Setup

1. Initial Database Setup: Downloads and processes MTG card data
2. Theme Tagging: Automatically categorizes cards by strategy and theme
3. Commander Database: Builds searchable commander index

Building Your First Deck

1. Commander Selection: Search by name, colors, or themes
2. Theme Prioritization: Choose primary, secondary, and tertiary themes
3. Power Bracket: Select target power level (casual to cEDH)
4. Automated Building: Watch as your deck comes together intelligently
5. Instant Results: Deck list displayed immediately for upload to online platforms

Example Workflow

🃏 MTG Python Deckbuilder v1.0.0

Main Menu:
1. Build a New Deck
2. Setup & Configuration
3. Tag CSV Files

> Enter choice: 1

Commander Search: Atraxa
> Found: Atraxa, Praetors' Voice

Power Bracket Selection:
1. Casual (Budget-friendly, fun interactions)
2. Focused (Coherent strategy, some optimization)  
3. Optimized (Efficient, competitive cards)
4. High Power (Near-cEDH, fast combos)

> Power Level: 2

Building deck... ⚡

============================================================
DECK LIST - Atraxa_Superfriends_20250821.txt
Ready for copy/paste to Moxfield, EDHREC, or other deck builders
============================================================
1 Atraxa, Praetors' Voice
1 Jace, the Mind Sculptor
1 Elspeth, Knight-Errant
... (97 more cards)
============================================================

🗂️ File Structure

After running, your workspace will contain:

mtg_python_deckbuilder/
├── deck_files/              # 📁 Your completed decks
│   ├── Atraxa_Superfriends_20250821.csv
│   ├── Atraxa_Superfriends_20250821.txt
│   └── ...
├── csv_files/               # 📊 Card database files
│   ├── commander_cards.csv
│   ├── white_cards.csv
│   └── ...
├── logs/                    # 📝 Application logs
│   └── deck_builder.log
└── code/                    # 💻 Source code (if running from source)

⚙️ Configuration

Docker Configuration

• Volume Mounts: Persist data between container runs
• Interactive Mode: Full terminal interaction support
• Cross-Platform: Consistent behavior across operating systems

Python Configuration

• Virtual Environment: Isolated dependency management
• Type Checking: MyPy integration for development
• Logging: Comprehensive debug and error tracking

🔧 Advanced Usage

Power Bracket System

Bracket	Description	Card Examples
1 - Casual	Budget-friendly, social gameplay	Basic lands, simple removal
2 - Focused	Coherent strategy, light optimization	Shock lands, efficient spells
3 - Optimized	Competitive cards, fast mana	Fetch lands, tutors
4 - High Power	Near-cEDH, powerful combos	Original duals, fast mana

Theme Categories

• Kindred: Creature type synergies (Elves, Dragons, etc.)
• Mechanical: Game mechanic focus (Lifegain, Tokens, etc.)
• Strategic: Win condition strategies (Voltron, Control, etc.)
• Synergistic: Card interaction patterns (Artifacts, Enchantments, etc.)

📦 Dependencies

Core Runtime

pandas >= 1.5.0          # Data processing
inquirer >= 3.1.3        # Interactive menus  
scrython >= 1.10.0       # MTG API integration
numpy >= 1.24.0          # Numerical operations
requests >= 2.31.0       # HTTP requests
fuzzywuzzy >= 0.18.0     # Fuzzy string matching
python-Levenshtein       # String similarity

Development

mypy >= 1.3.0           # Static type checking
pandas-stubs >= 2.0.0   # Type stubs for pandas
pytest >= 8.0.0         # Testing framework

🐳 Docker Details

Docker Hub

The official Docker image is available on Docker Hub:

• Repository: mwisnowski/mtg-python-deckbuilder
• Tags: latest, 1.0.0
• Auto-updates: New versions pushed with each release

# Pull the latest image
docker pull mwisnowski/mtg-python-deckbuilder:latest

# Run with volume mounting for data persistence
docker run -it --rm \
  -v "$(pwd)/deck_files":/app/deck_files \
  -v "$(pwd)/logs":/app/logs \
  -v "$(pwd)/csv_files":/app/csv_files \
  mwisnowski/mtg-python-deckbuilder:latest

Container Features

• Lightweight: Based on Python 3.11-slim
• Persistent Storage: Volume mounts preserve your data
• Interactive Terminal: Full CLI experience in container
• Cross-Platform: Identical behavior on all systems

Docker Commands

# From Docker Hub (easiest)
docker run -it --rm \
  -v "$(pwd)/deck_files":/app/deck_files \
  -v "$(pwd)/logs":/app/logs \
  -v "$(pwd)/csv_files":/app/csv_files \
  mwisnowski/mtg-python-deckbuilder:latest

# Interactive session (from source)
docker-compose run --rm mtg-deckbuilder-interactive

# Background service
docker-compose up mtg-deckbuilder-main

# Custom command
docker run -it --rm -v "$(pwd)":/app/host mtg-deckbuilder python code/main.py

# Build locally
docker build -t mtg-deckbuilder .

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

git clone https://github.com/mwisnowski/mtg_python_deckbuilder.git
cd mtg_python_deckbuilder

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Run type checks
mypy code/

# Run tests
python -m pytest

Contribution Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Test your changes thoroughly
4. Commit with clear messages (git commit -m 'Add amazing feature')
5. Push to your branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📞 Support & Community

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 Documentation: See DOCKER.md for container details
• 🔧 Docker Help: Run ./run-docker.sh help for commands

🙏 Acknowledgments

• MTG JSON for comprehensive card database
• Scryfall for card imagery and additional data
• The Python Community for excellent libraries and tools
• MTG Deckbuilding Community for feedback and inspiration

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

⭐ Star this repository if you find it helpful! ⭐

Built with ❤️ for the Magic: The Gathering community