| | --- |
| | language: |
| | - en |
| | tags: |
| | - classification |
| | - customs |
| | - trade |
| | - hscode |
| | - product-classification |
| | - pytorch |
| | license: mit |
| | pipeline_tag: text-classification |
| | --- |
| | |
| |  |
| |
|
| | # HS Code Classifier (English) |
| |
|
| | A 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). |
| |
|
| | --- |
| |
|
| | ## Overview |
| |
|
| | The 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. |
| |
|
| | **Task:** Multi-class text classification |
| | **Input:** English product description (free-form text) |
| | **Output:** HS code predictions at 2-, 4-, and 6-digit levels with confidence scores |
| | **Base model:** `bert-base-uncased` |
| |
|
| | --- |
| |
|
| | ## Performance |
| |
|
| | The model was trained for 25 epochs and evaluated on a held-out validation set. The results below reflect the best checkpoint selected during training. |
| |
|
| | | Level | Granularity | Accuracy | |
| | |-------------|---------------|------------| |
| | | 2-digit | Chapter | **97.74%** | |
| | | 4-digit | Heading | **97.50%** | |
| | | 6-digit | Subheading | **90.12%** | |
| |
|
| | Training and validation loss progression confirmed stable convergence without overfitting, supported by learning rate scheduling and weight averaging over the final epochs. |
| |
|
| | --- |
| |
|
| | ## Training Details |
| |
|
| | | Parameter | Value | |
| | |---------------------|------------------------| |
| | | Training started | 2026-03-09 | |
| | | Total epochs | 25 | |
| | | Final training loss | 0.40 | |
| | | Hardware | GPU | |
| | | Framework | PyTorch + Transformers | |
| |
|
| | --- |
| |
|
| | ## Usage |
| |
|
| | This model uses a custom PyTorch architecture. Loading requires the class definition from the original inference script. Below is a high-level usage example. |
| |
|
| | ### Requirements |
| |
|
| | ```bash |
| | pip install torch transformers sentencepiece safetensors |
| | ``` |
| |
|
| | ### Loading and Running Inference |
| |
|
| | ```python |
| | import torch |
| | import json |
| | from transformers import AutoTokenizer, AutoModel |
| | |
| | # Load configuration |
| | config = json.load(open("model/model_config.json")) |
| | |
| | # Load tokenizer |
| | tokenizer = AutoTokenizer.from_pretrained("model/tokenizer") |
| | |
| | # Load label mappings |
| | label2id_6 = json.load(open("model/label2id_6.json")) |
| | id2label_6 = {v: k for k, v in label2id_6.items()} |
| | |
| | # Run inference using the provided inference script: |
| | # python inference.py |
| | ``` |
| |
|
| | For 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. |
| |
|
| | ### Output Format |
| |
|
| | ``` |
| | Input: "wireless bluetooth headphones with noise cancellation" |
| | |
| | Rank | Code | Score | Confidence |
| | -----|------------|-----------|------------------------ |
| | 1 | 851830 | 4.12e-01 | 85.21 -> 91.43 -> 87.62 |
| | 2 | 851890 | 2.87e-01 | 85.21 -> 91.43 -> 72.18 |
| | 3 | 852520 | 1.03e-01 | ... |
| | ``` |
| |
|
| | Each result shows the predicted 6-digit subheading with a chain of probabilities: chapter (2-digit) -> heading (4-digit) -> subheading (6-digit). |
| |
|
| | --- |
| |
|
| | ## Model Files |
| |
|
| | | File | Description | |
| | |-----------------------|------------------------------------| |
| | | `cascaded_best.pt` | Trained model weights | |
| | | `model_config.json` | Model architecture configuration | |
| | | `label2id_2.json` | Chapter-level (2-digit) label map | |
| | | `label2id_4.json` | Heading-level (4-digit) label map | |
| | | `label2id_6.json` | Subheading-level (6-digit) label map | |
| | | `tokenizer/` | Tokenizer files | |
| | | `base_model/` | Fine-tuned base transformer weights | |
| |
|
| | --- |
| |
|
| | ## Limitations |
| |
|
| | - The model was trained on English-language product descriptions. Other languages are not supported. |
| | - Coverage is limited to HS codes present in the training data. Very rare or newly introduced subheadings may not be recognized. |
| | - Confidence scores should be treated as relative rankings rather than calibrated probabilities. |
| | - The model predicts based on text alone. Physical measurements, materials composition, or country-specific tariff rulings are not taken into account. |
| |
|
| | --- |
| |
|
| | ## License |
| |
|
| | This model is released under the MIT License. |
| |
|
| | --- |
| |
|
| | ## Contact |
| |
|
| | Developed by **ENTUM-AI**. |
| | For questions or collaboration, contact us via the Hugging Face profile page. |
| |
|
