Metadata-Version: 2.2
Name: tome-mtg
Version: 1.0.0
Summary: MTG Commander Deck Analyzer - Decode the secrets of your Commander deck
Author: Adrian
License: MIT
Project-URL: Homepage, https://github.com/adrianf/tome-mtg
Project-URL: Repository, https://github.com/adrianf/tome-mtg
Keywords: mtg,magic-the-gathering,commander,edh,deck-analyzer,deck-building
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.42.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0

# Tome - MTG Commander Deck Analyzer


                                                                                                     .-+*+=*+=:
                                                                                                   :=#@@% :@@%#+:
                                                                                                  =@+..-#:.+* .%@+
                                                                                                 .@@%*-:   .::***@-
                                                                                                 =*- .=.     =. -*+
                                                                                                 .@###::.....:*%@@:
                                                                                                  -@@: +* .#-:.+@=
                                                                                                   .=#%@@-.#@@#=:
                                                                                                     .:=+=++=:.
                                                                                   .--::-=-:                             :=++*++-:
                                                                                 ::-=    ...-=                         =#%%@%=+@%%#=
                                                                                *=           :*:                     .#%%%%+. -%%%%%*
                                                                               -=     .. -    .*                     *%%%%=    -%%%%%+
                                                                               +.   .:   ..    +:                    %%%%=      -#%%%#
                                                                               --  -=:   .+++==+                     *%%%      +*.%#%+
                                                                                +##%%*   +%%#%#:                      *%%-       -%%*
                                                                                 :**+-.  :=+*=                         -#%+-...-+%*-
                                                                                   .:---=::                              .=+++++-.



                                                                                             ....                   .:::..
                                                                                         :--++=-:-==.            -+-:::::-==.
                                                                                       .*+:=**=:+=.-*-         :+:-.      .:+=
                                                                                      .####%##==#+. .-=       :*  ::     ..  ++
                                                                                      +####*+***-=+-  *.      *-.%%%*.  =%%%= #.
                                                                                      +##=.     -+. .=#.      **:------:------#
                                                                                      .#*      =+.  -+=       .%%**: -*+  **#%=
                                                                                       .*:       :-==-         .*%@:. :...%%#-
                                                                                         ::.::::=++=.            :+-++*#*:+-
                                                                                            ..::.                    ....
                                                                                                                                            ..
                                                -@%%%%@@@%%%%%%%%@@@%%%%%#                                                                  :=#%%%%%%%@@@@@%%%%@+
                                                -@%@@#**+*@@@@@@%++**%@@@%                                                                    +@%@@@@#++++*#%@@@+
                                                -@%+.    :@%%%%@#     :*@#                                                                    +@%%%%@=       :*@+
                                                -@:      :@%%%%@#       +%         .:-====.              :::::::::.           :::::::::       +@%%%%@+         +*
                                                --       :@%%%%@#        +      -*#%@@@@@%  .%*=.        .=%@@@@@@%.         #@@@@@@%=:       +@%%%%@=          :
                                                         :@%%%%@#             =%@@@@#:.%@=  *@@@%*.        *@%%%%%@#        +@%%%%%@#         +@%%%%@=
                                                         :@%%%%@#            #@@%%@#   +@   =@%%%@%:       *@%%%%%%@*      -@%%%%%%@#         +@%%%%@=
                                                         :@%%%%@#           #@%%%%@.   .=    #@%%%@@:      *@%@@%%%%@=    :@%@@%%%%@#         +@%%%%@%######%*-
                                                         :@%%%%@#          -@%%%%@#          =@%%%%@*      *@%%#@%%%%@:   %@@*%@%%%@#         +@%%%%@%%%%%%#=.
                                                         :@%%%%@#          +@%%%%@*          -@%%%%@%      *@%%.*@%@%@%. *@@* %@%%%@#         +@%%%%@+
                                                         :@%%%%@#          +@%%%%@*          -@%%%%@%      *@%%  %@%@%@*+@@%  %@%%%@#         +@%%%%@=
                                                         :@%%%%@#          =@%%%%@#          =@%%%%@#      *@%%. :@@%@%@@%@: .%@%%%@#         +@%%%%@=           .
                                                         :@%%%%@#           %@%%%@%          *@%%%%@-      *@%%.  -@%%%%%@-   %@%%%@#         +@%%%%@+          -+
                                                         :@%%%%@#           :%@%%%@+        :@%%%@@=       *@%%.   =@%@%@+    %@%%%@#         +@%%%%@=         =@+
                                                         :@%%%%%%            .*@@@%@+      -%@@@@%-        *@%%.    *@%@#     %%%%%@#         =@%%%%@+......-+#@@+
                                                       .:+@@@@@@@#:            :+%@@@@#++*%@@@%*-         :%@@@.     #@%.     @@@@@@%:       :#@@@@@@@@@@@@@@@@@@*
                                                      :-===========:.             .-=+*##**+=:           :=====      .%:      ========-     :====================:


**Tome** is a Python CLI tool that analyzes Commander decklists against best practices, combining rule-based heuristics validation with LLM-powered strategic analysis using the Scryfall API for card data and Claude API for intelligent recommendations.

> 📖 *Decode the secrets of your Commander deck*

## Features

### Deck Analysis
- **Decklist Parsing**: Supports multiple common formats (Moxfield, MTGO, simple text)
- **Moxfield URL Support**: Analyze decks directly from Moxfield URLs
- **Flexible Deck Size**: Analyze incomplete (<100) or oversized (>100) decks with suggestions
- **Scryfall Integration**: Automatic card data retrieval with 30-day local caching

### Heuristic Validation
Checks your deck against established Commander best practices:
- Land count and mana base analysis
- Ramp spells (8-10 recommended)
- Card draw (10+ recommended)
- Removal and board wipes
- Instant-speed interaction
- Graveyard hate
- Color fixing analysis per color

### Budget Analysis
- Total deck cost calculation
- Identifies expensive cards (>10% of budget)
- Budget category classification (Ultra-Budget to No-Budget)

### LLM Strategic Analysis
- Claude-powered insights on theme, synergies, and improvements
- Interactive chat mode for follow-up questions
- Context-aware recommendations based on your deck's strengths and weaknesses

### Interactive Deck Modification
- Add cards: `add Sol Ring` or `add Rhystic Study x2`
- Remove cards: `remove Temple of the False God`
- Swap cards: `swap Diabolic Tutor for Demonic Tutor`
- Batch add/remove: paste multiple card names at once
- Export updated decklist in Moxfield-compatible format

### Collection Comparison
- Compare your deck against your existing card collection
- Find budget savings: cards you own that could replace expensive cards
- Find upgrades: better cards you already have
- Interactive swap acceptance: `accept 1` or `accept all budget`

### Beautiful Terminal UI
- Color-coded ASCII art banner
- MTG-themed loading states ("Scrying 3...", "Consulting the council...")
- Formatted tables and visual mana curve

## Installation

### Quick Install (Recommended)

```bash
pip install tome-mtg
```

### Configure API Key

Set your Anthropic API key as an environment variable:

```bash
# On Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "your_api_key_here"

# On Windows (Command Prompt)
set ANTHROPIC_API_KEY=your_api_key_here

# On macOS/Linux
export ANTHROPIC_API_KEY=your_api_key_here
```

Or create a `.env` file in your working directory:

```
ANTHROPIC_API_KEY=your_api_key_here
```

Get your API key from: https://console.anthropic.com/

### Install from Source

```bash
git clone https://github.com/adrianf/tome-mtg.git
cd tome-mtg
pip install -e .
```

## Usage

### Basic Analysis

Analyze a Commander decklist:

```bash
tome analyze my_deck.txt
```

Or using Python module:

```bash
python -m tome analyze my_deck.txt
```

### Decklist Format

The analyzer supports multiple formats:

```text
// Commander section (optional)
Commander:
1 Korvold, Fae-Cursed King

// Main deck
Deck:
1 Sol Ring
1x Arcane Signet
1 x Command Tower
Blasphemous Act

// Comments are supported
// Lines starting with // or # are ignored
```

Supported formats:
- `1x Card Name` or `1 x Card Name`
- `1 Card Name`
- `Card Name` (assumes quantity 1)

### Example Output

```
╔═══════════════════════════════════════╗
║  Korvold, Fae-Cursed King             ║
║  Commander: Korvold, Fae-Cursed King  ║
╚═══════════════════════════════════════╝

DECK OVERVIEW
Total Cards: 100
Average CMC: 3.2 (non-land)
Color Identity: B/R/G

HEURISTIC CHECKLIST
┌──────────────┬────────┬──────────┬────────┐
│ Category     │ Count  │ Expected │ Status │
├──────────────┼────────┼──────────┼────────┤
│ Lands        │ 38     │ 37-39    │   ✓    │
│ Ramp         │ 10     │ 8-10     │   ✓    │
│ Card Draw    │ 9      │ 10+      │   ✗    │
│ Removal      │ 8      │ ~8       │   ✓    │
│ Board Wipes  │ 4      │ 3-5      │   ✓    │
└──────────────┴────────┴──────────┴────────┘

MANA CURVE
  0 | ██ 2
  1 | ████ 4
  2 | ████████████████ 14
  3 | ████████████████ 14
  4 | ████████████ 10
  5 | ████████ 7
  6 | ████ 4
 7+ | ██ 2

Average CMC: 3.2

STRATEGIC ANALYSIS

**Theme Assessment:**
This is a well-constructed Jund sacrifice/aristocrats deck...

[LLM analysis continues...]

Interactive Mode
Ask questions about your deck (or type 'quit' to exit)

> What should I replace to add more card draw?
[Claude response...]
```

### Collection Comparison

Compare your deck against cards you already own:

```bash
tome analyze my_deck.txt --collection my_collection.txt
```

The collection file uses the same format as deck files. Tome will suggest:
- Budget swaps: expensive cards that can be replaced with cheaper cards you own
- Upgrades: better cards you already have

### Interactive Mode

After the analysis, you can ask questions about your deck:

```
> What cards should I cut for more draw?
> Is this deck too slow?
> Should I add more ramp or cut lands?
> show swaps          # Show collection swap suggestions again
> accept 1            # Accept swap suggestion #1
> accept all budget   # Accept all high-confidence budget swaps
> quit
```

## Project Structure

```
mtg/
├── tome/                  # Main package
│   ├── __init__.py
│   ├── __main__.py        # Entry point
│   ├── cli.py             # CLI interface
│   ├── parser.py          # Decklist parsing
│   ├── scryfall_client.py # Scryfall API client
│   ├── models.py          # Data models
│   ├── heuristics.py      # Deck building rules
│   ├── analyzer.py        # Rule-based analysis
│   ├── llm_analyzer.py    # Claude integration
│   ├── formatter.py       # Terminal output
│   └── loading_states.py  # MTG-themed loading messages
├── learnings/             # Deck building guides
├── cache/                 # Card data cache (auto-generated)
├── requirements.txt       # Dependencies
├── .env                   # API keys (create from .env.template)
└── README.md             # This file
```

## Cost Estimates

- **Scryfall API**: Free (with rate limiting)
- **Claude Analysis**: ~$0.05 per deck analysis
- **Interactive Questions**: ~$0.01-0.02 per question
- **Total**: ~$0.05-0.10 per deck with questions

## Troubleshooting

### "ANTHROPIC_API_KEY not found"
Make sure you've created the `.env` file and added your API key.

### "Card not found in Scryfall"
The tool uses fuzzy matching, but some card names may not be recognized. Double-check spelling or try the exact name from Scryfall.

### Import errors
Make sure you've installed the package correctly:
```bash
pip install tome-mtg
```

## Contributing

This is a personal project, but suggestions are welcome! Feel free to fork and customize for your own use.

## License

MIT License - Free to use and modify for personal use.

## Credits

- **Scryfall**: Card data provided by Scryfall API (https://scryfall.com/)
- **Anthropic**: LLM analysis powered by Claude API
- **Deck Building Heuristics**: Based on guides in the `learnings/` folder

## Support

For issues or questions, check the troubleshooting section above or review the code comments in each module.

Happy deck building! 🎴
