Skip to content

README.md

Latest commit

 

History

History
86 lines (72 loc) · 1.78 KB

README.md

File metadata and controls

86 lines (72 loc) · 1.78 KB

Kappa Backend

REST API for Kappa, a cluster-based comic recommender using K-Means/DBSCAN + KNN.

Project Structure

kappa-backend/
  src/
    kappa/        # App code (Flask routes + ML pipeline)
    scripts/      # Maintenance scripts (migration)
  tests/          # Pytest suite
  wsgi.py         # Gunicorn entrypoint
  run.sh          # Prod runner
  *.csv           # Seed data files

Quick Start

Local (uv)

uv venv
uv pip install -r requirements.txt
uv pip sync uv.lock
export PYTHONPATH=./src
python src/scripts/migrate.py
python wsgi.py

Makefile shortcuts

make venv
make sync
make migrate
make run

Tests

uv venv
uv pip install -r requirements.txt
uv pip sync uv.lock
pytest

Production (Gunicorn)

bash run.sh

Docker

docker build -t kappa-api .
docker run -p 80:80 kappa-api

API Endpoints

Core

  • GET / -> WELCOME TO KAPPA
  • GET /health -> OK
  • POST /api/kmeans -> recommendations via K-Means
  • POST /api/dbscan -> recommendations via DBSCAN

Data management

  • GET /api/comics -> list comics
  • GET /api/comics/<id> -> comic details
  • POST /api/comics -> insert/update comics
  • POST /api/comics/genres -> insert/update genre flags
  • POST /api/ratings -> insert ratings

Precompute

  • POST /api/precompute -> compute clustering caches
  • GET /api/precompute/status -> last compute timestamps

Request Input

Recommendation requests expect a JSON array with comic_id (or id) and rating:

[
  {"comic_id": 44489, "rating": 5},
  {"comic_id": 72025, "rating": 4}
]

Notes

  • Recommendations require precomputed data. Call POST /api/precompute after seeding or data changes.
  • The SQLite database path is controlled via KAPPA_DB_PATH (default: kappa.db).