How t-redactyl/llm-semantic-book-recommender works
This is a Python ML/LLM prototype + tutorial repo that builds a semantic book recommender. Architecturally, it’s best represented as two “modes”:
Offline / batch pipeline (notebooks) that
• downloads + cleans data
• builds embeddings and a vector database (Chroma via LangChain)
• derives metadata facets (fiction/non-fiction via zero-shot classification)
• derives sentiment/emotion scores (LLM-driven sentiment analysis)
Online / interactive app (Gradio) that
• accepts a natural-language query + filters/sort options
• performs vector search against the persisted vector DB
• returns ranked recommendations (optionally using the precomputed facets)
What the file tree implies (map files to architectural components)
Top-level files are “the architecture” here—there’s no src/ package layering. Each notebook is effectively a pipeline stage.
• data-exploration.ipynb
ETL / data cleaning + exploration; likely produces cleaned dataset artifacts (CSV/parquet) used downstream.
• vector-search.ipynb
Embedding + indexing stage; creates/persists a Chroma vector database via langchain-chroma. This is the core retrieval component used by the app.
• text-classification.ipynb
Zero-shot classification stage (Transformers or LLM). Output is likely per-book labels (fiction/non-fiction) used as metadata filters.
• sentiment-analysis.ipynb
Emotion/sentiment extraction stage; output is per-book emotion scores (suspenseful/joyful/sad, etc.) used for sorting/facets.
• gradio-dashboard.py
The serving layer (a small “backend” + UI). It loads the vector DB and metadata and exposes search/recommendation interactions via Gradio.
• requirements.txt
Captures the runtime ecosystem: Kaggle download (kagglehub), data libs, LangChain integrations, Chroma, Transformers, Gradio.
• .env (implied by README)
Key architecture/tech to highlight (from README)
• Kaggle as the data source (downloaded via kagglehub)
• OpenAI API (embeddings and/or LLM calls; configured via .env)
• LangChain (orchestrates embedding + retrieval + maybe LLM calls)
• Chroma as the vector database (local persistent store is the likely deployment)
• Transformers for zero-shot classification (depending on notebook implementation)
• Gradio as the web UI/app container
Architectural pattern:
• A classic RAG-style retrieval workflow (query → embedding → vector search → results), augmented with metadata enrichment (classification + sentiment) to support filtering/sorting.
Ingestion & Cleaning (data-exploration.ipynb, pandas)
3. Embedding + Vector Index Builder (vector-search.ipynb, LangChain + OpenAI embeddings)
Artifacts Store
• Cleaned dataset files (CSV/parquet)
• Enrichment outputs (labels, emotion scores)
• (Optionally combined metadata table)
Storage / Retrieval
Vector DB: Chroma (persisted locally)
Stores embeddings + document text + metadata.
Online / App
Gradio Web App (gradio-dashboard.py)
UI + orchestration to query Chroma and present recommendations.
External Services
Important design principles (annotate)
• Batch preprocessing + offline indexing (notebooks) vs online retrieval (Gradio)
• Vector search is the core retrieval mechanism (semantic similarity)
• Metadata facets enable filtering (fiction/non-fiction) and ranking by tone
• Secrets management via .env (OpenAI key)
• Persistence boundary: Chroma local persistence (stateful storage)
Relevant technologies (label inside components)
• “pandas / seaborn / matplotlib” in cleaning/exploration
• “LangChain + Chroma” in vector store stage
• “OpenAI Embeddings” (if used) on the embedding edge
• “Transformers zero-shot” on classification (or “OpenAI LLM” if used)