Skip to content

🚀 Getting Started

🛠 Setup and Installation

  1. Clone the repository: 

    git clone https://github.com/nicholaswilde/fantasy-football-ai.git
cd fantasy-football-ai

  2. Install task: Follow the instructions at taskfile.dev/installation to install task.

  3. Install python3 & pip: Follow the instructions at python.org to install python3 and pip.

⚙ Configuration

To use the Gemini API, you need to configure your API key.

  1. Obtain an API key from Google AI Studio: https://aistudio.google.com/app/apikey

    To ensure the Google CLI utilizes the AGENTS.md files for context, add the following to your ~/.gemini/settings.json file:

    { "contextFileName": "AGENTS.md" }

To use the OpenAI API, you need to configure your API key.

  1. Obtain an API key from OpenAI: https://platform.openai.com/account/api-keys

  2. Find your LEAGUE_ID from the URL of your ESPN fantasy football league.

  3. Find your ESPN_S2 and SWID cookies from your browser after logging into your ESPN account. See this discussion.

  4. Create a .env file from the template:

    task init

    cp .env.tmpl .env

  5. Add your API key and ESPN credentials to the .env file:

    .env 
    GOOGLE_API_KEY=
LEAGUE_ID=
ESPN_S2=
SWID=
GEMINI_MODEL=gemini-2.5-flash
OPENAI_API_KEY=

📝 Usage

  1. Bootstrap the project: This command will create a virtual environment, install all the necessary dependencies, and guide you through selecting your team.

    task bootstrap
    1. Activate the virtual environment: 
      source venv/bin/activate  # On Windows use `venv\Scripts\activate`

    python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 scripts/get_league_settings.py
python3 scripts/identify_my_team.py

⚙ Options

  1. Customize Scoring Rules (Optional): The project includes a config.yaml file in the root directory. You can modify this file to adjust the fantasy football scoring rules to match your league's settings. This allows for flexible customization without changing the Python code.

    Alternatively, you can run the following command to automatically fetch the scoring rules from your league and update config.yaml:

    task get_league_settings

    python3 scripts/get_league_settings.py

    # config.yaml example
scoring_rules:
    every_25_passing_yards: 1.0
    td_pass: 6.0
    interceptions_thrown: -3.0
    # ... other scoring rules

  2. Configure AI Provider (Optional): The config.yaml file also allows you to specify which AI provider to use (Gemini or OpenAI) and, for OpenAI, the specific model name.

    # config.yaml example
ai_provider: "gemini" # or "openai"
openai_model_name: "gpt-4" # or other OpenAI model name
    For a list of available OpenAI models, refer to the OpenAI Models documentation.

  3. Configure Year Settings (Optional): The config.yaml file also contains fields for year and data_years under the league_settings section.

    • year: This field specifies the current year for your fantasy football league. It is used to fetch the correct league data.
    • data_years: This is a list of years for which to download player stats. By default, it's set to the current and previous year.

    You can manually edit these fields in config.yaml to match your needs.

    # config.yaml example
league_settings:
    year: 2024
    data_years: [2023, 2024]

⬇ ADP Data

The project uses Average Draft Position (ADP) data for draft strategy and player valuation. This data is automatically downloaded when you run task download_adp.

task download_adp

This will fetch the latest ADP data and save it to data/player_adp.csv.