Reference Tools

Tools for querying code cross-references and database status.

get_tariff_references

Get all HTS codes referenced within a tariff’s description text.

Parameters

Parameter	Type	Required	Default	Description
`hts_code`	string	Yes	-	8-digit HTS code

Response


{
  "hts8": "02013080",
  "references": [
    {
      "referenced_code": "0202.30",
      "referenced_code_clean": "020230",
      "code_length": 6
    },
    {
      "referenced_code": "0206",
      "referenced_code_clean": "0206",
      "code_length": 4
    }
  ],
  "count": 2
}

Details

References are pre-extracted from tariff descriptions using regex pattern matching and validated against known tariff prefixes. The extraction happens during the extract-code-references pipeline step.

Returns 503 if the references table is unavailable or empty.

get_tariffs_referencing_code

Find all tariffs whose descriptions reference a given code. Uses prefix matching so a 4-digit code will match all tariffs referencing any code starting with those digits.

Parameters

Parameter	Type	Required	Default	Description
`code`	string	Yes	-	HTS code to search for (4-8 digits)
`limit`	integer	No	`20`	Maximum results

Response


{
  "code": "0206",
  "referenced_by": [
    {
      "source_hts8": "02013080",
      "source_description": "Meat of bovine animals, fresh or chilled: Boneless: Other"
    },
    {
      "source_hts8": "02023080",
      "source_description": "Meat of bovine animals, frozen: Boneless: Other"
    }
  ],
  "count": 2
}

get_database_status

Comprehensive database health check covering all data tables and pipeline status.

Parameters

None.

Response


{
  "tariffs": {
    "count": 19228,
    "date_range": {
      "earliest": "2024-01-01",
      "latest": "2024-12-31"
    }
  },
  "embeddings": {
    "available": true,
    "count": 48230,
    "summary": {
      "hts8_full": 19228,
      "hts8_short": 19228,
      "hts6_full": 3560,
      "hts4_full": 1228,
      "chapter_full": 99
    }
  },
  "enrichments": {
    "available": true,
    "count": 1247
  },
  "references": {
    "available": true,
    "count": 8420
  },
  "resources": {
    "count": 45
  },
  "graph": {
    "candidates": 142380,
    "classified": 142368,
    "pending": 12
  }
}

Usage

Call this at the start of a session to verify data availability. Key checks:

Embeddings unavailable → Search falls back to lexical only
Enrichments unavailable → HTS6-level search won’t have AI descriptions
Graph candidates = 0 → Run generate_graph_edges first
Graph pending > 0 → Some edges still need classification