ENTUM-AI/hscode-classifier-en

1---2language:3  - en4tags:5  - classification6  - customs7  - trade8  - hscode9  - product-classification10  - pytorch11license: mit12pipeline_tag: text-classification13---14 15![HS Code Classifier](hscode_class_entum.webp)16 17# HS Code Classifier (English)18 19A deep learning model for automatic classification of goods by Harmonized System (HS) codes based on English-language product descriptions. The model predicts HS codes at three levels of granularity: 2-digit (chapter), 4-digit (heading), and 6-digit (subheading).20 21---22 23## Overview24 25The Harmonized System is an internationally standardized nomenclature for the classification of traded products. Manual assignment of HS codes is time-consuming and error-prone. This model automates that process from plain English product text, providing multi-level predictions with confidence scores.26 27**Task:** Multi-class text classification28**Input:** English product description (free-form text)29**Output:** HS code predictions at 2-, 4-, and 6-digit levels with confidence scores30**Base model:** `bert-base-uncased`31 32---33 34## Performance35 36The model was trained for 25 epochs and evaluated on a held-out validation set. The results below reflect the best checkpoint selected during training.37 38| Level       | Granularity   | Accuracy   |39|-------------|---------------|------------|40| 2-digit     | Chapter       | **97.74%** |41| 4-digit     | Heading       | **97.50%** |42| 6-digit     | Subheading    | **90.12%** |43 44Training and validation loss progression confirmed stable convergence without overfitting, supported by learning rate scheduling and weight averaging over the final epochs.45 46---47 48## Training Details49 50| Parameter           | Value                  |51|---------------------|------------------------|52| Training started    | 2026-03-09             |53| Total epochs        | 25                     |54| Final training loss | 0.40                   |55| Hardware            | GPU                    |56| Framework           | PyTorch + Transformers |57 58---59 60## Usage61 62This model uses a custom PyTorch architecture. Loading requires the class definition from the original inference script. Below is a high-level usage example.63 64### Requirements65 66```bash67pip install torch transformers sentencepiece safetensors68```69 70### Loading and Running Inference71 72```python73import torch74import json75from transformers import AutoTokenizer, AutoModel76 77# Load configuration78config = json.load(open("model/model_config.json"))79 80# Load tokenizer81tokenizer = AutoTokenizer.from_pretrained("model/tokenizer")82 83# Load label mappings84label2id_6 = json.load(open("model/label2id_6.json"))85id2label_6 = {v: k for k, v in label2id_6.items()}86 87# Run inference using the provided inference script:88# python inference.py89```90 91For full inference, use the `inference.py` script included in the repository. It loads all model components, accepts a product description as input, and returns the top-5 HS code candidates with confidence scores at each level.92 93### Output Format94 95```96Input: "wireless bluetooth headphones with noise cancellation"97 98Rank | Code       | Score     | Confidence99-----|------------|-----------|------------------------100  1  | 851830     | 4.12e-01  | 85.21 -> 91.43 -> 87.62101  2  | 851890     | 2.87e-01  | 85.21 -> 91.43 -> 72.18102  3  | 852520     | 1.03e-01  | ...103```104 105Each result shows the predicted 6-digit subheading with a chain of probabilities: chapter (2-digit) -> heading (4-digit) -> subheading (6-digit).106 107---108 109## Model Files110 111| File                  | Description                        |112|-----------------------|------------------------------------|113| `cascaded_best.pt`    | Trained model weights              |114| `model_config.json`   | Model architecture configuration   |115| `label2id_2.json`     | Chapter-level (2-digit) label map  |116| `label2id_4.json`     | Heading-level (4-digit) label map  |117| `label2id_6.json`     | Subheading-level (6-digit) label map |118| `tokenizer/`          | Tokenizer files                    |119| `base_model/`         | Fine-tuned base transformer weights |120 121---122 123## Limitations124 125- The model was trained on English-language product descriptions. Other languages are not supported.126- Coverage is limited to HS codes present in the training data. Very rare or newly introduced subheadings may not be recognized.127- Confidence scores should be treated as relative rankings rather than calibrated probabilities.128- The model predicts based on text alone. Physical measurements, materials composition, or country-specific tariff rulings are not taken into account.129 130---131 132## License133 134This model is released under the MIT License.135 136---137 138## Contact139 140Developed by **ENTUM-AI**.141For questions or collaboration, contact us via the Hugging Face profile page.142