Curio

Curio is a deterministic-first taste engine for discovering anime, manga, and animated films. Recommendations come from a weighted scoring engine, not an LLM.

Folder structure

backend/
  app/
    api/
    core/
    models/
    services/
    scoring/
    data/
frontend/
docs/

Backend (FastAPI)

Setup

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

API defaults to http://127.0.0.1:8000.

Endpoint

• POST /recommend
• Input: UserPreferences (core taste + refinement/session signals)
• Output: RecommendationResponse with ranked items and response metadata

Example request

curl -X POST http://127.0.0.1:8000/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tone": "emotional",
    "pacing": "medium",
    "format": "series",
    "complexity": "complex",
    "violenceTolerance": "medium",
    "discoveryMode": "hidden_gems",
    "recommendationMode": "stretch",
    "commitmentLevel": "medium",
    "favoriteTitles": ["Monster"],
    "avoidTitles": ["romance"],
    "likedTitles": ["Odd Taxi"],
    "dislikedTitles": []
  }'

Example response

{
  "recommendations": [
    {
      "id": "monster",
      "title": "Monster",
      "imageUrl": "https://...",
      "genres": ["Psychological", "Thriller"],
      "tags": ["cat-and-mouse", "slow-burn"],
      "rating": 8.9,
      "score": 83.4,
      "scoreBreakdown": {"format": 25.0, "tone": 22.0},
      "matchReasons": ["fits your emotional tone preference"],
      "explanation": "Picked because it fits your emotional tone preference.",
      "detailsUrl": "https://myanimelist.net/search/all?q=Monster"
    }
  ],
  "meta": {
    "summary": "Top picks tuned for emotional tone, medium pacing, medium commitment, and stretch mode.",
    "appliedRefinements": ["session likes incorporated", "stretch mode"]
  }
}

Frontend (minimal one-page UI)

cd frontend
python -m http.server 4173

Open http://127.0.0.1:4173.

The frontend uses a curio-api-base meta tag (or window.CURIO_API_BASE) to configure backend URL.

Deterministic scoring summary

Each ContentItem is scored by explicit weighted signals:

• format / tone / pacing / complexity
• violence tolerance
• mainstream vs hidden gems discovery preference
• favorite overlap
• session refinements (liked/disliked titles)
• avoid-term penalties
• recommendation mode and commitment-level adjustments

Explanations are assembled from scored signals only.