🎮 DraftOracle

AI-Powered Drafting Assistant for League of Legends Esports

Built for the Sky's the Limit - Cloud9 x JetBrains Hackathon

---

🎯 Overview

DraftOracle is an AI-powered tool that helps esports teams make optimal draft decisions in League of Legends. By analyzing historical match data from the GRID Esports API, it provides real-time recommendations for picks and bans based on:

• Champion Synergies - How well champions work together
• Counter Matchups - Lane advantages and phase-specific counters
• Meta Analysis - Current patch tier lists and pick/ban priorities
• Player Comfort - Individual player champion pools and performance

✨ Features

Core Capabilities

Feature	Description
🎯 Pick Recommendations	Get optimal champion suggestions with reasoning
🚫 Ban Recommendations	Smart bans targeting opponent weaknesses
📊 Draft Analysis	Full draft breakdown with win probability
⚡ Real-Time WebSocket	Live updates during pick/ban phase
📈 Meta Snapshots	Current patch tier lists and statistics

API Endpoints

POST /api/v1/draft/recommend/pick  - Get pick recommendations
POST /api/v1/draft/recommend/ban   - Get ban recommendations
POST /api/v1/draft/analyze         - Analyze draft composition
GET  /api/v1/meta/current          - Get current meta snapshot
GET  /api/v1/meta/champions        - Get all champions
WS   /ws/draft/{session_id}        - Real-time draft session

🚀 Quick Start

Prerequisites

• Python 3.11+
• PostgreSQL 15+
• Redis 7+

Installation

# Clone the repository
git clone https://github.com/your-team/draftoracle.git
cd draftoracle

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: .\venv\Scripts\activate  # Windows

# Install dependencies
pip install -e ".[dev]"

# Copy environment config
cp .env.example .env
# Edit .env with your settings

# Run database migrations (coming soon)
# alembic upgrade head

# Start the API
python -m src.api.main

Using Docker (Recommended)

docker-compose up -d

The API will be available at http://localhost:8000.

Frontend Setup

The modern React frontend is located in frontend/.

cd frontend
npm install
npm run dev

The UI will be available at http://localhost:5173.

The API will be available at http://localhost:8000

📖 API Documentation

Once running, access the interactive API docs:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Example: Get Pick Recommendations

import httpx

response = httpx.post(
    "http://localhost:8000/api/v1/draft/recommend/pick",
    json={
        "draft_state": {
            "blue_picks": [{"champion_id": 1, "role": "top"}],
            "red_picks": [],
            "blue_bans": [10, 20, 30],
            "red_bans": [40, 50, 60],
            "patch_version": "26.02"
        },
        "our_side": "blue",
        "role_needed": "mid",
        "top_k": 5
    }
)

recommendations = response.json()["recommendations"]
for rec in recommendations:
    print(f"{rec['champion_name']}: {rec['score']:.2f}")
    print(f"  Reasoning: {', '.join(rec['reasoning'])}")

Example: WebSocket Draft Session

const ws = new WebSocket("ws://localhost:8000/ws/draft/my-session-123");

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log("Update:", data);
};

// Make a pick
ws.send(JSON.stringify({
    type: "pick",
    side: "blue",
    champion_id: 1,
    role: "mid"
}));

// Request recommendations
ws.send(JSON.stringify({
    type: "request_recommendations",
    side: "blue",
    role: "jungle"
}));

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Frontend                              │
│                   (Future: React/Vue)                        │
└─────────────────────────┬───────────────────────────────────┘
                          │
              ┌───────────┴───────────┐
              │    FastAPI + WS       │
              │    REST & WebSocket   │
              └───────────┬───────────┘
                          │
    ┌─────────────────────┼─────────────────────┐
    ▼                     ▼                     ▼
┌─────────┐       ┌─────────────┐       ┌─────────────┐
│ Synergy │       │   Counter   │       │    Draft    │
│ Engine  │       │   Engine    │       │  Optimizer  │
└────┬────┘       └──────┬──────┘       └──────┬──────┘
     │                   │                      │
     └───────────────────┼──────────────────────┘
                         │
              ┌──────────┴──────────┐
              │  PostgreSQL + Redis  │
              │   Data & Cache       │
              └──────────┬───────────┘
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
    ┌─────────┐   ┌─────────────┐   ┌─────────┐
    │  GRID   │   │ Data Dragon │   │  Celery │
    │   API   │   │     API     │   │  Tasks  │
    └─────────┘   └─────────────┘   └─────────┘

📁 Project Structure

draftoracle/
├── src/
│   ├── api/              # FastAPI application
│   │   ├── routes/       # REST endpoints
│   │   ├── websocket/    # WebSocket handlers
│   │   ├── middleware/   # Rate limiting, auth
│   │   ├── schemas.py    # Pydantic models
│   │   └── main.py       # App entry point
│   ├── services/         # Business logic
│   │   ├── grid_ingestion.py
│   │   ├── data_dragon.py
│   │   ├── synergy_engine.py
│   │   ├── counter_engine.py
│   │   └── draft_optimizer.py
│   ├── ml/              # Machine learning
│   │   ├── models/
│   │   ├── features/
│   │   └── training/
│   ├── db/              # Database
│   │   ├── models.py
│   │   ├── session.py
│   │   └── migrations/
│   └── tasks/           # Background jobs
├── tests/
├── config/
├── docker/
└── scripts/

🔧 Configuration

All configuration is managed via environment variables. See .env.example for available options:

Variable	Description	Default
GRID_API_KEY	GRID API authentication key	Required
DATABASE_URL	PostgreSQL connection string	postgresql+asyncpg://...
REDIS_URL	Redis connection string	redis://localhost:6379/0
API_PORT	API server port	8000
ML_EMBEDDING_DIM	Champion embedding dimension	128

🧪 Testing

# Run all tests
pytest

# With coverage
pytest --cov=src --cov-report=html

# Specific test category
pytest tests/unit/
pytest tests/integration/

📊 Data Sources

• GRID Esports API - Historical match data, draft sequences, player stats
• Riot Data Dragon - Champion metadata, patch information

🗺️ Roadmap

• Phase 1: Research & Planning
• Phase 2: Core Backend (Services, DB, API)
• Phase 3: ML Models (Embeddings, Win Predictor)
• Phase 4: Real-Time System (WebSockets, Drag & Drop)
• Phase 5: Testing & Documentation
• Phase 6: Frontend Application (React + Vite, Glassmorphism UI)

👥 Team

Built for the Sky's the Limit Hackathon by passionate esports fans.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🎮 Powered by GRID Esports Data 🎮