31a4995bbe
- Add build_deck.py script for automated deck building - Support multiple collection files for comprehensive deck building - Rename main collection file to full_collection.json - Add comprehensive documentation and usage examples - Include design and implementation plans - Enhance synergy detection and commander suggestion
109 lines
3.5 KiB
Markdown
109 lines
3.5 KiB
Markdown
# AGENTS.md
|
|
|
|
Guide for AI assistants working on this codebase.
|
|
|
|
## Build/Verify Commands
|
|
|
|
This project has no external dependencies or test framework.
|
|
|
|
```bash
|
|
# No lint/typecheck commands currently
|
|
# Verify scripts work by running them:
|
|
python hydrate.py --help
|
|
python scripts/analyze_decks.py --help
|
|
```
|
|
|
|
## Code Style
|
|
|
|
- **Language:** Python 3 (stdlib only, no external packages)
|
|
- **Formatting:** 4-space indent, max line length ~100
|
|
- **Imports:** Standard library only (argparse, json, pathlib, urllib, re, sys, os, time)
|
|
- **CLI:** Use `argparse` with subparsers for multi-command tools
|
|
- **Error handling:** Print to stderr, use sys.exit(1) for failures
|
|
- **Docstrings:** Triple-quoted at module and function level with usage examples
|
|
- **Type hints:** Optional but encouraged for complex functions
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
├── hydrate.py # Main CLI - fetches card data from Scryfall
|
|
├── cache/
|
|
│ └── card_cache.json # Local cache of Scryfall card data
|
|
├── output/
|
|
│ ├── deck_analysis.json # Analysis output
|
|
│ └── hydrated/ # Enriched card data by type
|
|
│ ├── deck.json # All cards combined
|
|
│ ├── commander.json
|
|
│ ├── creatures.json
|
|
│ ├── instants.json
|
|
│ ├── sorceries.json
|
|
│ ├── artifacts.json
|
|
│ ├── enchantments.json
|
|
│ ├── lands.json
|
|
│ └── planeswalkers.json
|
|
├── data/
|
|
│ ├── collection/ # Raw decklist text files
|
|
│ └── decks/ # Deck definitions (JSON)
|
|
│ └── <deck_name>.json # name, commander, colors, archetype, cards
|
|
├── scripts/
|
|
│ ├── analyze_decks.py # Find upgrade options for decks
|
|
│ ├── find_synergies.py # Search for synergistic cards
|
|
│ ├── parse_deck.py # Parse text decklists to JSON
|
|
│ └── deck_report.py # Generate markdown reports
|
|
└── docs/
|
|
└── templates/ # Documentation templates
|
|
```
|
|
|
|
## Data Formats
|
|
|
|
### Deck JSON (`data/decks/*.json`)
|
|
|
|
```json
|
|
{
|
|
"name": "Deck Name",
|
|
"commander": "Commander Name",
|
|
"colors": ["U", "G", "W"],
|
|
"archetype": "Theme Description",
|
|
"cards": {
|
|
"Card Name": count,
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
### Card Data (`output/hydrated/*.json`)
|
|
|
|
Array of card objects with Scryfall fields:
|
|
- `name`, `mana_cost`, `cmc`, `colors`, `color_identity`
|
|
- `type_line`, `oracle_text`, `power`, `toughness`, `loyalty`
|
|
- `scryfall_uri`, `count`
|
|
|
|
## Extension Guide
|
|
|
|
### Adding a New Deck
|
|
|
|
1. Create `data/decks/<name>.json` with required fields
|
|
2. Run `python scripts/update_docs.py` to regenerate documentation
|
|
|
|
### Adding a New Script
|
|
|
|
1. Create `scripts/<name>.py` with argparse CLI
|
|
2. Follow existing patterns: `load_collection()`, argparse with --help
|
|
3. Update README template with usage example
|
|
4. Run `python scripts/update_docs.py`
|
|
|
|
### Modifying Deck Analysis
|
|
|
|
- `scripts/analyze_decks.py`: Core logic for finding upgrades
|
|
- Color identity matching uses `color_identity` field from Scryfall
|
|
- Cards are categorized by `type_line`
|
|
|
|
## Current Decks
|
|
|
|
| Deck | Colors | Commander | Archetype |
|
|
|------|--------|-----------|-----------|
|
|
| my_choco_deck | BUW | G'raha Tia, Scion Reborn | Auto-generated |
|
|
| Choco | UGW | Choco, Seeker of Paradise | Bird Tribal Landfall |
|
|
| Hazel | BG | Hazel of the Rootbloom | Golgari Aristocrats |
|
|
| Palamecia | UR | The Emperor of Palamecia // The Lord Master of Hell | Izzet Self-Mill Storm |
|
|
| Yshtola | UBW | Y'shtola, Night's Blessed | Esper Stax Drain | |