# Backend

The backend is now organized around the `anirec/` package.

## Structure

- `anirec/api.py`: FastAPI app and API routes.
- `anirec/recommendation.py`: runtime MAL fetch + recommendation/filtering logic.
- `anirec/training.py`: user feature derivation, LightFM training, evaluation, artifact writing.
- `anirec/catalog.py`: anime catalog refresh and seasonal discovery.
- `anirec/pipeline.py`: username scraping, user-list ingestion, relationship refresh, full refresh orchestration.
- `anirec/atlas.py`: atlas coordinate generation.
- `anirec/cli.py`: the new command line entrypoint.
- `helpers/`: legacy one-off scripts kept only for reference.

## Canonical Outputs

Going forward, the pipeline writes these canonical files:

- `data/user_interactions.csv`
- `data/anime_catalog.csv`
- `data/anime_relationships.csv`
- `data/user_genre_features.csv`
- `data/atlas.csv`
- `model_files/lightfm_model.pkl`
- `model_files/lightfm_dataset.pkl`
- `model_files/training_report.json`

Legacy files like `anime_data_master.csv`, `atlas_data.csv`, and `lightfm_anime_model.pkl` are still updated for compatibility.

## Commands

Run commands from `backend/`.

```bash
python -m anirec.cli scrape-usernames
python -m anirec.cli fetch-user-interactions
python -m anirec.cli refresh-anime-catalog --years-back 2
python -m anirec.cli refresh-relationships
python -m anirec.cli build-user-genre-features
python -m anirec.cli train
python -m anirec.cli build-atlas
python -m anirec.cli serve
```

Or run the whole refresh pipeline:

```bash
python -m anirec.cli refresh-all --years-back 2
```

## Update Workflow

Use this when new anime releases land and the recommender is stale:

1. `python -m anirec.cli refresh-all --years-back 2`
2. Restart the API with `python main.py`

The full refresh does this:

1. Scrapes fresh public usernames from MAL.
2. Fetches user anime lists from MAL and writes `data/user_interactions.csv`.
3. Discovers recent seasonal anime and refreshes `data/anime_catalog.csv`.
4. Refreshes relationship labels used by the sequel filter.
5. Retrains the LightFM model and regenerates derived user genre features.
6. Rebuilds the atlas coordinates.

## Note On User Genre Features

The old backend scraped MAL profile genre tables into `user_genre_data_nsfw.txt`.
The new pipeline no longer depends on that extra website scrape.
User genre features are derived directly from `user_interactions.csv` and `anime_catalog.csv`, which makes refreshes easier and less fragile.
`build-user-genre-features` is available if you want that artifact without retraining, but `train` already regenerates it automatically.