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.
- 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
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
pip install -r requirements.txt
pip install -e .
pytest -q
streamlit run streamlit_app/Home.pyOptional demo:
streamlit run streamlit_app/Home.pyAll runtime assets are versioned under data/.
Scripts used to generate or validate these assets are documented in Scripts/README.md.
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.
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.
MIT