Repolode
Submit
SakanaAI

SakanaAI/QD-Rec

Research code for QD-Rec, a quality-diversity method that evolves an archive of item-hypothesis pairs to produce diverse recommendations.

View on GitHub
Stars
13
Forks
0
Open issues
0
Last commit
2 days ago

What is it?

QD-Rec is the reference implementation of a recommendation method from a research paper. It maintains an archive of pairs, each consisting of an item from a fixed pool and a natural-language hypothesis explaining why that item suits a user. New pairs are admitted with a novelty-first rule and compete locally with similar entries, and items are selected with a diversity-aware contextual bandit.

The repository includes four example applications: finding likely customers from public persona data, recommending books from the Goodreads Children subset, discovering relevant academic papers from conference accept lists, and identifying M&A targets from a company table. Each app ships download, embedding and seeding scripts, plus a dashboard for viewing archives in the browser. The code runs every model through OpenRouter, so one API key covers the proposer, judge and embeddings.

The project also includes scripts for the Novelty and Novelty+Evo ablations used in the paper's comparisons. Developers can adapt the code to their own domain by supplying a pool of text items and a profile to recommend for.

Key features

  • 01Maintains an archive of item-hypothesis pairs with novelty-first admission and local competition.
  • 02Selects items using a diversity-aware contextual bandit.
  • 03Includes four example domains: customers, books, papers and M&A targets.
  • 04Runs all models, including proposer, judge and embeddings, through OpenRouter with one API key.
  • 05Provides a browser dashboard for inspecting saved archives.
  • 06Supports Novelty and Novelty+Evo ablation methods for comparison.

Use cases

  • Researchers reproducing or extending the QD-Rec paper's experiments.
  • Teams prototyping diverse recommendations over a fixed item catalog with LLM-written rationales.
  • Finding relevant papers by describing your research interests in a profile.
  • Adapting the pipeline to a custom domain that has text-described items.

Quick start

  1. 1

    Install dependencies with uv

    uv sync
  2. 2

    Create the .env file and add your OPENROUTER_API_KEY

    cp .env.example .env
  3. 3

    Download the personas, then create embeddings and seed the archive with the README's commands for those steps

  4. 4

    Run QD-Rec for 100 evaluations on the Customers domain

    uv run python -m apps.customers.qd_rec --profile SkillForge --iterations 100

Things to know

  • Every model call goes through OpenRouter, so you need a paid API key to run it.
  • This is research code released with a paper, so expect a setup that is less polished than a packaged tool.

Topics

#recommender-systems#quality-diversity#llm#contextual-bandit#openrouter#research#embeddings

FAQ

What is QD-Rec?
Research code for QD-Rec, a quality-diversity method that evolves an archive of item-hypothesis pairs to produce diverse recommendations. QD-Rec is the reference implementation of a recommendation method from a research paper. It maintains an archive of pairs, each consisting of an item from a fixed pool and a natural-language hypothesis explaining why that item suits a user. New pairs are admitted with a novelty-first rule and compete locally with similar entries, and items are selected with a diversity-aware contextual bandit.
Is QD-Rec free to use? What license does it have?
QD-Rec is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is QD-Rec still maintained?
Actively maintained. The last commit to QD-Rec was on Oct 19, 2026.
What can I use QD-Rec for?
Researchers reproducing or extending the QD-Rec paper's experiments. Teams prototyping diverse recommendations over a fixed item catalog with LLM-written rationales. Finding relevant papers by describing your research interests in a profile. Adapting the pipeline to a custom domain that has text-described items.
How do I install QD-Rec?
Install dependencies with uv: uv sync Create the .env file and add your OPENROUTER_API_KEY: cp .env.example .env Download the personas, then create embeddings and seed the archive with the README's commands for those steps Run QD-Rec for 100 evaluations on the Customers domain: uv run python -m apps.customers.qd_rec --profile SkillForge --iterations 100
Where can I get QD-Rec?
The source code and installation instructions are on GitHub: https://github.com/SakanaAI/QD-Rec

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects