mtg_python_deckbuilder/.env.example

######################################################################
# MTG Python Deckbuilder – Environment Variables Reference
#
# Copy this file to `.env` and uncomment the lines you want to override.
# All lines are commented so copying it is safe; defaults apply otherwise.
######################################################################

############################
# Core Application Modes
############################
# DECK_MODE=headless                 # headless|auto|<blank>. When set to 'headless' (or 'auto'), runs non-interactive build on start (CLI entrypoint).
# APP_MODE=web                       # (Not explicitly set in dockerhub compose; uncomment to force.)
# HOST=0.0.0.0                       # Uvicorn bind host (only when APP_MODE=web).
# PORT=8080                          # Uvicorn port.
# WORKERS=1                          # Uvicorn worker count.
APP_VERSION=v3.0.1                 # Matches dockerhub compose.

############################
# Theming
############################
THEME=system                        # system|light|dark (initial default; user preference persists in browser).

############################
# Paths & Directories (override discovery)
############################
# DECK_CONFIG=/app/config/deck.json  # File OR directory. File: run that config. Dir: discover JSON configs. CLI>ENV precedence.
# DECK_EXPORTS=/app/deck_files       # Where finished deck exports are read by Web UI.
# OWNED_CARDS_DIR=/app/owned_cards   # Preferred directory for owned inventory uploads.
# CARD_LIBRARY_DIR=/app/owned_cards  # Back-compat alias for OWNED_CARDS_DIR.
# CSV_FILES_DIR=/app/csv_files       # Override CSV base dir (DEPRECATED v3.0.0+, use CARD_FILES_* instead)
# CARD_INDEX_EXTRA_CSV=              # Inject an extra CSV into the card index for testing

# Parquet-based card files (v3.0.0+)
# CARD_FILES_DIR=card_files          # Base directory for Parquet files (default: card_files)
# CARD_FILES_RAW_DIR=card_files/raw  # Raw MTGJSON Parquet files (default: card_files/raw)
# CARD_FILES_PROCESSED_DIR=card_files/processed  # Processed/tagged Parquet files (default: card_files/processed)

# Legacy CSV compatibility (v3.0.0 only, removed in v3.1.0)
# LEGACY_CSV_COMPAT=0                # Set to 1 to enable CSV fallback when Parquet loading fails

############################
# Web UI Feature Flags
############################
SHOW_SETUP=1                        # dockerhub: SHOW_SETUP="1"
SHOW_LOGS=1                         # dockerhub: SHOW_LOGS="1"
SHOW_DIAGNOSTICS=1                  # dockerhub: SHOW_DIAGNOSTICS="1"
ENABLE_THEMES=1                     # dockerhub: ENABLE_THEMES="1"
ENABLE_CUSTOM_THEMES=1              # dockerhub: ENABLE_CUSTOM_THEMES="1"
USER_THEME_LIMIT=8                  # dockerhub: USER_THEME_LIMIT="8"
ENABLE_PWA=0                        # dockerhub: ENABLE_PWA="0"
ENABLE_PRESETS=0                    # dockerhub: ENABLE_PRESETS="0"
WEB_VIRTUALIZE=1                    # dockerhub: WEB_VIRTUALIZE="1"
ALLOW_MUST_HAVES=1                  # dockerhub: ALLOW_MUST_HAVES="1"
SHOW_MUST_HAVE_BUTTONS=0           # dockerhub: SHOW_MUST_HAVE_BUTTONS="0" (set to 1 to surface must include/exclude buttons)
WEB_THEME_PICKER_DIAGNOSTICS=1      # dockerhub: WEB_THEME_PICKER_DIAGNOSTICS="1"
ENABLE_CARD_DETAILS=1               # dockerhub: ENABLE_CARD_DETAILS="1"
SIMILARITY_CACHE_ENABLED=1          # dockerhub: SIMILARITY_CACHE_ENABLED="1"
SIMILARITY_CACHE_PATH="card_files/similarity_cache.parquet"     # Path to Parquet cache file
ENABLE_BATCH_BUILD=1                # dockerhub: ENABLE_BATCH_BUILD="1" (enable Build X and Compare feature)

############################
# Partner / Background Mechanics
############################
# HEADLESS_EXPORT_JSON=1              # 1=export resolved run config JSON
ENABLE_PARTNER_MECHANICS=1          # 1=unlock partner/background commander inputs for headless (web wiring in progress)
ENABLE_PARTNER_SUGGESTIONS=1        # 1=enable partner suggestion API and UI chips (dataset auto-refreshes when missing)
# PARTNER_SUGGESTIONS_DATASET=config/analytics/partner_synergy.json  # Optional override path for the suggestion dataset

############################
# Random Modes (alpha)
############################
RANDOM_MODES=1                     # Enable backend random build endpoints
RANDOM_UI=1                        # Show Surprise/Reroll/Share controls in UI
RANDOM_MAX_ATTEMPTS=5              # Cap retry attempts for constrained random builds
# RANDOM_TIMEOUT_MS=5000             # Per-attempt timeout (ms)
# RANDOM_REROLL_THROTTLE_MS=350      # Minimum ms between reroll requests
# RANDOM_STRUCTURED_LOGS=0           # 1=emit structured JSON logs for random builds
# RANDOM_TELEMETRY=0                 # 1=emit lightweight timing/attempt metrics
# HEADLESS_RANDOM_MODE=1             # Force headless runner to invoke random flow instead of scripted build
# RANDOM_THEME=Treasure              # Legacy single-theme alias (maps to primary theme if others unset)
# RANDOM_PRIMARY_THEME=Treasure      # Primary theme slug (case-insensitive)
# RANDOM_SECONDARY_THEME=Artifacts   # Secondary theme slug
# RANDOM_TERTIARY_THEME=Tokens       # Tertiary theme slug
RANDOM_AUTO_FILL=1                 # Auto-fill missing secondary/tertiary slots
RANDOM_AUTO_FILL_SECONDARY=1       # Explicit secondary auto-fill override (fallback from RANDOM_AUTO_FILL)
RANDOM_AUTO_FILL_TERTIARY=1        # Explicit tertiary auto-fill override (fallback from RANDOM_AUTO_FILL)
# RANDOM_STRICT_THEME_MATCH=0        # Require strict commander theme matches
# RANDOM_CONSTRAINTS=                # Inline JSON or path to JSON constraints for random selection
# RANDOM_CONSTRAINTS_PATH=           # Alternate path-based constraints override (takes precedence if set)
# RANDOM_SEED=                       # Optional deterministic seed (int or string)
# RANDOM_OUTPUT_JSON=deck_files/random_build.json  # Where to write random build metadata payload

# Optional server rate limiting (random endpoints)
# RATE_LIMIT_ENABLED=0               # 1=enable server-side rate limiting for random endpoints
# RATE_LIMIT_WINDOW_S=10             # window size in seconds
# RATE_LIMIT_RANDOM=10               # max random attempts per window
# RATE_LIMIT_BUILD=10                # max builds per window
# RATE_LIMIT_SUGGEST=30              # max suggestions per window

############################
# Automation & Performance (Web)
############################
WEB_AUTO_SETUP=1                    # dockerhub: WEB_AUTO_SETUP="1"
WEB_AUTO_REFRESH_DAYS=7             # dockerhub: WEB_AUTO_REFRESH_DAYS="7"
WEB_TAG_PARALLEL=1                  # dockerhub: WEB_TAG_PARALLEL="1"
WEB_TAG_WORKERS=2                   # dockerhub: WEB_TAG_WORKERS="4"
WEB_AUTO_ENFORCE=0                  # dockerhub: WEB_AUTO_ENFORCE="0"

# Card Image Caching (optional, uses Scryfall bulk data API)
CACHE_CARD_IMAGES=1                 # dockerhub: CACHE_CARD_IMAGES="1" (1=download images to card_files/images/, 0=fetch from Scryfall API on demand)

# Build Stage Ordering
WEB_STAGE_ORDER=new                 # new|legacy. 'new' (default): creatures → spells → lands → fill. 'legacy': lands → creatures → spells → fill

# Ideals UI Mode
WEB_IDEALS_UI=slider                # input|slider. 'slider' (default): range sliders with live value display. 'input': text input boxes

# Tagging Refinement Feature Flags
TAG_NORMALIZE_KEYWORDS=1            # dockerhub: TAG_NORMALIZE_KEYWORDS="1"    # Normalize keywords & filter specialty mechanics
TAG_PROTECTION_GRANTS=1             # dockerhub: TAG_PROTECTION_GRANTS="1"     # Protection tag only for cards granting shields
TAG_METADATA_SPLIT=1                # dockerhub: TAG_METADATA_SPLIT="1"        # Separate metadata tags from themes in CSVs

# DFC_COMPAT_SNAPSHOT=0             # 1=write legacy unmerged MDFC snapshots alongside merged catalogs (deprecated compatibility workflow)
# WEB_CUSTOM_EXPORT_BASE=           # Custom basename for exports (optional).
# THEME_CATALOG_YAML_SCAN_INTERVAL_SEC=2.0  # Poll for YAML changes (dev)
# WEB_THEME_FILTER_PREWARM=0         # 1=prewarm common filters for faster first renders

############################
# Testing & CI helpers
############################
# EDITORIAL_TEST_USE_FIXTURES=0      # 1=stage lightweight catalog fixtures for editorial governance tests (CI convenience)

############################
# Headless Export Options
############################
# HEADLESS_EXPORT_JSON=1             # 1=export resolved run config JSON alongside CSV/TXT (headless runs only).

############################
# Commander & Theme Selection (Headless / Env Overrides)
############################
# DECK_COMMANDER=Pantlaza, Sun-Favored          # Commander name query.
# (Index-based theme choices – mutually exclusive with *_TAG names per slot):
# DECK_PRIMARY_CHOICE=1
# DECK_SECONDARY_CHOICE=2
# DECK_TERTIARY_CHOICE=3
# (Name-based theme tags – preferred; resolved to indices automatically):
# DECK_PRIMARY_TAG=Tokens
# DECK_SECONDARY_TAG=Treasure
# DECK_TERTIARY_TAG=Sacrifice
# DECK_BRACKET_LEVEL=3               # 1–5 Power/Bracket selection.
# DECK_ADDITIONAL_THEMES=Lifegain;Tokens Matter  # Supplemental themes (comma/semicolon separated list) resolved via theme catalog.
# THEME_MATCH_MODE=permissive         # permissive|strict fuzzy resolution (strict aborts on unresolved themes).

############################
# Category Toggles (Spell / Creature / Land Inclusion)
############################
# DECK_ADD_LANDS=1                   # Include land-building sequence.
# DECK_ADD_CREATURES=1               # Add creatures.
# DECK_ADD_NON_CREATURE_SPELLS=1     # Bulk add for non-creatures (if supported); else individual toggles below.
# DECK_ADD_RAMP=1
# DECK_ADD_REMOVAL=1
# DECK_ADD_WIPES=1
# DECK_ADD_CARD_ADVANTAGE=1
# DECK_ADD_PROTECTION=1

############################
# Land Count Requests / Adjustments
############################
# DECK_FETCH_COUNT=3                 # Requested fetch land count.
# DECK_DUAL_COUNT=                   # Requested dual land count (optional).
# DECK_TRIPLE_COUNT=                 # Requested triple land count (optional).
# DECK_UTILITY_COUNT=                # Requested utility land count (optional).

############################
# Optional Convenience / Misc (normally container-set or not required)
############################
PYTHONUNBUFFERED=1                  # Improves real-time log flushing.
TERM=xterm-256color                 # Terminal color capability.
DEBIAN_FRONTEND=noninteractive      # Suppress apt UI in Docker builds.

############################
# Editorial / Theme Catalog (Phase D) – Advanced
############################
# The following variables control automated theme catalog generation,
# description heuristics, popularity bucketing, backfilling curated YAML,
# and optional regression/metrics outputs. They are primarily for maintainers
# refining the catalog; leave commented for normal use.
#
# EDITORIAL_SEED=1234                     # Deterministic seed for reproducible ordering & any randomness.
# EDITORIAL_AGGRESSIVE_FILL=0             # 1=borrow extra inferred synergies for very sparse themes.
# EDITORIAL_POP_BOUNDARIES=50,120,250,600 # Override popularity bucket thresholds (must be 4 ascending ints).
# EDITORIAL_POP_EXPORT=0                  # 1=write theme_popularity_metrics.json with bucket counts.
# EDITORIAL_BACKFILL_YAML=0               # 1=write auto description/popularity back into per-theme YAML (missing only).
# EDITORIAL_INCLUDE_FALLBACK_SUMMARY=0    # 1=embed generic description usage summary in theme_list.json.
# EDITORIAL_REQUIRE_DESCRIPTION=0         # 1=lint failure if any theme missing description (lint script usage).
# EDITORIAL_REQUIRE_POPULARITY=0          # 1=lint failure if any theme missing popularity bucket.
# EDITORIAL_MIN_EXAMPLES=0                # (Future) minimum curated examples (cards/commanders) target.
# EDITORIAL_MIN_EXAMPLES_ENFORCE=0        # (Future) enforce vs warn.

############################
# Sampling & Rarity Tuning (advanced)
############################
# SPLASH_ADAPTIVE=0                  # 1=enable adaptive off-color penalty
# SPLASH_ADAPTIVE_SCALE=1:1.0,2:1.0,3:1.0,4:0.6,5:0.35
# RARITY_W_MYTHIC=1.2
# RARITY_W_RARE=0.9
# RARITY_W_UNCOMMON=0.65
# RARITY_W_COMMON=0.4
# RARITY_DIVERSITY_TARGETS=mythic:0-1,rare:0-2,uncommon:0-4,common:0-6
# RARITY_DIVERSITY_OVER_PENALTY=-0.5

############################
# Theme Preview Cache & Redis (optional)
############################
# THEME_PREVIEW_CACHE_MAX=400                # Max previews cached in memory
# WEB_THEME_PREVIEW_LOG=0                    # 1=verbose cache logs
# THEME_PREVIEW_ADAPTIVE=0                   # 1=adaptive cache policy
# THEME_PREVIEW_EVICT_COST_THRESHOLDS=5,15,40
# THEME_PREVIEW_BG_REFRESH=0                 # 1=background refresh worker
# THEME_PREVIEW_BG_REFRESH_INTERVAL=120      # seconds
# THEME_PREVIEW_TTL_BASE=300
# THEME_PREVIEW_TTL_MIN=60
# THEME_PREVIEW_TTL_MAX=900
# THEME_PREVIEW_TTL_BANDS=0.2,0.5,0.8
# THEME_PREVIEW_TTL_STEPS=2,4,2,3,1
# THEME_PREVIEW_REDIS_URL=redis://localhost:6379/0
# THEME_PREVIEW_REDIS_DISABLE=0              # 1=disable redis even if URL set


######################################################################
# Notes
# - CLI arguments override env vars; env overrides JSON config; JSON overrides defaults.
# - For include/exclude card functionality enable ALLOW_MUST_HAVES=1 (Web) and use UI or CLI flags.
# - For Random Modes UI, set RANDOM_MODES=1 and RANDOM_UI=1; see /random.
# - Path overrides must point to mounted volumes inside the container.
# - Remove a value or leave it commented to fall back to internal defaults.
######################################################################