major-domo-v2/commands/players/CLAUDE.md

Player Commands

This directory contains Discord slash commands for player information and statistics.

Files

info.py

• Command: /player
• Description: Display comprehensive player information and statistics
• Parameters:
  • name (required): Player name to search for
  • season (optional): Season for statistics (defaults to most recent season player appears in)
• Service Dependencies:
  • player_service.search_players() - All-season search with deduplication
  • player_service.get_players_by_name() - Season-specific search
  • player_service.search_players_fuzzy() - Fallback fuzzy matching
  • player_service.get_player()
  • stats_service.get_player_stats()

Key Features

All-Season Player Search (v2.27.0 - January 2025)

• Autocomplete: Searches across ALL 13 seasons, returns deduplicated unique player names
• Display Format: "Player Name (Position) - Team" showing most recent season's team
• Deduplication: Only shows one entry per player name (most recent season takes priority)
• Minimum Characters: Requires 2+ characters before autocomplete activates

Player Search

• All-Season Default: When no season specified, searches all seasons and uses most recent
• Season-Specific: When season parameter provided, searches only that season
• Fuzzy Search Fallback: If no exact match, suggests similar player names with season info
• Multiple Player Handling: When multiple players match, shows season info to help distinguish
• Suggestion System: Shows up to 10 suggested players with positions and seasons

Player Information Display

• Basic Info: Name, position(s), team, season, sWAR, injury status
• Injury Indicator: 🤕 emoji in title if player has active injury
• Injury Information:
  • Injury Rating (always displayed)
  • Injury Return date (displayed only when injured, format: w##g#)
• Statistics Integration:
  • Batting stats displayed in two inline fields with rounded box code blocks:
    • Rate Stats: AVG, OBP, SLG, OPS, wOBA
    • Counting Stats: HR, RBI, R, AB, H, BB, SO
  • Pitching stats displayed in two inline fields with rounded box code blocks:
    • Record Stats: G-GS, W-L, H-SV, ERA, WHIP, IP
    • Counting Stats: SO, BB, H
  • Two-way player detection and display
• Visual Elements:
  • Player name as embed title (with 🤕 emoji if injured)
  • Player card image as main image
  • Thumbnail priority: fancy card → headshot → team logo
  • Team color theming for embed

Advanced Features

• Concurrent Data Fetching: Player data and statistics retrieved in parallel for performance
• sWAR Display: Shows Strat-o-Matic WAR value
• Multi-Position Support: Displays all eligible positions
• Rich Error Handling: Graceful fallbacks when data is unavailable

Architecture Notes

Search Logic Flow

1. Without season parameter: Search ALL seasons via search_players(all_seasons=True), use most recent match
2. With season parameter: Search only specified season via get_players_by_name()
3. If no results, try fuzzy search across all seasons
4. If single result, display player card
5. If multiple results, attempt exact name match
6. If still multiple, show disambiguation list with season info

Performance Optimizations

• asyncio.gather() for concurrent API calls
• Efficient player data and statistics retrieval
• Lazy loading of optional player images

Error Handling

• No players found: Suggests fuzzy matches
• Multiple matches: Provides clarification options
• Missing data: Shows partial information with clear indicators
• API failures: Graceful degradation with fallback data

Troubleshooting

Common Issues

1. Player not found:

   • Check player name spelling
   • Verify player exists in the specified season
   • Use fuzzy search suggestions

2. Statistics not loading:

   • Verify stats_service.get_player_stats() API endpoint
   • Check if player has statistics for the requested season
   • Ensure season parameter is valid

3. Images not displaying:

   • Check player image URLs in database
   • Verify team thumbnail URLs
   • Ensure image hosting is accessible

4. Performance issues:

   • Monitor concurrent API call efficiency
   • Check database query performance
   • Verify embed size limits

Dependencies

• services.player_service
• services.stats_service
• utils.decorators.logged_command
• views.embeds.EmbedTemplate
• constants.SBA_CURRENT_SEASON
• exceptions.BotException

Testing

Run tests with: python -m pytest tests/test_commands_players.py -v

Stat Display Format (January 2025)

Batting Stats

Stats are displayed in two side-by-side inline fields using rounded box code blocks:

Rate Stats (Left):

╭─────────────╮
│ AVG  .305  │
│ OBP  .385  │
│ SLG  .545  │
│ OPS  .830  │
│ wOBA .355  │
╰─────────────╯

Counting Stats (Right):

╭───────────╮
│  HR  25  │
│ RBI  80  │
│   R  95  │
│  AB 450  │
│   H 137  │
│  BB  55  │
│  SO  98  │
╰───────────╯

Pitching Stats

Stats are displayed in two side-by-side inline fields using rounded box code blocks:

Record Stats (Left):

╭─────────────╮
│ G-GS 28-28  │
│  W-L 12-8   │
│ H-SV  3-0   │
│  ERA  3.45  │
│ WHIP  1.25  │
│   IP 165.1  │
╰─────────────╯

Counting Stats (Right):

╭────────╮
│ SO 185 │
│ BB  48 │
│  H 145 │
╰────────╯

Design Features:

• Compact, professional appearance using rounded box characters (╭╮╰╯─│)
• Right-aligned numeric values for clean alignment
• Inline fields allow side-by-side display
• Empty field separator above stats for visual spacing
• Consistent styling between batting and pitching displays

Database Requirements

• Player records with name, positions, team associations
• Player injury data (injury_rating, il_return fields)
• Statistics tables for batting and pitching
• Image URLs for player cards, headshots, and fancy cards
• Team logo and color information