File size: 3,536 Bytes
1e5a39f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4031985
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
---
title: ThreadNode
emoji: ⚡
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
app_port: 7860
---

# ThreadNode: Visual Inference Engine

**Live Deployment:** [Hugging Face Space](https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode)  
**Source Code:** [GitHub Repository](https://github.com/abdur-rehmansaeed/ThreadNode)

ThreadNode is a production-ready, hierarchical multi-label computer vision pipeline designed to automate product categorization for e-commerce platforms. 

## The Vision: E-Commerce Automation
The primary motivation behind ThreadNode is not simply to build a standalone classifier, but to solve a massive operational bottleneck in retail technology. Currently, many e-commerce platforms rely on manual data entry to categorize thousands of new product listings. 

ThreadNode demonstrates an automated pipeline where raw product imagery is instantly parsed into a highly accurate semantic taxonomy (e.g., `Apparel > Topwear > Tshirts`). By integrating this visual inference engine, platforms can automatically route inventory into the correct catalog architecture, entirely bypassing manual human classification.

## Dataset & Taxonomy
This engine was trained using the [Fashion Product Images Dataset](https://www.kaggle.com/datasets/paramaggarwal/fashion-product-images-dataset), which provides a robust corpus of high-resolution e-commerce imagery paired with rich product metadata. 

To create the taxonomy engine, the raw tabular metadata was parsed to extract a hierarchical relationship (e.g., `MasterCategory > SubCategory > ArticleType`). This text data was then vectorized into a 132-node MultiLabelBinarizer matrix to serve as the ground truth for the neural network's classification head.

## System Architecture
This project utilizes a decoupled microservice architecture:
* **The Brain (PyTorch):** An EfficientNet-B0 CNN, optimized with transfer learning, featuring a custom 132-node classification head.
* **The Engine (FastAPI):** An asynchronous Python backend that holds the model state in memory and executes inference via a RESTful `/predict` endpoint.
* **The Client (Vanilla JS/Tailwind):** A lightweight, zero-dependency diagnostic dashboard for real-time visual inference.

## Engineering Solutions

### 1. Solving the "Long-Tail" Class Imbalance
The original dataset exhibited a severe 1:1000 class imbalance (e.g., thousands of "Shirts" but only a few "Shrugs"). A standard binary cross-entropy (BCE) loss function resulted in a model that simply ignored minority classes (Macro F1: ~0.05). 

**The Fix:** I engineered a dynamically calculated `pos_weight` tensor and injected it directly into the `BCEWithLogitsLoss` function. This mathematically penalized the network heavily for missing rare items, forcing it to learn minority visual features and drastically improving the Macro F1 score across all 132 classes.

### 2. The API Confidence Threshold
To prevent the model from hallucinating "safe" guesses, business logic was separated from the neural network. The FastAPI endpoint enforces a strict 85% confidence threshold.
* **Micro Precision:** Increased from 35.5% to 61.5%.
* **Micro Recall:** Maintained at an excellent 93.5%.
* **Micro F1-Score:** Stabilized at a highly functional 0.7422.

## Usage & Deployment

ThreadNode is fully containerized via Docker and is deployed live on Hugging Face Spaces for public access and testing. 

**Try the live application here:** [ThreadNode on Hugging Face](https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode)