mtg_python_deckbuilder/README.md

<EFBFBD><EFBFBD># <<EFBFBD><EFBFBD><EFBFBD> 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

### <<EFBFBD><EFBFBD><EFBFBD><0F> **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

### =<3D><><EFBFBD> **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

### =<3D><04> **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

### =<3D>3<EFBFBD> **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

# Run directly from Docker Hub (no git clone needed!)
docker run -it --rm -v "$(pwd)":/app/host mwisnowski/mtg-python-deckbuilder:latest

# Windows PowerShell equivalent
docker run -it --rm -v "${PWD}:/app/host" 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: Python Package

```bash
pip install mtg-deckbuilder
mtg-deckbuilder
```

### Option 4: 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
```

## =<3D><><EFBFBD> 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 |

## <د<EFBFBD> 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
```
<<EFBFBD><EFBFBD><EFBFBD> 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... <00>&

============================================================
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)
============================================================
```

## =<3D><><EFBFBD><0F> File Structure

After running, your workspace will contain:

```
mtg_python_deckbuilder/
%%% deck_files/              # =<3D><><EFBFBD> Your completed decks
%   %%% Atraxa_Superfriends_20250821.csv
%   %%% Atraxa_Superfriends_20250821.txt
%   %%% ...
%%% csv_files/               # =<3D><><EFBFBD> Card database files
%   %%% commander_cards.csv
%   %%% white_cards.csv
%   %%% ...
%%% logs/                    # =<3D><><EFBFBD> Application logs
%   %%% deck_builder.log
%%% code/                    # =ػ<> Source code (if running from source)
```

## <00>&<0F> 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

## =<3D>'<27> 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.)

## =<3D><><EFBFBD> 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
```

## =<3D>3<EFBFBD> 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)":/app/host 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)":/app/host 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 .
```

## ><3E><1D> 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

## =<3D><><EFBFBD> Support & Community

- **=<3D><1B> Bug Reports**: [GitHub Issues](https://github.com/mwisnowski/mtg_python_deckbuilder/issues)
- **=ء<> Feature Requests**: [GitHub Discussions](https://github.com/mwisnowski/mtg_python_deckbuilder/discussions)
- **=<3D><><EFBFBD> Documentation**: See `DOCKER.md` for container details
- **=<3D>'<27> Docker Help**: Run `./run-docker.sh help` for commands

## =<3D>O<EFBFBD> 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

## =<3D><><EFBFBD> License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

<div align="center">

**P+ Star this repository if you find it helpful! P+**

*Built with d'<0F> for the Magic: The Gathering community*

</div>