Fantasy MCP - Multi-Agent Parlay Optimization System

A sophisticated AI-powered betting advisor featuring a multi-agent architecture built with CrewAI. Four specialized AI agents collaborate to analyze games, evaluate props, and construct optimal parlay combinations.

🎯 Overview

This system uses CrewAI to orchestrate multiple specialized agents that work together to provide intelligent, high-confidence parlay recommendations. The agents analyze player availability, run ML predictions, optimize parlay combinations, and validate recommendations for quality and accuracy.

🤖 Multi-Agent Architecture

┌─────────────────────────────────────────────────────────────┐
│                    USER REQUEST                              │
│  "Build 8-leg 100x parlay for Bengals vs Packers"          │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
            ┌──────────────────────┐
            │  Crew Orchestrator   │
            │  - Request Analysis  │
            │  - Agent Routing     │
            └──────────┬───────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
┌───────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Roster Agent  │ │ Stats Agent  │ │ Parlay Optimizer│
│ • Injuries    │ │ • ML Models  │ │ • Combinations  │
│ • Availability│ │ • Props      │ │ • Correlations  │
│ • Weather     │ │ • Matchups   │ │ • Optimization  │
└───────┬───────┘ └──────┬───────┘ └────────┬────────┘
        │                │                   │
        └────────────────┼───────────────────┘
                         ▼
                  ┌─────────────┐
                  │  QA Agent   │
                  │ • Validate  │
                  │ • Correlate │
                  │ • Approve   │
                  └──────┬──────┘
                         │
                         ▼
              ┌──────────────────────┐
              │  2-3 Parlay Options   │
              │  • 8 legs            │
              │  • ~100x multiplier  │
              │  • Confidence scores │
              │  • Full reasoning    │
              └──────────────────────┘

✨ Key Features

🎭 Four Specialized Agents

1. Roster Intelligence Agent

   • Monitors player injury status and availability
   • Analyzes weather conditions and game factors
   • Checks depth charts and playing time projections
   • Validates all players are healthy and active

2. Stats & Props Agent

   • Runs ML predictions for player performance
   • Analyzes historical stats and matchups
   • Calculates prop hit probabilities
   • Identifies 20-30 high-confidence opportunities

3. Quality Assurance Agent

   • Validates all recommendations for accuracy
   • Checks for contradictory or correlated props
   • Assesses overall correlation risk
   • Provides final approval or rejection

4. Parlay Optimizer Agent

   • Constructs optimal parlay combinations
   • Balances confidence with target multipliers
   • Manages correlation risk across legs
   • Generates multiple parlay options

🛠️ 16 Specialized Tools

Roster Tools:

• Player injury status checking
• Team roster analysis
• Player availability verification
• Weather condition forecasting

Stats Tools:

• Historical stats analysis
• ML-based predictions
• Matchup analysis
• Prop probability calculations

Betting Tools:

• Parlay odds calculation
• Leg optimization algorithms
• Expected value calculation
• Correlation risk assessment

Data Tools:

• Player search and filtering
• Game schedule retrieval
• Prop market analysis

🚀 Quick Start

1. Installation

# Clone repository
git clone https://github.com/mattarm/fantasy_mcp.git
cd fantasy_mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configuration

# Copy environment template
cp env.example .env

# Edit .env and add your OpenAI API key
OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4

# Other optional configurations
AGENT_VERBOSE=true
PARLAY_MIN_CONFIDENCE=0.65
PARLAY_MAX_LEGS=15

3. Test the System

# Run validation tests
python test_agent_system.py

4. Start the Server

# Start MCP server
python -m fantasy_mcp.main

💡 Usage Examples

Example 1: Single Game Parlay

Request:

"Put together high confidence 8 leg parlay with a 100x return for this weeks Bengals Packers game"

Process:

1. Roster Agent identifies the game and checks all players
2. Stats Agent analyzes props and runs ML predictions
3. Parlay Optimizer finds 8-leg combinations hitting ~100x
4. QA Agent validates and provides final recommendations

Output:

• 2-3 complete parlay options
• Each with 8 legs, ~100x multiplier
• Confidence scores for each leg
• Correlation risk analysis
• Detailed reasoning

Example 2: Multi-Game Parlay

Request:

"Put together a 800x parlay for this Sunday's noon games"

Process:

1. Identifies all Sunday noon games (4-6 games)
2. Analyzes 60-100+ props across all games
3. Finds 10-12 leg combinations hitting ~800x
4. Diversifies across games to reduce correlation
5. Validates and provides recommendations

Example 3: Via MCP Tools

# Use build_optimized_parlay tool
result = await mcp_client.call_tool("build_optimized_parlay", {
    "request": "Build 8-leg 100x parlay for Bengals vs Packers game"
})

# Get parlay history
history = await mcp_client.call_tool("get_parlay_history", {
    "limit": 10
})

# Retrieve specific parlay
parlay = await mcp_client.call_tool("get_parlay_by_id", {
    "parlay_id": "abc123..."
})

📂 Project Structure

fantasy_mcp/
├── src/fantasy_mcp/
│   ├── agents/              # AI agents
│   │   ├── roster_intelligence_agent.py
│   │   ├── stats_props_agent.py
│   │   ├── qa_agent.py
│   │   └── parlay_optimizer_agent.py
│   ├── crews/               # Crew orchestration
│   │   ├── betting_crew.py
│   │   └── crew_orchestrator.py
│   ├── tools/               # Agent tools
│   │   ├── roster_tools.py
│   │   ├── stats_tools.py
│   │   ├── betting_tools.py
│   │   └── data_tools.py
│   ├── data_store/          # Data management
│   │   ├── file_manager.py
│   │   └── cache_manager.py
│   ├── services/            # Core services
│   │   ├── sleeper_api.py
│   │   ├── ml_predictor.py
│   │   └── betting_advisor.py
│   ├── api/                 # MCP server
│   │   └── mcp_server.py
│   └── core/                # Core utilities
│       ├── config.py
│       └── database.py
├── data/                    # File-based storage
│   ├── players/
│   ├── stats/
│   ├── predictions/
│   ├── bets/parlays/
│   └── cache/
├── tests/                   # Test suite
├── archive/                 # Archived old scripts
├── test_agent_system.py     # System tests
├── AGENT_SYSTEM_README.md   # Detailed agent docs
├── IMPLEMENTATION_SUMMARY.md # Implementation details
└── requirements.txt         # Dependencies

🎯 Agent Workflow

Sequential Execution with Context Sharing

1. Request Analysis (Orchestrator)

   • Parse user request
   • Extract: target multiplier, number of legs, games, time slots
   • Route to appropriate workflow

2. Player Availability (Roster Agent)

   • Check all relevant players
   • Verify injury status
   • Assess weather conditions
   • Return availability report

3. Prop Analysis (Stats Agent)

   • Analyze available props
   • Run ML predictions
   • Calculate hit probabilities
   • Return ranked high-confidence props

4. Parlay Construction (Optimizer Agent)

   • Build leg combinations
   • Optimize for target multiplier
   • Manage correlation risk
   • Generate multiple options

5. Quality Validation (QA Agent)

   • Validate player status
   • Check for contradictions
   • Assess correlations
   • Approve or reject

6. Final Output

   • 2-3 complete parlay recommendations
   • Confidence scores and reasoning
   • Risk assessment
   • Saved to data/bets/parlays/

⚙️ Configuration

Environment Variables

# AI/LLM (Required)
OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4

# Agent Configuration
AGENT_VERBOSE=true
AGENT_MAX_ITERATIONS=15
AGENT_MAX_EXECUTION_TIME=300

# Parlay Settings
PARLAY_MIN_CONFIDENCE=0.65
PARLAY_MAX_LEGS=15
PARLAY_CORRELATION_THRESHOLD=0.3

# Betting Configuration
DEFAULT_BANKROLL=1000.0
KELLY_FRACTION=0.25

Adjustable Parameters

• Confidence Threshold: Minimum confidence for props (default: 0.65)
• Max Legs: Maximum parlay legs (default: 15)
• Correlation Threshold: Maximum acceptable correlation (default: 0.3)
• Kelly Fraction: Bet sizing aggressiveness (default: 0.25)

📊 Data Storage

File-based storage (migration-ready for database):

data/
├── players/
│   └── {player_id}.json         # Player info
├── stats/
│   └── {player_id}/
│       └── {season}_week_{week}.json
├── predictions/
│   └── {date}/
│       └── {player_id}.json     # ML predictions
├── bets/
│   ├── parlays/
│   │   └── {parlay_id}.json     # Saved parlays
│   └── history/
└── cache/
    └── {cache_key}.json         # API cache

🧪 Testing

# Run system tests
python test_agent_system.py

# With full agent execution (requires API key)
OPENAI_API_KEY=your_key python test_agent_system.py

# Run pytest suite
pytest tests/

# Run with coverage
pytest --cov=src/fantasy_mcp

📚 Documentation

• AGENT_SYSTEM_README.md - Complete agent system documentation
• IMPLEMENTATION_SUMMARY.md - Detailed implementation overview
• test_agent_system.py - Usage examples and tests
• archive/README.md - Information about archived files

🔧 MCP Server Integration

The system provides three main MCP tools:

1. build_optimized_parlay

Build an AI-optimized parlay with specified parameters.

{
    "request": "Natural language parlay request"
}

2. get_parlay_history

View recent parlay recommendations.

{
    "limit": 10  # Number of parlays to retrieve
}

3. get_parlay_by_id

Retrieve a specific parlay recommendation.

{
    "parlay_id": "unique_parlay_id"
}

🚦 Performance

• Request Analysis: <1 second
• Full Agent Workflow: 30-60 seconds
• API Response Caching: 30-60 minutes TTL
• Data Persistence: Immediate (file-based)

🎓 Key Technologies

• CrewAI: Multi-agent orchestration framework
• LangChain: LLM integration and tools
• OpenAI GPT-4: Agent reasoning and decision-making
• Sleeper API: NFL data and player stats
• scikit-learn/XGBoost: ML models
• Python 3.11+: Core language

🔮 Future Enhancements

• Real-time sportsbook odds integration
• Live injury monitoring via X (Twitter)
• Historical parlay performance tracking
• Multi-LLM support (Anthropic Claude)
• Automated bet placement
• Social sentiment analysis
• Database migration from file storage

⚠️ Important Notes

1. API Key Required: OpenAI API key needed for agent execution
2. Educational Purpose: For research and learning only
3. Data Sources: Currently using Sleeper API (free tier)
4. File Storage: All data stored in JSON files (DB-ready architecture)
5. Responsible Gaming: This is a tool to aid analysis, not a guarantee of success

🤝 Contributing

Contributions welcome! Please see our contributing guidelines.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

📞 Support

• Issues: GitHub Issues
• Documentation: See AGENT_SYSTEM_README.md
• Email: Support via GitHub

🙏 Acknowledgments

• CrewAI for the multi-agent framework
• LangChain for LLM tooling
• Sleeper API for NFL data
• OpenAI for GPT-4

---

Built with AI 🤖 for intelligent sports betting analysis