Skip to content

Books-specific framing hides the category-generic design #15

Open

Description

@murray-ds

Problem

The pipeline is category-generic — AMAZON_CATEGORIES in holmes/data/preprocess.py enumerates ~30 Amazon Reviews 2023 categories (All_Beauty, Electronics, Video_Games, …), preprocess --all fans out over every one into data/processed/<category>/, and build_dataset accepts any category by name. Books is only the default --category, not the domain.

But the project's own materials narrate it as a Books-specific system, which misleads readers into thinking there is a single domain:

  • CLAUDE.md calls it an "ALS book recommender (Amazon Reviews 2023, Books)".
  • holmes/data/preprocess.py:1 module docstring: "Build a sparse user-item interaction matrix from Amazon Reviews 2023 (Books)", as if Books were the domain.
  • tests/conftest.py names the shared fixture books_dataset and frames it in book/customer terms — yet it models a generic grouped user×item interaction matrix with nothing book-specific about it.

Three independent artifacts encode the default as if it were the design. This is drift: the docs/naming under-describe the system's generality.

Proposed fix

  • Rename the books_dataset fixture to something category-neutral (e.g. grouped_dataset / interaction_dataset) across tests/ — used in conftest.py, test_dataset.py, test_harness.py, test_als.py, test_diagnostics.py.
  • Correct the preprocess.py module docstring to describe the matrix as built from any Amazon Reviews 2023 category (Books being the default), not Books specifically.
  • Update the CLAUDE.md "What this project is" framing from "book recommender" to a category-generic Amazon Reviews recommender.
  • (Optional) Align the fixture's "customer" vocabulary with the Dataset class's "user" naming.

Why it matters

The framing is misleading enough that a reader working only from the project's docs concludes it is single-domain. Naming/docs should reflect that the system is category-generic.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions