Book Recommendations

CI License: MIT PyPI

Book recommendations for AI agents: "what should I read next?" answered from millions of works — topic recommendations, blind-date serendipity spins hooked by the book's actual first sentence, and free public-domain classics you can start reading right now. Zero API keys.

Ask any agent "what should I read next?", "books like Dune", or "surprise me with a book" — book-recommendations is the tool that answers.

Why this exists

• LLMs recommend the same 50 canon books for every ask. This fishes OpenLibrary's millions of works — including a blind-date spin that picks a random subject shelf at random depth, deliberately off the bestseller lists, and hooks you with the book's actual first sentence before the reveal.
• Read-now intelligence on every card: read_now says when a book is freely readable at archive.org (public) or borrowable (free loan) — instant reading beats a shopping link.
• Free classics via Project Gutenberg (fail-soft: when the Gutenberg index is down, the error itself points at archive.org alternatives).
• Honest attribution: every card says why_picked — how the book was actually chosen. Discovery you can trust.

Tools

Plus the prompt: what-should-i-read-next.

Quickstart

# 1-Line Universal Installer (auto-configures Claude Desktop, Cursor, Claude Code, VS Code, ...)
curl -fsSL "https://book-recommendations.builditwithai.xyz/install" | bash

# Or run directly via your preferred runtime:
uvx book-recommendations
npx -y book-recommendations

Example

User:  surprise me with a book

blind_date()
→ picks: [{
     first_sentence: "The lighthouse kept its own counsel…",
     subjects: ["lighthouses", "islands", "solitude"], first_published: 1962,
     why_picked: "blind date: fished the “lighthouses” shelf at depth 3 — picked
                  for serendipity, not sales rank",
     title: "…", author: "…", read_now: "borrowable at archive.org",
     openlibrary_url: "https://openlibrary.org/works/…" }]

Present the hook first, then the reveal — the two-beat structure is the product.

Telemetry & privacy

Anonymous usage telemetry (no PII, no queries, no paths) via the fleet standard (schema v2, dual-endpoint fallback). Opt out any time: BOOK_RECOMMENDATIONS_TELEMETRY=false or DO_NOT_TRACK=1.

Development

uv venv && uv pip install -e ".[dev]"
DO_NOT_TRACK=1 .venv/bin/python -m pytest tests/ -q   # unit + live + e2e

Live tests hit the real OpenLibrary API and self-skip offline.

License

MIT