https://github.com/margotrud/shopping_assistant
NLP-driven lipstick recommender that turns free-text preferences into color-constrained rankings.
https://github.com/margotrud/shopping_assistant
color-science lab-color-space nlp python recommendation-system streamlit
Last synced: 2 months ago
JSON representation
NLP-driven lipstick recommender that turns free-text preferences into color-constrained rankings.
- Host: GitHub
- URL: https://github.com/margotrud/shopping_assistant
- Owner: margotrud
- License: mit
- Created: 2026-01-20T13:16:52.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-02-10T11:21:05.000Z (4 months ago)
- Last Synced: 2026-02-10T15:53:35.605Z (4 months ago)
- Topics: color-science, lab-color-space, nlp, python, recommendation-system, streamlit
- Language: Python
- Homepage: https://github.com/margotrud/Shopping_assistant
- Size: 16.9 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Shopping Assistant — Color-Aware Recommendation from Natural Language
This project is a color-aware recommendation system that focuses on the interpretation
and ranking stages of cosmetic shade selection, starting from free-text user preferences.
It parses natural language constraints (e.g. brightness, warmth, exclusions), resolves
color anchors in Lab space, builds adaptive candidate pools, and ranks products using
fully deterministic, test-backed logic. The project is designed as a reproducible
portfolio system, not a production or end-to-end service.
---
## Key features
- Natural language preference interpretation with explicit constraint contracts
- Domain-aware color anchoring and adaptive candidate pooling
- Calibrated Lab-space scoring with deterministic tie-breaking
- Fully test-covered core logic (pytest)
- Streamlit demo application for interactive exploration
---
## Project structure
```
src/Shopping_assistant/ # Core Python package (NLP, color, scoring, recommendation)
Scripts/ # Offline asset generation and diagnostics (not required at runtime)
data/ # Versioned runtime assets (lexicons, anchors, calibration)
tests/ # Pytest-only unit and contract tests
streamlit_app/ # Demo application
```
---
## Quickstart
```bash
pip install -r requirements.txt
pip install -e .
pytest -q
streamlit run streamlit_app/Home.py
```
Optional demo:
```bash
streamlit run streamlit_app/Home.py
```
---
## Data & assets
All runtime assets are versioned under `data/`.
Scripts used to generate or validate these assets are documented in `Scripts/README.md`.
### Dataset limitations
The included dataset is a truncated subset of the original catalog.
It is intended to make the application runnable and illustrate the
interpretation and ranking logic, not to reflect final recommendation quality.
As a result, some rankings or explanations may appear less accurate
than in the full internal setup.
---
## Scope and intent
This repository prioritizes clarity, determinism, and testability over production concerns
(scaling, latency, serving infrastructure).
It is intended to demonstrate applied data science, NLP interpretation, and color-aware
recommendation design.
---
## License
MIT