Mitchins/book-genre-v5-title-author

Book Genre V5 Title+Author Classifier

This package contains a weak title+author genre classifier intended for rough corpus segmentation, triage, and candidate labeling of raw book libraries.

IMPORTANT: This is not a ground-truth model. It is designed to operate on minimal metadata (Title and Author) to provide broad categorizations when rich descriptions or human curation are unavailable.

Features

• No Breadcrumbs: This model does not rely on Amazon categories, breadcrumbs, or scraped metadata for its input. It uses only Title and Author.
• 5 Canonical Classes:
  • Literary / General Fiction
  • Romance
  • Sci-Fi / Fantasy
  • Mystery / Thriller / Crime
  • Nonfiction
• Decision Policy Gating: Included scripts enforce a strict decision policy that yields high-precision exact labels, identifies semantic ambiguity, and abstains when confidence is low.

Performance & Expectations

Based on validation audits:

• Exact Auto-Label Precision: Expected ~84.7% (on the ~61% of books that pass the confidence threshold).
• Top-2 Containment: The correct label is in the Top-2 predictions ~86.6% of the time.
• Limitations:
  • Generic titles (e.g., "The Return") are often underdetermined and will likely result in an abstain or ambiguous_bucket decision.
  • The model is strongly influenced by author priors (e.g., Stephen King -> Horror/Thriller).
  • Demographic/Age classifications (Children's, YA) are NOT predicted by this model.

Do not overwrite existing curated metadata without review.

Usage

1. Single Item Inference

Run a quick test on a single title and author:

python inference.py --title "Dune" --author "Frank Herbert"

2. Batch Inference

Score a JSONL or CSV file of books:

python batch_infer.py --input example_inputs.jsonl --output predictions.jsonl --batch-size 64

3. Disk / NAS Corpus Segmentation

Scan a local folder tree of ebooks, infer titles/authors from paths, and generate a classification manifest:

python segment_disk_corpus.py --root /path/to/books --output manifest.jsonl --batch-size 64

Requirements

• transformers>=4.20.0
• torch>=1.10.0
• pandas
• tqdm