# 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

```bash
# 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

```bash
# 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

```bash
# Run validation tests
python test_agent_system.py
```

### 4. Start the Server

```bash
# 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

```python
# 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

```bash
# 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

```bash
# 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.

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

### 2. get_parlay_history
View recent parlay recommendations.

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

### 3. get_parlay_by_id
Retrieve a specific parlay recommendation.

```python
{
    "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](https://github.com/mattarm/fantasy_mcp/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**