Fantasy Football Trade Analyzer

A production-quality CLI tool for fantasy football trade analysis that finds optimal trades using real player values, slot rankings, and advanced algorithms.

✨ Current Features

• 🔍 Instant Player Lookups - New players command for instant player/team searches and roster views
• 🧠 Advanced Trade Engine - Production CLI with comprehensive trade generation and caching system
• 📊 Slot Ranking Analysis - League-wide positional rankings (QB, RB1/RB2, WR1/WR2, TE, FLEX1/FLEX2)
• ⚖️ Bench Drop Penalty System - Accounts for roster management complexity in imbalanced trades
• 🎯 Strategic Filtering - Multiple filter chains including fair ratios, win-win trades, team targeting
• 📈 Real-Time Data Integration - FantasyCalc API + Sleeper GraphQL with caching and validation
• 🏆 Multi-Tier Trade Analysis - Clear trade tiers with ranking improvements and strategic scoring
• 🛠️ Clean Architecture - Separation of concerns: data → generation → filtering → presentation

🚀 Quick Start

1. Sync League Data

# Pull latest player values and rosters
python3 tradefinder.py sync

2. Quick Player Lookups (NEW!)

# Look up specific players (instant owner + value lookup)
python3 tradefinder.py players "Josh Jacobs" "Davante Adams"
# Josh Jacobs    cb0729    6,409 pts    RB
# Davante Adams  bool1060  4,824 pts    WR

# Just get team ownership (perfect for "who owns X?" questions)
python3 tradefinder.py players "Josh Jacobs" --team-only
# cb0729

# View full team roster with values
python3 tradefinder.py players --team cb0729

# Fuzzy search for players
python3 tradefinder.py players "Smith" --fuzzy
# Jaxon Smith-Njigba    dwengw50    6,944 pts    WR
# DeVonta Smith         cb0729      2,034 pts    WR

3. Find Optimal Trades

# Find win-win trades for a specific team
python3 tradefinder.py search --team cb0729 --win-win --limit 10

# Find trades between two teams with fair ratios
python3 tradefinder.py search --team1 bool1060 --team2 cb0729 --max-ratio 1.1 --min-ratio 0.9

# Exclude 1-for-1 trades (multi-player only)
python3 tradefinder.py search --team cb0729 --min-players 3 --format detailed

# Show top trades across the league
python3 tradefinder.py search --limit 20

4. Advanced Analysis

# Clear cache and regenerate trades
python3 tradefinder.py clear-cache

# Configure league settings
python3 tradefinder.py config

# View version info
python3 tradefinder.py version

📊 Current Trade Analysis Results

Elite Tier (Strategic Score 2,800+)

bool1060 ↔ cb0729 - Perfect trade synergy

• Josh Jacobs → 2 players (Drake London + depth)
• cb0729 gains: +13 slot ranks, strategic roster balance
• bool1060 gains: Elite RB1 upgrade (+3,493 pts)
• Fairness: 1.05 ratio with bench drop compensation

Win-Win Tier (Strategic Score 2,200+)

bool1060 ↔ cb0729 - Premium WR1 upgrade trades

• Josh Jacobs + small add → CeeDee Lamb
• Both teams gain: Points AND league rankings
• Example: Josh Jacobs + Wan'Dale → CeeDee Lamb (+542/+1,705 pts)

Core Architecture

Component	Purpose	Technology
tradefinder.py	Main CLI interface	argparse + subcommands
trade_engine.py	Trade generation & caching	Combinatorics + pickle
ranking_analyzer.py	Slot ranking analysis	League-wide calculations
trade_filters.py	Filter chain system	Modular filter classes
output_formatter.py	Multi-format display	On-demand ranking calc
models.py	Core data structures	Python dataclasses

📋 Sample Output

Summary View

🏆 Top 3 Trades

1. bool1060 ↔ cb0729
   bool1060 gets: Josh Jacobs
   cb0729 gets: Drake London, Jacory Croskey-Merritt
   💰 Values: 6,737 ↔ 6,409 (ratio: 1.05)
   📈 Gains: +3,493 | -666.0 | Total: +2,827.0
   🗑️  Overpay compensation: 261 | 0
   📊 Slot ranks: +6 | +13
   ⭐ Strategic Score: 2827

Detailed View

🔄 bool1060 ↔ cb0729

📤 bool1060 gives:
   • Drake London (WR) - 4,982 pts
   • Jacory Croskey-Merritt (RB) - 1,755 pts
📥 bool1060 gets:
   • Josh Jacobs (RB) - 6,409 pts

📊 Slot Ranking Improvements:
   bool1060: +6 slot ranks
   cb0729: +13 slot ranks
   Strategic score: 2827.0

🔧 How It Works

Data Pipeline

Raw Data → Transform → Generate All Trades → Apply Filters → Present Results

Data Sources

• FantasyCalc API - Real-time player trade values
• Sleeper GraphQL - Live league rosters with real team names
• Reddit Integration (Next) - Community sentiment and trade consensus

Advanced Features

• Slot Rankings - League-wide positional analysis (QB #4/12, RB1 #9/12, etc.)
• Bench Drop Penalties - Accounts for roster management complexity
• Strategic Scoring - Combines value improvement + ranking improvements + fairness
• Multi-Format Output - Summary, detailed, table, and quick views
• Global Caching - 225K+ trades cached with hash-based invalidation

Trade Validation

• Mutual Benefit - Filters for beneficial trades (configurable thresholds)
• Fair Value Ratios - 0.9-1.1 default (10% max difference)
• Complexity Handling - Bench drop compensation for imbalanced trades
• Win-Win Filtering - Both teams must gain significant points

🚧 Next Steps: Reddit Community Integration

Planned Enhancement

We're implementing Reddit trade sentiment analysis to adjust raw FantasyCalc values with community consensus:

# Planned workflow:
1. Extract trade discussions from r/fantasyfootball Trade Value Tuesday posts
2. Parse player mentions and trade values from comments
3. Aggregate community sentiment (buy low, sell high, hold, avoid)
4. Apply sentiment multipliers to FantasyCalc base values
5. Re-calculate all trades with sentiment-adjusted values

Reddit API Integration

• Current: Using Reddit's public JSON endpoints (.json suffix)
• Status: Successfully extracting comments and trade discussions
• Next: Parse player mentions and sentiment analysis
• Goal: Hybrid FantasyCalc + Reddit consensus values

Implementation Plan

1. Reddit Scraper - Extract Trade Value Tuesday comments
2. NLP Parser - Identify player mentions and sentiment
3. Value Adjuster - Apply community sentiment to base values
4. Re-analysis - Generate new trade recommendations with adjusted values

This will provide more realistic trade values that account for both mathematical optimization AND community trading behavior.

⚙️ Configuration

League Settings

# Configure league ID and settings
python3 tradefinder.py config

# Stored in .tradefinder.config (JSON format)
{
  "1257070576472690688": {
    "teams": 12,
    "scoring": "half_ppr",
    "lineup_requirements": {"QB": 1, "RB": 2, "WR": 2, "TE": 1, "FLEX": 2}
  }
}

Filter Customization

• Trade ratios: --max-ratio 1.1 --min-ratio 0.9 (10% fairness window)
• Complexity: --min-players 3 (exclude 1-for-1 trades)
• Team targeting: --team1 bool1060 --team2 cb0729
• Win-win filtering: --win-win (both teams must benefit)

📈 Performance Stats

• Trade Generation: 225,106 trades from 10.9M combinations in ~12s
• Caching System: Global trade cache with hash-based invalidation
• Ranking Analysis: On-demand slot ranking calculations (post-trade analysis)
• Filter Performance: 225K → 67 filtered trades in <0.3s
• Memory Efficient: Pickle-based caching with minimal RAM usage

📁 File Structure

Production CLI

fantasy/
├── tradefinder.py               # Main CLI interface
├── trade_engine.py              # Trade generation & caching
├── ranking_analyzer.py          # Slot ranking analysis
├── trade_filters.py             # Filter chain system
├── output_formatter.py          # Multi-format output
├── models.py                    # Core data structures
├── config.py                    # Configuration management
├── loader.py                    # Data loading (APIs)
└── .tradefinder.config          # League settings (JSON)

Research Scripts (Legacy)

scripts/
├── optimized_trade_finder.py    # Original brute force analysis
├── enhanced_trade_view.py       # Slot ranking prototype
├── analyze_league.py            # League overview
└── [14 other research scripts]   # Archived implementations

Reddit Integration (In Progress)

├── extract_reddit_comments.py   # Comment extraction
├── test_reddit_fetch.py         # Reddit API testing
└── [sentiment analysis - planned] # NLP processing

🎯 Daily Usage

# 1. Sync fresh data (once per day)
python3 tradefinder.py sync

# 2. Quick player lookups (NEW - instant answers!)
python3 tradefinder.py players "Josh Jacobs" --team-only  # Who owns Josh Jacobs?
python3 tradefinder.py players --team cb0729              # Show my roster

# 3. Find your best trades
python3 tradefinder.py search --team cb0729 --win-win --limit 10

# 4. Analyze specific matchups
python3 tradefinder.py search --team1 bool1060 --team2 cb0729 --format detailed

# 5. Get trade recommendations
python3 tradefinder.py search --max-ratio 1.05 --min-players 3

🛠️ Requirements

• Python 3.7+ (uses dataclasses)
• curl (for API calls)
• No external dependencies (uses only built-ins: subprocess, pickle, json, etc.)

💡 Key Insights

• bool1060 is cb0729's perfect trading partner (47 of top 47 trades)
• Josh Jacobs trades offer the highest value (+13 slot ranking improvements for cb0729)
• Win-win trades exist with fair 0.98-1.05 ratios
• Slot rankings matter more than raw values for team improvement

---

Regarding Reddit API: We're using Reddit's public JSON endpoints (appending .json to URLs) rather than the official Reddit API, which requires authentication and has stricter rate limits. This approach successfully extracts trade discussions and comments for sentiment analysis.

Built for optimal fantasy football trades using mathematical optimization, real player values, and community sentiment.