zeiban (税番)

A small model that predicts the 10-digit US Harmonized Tariff Schedule (HTS) code from a product text (name, material, categories, description). It runs on CPU only, with no LLM and no network access at inference time.

  • Small: one 55 MB bundle, about 76 MB resident memory, 0.07–0.33 s per item on 2 CPU threads (Rust runtime).
  • Answers with its doubts: the 10-digit code, calibrated confidence, alternates, the basic duty rate, and a clarifying question built from the official tariff text (for a tote bag: "outer surface of textile materials — of cotton / of man-made fibers / other"), with the duty rate of each option.
  • English and Japanese input, read by one multilingual reader.
  • Tariff release pinned: 2026HTSRev22. Every response carries htsRelease.

Code, the Rust runtime, the WebAssembly build and the full write-up (data, training, evaluation, things that did not work) are on GitHub: https://github.com/ikenokazuki/zeiban (README in English; the complete write-up is the Japanese README).

Read this first.

  • The top-1 10-digit code is not accurate enough to file a customs entry as is. Use the 6-digit code and the confidence, and narrow the 10 digits with the alternates and the question.
  • v0.3.0 replaced the reader. On the held-out test items, accuracy without questions is about the same as v0.2.1. What improved is accuracy on rulings issued after the training data, and accuracy after answering questions. Japanese customs-style text got slightly worse. It is about 10 times slower than v0.2.1.
  • This is not legal advice or a customs ruling. Duty rates are the basic columns of the tariff schedule and do not include additional duties.
  • The previous version (v0.2.1: 61 MB, 6–36 ms per item, a separate Japanese reader) is at revision v0.2.1 of this repository and in the GitHub releases.

Use with Python

pip install numpy torch tokenizers huggingface_hub
import sys
from huggingface_hub import snapshot_download

d = snapshot_download("ikeno-ada/zeiban")
sys.path.insert(0, d)
from zeiban import Zeiban

z = Zeiban(d)
r = z.classify({"name": "Womens tote bag", "material": "cotton canvas"})
print(r["hsCode"]["code"], r["sixDigit"], r["dutyRate"]["general"])   # 4202921500 420292 6.3%

r = z.classify({"name": "メンズ 半袖 Tシャツ", "material": "綿100% ニット"})
print(r["hsCode"]["code"], r["sixDigit"])                              # 6109100027 610910

Input fields: name (required), material, categories (string or list), description, prefix (digits you already know: 2, 4, 6, 8 or 10 digits — pass the prefix of the option you chose in questions to narrow the answer in one more stateless call), and confirm (true to be asked from the top level even where the model is confident).

Response fields: hsCode, sixDigit, confidenceScore, sixDigitConfidence, dutyRate, alternates, questions, htsRelease, codes, scores.

The Python implementation loads in about 3 s, takes about 50 ms per short item and about 650 MB of memory (torch). For speed and a small footprint, use the Rust runtime or zeiban.wasm from the GitHub repository with zeiban.bin and zeiban.json from this repository. All three give the same answers (checked on 3,805 inputs for Rust vs Python and 467 for WebAssembly).

Files

File Content
zeiban.bin, zeiban.json The bundle (4-bit weights of the reader, tariff tree, node vectors, lexical index, labels, duty rates) and its manifest
tokenizer.json, bmx-tokenizer.json Tokenizer definitions used by the Python implementation (reader; lexical index)
zeiban.py The Python implementation (reader in torch, the rest in numpy)

How it works

The reader is the first 6 layers (width 512) of google/embeddinggemma-2, fine-tuned for tariff classification, quantized to 4 bits with quantization-aware training, with the vocabulary reduced to 49,106 tokens. Five projections give one query vector per tariff level (2, 4, 6, 8, 10 digits), compared by cosine with pre-computed vectors of the 38,276 nodes of the tariff tree. A lexical index (BMX) over the 19,926 leaf documents adds a word-match score. The leaf score is the sum of the five level-wise log-softmax scores along its path. Confidence is calibrated per level with logistic regression.

The question: the model finds the first level where its confidence is below 0.7, gathers up to 30 candidates that agree with the top answer above that level, and asks where they split. Confident levels are skipped unless confirm is set.

Evaluation

Top-1 accuracy on test items that were held out and scored once for this version (2026-11-18), on the same items as v0.2.1.

Test set Items 10 digits (v0.2.1 → v0.3.0) 6 digits Top-5, 10 digits
Ruling-like text (ATLAS test, near-duplicates of training items removed) 145 0.462 → 0.462 0.586 → 0.545 0.621 → 0.586
Ruling-like text (ATLAS test, all) 200 0.520 → 0.515 0.640 → 0.600 0.650 → 0.625
Short e-commerce titles (HSCodeComp, held-out part) 422 0.249 → 0.268 0.384 → 0.419 0.498 → 0.552
Everyday goods (6-digit labels) 98 — 0.908 → 0.908 —
Rulings issued after the training data (name + description; never read before the final run) 1,403 0.270 → 0.387 0.411 → 0.533 0.528 → 0.659
  • None of the differences on the first four rows is statistically clear (the 95% intervals of the paired differences include zero). On the development items the e-commerce titles had looked much better (0.262 → 0.371); the test did not confirm that.
  • The last row favours v0.3.0: older rulings written in the same style were added to its training data.
  • With questions answered correctly (an upper bound), 10-digit accuracy on the e-commerce titles goes from 0.268 to 0.434 (one question), 0.664 (up to three), and 0.839 with confirm and up to four. v0.2.1 reached 0.576 with three.
  • Targets set before development: 30% at 10 digits on HSCodeComp was not met (26.8%); 90% accuracy among answers with confidence ≥ 0.9 was not met (86–87%, on 14 and 30 items).

Japanese: advance classification rulings published by Japan Customs (1,788 held-out items, 6-digit labels).

Input v0.2.1 v0.3.0 v0.3.0, items with no near-duplicate in training (1,099)
Product name only 0.633 0.584 0.575
Name + description 0.769 0.739 0.652
Facts only (materials, process, use; no name, no summary sentence) 0.538 0.559 0.423

These numbers need a discount: 39% of the test items have a near-identical ruling in the training part, and the names and summary sentences written by customs are close to the tariff wording.

Limits

  • 10-digit top-1 is not at filing quality, especially for short product titles.
  • Confidence is too high on short e-commerce titles and on name-only inputs.
  • About 10 times slower than v0.2.1; in WebAssembly (single thread) the longest inputs take over a second.
  • US HTS only. Tariff notes and the General Rules of Interpretation are not read as text.
  • Languages other than English and Japanese have not been measured.
  • Tested on x86-64 Linux; ARM64 not verified on real hardware.

Data and attribution

  • Tariff schedule: US International Trade Commission (work of the US Government).
  • Base model of the reader: google/embeddinggemma-2 (Apache-2.0). Changes: first six layers of the text encoder only, fine-tuned, quantized to 4 bits, vocabulary reduced. Its model card states: "Deployments must adhere to the Gemma Prohibited Use Policy".
  • The vocabulary and tokenizer of the lexical index, and the starting values of the node vectors, derive from cl-nagoya/ruri-v3-30m (Apache-2.0), built on sbintuitions/modernbert-ja-30m (MIT).
  • "CROSS Rulings HTS Dataset for Tariff Classification by Flexify.AI Inc. (https://www.flexify.ai)" (Apache-2.0), with changes.
  • fklc/cbp-rulings-past-2012 (MIT): product names and descriptions extracted from rulings of US Customs and Border Protection.
  • Product texts from Amazon ESCI and Shopify/product-catalogue (Apache-2.0), labelled with an LLM. Rulings of US Customs and Border Protection were rewritten into product texts with an LLM.
  • Advance classification rulings published by Japan Customs (source: Japan Customs website, https://www.customs.go.jp/; the search-result listing was processed).
  • Advance Tariff Rulings published by HM Revenue & Customs (UK). Contains public sector information licensed under the Open Government Licence v3.0.
  • None of the source texts are redistributed. See NOTICE.

日本語の説明

商品の文(品名・素材・分類・説明)から、米国の関税率表(HTS)の 10 桁の番号を出す小さなモデル。CPU だけで動き、実行時に LLM もネットワークも使わない。10 桁のコードに、確度・代わりの候補・基本の税率・確認の質問を付けて返す。英語と日本語の文を、1 つの読み手で読む。

v0.3.0 で、文を読む層を入れ替えた。テスト用の品での質問なしの精度は、v0.2.1 とほぼ同じ(判例に近い文の 10 桁 46%・短い通販の商品名の 10 桁 27%)。伸びたのは、学習よりあとに出た判例(10 桁 27% → 39%)と、質問に答える流れ(通販の商品名の 10 桁が、3 回までで 66%)。日本の税関の書き方の文は少し下がり、速さは約 10 分の 1 になった。前の版は、このリポジトリのリビジョン v0.2.1 にある。

1 位の 10 桁は、そのまま申告に使える精度ではない。通関の判断の代わりにはならない。使い方・データの出どころ・測り方・効かなかった試しは、GitHub の README(日本語)に書いてある: https://github.com/ikenokazuki/zeiban

Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support

Model tree for ikeno-ada/zeiban

Finetuned
(183)
this model