Metadata-Version: 2.4
Name: airsenal
Version: 1.11.0
Summary: AI manager for Fantasy Premier League
Author-email: Angus Williams <anguswilliams91@gmail.com>, Jack Roberts <jroberts@turing.ac.uk>, Nick Barlow <nbarlow@turing.ac.uk>
License: MIT License
        
        Copyright (c) 2018 The Alan Turing Institute
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.3
Requires-Dist: bpl-next>=0.4.0
Requires-Dist: click>=8.1.7
Requires-Dist: dateparser>=1.2.0
Requires-Dist: deap>=1.4.1
Requires-Dist: html5lib>=1.1
Requires-Dist: jax==0.4.24
Requires-Dist: jaxlib==0.4.24
Requires-Dist: lxml>=5.1.0
Requires-Dist: numpy<2,>1
Requires-Dist: pandas>=2.2.1
Requires-Dist: platformdirs>=4.2.0
Requires-Dist: prettytable>=3.10.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: requests>=2.31.0
Requires-Dist: sqlalchemy>=2.0.27
Requires-Dist: tqdm>=4.66.2
Provides-Extra: api
Requires-Dist: flask>=3.0.2; extra == 'api'
Provides-Extra: dev
Requires-Dist: mypy>=1.17.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.2; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-sugar>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.1; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: types-dateparser>=1.2.2.20250627; extra == 'dev'
Requires-Dist: types-python-dateutil>=2.9.0.20250708; extra == 'dev'
Requires-Dist: types-requests>=2.32.4.20250611; extra == 'dev'
Provides-Extra: notebook
Requires-Dist: jupyterlab>=4.1.2; extra == 'notebook'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8.3; extra == 'plot'
Requires-Dist: seaborn>=0.13.2; extra == 'plot'
Description-Content-Type: text/markdown

# AIrsenal

![Build Status](https://github.com/alan-turing-institute/AIrsenal/actions/workflows/main.yml/badge.svg)

*AIrsenal* is a package for using Machine learning to pick a Fantasy Premier League team.

For some background information and details see https://www.turing.ac.uk/research/research-programmes/research-engineering/programme-articles/airsenal.

We welcome contributions and comments - if you'd like to join the AIrsenal community please refer to our [contribution guidelines](https://github.com/alan-turing-institute/AIrsenal/blob/master/CONTRIBUTING.md)

## Mini-league for 2025/26 season

We have made a mini-league **"Prem-AI League"** for players using this software.  To join, login to the FPL website, and navigate to the page to join a league: https://fantasy.premierleague.com/leagues/create-join then click "join a league or cup".
The code to join is: **xoz7vm**.
Hope to see your AI team there!! :)

Our own AIrsenal team's ID for the 2025/26 season is **[742663](https://fantasy.premierleague.com/entry/742663/history)**.

## Installation

We recommend using [uv](https://docs.astral.sh/uv/) for managing Python versions and dependencies. For instructions on how to install uv, go to: https://docs.astral.sh/uv/getting-started/installation/

With uv installed, run these commands in a terminal to download and install AIrsenal:

### Linux and macOS

<details>
  
```shell
git clone https://github.com/alan-turing-institute/AIrsenal.git
cd AIrsenal
uv sync
```

</details>

### Windows

<details>
  
The best ways to run AIrsenal on Windows are either to use [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install) (WSL), which allows you to run AIrsenal in a Linux environment on your Windows system, or Docker (see below).

After installing WSL, you can install uv by following the instructions [here](https://docs.astral.sh/uv/getting-started/installation/).

You can then follow the installation instructions for Linux and macOS above (or the instructions for without uv below).

You're free to try installing and using AIrsenal in Windows itself, but so far we haven't got it working. The main difficulties are with installing [jax](https://github.com/google/jax#installation) and some database/pickling errors (e.g. #165). If you do get it working we'd love to hear from you!

</details>

### Use AIrsenal without uv

<details>

  To use AIrsenal without uv:

```shell
git clone https://github.com/alan-turing-institute/AIrsenal.git
cd AIrsenal
pip install .
```

</details>

### Docker

<details>

Rather than building and running natively on your machine, you can instead use a Docker image if you prefer.
  
Build the docker-image:

```console
$ docker build -t airsenal .
```

If `docker build` fails due to a `RuntimeError` like

```console
Unable to find installation candidates for jaxlib (0.4.11)
```

this may be a lack of maintained versions of a package for `m1` on Linux.

A slow solution for this error is to force a `linux/amd64` build like

```console
$ docker build --platform linux/amd64 -t airsenal .
```

If that fails try

```console
$ docker build --platform linux/amd64 --no-cache -t airsenal .
```

See ticket [#547](https://github.com/alan-turing-institute/AIrsenal/issues/574) for latest on this issue.

Create a volume for data persistance:

```console
$ docker volume create airsenal_data
```

Run commands with your configuration as environment variables, eg:

```console
$ docker run -it --rm -v airsenal_data:/tmp/ -e "FPL_TEAM_ID=<your_id>" -e "AIRSENAL_HOME=/tmp" airsenal bash
```

or

```console
$ docker run -it --rm -v airsenal_data:/tmp/ -e "FPL_TEAM_ID=<your_id>" -e "AIRSENAL_HOME=/tmp" airsenal airsenal_run_pipeline
```

`airsenal_run_pipeline` is the default command.

</details>

## Optional dependencies

<details>

  AIrsenal has optional dependencies for plotting, running notebooks, and an in development AIrsenal API. To install them run:

```shell
pip install ".[api,notebook,plot]"
```

</details>

## Configuration

Once you've installed the module, you will need to set the following parameters:

**Required:**

1. `FPL_TEAM_ID`: the team ID for your FPL side.

**Optional:**

2. `FPL_LOGIN`: your FPL login, usually email (this is only required to get FPL league standings, or automating transfers via the API).

3. `FPL_PASSWORD`: your FPL password (this is only required to get FPL league standings, or automating transfers via the API).

4. `FPL_LEAGUE_ID`: a league ID for FPL (this is only required for plotting FPL league standings).

5. `AIRSENAL_DB_FILE`: Local path to where you would like to store the AIrsenal sqlite3 database. If not set `AIRSENAL_HOME/data.db` will be used by default.

The values for these should be defined either in environment variables with the names given above, or as files in `AIRSENAL_HOME` (a directory AIrsenal creates on your system to save config files and the database).

To view the location of `AIRSENAL_HOME` and the current values of all set AIrsenal environment variables run:

```bash
airsenal_env get
```

Use `airsenal_env set` to set values and store them for future use. For example:

```bash
airsenal_env set -k FPL_TEAM_ID -v 123456
```

See `airsenal_env --help` for other options.

## Getting Started

If you installed AIrsenal with `pip`, you should always make sure the `airsenalenv` virtual environment is activated before running AIrsenal commands. To create and activate the environment use:

```shell
python3 -m venv airsenalenv
source airsenalenv/bin/activate
```
If installed using `uv`, all the following commands can be run with `uv run` before them.

Note: Most the commands below can be run with the `--help` flag to see additional options and information.

### 1. Creating the database

Once the module has been installed and your team ID configured, run the following command to create the AIrsenal database:

```shell
airsenal_setup_initial_db
```

This will fill the database with data from the last 3 seasons, as well as all available fixtures and results for the current season.
On Linux/Mac you should get a file ```/tmp/data.db``` containing the database (on Windows you will get a `data.db` file in a the temporary directory returned by the python [tempfile module](https://docs.python.org/3/library/tempfile.html) on your system).

You can run sanity checks on the data using the following command:

```shell
airsenal_check_data
```

### 2. Updating and Running Predictions

To stay up to date in the future, you will need to fill three tables: ```match```, ```player_score```, and ```transaction```
with more recent data, using the command

```shell
airsenal_update_db
```

The next step is to use the team- and player-level NumPyro models to predict the expected points for all players for the next fixtures.  This is done using the command

```shell
airsenal_run_prediction --weeks_ahead 3
```

(we normally look 3 weeks ahead, as this is an achievable horizon to run the optimization over, but also because things like form and injuries can change a lot in 3 weeks!)

Predicted points must be generated before running the transfer or squad optimization (see below).

### 3. Transfer or Squad Optimization

Finally, we need to run the optimizer to pick the best transfer strategy over the next weeks (and hence the best team for the next week).

```shell
airsenal_run_optimization --weeks_ahead 3
```

This will take a while, but should eventually provide a printout of the optimal transfer strategy, in addition to the teamsheet for the next match (including who to make captain, and the order of the substitutes). You can also optimise chip usage with the arguments ` --wildcard_week <GW>`, `--free_hit_week <GW>`, `--triple_captain_week <GW>` and `--bench_boost_week <GW>`, replacing `<GW>` with the gameweek you want to play the chip (or use `0` to try playing the chip in all gameweeks).

Note that `airsenal_run_optimization` should only be used for transfer suggestions after the season has started. If it's before the season has started and you want to generate a full squad for gameweek one you should instead use:

```shell
airsenal_make_squad --num_gameweeks 3
```

### 4. Apply Transfers and Lineup

To apply the transfers recommended by AIrsenal to your team on the FPL website run `airsenal_make_transfers`. This can't be undone! You can also use `airsenal_set_lineup` to set your starting lineup, captaincy choices, and substitute order to AIrsenal's recommendation (without making any transfers). Note that you must have created the `FPL_LOGIN` and `FPL_PASSWORD` files for these to work (as described in the "Configuration" section above).

Also note that this command can't currently apply chips such as "free hit" or "wildcard", even if those were specified in the `airsenal_run_optimization` step.  If you do want to use this command to apply the transfers anyway, you can play the chip at any time before the gameweek deadline via the FPL website.

### Run the Full AIrsenal Pipeline

Instead of running the commands above individually you can use:

```shell
airsenal_run_pipeline
```

This will update the database and then run the points predictions and transfer optimization.  Add `--help` to see the available options.

## Issues and New Features

AIrsenal is regularly developed to fix bugs and add new features. If you have any problems during installation or usage please let us know by [creating an issue](https://github.com/alan-turing-institute/AIrsenal/issues/new) (or have a look through [existing issues](https://github.com/alan-turing-institute/AIrsenal/issues) to see if it's something we're already working on).

You may also like to try the development version of AIrsenal, which has the latest fixes and features. To do this checkout the `develop` branch of the repo and reinstall:

```shell
git checkout develop
git pull
pip install --force-reinstall .
```

## Contributing

We welcome all types of contribution to AIrsenal, for example questions, documentation, bug fixes, new features and more. Please see our [contributing guidelines](CONTRIBUTING.md). If you're contributing for the first time but not sure what to do a good place to start may be to look at our [current issues](https://github.com/alan-turing-institute/AIrsenal/issues), particularly any with the ["Good first issue" tag](https://github.com/alan-turing-institute/AIrsenal/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). Also feel free to just say hello!

## Development

If you're developing AIrsenal you may find it helpful to install it in editable mode:

```shell
pip install -e .
```

We also have a [pre-commit](https://pre-commit.com/) config to run the code quality tools we use (`flake8`, `isort`, and `black`) automatically when making commits. If you're using `poetry` it will be installed as a dev dependency, otherwise run `pip install pre-commit`. Then to setup the commit hooks:

```shell
pre-commit install --install-hooks
```
