README.md

---
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

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

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

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

## Deploy to HuggingFace Space

```bash
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:

```csv
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.