MTG Python Deckbuilder v4.1.0

Summary

Theme system overhaul with comprehensive badge system, advanced filtering, quality dashboard, and pool size indicators. Includes deck builder enhancements with smart theme sorting, optional pool size sections, and improved partner-aware display. Build process modernized to use parquet files with automatic theme stripping integration.

Added

Theme Catalog Badge System: Three-tier metric visualization with granular display control
- Quality Badges: Editorial quality indicators (Excellent/Good/Fair/Poor) with semantic colors
- Pool Size Badges: Card availability indicators (Vast/Large/Moderate/Small/Tiny) showing total cards per theme
- Popularity Badges: Usage frequency indicators (Very Common/Common/Uncommon/Niche/Rare) based on theme adoption
- Badge Feature Flags: Individual toggle flags for each badge type (SHOW_THEME_QUALITY_BADGES, SHOW_THEME_POOL_BADGES, SHOW_THEME_POPULARITY_BADGES)
- Filter Controls: Dropdown filters and quick-select chips for all three metrics with master toggle (SHOW_THEME_FILTERS)
Theme Catalog Filtering: Advanced filtering system for quality, pool size, and popularity
- Filter Dropdowns: Select-based filters for precise tier selection
- Quick Filter Chips: Single-click filter activation with letter-based shortcuts
- Combined Filtering: Multiple filter types work together with AND logic
- Filter Performance: Backend filtering in both fast path (theme_list.json) and fallback (full index) with sub-200ms response times
Theme Quality Dashboard: Diagnostic dashboard for monitoring catalog health at /diagnostics/quality
- Quality Distribution: Visual breakdown of theme counts by tier (Excellent/Good/Fair/Poor)
- Top/Bottom 10 Lists: Best-curated themes and themes needing improvement with actionable suggestions
- Protected Access: Dashboard gated behind SHOW_DIAGNOSTICS=1 flag for admin use
Theme Badge Explanations: Detailed reasoning for quality, pool size, and popularity badges on individual theme pages
- Quality Explanations: Multi-factor breakdown showing synergy breakdown, deck archetype classification, description curation status
- Pool Size Explanations: Card count with contextual guidance on flexibility and optimization potential
- Popularity Explanations: Adoption pattern descriptions explaining why themes have their popularity tier
Deck Builder Theme Selection: Enhanced theme picker with pool size indicators and smart sorting
- Pool Size Badges: Numeric card count displayed on all theme chips (recommended + general)
- Smart Sorting: Themes automatically sorted by pool size (descending), then alphabetically
- Pool Size Sections: Optional grouping of themes into Vast/Large/Moderate/Small/Tiny sections (THEME_POOL_SECTIONS env var)
- Partner-Aware Sections: Partner themes bucketed into correct pool size section
- Popup Wizard Parity: New Deck modal has full feature parity with legacy builder
Theme Editorial Quality & Standards: Complete editorial system for theme catalog curation
- Editorial Metadata Fields: description_source (tracks provenance: official/inferred/custom) and popularity_pinned (manual tier override)
- Enhanced Quality Scoring: Four-tier system with 0.0-1.0 numerical scores based on uniqueness, duplication, description quality, and metadata completeness
- CLI Linter: validate_theme_catalog.py --lint flag with configurable thresholds and actionable suggestions
- Editorial Documentation: Comprehensive guide at docs/theme_editorial_guide.md
Theme Stripping Configuration: Configurable minimum card threshold for theme retention
- THEME_MIN_CARDS Setting: Environment variable (default: 5) to strip themes with too few cards
- Analysis Tooling: Scripts to visualize theme distribution and identify stripping candidates
- Automatic Integration: Theme stripping runs automatically in run_tagging() after tagging completes

Changed

Build Process Modernization: Theme catalog generation now reads from parquet files instead of obsolete CSV format
- Updated build_theme_catalog.py and extract_themes.py to use parquet data
- Added THEME_MIN_CARDS filtering directly in build pipeline
- theme_list.json now auto-generated from stripped parquet data after theme stripping
- Eliminated manual JSON stripping step (JSON is derived artifact, not source of truth)
Parquet Theme Stripping: Strip low-card themes directly from card data files
- Handles multiple themeTags formats: numpy arrays, lists, and comma/pipe-separated strings
- Stripped 97 theme tag occurrences from 30,674 cards in all_cards.parquet
- Integrated into web UI setup, CLI tagging, and CI/CD workflows

Fixed

Counter Type Tags: Fixed leading spaces in theme names for Blood and Hone counter types
- Corrected Blood to Blood and Hone to Hone in tag_constants.py COUNTER_TYPES list
- Prevents creation of malformed theme names like Blood Counters (with leading space)

For Users

Better Theme Discovery: Visual badges help you quickly identify high-quality themes with large card pools
Advanced Filtering: Find exactly what you're looking for with quality, pool size, and popularity filters
Informed Decisions: Pool size badges show how many cards are available for each theme in your commander's colors
Quality Dashboard: Admin tool to monitor theme catalog health and identify improvement opportunities
Smart Theme Sorting: Themes automatically sorted by card availability to help you find the most flexible options first

Infrastructure

Theme catalog quality scoring system with four tiers
Pool size calculation and tier assignment from parquet data
Advanced filtering system with combined AND logic
Editorial metadata fields for manual curation overrides
Automated theme stripping integration in tagging pipeline
CLI linter for theme quality validation

5.9 KiB Raw Blame History