Data Model

The HTS hierarchy, data structures, and enrichment fields.

HTS Hierarchy


Section (Roman numeral I–XXII)
  └─ Chapter (2 digits, 01–99)
       └─ Heading / HTS4 (4 digits)
            └─ Subheading / HTS6 (6 digits)
                 └─ Tariff Line / HTS8 (8 digits)

Sections

22 sections grouping chapters by broad commodity type. Each section has:

Roman numeral identifier (I–XXII)
Title (e.g., “Live Animals; Animal Products”)
Chapter range (e.g., chapters 01–05)
Interpretive notes

Chapters

98 chapters, each with:

2-digit code
Description
Section assignment
Chapter notes (legal classification rules)

Headings (HTS4)

4-digit headings subdivide chapters. Each heading has:

4-digit code
Description extracted from the hierarchical section data

Subheadings (HTS6)

6-digit subheadings are the international standard level (Harmonized System). With AI enrichment, each HTS6 code gains:

Enriched description: Concise AI-generated summary (max 100 chars)
Keywords: 5-7 product-specific terms
Exclusionary terms: Attributes that don’t apply to this category
Common attributes: Attributes shared by all child HTS8 codes

Tariff Lines (HTS8)

8-digit tariff lines are the most specific level. Each has:

HTS8 code
Brief description
MFN rates (text rate, ad valorem percentage, specific rate)
50+ FTA rate columns (USMCA, CAFTA-DR, AGOA, GSP, etc.)
Effective date range

FTA Rate Structure

The tariffs table includes columns for every major FTA program. Key rate columns:

Column Pattern	Example	Description
`mfn_text_rate`	`"6.4%"`	MFN rate as text
`mfn_ad_val_rate`	`6.4`	MFN ad valorem as number
`mfn_specific_rate`	`0.26`	MFN specific rate
`*_text_rate`	Various	FTA rate as text
`*_ad_val_rate`	Various	FTA ad valorem as number
`*_specific_rate`	Various	FTA specific rate

Embeddings

Multi-level embeddings enable search at every hierarchy level:

Level	Variant	Embedding Text Format
chapter	full	`"section {roman}: {title}; chapter {num}: {title}"`
hts4	full	`"section ...; chapter ...; category: {heading_desc}"`
hts6	full	`"section ...; chapter ...; category: {hts4_desc}; hts 6-digit: {code} - {enriched_desc}; keywords: {kw}"`
hts6	short	`"hts 6-digit: {code} - {enriched_desc}; keywords: {kw}"`
hts8	full	`"category: {hts4_desc}; hts 6-digit: {hts6}; keywords: {kw}; hts 8-digit: {code} - {desc}"`
hts8	short	`"hts 8-digit: {code} - {desc}"`

All embeddings use OpenAI text-embedding-3-small (1536 dimensions).

Knowledge Graph

Semantic edges connect related tariff codes with classified relationships:

Field	Type	Description
`source_code`	string	Source HTS code
`target_code`	string	Target HTS code
`relationship_type`	enum	One of 10 types (see below)
`confidence`	float	0-1 classification confidence
`reasoning`	string	LLM reasoning (25-30 words)
`key_differentiator`	string	What distinguishes the codes (max 8 words)
`bidirectional`	boolean	Whether the relationship is symmetric
`similarity`	float	Original cosine similarity from KNN

Relationship Types

Type	Definition
`material_affinity`	Same material, different forms or processing
`functional_similarity`	Same purpose, different materials or construction
`manufacturing_process`	Similar production methods
`end_use`	Complementary products used together
`substitution`	Borderline products straddling categories
`component_assembly`	Part-to-whole relationships
`cross_category_bridge`	Unexpected connection across taxonomy
`abstraction`	Hierarchical parent-child relationship
`weak_association`	Tangentially related
`no_meaningful_relationship`	False positive from KNN

Code References

The tariff_code_references table maps cross-references found in tariff descriptions:

Field	Description
`source_hts8`	The tariff whose description contains the reference
`referenced_code`	The code as it appears in the text (may include dots)
`referenced_code_clean`	Normalized code (digits only)
`code_length`	Length of the referenced code (4, 6, or 8 digits)