README.md

metadata

title: Replacement Products Viewer
emoji: 📦
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.29.0
app_file: app.py
python_version: '3.12'
pinned: false
short_description: Browse and annotate rejected items and replacements.
tags:
  - annotation
  - product-management
datasets: []

Replacement Products Annotation

A Gradio app for annotating rejected interior-design items and their approved replacement alternatives. Annotators decide whether each approved item is a direct replacement for the rejected one, and all annotations are persisted to a HuggingFace dataset repo.

This app requires a .csv file which is created by alternate_product_recs_labelling/classify.py.

Local development

pip install -r requirements.txt
gradio app.py --reload

or if you have uv installed, go to alternate_product_recs_labelling/ and run

uv sync
cd hf_deploy
uv run app.py --reload

Deploy to HuggingFace Space

hf upload brianleprograma/alternate_product_recs_labelling . . --repo-type space

Instructions for Annotators

1. Browse the list of rejected items and their approved alternatives in the Annotation tab.
2. Select a rejected item from the dropdown to view its details and the corresponding approved alternatives.
   • You can select an approved item for review from the list of options
3. For each pair, select the most appropriate label (Direct Replacement / Not Direct / Needs SME) and optionally add reasoning (highly recommended).
   • You can select an approved alternative either by clicking on its card or using the dropdown menu in the annotation controls.
   • A blue outline indicates the currently selected alternative, and a green badge confirms that an annotation has been saved for that pair.
4. Click Confirm to save your annotation. You can revisit and update annotations at any time.
5. Go to the Analysis tab to see aggregated insights across all annotations, including label distributions and breakdowns by category and rejection reason.
6. Download the full annotation log as a CSV for further analysis or reporting.
   • It is IMPORTANT that you download it before ending your session!
7. Send this to Vincent or Brian for review and next steps.

Annotation notes

• Focus on whether the product is a DIRECT replacement and not another item type in the same schedule section
  • Example 1: In the "Chairs" section an armchair was rejected. If the approved item is a desk chair, this should be marked as "Not Direct" even though it's in the same category, because it's not a like-for-like substitute
  • Example 2: In the "Lighting" section a pendant light was rejected. If the approved item is a floor lamp, this should be marked as "Not Direct" for the same reason, even though it's in the same category
• If there are not items in the approved items list that you think are a direct replacement DO NOT mark any of them as direct replacements just to complete the annotation — it's perfectly valid for a rejected item to have no direct replacement among the approved alternatives
• You should try and check the URL if there is information that is available there
  • Often URLs are broken in which case you can try a web search for the product name + brand to find more details
  • If you do not have enough information mark as "Needs SME" rather than guessing, and add any notes about what information is missing that would be helpful for the SME to make a decision
• When in doubt, add reasoning and/or flag for SME review rather than guessing - this will help us diagnose the issues in future

Layout

Annotation tab

Three-column layout:

Column	Content
Left	Rejected item details — image, name, brand, category, rejection reason, AI confidence
Middle	Scrollable list of approved alternative cards — click any card to select it for annotation
Right (floating)	Annotation controls — alternative dropdown, direct/not-direct/SME radio, reasoning text, Confirm button

Selecting an alternative via the dropdown or by clicking a card highlights the card with a blue outline and scrolls it into view. Annotated cards show a green badge with the saved label.

Analysis tab

Aggregated charts across all saved annotations:

• Donut — distribution of annotation labels
• Box plot — days to approval by label
• Bar — annotation breakdown by rejected category
• Bar — annotation breakdown by rejection reason (AI)
• Bar — status of items labelled as direct replacements
• Table — full annotation log

Annotation guidelines

For each rejected item / approved alternative pair, choose one label:

Label	When to use
✓ Direct Replacement	The approved item serves the same function, belongs to the same category, and would be a suitable substitute for the client
✗ Not Direct	The approved item is clearly different — different category, purpose, or not a like-for-like substitute
? Needs SME	You're unsure — flag for review by a subject-matter expert

Add optional reasoning to explain your decision, especially for borderline cases. Hit Confirm to save. You can re-annotate a pair at any time — the latest annotation overwrites the previous one.

Filters

• Match category only — limits approved alternatives to those sharing the rejected item's top-level category
• Resolution — filter the rejected item dropdown to All / Resolved only / Unresolved only

Required files

The following file must be present in the Space root alongside app.py:

File	Purpose
approved_after_with_comments_for_analysis.csv	Source data — rejected items and their approved alternatives

Optionally, provide item_images.csv to show product images:

ITEM_ID,image_path
12345,images/12345.png

If an image path is missing or the file doesn't exist, a placeholder image is shown.

Secrets / environment variables

Set these in Space Settings → Variables and secrets:

Secret	Description
HF_TOKEN	Write-access token for the dataset repo
HF_DATASET_REPO	Dataset repo ID where annotations are stored, e.g. your-username/rejected-items-annotations

Without these, the app still runs but annotations are saved locally only and will be lost on Space restart.