# 🃏 MTG Python Deckbuilder

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Docker](https://img.shields.io/badge/docker-supported-blue.svg)](https://www.docker.com/)

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](https://www.docker.com/get-started/) installed

```bash
# 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](https://www.docker.com/get-started/) installed

```bash
# 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

```bash
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

```bash
# 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
```bash
# 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
```bash
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](https://github.com/mwisnowski/mtg_python_deckbuilder/issues)
- **💡 Feature Requests**: [GitHub Discussions](https://github.com/mwisnowski/mtg_python_deckbuilder/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](LICENSE) file for details.

---

<div align="center">

**⭐ Star this repository if you find it helpful! ⭐**

*Built with ❤️ for the Magic: The Gathering community*

</div>