ThreadNode / README.md
abdurrehmansaeed's picture
Update README.md
1e5a39f verified
|
Raw History Blame Contribute Delete
3.54 kB
---
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)