Smart Librarian is a full-stack book recommendation application. The React frontend sends natural-language questions to a FastAPI backend, which combines input filtering, semantic retrieval from a Chroma catalogue, OpenAI recommendations, local summaries, and Google Books fallback search.
The chatbox can:
- Recommend books from the local catalogue using natural-language questions.
- Refine recommendations by mood, genre, theme, or reading preferences.
- Search and prioritize books in the language of the prompt or a language explicitly specified by the user.
- Retrieve complete summaries for books in the local catalogue.
- Search Google Books when the local catalogue does not have enough relevant results.
- Continue conversations with bounded message history.
- Python 3.11+
- Node.js 20.19+ or 22.12+
- npm 10+
- An OpenAI API key
Create the backend environment file from the template and set OPENAI_API_KEY:
Copy-Item backend/.env.example backend/.envInstall dependencies once:
Set-Location backend
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
Set-Location ..\frontend
npm install
Set-Location ..
npm installStart both development servers from the repository root:
npm run dev:serversThe frontend is available at http://127.0.0.1:5173/ and the backend at http://127.0.0.1:8000/. To start them individually, follow the backend and frontend guides below.
Before making recommendations, ingest the local catalogue:
Set-Location backend
.\.venv\Scripts\python.exe -m app.scripts.ingest_booksConfigure backend/.env with OPENAI_API_KEY, then run from the repository root:
Copy-Item backend/.env.example backend/.env
docker compose up --buildThe frontend is available at http://localhost:8080/ and the backend at http://localhost:8000/. Chroma data and backend logs are persisted in named volumes.
Stop the stack while retaining its volumes:
docker compose downThe complete Compose configuration and volume guidance are in docs/docker-compose.md.