Search & Graph

CLI commands for searching tariffs, extracting references, and managing the knowledge graph pipeline.

search

Interactive tariff search from the command line.

Usage


uv run hts search <query>

Arguments

Argument	Description
`query`	Search query (product description or keywords)

Options

Option	Type	Default	Description
`--strategy`	string	`hybrid`	Search strategy: `hybrid`, `semantic`, `lexical`
`--level`	string	`hts8`	Hierarchy level: `chapter`, `hts4`, `hts6`, `hts8`
`--variant`	string	`full`	Embedding variant: `full`, `short`
`--limit`	integer	`10`	Maximum results

Example


uv run hts search "fresh boneless beef" --strategy hybrid --limit 5

Example Output


Search results for "fresh boneless beef" (hybrid, hts8, full):

  1. 02013080 - Meat of bovine animals, fresh or chilled: Boneless: Other
     Score: 0.87 | MFN: 26.4%

  2. 02023080 - Meat of bovine animals, frozen: Boneless: Other
     Score: 0.81 | MFN: 26.4%

  3. 02013060 - Meat of bovine animals, fresh or chilled: Boneless: Described...
     Score: 0.78 | MFN: 4.4¢/kg

extract-code-references

Scan all tariff descriptions for HTS code mentions and store cross-references.

Usage


uv run hts extract-code-references

Details

Regex pattern: [0-9]{4}(\.[0-9]{1,2}){0,2}: matches codes like 0201.30, 0201, 0201.30.80
Validates against known tariff prefixes (4-digit, 6-digit, 8-digit)
Expands 5-digit codes to matching 6-digit codes
Deduplicates per source HTS8
Stores in tariff_code_references

Example Output


Extracting code references...
Processed 12,769 tariffs
Found 2,439 cross-references

generate-graph-edges

Generate semantic graph edge candidates using pgvector KNN.

Usage


uv run hts generate-graph-edges

Configuration

Setting	Default	Description
`graph_knn_k`	`30`	Nearest neighbors per code
`graph_knn_min_similarity`	`0.65`	Minimum cosine similarity
`graph_knn_level`	`hts8`	Embedding level
`graph_knn_variant`	`full`	Embedding variant

Example Output


Generating graph edge candidates...
Codes processed: 12,769
Candidates generated: 142,380
Time: 312.5 seconds

classify-graph-edges

Classify edge candidates using an LLM into 10 relationship types.

Usage


uv run hts classify-graph-edges

Configuration

Setting	Default	Description
`graph_classification_model`	`gpt-5.4-nano`	LLM model
`graph_classification_concurrency`	`200`	Concurrent API calls
`graph_classification_batch_size`	`500`	Database flush batch size
`graph_classification_chunk_size`	`1000`	Candidates per chunk
`graph_classification_chunk_delay`	`1.0`	Seconds between chunks

Resumable: If interrupted, re-running picks up where it left off.

Example Output


Classifying graph edges...
Classified: 142,380 | Errors: 12
Time: 8,234.1 seconds (2.3 hours)

graph-status

Show graph pipeline statistics.

Usage


uv run hts graph-status

Example Output


Graph Pipeline Status
=====================
Total candidates:  142,380
Total classified:  142,368
Pending:           12

By Relationship Type:
  material_affinity:           18,420 (avg conf: 0.82)
  functional_similarity:       15,230 (avg conf: 0.79)
  manufacturing_process:       12,100 (avg conf: 0.76)
  end_use:                     11,890 (avg conf: 0.74)
  substitution:                 8,920 (avg conf: 0.71)
  component_assembly:           7,650 (avg conf: 0.73)
  cross_category_bridge:        3,210 (avg conf: 0.68)
  abstraction:                  2,890 (avg conf: 0.85)
  weak_association:            24,560 (avg conf: 0.45)
  no_meaningful_relationship:  37,498 (avg conf: 0.88)