beacon

beacon 📚

beacon is meant to guide you to crispy, delicious bacons, oh oops— books. A fun tool, born from a test driven development, that recommends books based on a description. A tasty twist of fate!

features

• natural language book search
• semantic similarity matching
• fast vector database backend
• curated book collection from goodreads

installation

uv pip install git+https://github.com/proteusiq/beacon.git

quick start

Use a small database (for full database remove –test flag)

uv run beacon init --test

Enjoy some bacons

from beacon import recommend

# get book recommendations
results = recommend("fantasy adventure with dragons and magic")

# print matched books
for book in results:
    print(f"📖 {book['title']} by {book['author']}")

development setup

1. clone the repository

git clone https://github.com/proteusiq/beacon.git
cd beacon

1. install dependencies and pre-commit hooks

make install

1. run tests

uv run pytest

1. format code and run linters

uv run pre-commit run -a

examples

find books similar to your favorites:

recommend("detective solving murders in victorian london")
recommend("post-apocalyptic survival story")
recommend("romance in a small coastal town")

---

made with ❤️ using proteusiq/pyproject