ThreadNode / README.md
abdurrehmansaeed's picture
Update README.md
1e5a39f verified
|
Raw History Blame Contribute Delete
3.54 kB
metadata
title: ThreadNode
emoji: ⚡
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
app_port: 7860

ThreadNode: Visual Inference Engine

Live Deployment: Hugging Face Space
Source Code: GitHub Repository

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