abdurrehmansaeed commited on
Commit
1e5a39f
·
verified ·
1 Parent(s): 4031985

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +50 -39
README.md CHANGED
@@ -1,40 +1,51 @@
1
- # ThreadNode: Visual Inference Engine
2
-
3
- **Live Deployment:** [Hugging Face Space](https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode)
4
- **Source Code:** [GitHub Repository](https://github.com/abdur-rehmansaeed/ThreadNode)
5
-
6
- ThreadNode is a production-ready, hierarchical multi-label computer vision pipeline designed to automate product categorization for e-commerce platforms.
7
-
8
- ## The Vision: E-Commerce Automation
9
- 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.
10
-
11
- 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.
12
-
13
- ## Dataset & Taxonomy
14
- 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.
15
-
16
- 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.
17
- ## System Architecture
18
- This project utilizes a decoupled microservice architecture:
19
- * **The Brain (PyTorch):** An EfficientNet-B0 CNN, optimized with transfer learning, featuring a custom 132-node classification head.
20
- * **The Engine (FastAPI):** An asynchronous Python backend that holds the model state in memory and executes inference via a RESTful `/predict` endpoint.
21
- * **The Client (Vanilla JS/Tailwind):** A lightweight, zero-dependency diagnostic dashboard for real-time visual inference.
22
-
23
- ## Engineering Solutions
24
-
25
- ### 1. Solving the "Long-Tail" Class Imbalance
26
- 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).
27
-
28
- **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.
29
-
30
- ### 2. The API Confidence Threshold
31
- 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.
32
- * **Micro Precision:** Increased from 35.5% to 61.5%.
33
- * **Micro Recall:** Maintained at an excellent 93.5%.
34
- * **Micro F1-Score:** Stabilized at a highly functional 0.7422.
35
-
36
- ## Usage & Deployment
37
-
38
- ThreadNode is fully containerized via Docker and is deployed live on Hugging Face Spaces for public access and testing.
39
-
 
 
 
 
 
 
 
 
 
 
 
40
  **Try the live application here:** [ThreadNode on Hugging Face](https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode)
 
1
+ ---
2
+ title: ThreadNode
3
+ emoji: ⚡
4
+ colorFrom: indigo
5
+ colorTo: purple
6
+ sdk: docker
7
+ pinned: false
8
+ app_port: 7860
9
+ ---
10
+
11
+ # ThreadNode: Visual Inference Engine
12
+
13
+ **Live Deployment:** [Hugging Face Space](https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode)
14
+ **Source Code:** [GitHub Repository](https://github.com/abdur-rehmansaeed/ThreadNode)
15
+
16
+ ThreadNode is a production-ready, hierarchical multi-label computer vision pipeline designed to automate product categorization for e-commerce platforms.
17
+
18
+ ## The Vision: E-Commerce Automation
19
+ 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.
20
+
21
+ 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.
22
+
23
+ ## Dataset & Taxonomy
24
+ 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.
25
+
26
+ 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.
27
+
28
+ ## System Architecture
29
+ This project utilizes a decoupled microservice architecture:
30
+ * **The Brain (PyTorch):** An EfficientNet-B0 CNN, optimized with transfer learning, featuring a custom 132-node classification head.
31
+ * **The Engine (FastAPI):** An asynchronous Python backend that holds the model state in memory and executes inference via a RESTful `/predict` endpoint.
32
+ * **The Client (Vanilla JS/Tailwind):** A lightweight, zero-dependency diagnostic dashboard for real-time visual inference.
33
+
34
+ ## Engineering Solutions
35
+
36
+ ### 1. Solving the "Long-Tail" Class Imbalance
37
+ 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).
38
+
39
+ **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.
40
+
41
+ ### 2. The API Confidence Threshold
42
+ 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.
43
+ * **Micro Precision:** Increased from 35.5% to 61.5%.
44
+ * **Micro Recall:** Maintained at an excellent 93.5%.
45
+ * **Micro F1-Score:** Stabilized at a highly functional 0.7422.
46
+
47
+ ## Usage & Deployment
48
+
49
+ ThreadNode is fully containerized via Docker and is deployed live on Hugging Face Spaces for public access and testing.
50
+
51
  **Try the live application here:** [ThreadNode on Hugging Face](https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode)