Skip to main content

​
The pipeline

/v1/classify runs a five-stage pipeline. The full pipeline runs on the hot path (single line, low latency). Bulk paths can skip the voting and adversarial stages for throughput.

​
1. Embed

The product description is embedded once with the local 384-dim MiniLM model. No description ever leaves LandedFees infrastructure for embedding.

​
2. Vector-first retrieval

The engine issues two parallel vector lookups:
  • Top 10 HTS candidate lines from the destination country’s tariff schedule (US pulls from us_hts_codes, others from hs_codes).
  • Top 8 CROSS rulings (US Customs binding-ruling database).
If vector retrieval returns fewer than the target count, the shortfall is topped up with Postgres full-text search using a websearch tsquery. The two candidate sets are deduplicated by code and ruling ID.

​
3. Primary classification

The candidates and CROSS rulings are fed to a GRI-based classification prompt (General Rules of Interpretation, WCO). The model returns a recommended 6-digit HS code, a 10-digit HTS suggestion when the schedule supports it, a confidence score, and a natural-language reason string. If the caller passed hs_code_printed, the prompt is asked to compare and flag disagreements.

​
4. Three-sample consistency voting

Fires when the primary confidence is between 0.55 and 0.85. The engine re-runs the classifier three times at a slightly warmer temperature and takes the majority vote. Splits below majority are returned with needs_review: true.

​
5. Adversarial devil’s-advocate pass

Fires when the primary result lands high-confidence (0.85 or above). A separate prompt is instructed to argue for the strongest alternate HS code from the same candidate pool. The result carries one of three verdicts:
  • confirmed_primary: adversarial refused to flip. Primary stands.
  • plausible_alternate: a real alternate exists at or near primary confidence. needs_review is set.
  • not_triggered: voting split or explicit skip.

​
What you get back

​
When to trust the code

Ship-without-review is safe when needs_review: false and confidence is 0.85 or above. Below 0.85 the engine has already flagged the line; route it to a licensed broker before filing. The threshold is configurable per call via confidence_threshold.

​
Comparing the printed code

Suppliers often print an HS code on the commercial invoice that is wrong for your destination country. Pass it in hs_code_printed:
If the classifier chooses a different code, the response includes disagreement_with_printed: true and the recommended code in hs_6_code. This is the flag your broker wants to see before entry.

​
Batch mode

/v1/classify accepts either a single description or a lines[] batch of up to 50. Batch responses add a consistency block: when most lines share an HS chapter (first 2 digits) and one line diverges, the outlier is flagged. Useful for a bill of materials where all lines should live in the same tariff chapter.