{"id":40943264,"url":"https://github.com/stratosphereips/book_whisperer","last_synced_at":"2026-01-22T04:37:28.964Z","repository":{"id":289364466,"uuid":"971010214","full_name":"stratosphereips/book_whisperer","owner":"stratosphereips","description":"A book whisperer for you to recommend what to read from a Calibre DB","archived":false,"fork":false,"pushed_at":"2025-04-23T20:42:14.000Z","size":49,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-05T10:28:19.718Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stratosphereips.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-22T21:55:25.000Z","updated_at":"2025-04-23T20:42:00.000Z","dependencies_parsed_at":"2025-04-22T22:51:07.320Z","dependency_job_id":null,"html_url":"https://github.com/stratosphereips/book_whisperer","commit_stats":null,"previous_names":["stratosphereips/book_whisperer"],"tags_count":6,"template":false,"template_full_name":"stratosphereips/awesome-code-template","purl":"pkg:github/stratosphereips/book_whisperer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stratosphereips%2Fbook_whisperer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stratosphereips%2Fbook_whisperer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stratosphereips%2Fbook_whisperer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stratosphereips%2Fbook_whisperer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stratosphereips","download_url":"https://codeload.github.com/stratosphereips/book_whisperer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stratosphereips%2Fbook_whisperer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28654885,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T01:17:37.254Z","status":"online","status_checked_at":"2026-01-22T02:00:07.137Z","response_time":144,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-22T04:37:28.235Z","updated_at":"2026-01-22T04:37:28.959Z","avatar_url":"https://github.com/stratosphereips.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📚 Calibre Book Recommender\n\nWelcome to **Calibre Book Recommender**, a command-line tool that fetches your Calibre library catalog and suggests what to read next using various methods like TF-IDF, fuzzy matching, or query-based similarity, and can return multiple recommendations at once.\n\n---\n\n## 🎯 Purpose\n\n- Automatically recommend daily reading from your Calibre library 📖\n- Avoid recommending the same book twice until every book has been suggested 🔄\n- Support thematic searches (e.g., `-r fantasy`) and fuzzy title matching 🧙‍♂️\n- Return top **X** recommendations in one go 📋\n- Lightweight: pure Python, SQLite for caching, no heavy dependencies by default 🐍\n\n---\n\n## 🚀 Features\n\n- **TF-IDF**-based content similarity (default) 📝\n- **Fuzzy title matching** using FuzzyWuzzy 🔍\n- **Query-based TF-IDF** similarity for custom search strings ✏️\n- Return **top X** recommendations with `-x` 📊\n- Local **SQLite** cache of book metadata and history 🗄️\n- Rich console output with **Rich** tables 🌈\n- CLI flags for listing, recommending, clearing history, and debugging ⚙️\n\n\n---\n## 👽👽👽 Contributors\n\n- [Maria Rigaki](https://github.com/orgs/stratosphereips/people/MariaRigaki)\n\n---\n\n## 🛠️ Installation\n\n1. Clone this repo:\n   ```bash\n   git clone git@github.com:stratosphereips/book_whisperer.git\n   cd book_whisperer\n   ```\n2. Create and activate a virtual environment:\n   ```bash\n   python3 -m venv venv\n   source venv/bin/activate\n   ```\n3. Install dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n4. Create a `.env` in the project root with your Calibre server info and (optionally) OpenAI key:\n   ```dotenv\n   CALIBRE_URL=http://xx.xx.xx.xx:8081\n   CALIBRE_USER=your_user\n   CALIBRE_PASS=your_pass\n\n   # OPENAI_API_KEY=sk-... (if using OpenAI method)\n   ```\n\n---\n\n## 🎛️ Usage\n\n```bash\n# List all books\n./book_wisperer.py -l\n\n# Recommend 1 book (TF-IDF default)\n./book_wisperer.py\n\n# Recommend 3 books using TF-IDF\n./book_wisperer.py -x 3\n\n# Recommend a book with a search term\n./book_wisperer.py -r mystery\n\n# Recommend top 2 for 'fantasy'\n./book_wisperer.py -r fantasy -x 2\n\n# Use fuzzy title-matching\n./book_wisperer.py -m fuzzy -r 'python'\n\n# Use query-based TF-IDF explicitly\n./book_wisperer.py -m query -r 'deep learning'\n\n# Debug mode: show internal logs\n./book_wisperer.py -d\n\n# Clear recommendation history\n./book_wisperer.py -c\n```\n\n---\n\n## 📖 Parameters\n\n| Flag                | Alias        | Description                                                                                   |\n|---------------------|--------------|-----------------------------------------------------------------------------------------------|\n| `-l`, `--list`      | N/A          | List all books in a formatted table                                                          |\n| `-r`, `--recommend` | N/A          | Recommend books; optionally provide a query string                                            |\n| `-m`, `--method`    | N/A          | Choose method: `tfidf` (default), `fuzzy`, or `query`                                         |\n| `-x`, `--top`       | N/A          | Number of top recommendations to return (default: 1)                                          |\n| `-c`, `--clear`     | N/A          | Clear all past recommendation history                                                        |\n| `-d`, `--debug`     | N/A          | Enable debug logging                                                                         |\n\n---\n\n## 💡 Examples\n\n1. **Daily reading recommendation** (TF-IDF default):\n   ```bash\n   ./book_wisperer.py\n   # Library contains 659 books.\n   # Top 1 recommendation today:\n   #  - The Hobbit by J.R.R. Tolkien 🧝‍♂️\n   ```\n\n2. **Top 5 thematic picks**:\n   ```bash\n   ./book_wisperer.py -r sci-fi -x 5\n   # Top 5 for 'sci-fi':\n   #  - Dune by Frank Herbert 🚀\n   #  - Neuromancer by William Gibson 🧠\n   #  - Foundation by Isaac Asimov 📚\n   #  - Ender's Game by Orson Scott Card 🛰️\n   #  - Snow Crash by Neal Stephenson 🏙️\n   ```\n\n3. **Fuzzy title match**:\n   ```bash\n   ./book_wisperer.py -m fuzzy -r 'python'\n   # Recommended for 'python':\n   #  - Advanced Guide to Python 3 Programming by John Hunt 🐍\n   ```\n\n4. **Clear recommendation history**:\n   ```bash\n   ./book_wisperer.py -c\n   🔄 Recommendation history cleared.\n   ```\n\n---\n\n## 🔄 Caching Behavior\n\n- **Books metadata**: cached locally in `books_cache.db`, refreshed only when the library list changes.\n- **Recommendations history**: stored to avoid repeats until every book has been suggested.\n\n---\n\n## 🎉 Contribute\n\nFeel free to open issues or PRs! Your feedback and enhancements are welcome. ✨\n\n---\n\n© 2025 eldraco. Built with ❤️ and Python.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstratosphereips%2Fbook_whisperer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstratosphereips%2Fbook_whisperer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstratosphereips%2Fbook_whisperer/lists"}