# kavita-lightnovel-metadata-fetcher

Pulls metadata (summary, tags, genres, characters, staff, score,
cover, links, related series) for light novels from **MangaBaka**,
enriched with **MyAnimeList** and **AniList** data, and writes it
back to a **Kavita** server through its REST API.

No file mover, no ComicInfo.xml — the source of truth is Kavita
itself.  Series are discovered via the Kavita library API.

## Features

- Match every series in one or more Kavita libraries against
  MangaBaka and persist the match in `matches.json` (editable via
  the web UI).
- Update metadata for a single series or all matched series at
  once.  Updates are diff-based:
  - Locked fields in Kavita are never overwritten.
  - List fields (tags, genres, characters, writers, …) are merged:
    new items are added, removed items are dropped.
  - Cover images are only re-uploaded when MangaBaka's cover URL
    actually changed.
- Characters and authors are synced to Kavita Person records
  (image, description, MAL/AniList id) via Kavita's `/api/Person`
  endpoints.
- MangaBaka relationships (sequel / prequel / spin-off / …) are
  mirrored as Kavita series relationships, and every related
  series that exists in Kavita is added to a shared collection.

## Environment

| Variable           | Default                   | Description                                              |
| ------------------ | ------------------------- | -------------------------------------------------------- |
| `KAVITA_URL`       | —                         | Base URL of the Kavita server, e.g. `http://kavita:5000` |
| `KAVITA_API_KEY`   | —                         | API key from Kavita user settings                        |
| `LIBRARY_IDS`      | _(empty)_                 | Default libraries (CSV of ids).  Empty = pick in WebUI.  |
| `LANGUAGE`         | `en`                      | Series language ISO code (used for `language` field)     |
| `REQUEST_TIMEOUT`  | `30`                      | HTTP timeout in seconds                                  |
| `MATCH_PATH`       | `/config/matches.json`    | Where to persist the match cache                         |
| `WEB_HOST`         | `0.0.0.0`                 | Bind host for the Flask UI                               |
| `WEB_PORT`         | `8080`                    | Bind port for the Flask UI                               |

## Running locally

```bash
pip install -r requirements.txt
KAVITA_URL=http://localhost:5000 KAVITA_API_KEY=... python main.py
```

Then open <http://localhost:8080/>.

## Docker

```bash
docker compose -f docker-compose.prod.yml up -d
```