shinzobolte/product-recommendation-system

AI Product Recommendation System

A small full-stack project for the coding exercise:

• —frontend/: React app that shows a product catalog and a preference form
• —backend/: FastAPI API that returns products and asks Groq for recommendations

Hugging Face Spaces

This repository is set up for a Docker Space.

After creating the Space:

1. 1.Add the Space as a git remote:

git remote add hf https://huggingface.co/spaces/shinzobolte/product-recommendation-system

1. 1.Push the repository:

git push hf main

1. 1.In the Space settings, add a secret:

GROQ_API_KEY

Optional variable:

GROQ_MODEL=openai/gpt-oss-20b

What it does

1. 1.The React frontend loads a list of products from the backend.
2. 2.The user enters a preference such as I want a phone under $500.
3. 3.The FastAPI backend sends the filtered catalog and the preference to Groq.
4. 4.Groq returns recommended product IDs in JSON.
5. 5.The frontend highlights the recommended products and shows a short summary.

Tech Stack

• —Frontend: React + Vite + TypeScript
• —Backend: FastAPI
• —AI API: Groq
• —Data storage: local JSON file for simplicity

Backend setup

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

Add your Groq key to backend/.env:

GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=openai/gpt-oss-20b

Run the API:

.\.venv\Scripts\python -m uvicorn app.main:app --reload

The backend runs at http://127.0.0.1:8000.

Frontend setup

cd frontend
npm install
Copy-Item .env.example .env.local
npm run dev

The frontend runs at http://localhost:5173.

API endpoints

• —GET /health
• —GET /api/products
• —POST /api/recommendations

Example request body:

{
  "preference": "I want a phone under $500"
}

Notes

• —The project uses a local JSON catalog instead of a database because the exercise only requires browsing a small product list and returning recommendations.
• —The backend does a simple budget pre-filter first, then asks Groq to select the best matches from the remaining products.
• —If GROQ_API_KEY is missing, the frontend shows a clear error message from the backend.