Suspicious Books Screener (suspicious_books_screener.py)

#!/usr/bin/env python3
"""
suspicious_books_screener.py

Pop-up tool to flag books that look "mass-produced" or low-effort,
based on simple, transparent rules. It does NOT prove that a book is
AI-generated. It only surfaces titles that might deserve closer review.

Usage:
    python suspicious_books_screener.py books.csv books_with_flags.csv
"""

import csv
import sys
from collections import Counter
from pathlib import Path


GENERIC_PHRASES_TITLE = [
    "ultimate guide",
    "comprehensive guide",
    "for beginners",
    "for beginners and experts",
    "step by step",
    "step-by-step",
    "the complete guide",
    "the essential guide",
]

GENERIC_PHRASES_DESC = [
    "in this book you will learn",
    "in this book, you will learn",
    "this book will teach you",
    "this comprehensive guide will",
    "by the end of this book",
    "whether you are a beginner or an expert",
    "this book covers everything you need to know",
]


def score_title(title: str) -> int:
    if not title:
        return 0
    t = title.lower()
    score = 0
    if len(title) > 120:
        score += 1
    matches = sum(1 for phrase in GENERIC_PHRASES_TITLE if phrase in t)
    if matches >= 1:
        score += 1
    if "," in title and ":" in title and len(title.split()) > 15:
        score += 1
    return score


def score_description(desc: str) -> int:
    if not desc:
        return 0
    d = desc.lower()
    score = 0
    matches = sum(1 for phrase in GENERIC_PHRASES_DESC if phrase in d)
    if matches >= 2:
        score += 2
    elif matches == 1:
        score += 1
    if desc.count("you will") >= 3:
        score += 1
    if len(desc) > 0 and len(set(desc.split())) < len(desc.split()) * 0.5:
        score += 1
    return score


def count_authors(rows: list[dict], author_key: str) -> Counter:
    counter: Counter = Counter()
    for row in rows:
        author = row.get(author_key, "").strip()
        if author:
            counter[author] += 1
    return counter


def detect_author_volume_flags(rows: list[dict], author_key: str) -> dict:
    result: dict[int, int] = {}
    if not author_key:
        return result
    counts = count_authors(rows, author_key)
    high_volume_authors = {a for a, c in counts.items() if c >= 10}
    if not high_volume_authors:
        return result
    for idx, row in enumerate(rows):
        author = row.get(author_key, "").strip()
        if author in high_volume_authors:
            result[idx] = 1
    return result


def choose_key(row: dict, candidates: list[str]) -> str:
    for name in candidates:
        for key in row.keys():
            if key.lower() == name.lower():
                return key
    return ""


def screen_books(input_path: Path, output_path: Path) -> None:
    with input_path.open(newline="", encoding="utf-8-sig") as infile:
        reader = csv.DictReader(infile)
        rows = list(reader)

    if not rows:
        print("No rows found in input file.")
        return

    sample_row = rows[0]
    title_key = choose_key(sample_row, ["title", "book_title"])
    author_key = choose_key(sample_row, ["author", "author_name"])
    desc_key = choose_key(sample_row, ["description", "desc", "summary", "blurb"])

    author_volume_scores = detect_author_volume_flags(rows, author_key)

    fieldnames = list(sample_row.keys())
    for extra in ("suspicious_ai_like_score", "suspicious_notes"):
        if extra not in fieldnames:
            fieldnames.append(extra)

    suspicious_counts = Counter()

    with output_path.open("w", newline="", encoding="utf-8") as outfile:
        writer = csv.DictWriter(outfile, fieldnames=fieldnames)
        writer.writeheader()

        for idx, row in enumerate(rows):
            for key in row:
                if row[key] is None:
                    row[key] = ""

            title = row.get(title_key, "")
            desc = row.get(desc_key, "")

            score = 0
            notes: list[str] = []

            t_score = score_title(title)
            if t_score:
                score += t_score
                notes.append("generic/long title")

            d_score = score_description(desc)
            if d_score:
                score += d_score
                notes.append("repetitive / template-like description")

            extra = author_volume_scores.get(idx, 0)
            if extra:
                score += extra
                notes.append("author appears on many titles")

            if score > 3:
                score = 3

            row["suspicious_ai_like_score"] = str(score)
            row["suspicious_notes"] = "; ".join(sorted(set(notes))) if score > 0 else ""
            suspicious_counts[score] += 1
            writer.writerow(row)

    print(f\'Screened {len(rows)} books.")
    for s in sorted(suspicious_counts.keys()):
        print(f\'Score {s}: {suspicious_counts[s]} titles")
    print("Higher scores simply mean: worth a closer human look.")


def main(argv: list[str]) -> int:
    if len(argv) != 3:
        print("Usage: python suspicious_books_screener.py books.csv books_with_flags.csv")
        return 1
    input_path = Path(argv[1]).expanduser()
    output_path = Path(argv[2]).expanduser()
    if not input_path.exists():
        print(f\'Input file not found: {input_path}")
        return 1
    screen_books(input_path, output_path)
    print(f\'Flagged file written to: {output_path}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv))