Enrichment Tools

Tools for running the AI enrichment pipeline and generating embeddings.

enrich_hts6_codes

Generate AI-powered descriptions, keywords, and exclusionary terms for 6-digit HTS codes using GPT-5.4 Nano.

Parameters

Parameter	Type	Required	Default	Description
`batch_size`	integer	No	`50`	Number of codes to process per batch
`max_workers`	integer	No	`25`	Concurrent API calls

Response


{
  "count": 5714,
  "skipped": 0,
  "errors": 3,
  "already_existed": 0,
  "time_seconds": 892.4
}

Details

For each HTS6 code, the tool:

Collects all child HTS8 descriptions
Sends them to GPT-5.4 Nano with a structured prompt
Receives: enriched description (max 100 chars), 5-7 keywords, exclusionary terms, common attributes
Stores results in the hts6_enrichments table

The enrichment is idempotent: re-running skips already-enriched codes. The skipped count in the response shows how many were skipped.

generate_multilevel_embeddings

Generate OpenAI embeddings at multiple hierarchy levels with configurable text variants.

Parameters

Parameter	Type	Required	Default	Description
`levels`	list[string]	No	All levels	Levels to embed: `"chapter"`, `"hts4"`, `"hts6"`, `"hts8"`
`variants`	list[string]	No	All variants	Text variants: `"full"`, `"short"`
`batch_size`	integer	No	`500`	Texts per API batch call

Response


{
  "count": 38025,
  "by_level": {
    "chapter": 98,
    "hts4": 961,
    "hts6": 11428,
    "hts8": 25538
  },
  "time_seconds": 634.2
}

Details

The text builder constructs embedding text for each level/variant combination. See Data Model: Embeddings for the exact text formats.

Embeddings are stored in the hts_embeddings table with columns: code, level, variant, embedding (1536D vector), embedding_text.

Uses ON CONFLICT DO UPDATE for idempotent upserts.

get_enrichment_status

Check the availability and coverage of AI enrichments and embeddings.

Parameters

None.

Response


{
  "enrichments": {
    "available": true,
    "count": 5714
  },
  "embeddings": {
    "available": true,
    "summary": {
      "chapter_full": 98,
      "hts4_full": 961,
      "hts6_full": 5714,
      "hts6_short": 5714,
      "hts8_full": 12769,
      "hts8_short": 12769
    }
  }
}