{
  "anchors": [],
  "capability": "ai_infrastructure.equipment_trade",
  "codebooks": {
    "commodity": {
      "codes": {
        "8486": {
          "label": "Machines for the manufacture of semiconductors / ICs / flat panel displays; parts"
        }
      },
      "coverage": "HS-8486 at the HS4 heading",
      "note": "HS-8486 is 'Machines and apparatus of a kind used solely or principally for the manufacture of semiconductor boules or wafers, semiconductor devices, electronic integrated circuits or flat panel displays; parts and accessories' \u2014 the chip-MAKING equipment, INCLUDING flat-panel-display machinery. It is NOT the chips (HS-8542) and carries no tool-type or vendor breakdown at this level.",
      "semantics": "hs_commodity_heading",
      "source": "U.S. Census Bureau Harmonized System (HS) heading, verbatim."
    },
    "country_level": {
      "codes": {
        "country": {
          "label": "An individual country of origin"
        },
        "grouping": {
          "label": "A Census country grouping / continent (overlaps \u2014 never summed)"
        },
        "total": {
          "label": "All countries (the published U.S. total)"
        }
      },
      "coverage": "every served row is exactly one level",
      "note": "total = the all-countries TOTAL (CTY_CODE '-'); grouping = a Census bloc/continent (ASIA, APEC, EU, OECD, ASEAN, the '<n>XXX' continents) that OVERLAPS other rows; country = an individual country of origin. The groupings overlap each other and the countries \u2014 never sum across rows; the served TOTAL is the only national figure.",
      "semantics": "census_intltrade_country_level",
      "source": "Derived from the Census CTY_CODE structure."
    }
  },
  "data_point": {
    "does_not_answer": [
      "the chips themselves \u2014 HS-8486 is the MANUFACTURING EQUIPMENT; integrated-circuit imports are HS-8542 (ai_infrastructure.trade)",
      "a semiconductor-only reading \u2014 the HS-8486 heading ALSO covers flat-panel-display manufacturing machinery; Census does not split them at this level",
      "tool-type or vendor breakdown \u2014 one HS4 heading; no lithography-vs-deposition-vs-etch split, no per-manufacturer (e.g. ASML) series",
      "summing across country rows \u2014 Census's groupings (ASIA, APEC, EU, OECD, ASEAN, Pacific Rim, the continents) OVERLAP each other and the individual countries; the served \"TOTAL FOR ALL COUNTRIES\" (country_level=total) is the only valid total, never a sum the agent computes",
      "quantity or unit counts of tools \u2014 the measure is customs value (USD) only at this level",
      "landed / CIF / duty-paid cost \u2014 general imports value is customs value; CIF, charges, and calculated duty are separate Census fields not served here",
      "which U.S. fab, state, county, or operator receives the equipment \u2014 country is the country of ORIGIN (Census attribution), not a U.S. destination; this series carries no U.S. geographic anchor",
      "exports (this block serves IMPORTS only) or trade in non-HS-8486 goods",
      "finality (recent months are preliminary and revised in later Census releases)"
    ],
    "grain": "commodity_country_monthly",
    "id": "ai_infrastructure.equipment_trade",
    "note": "This is the monthly customs value (USD) of U.S. imports of HS-8486 \u2014 semiconductor-MANUFACTURING equipment (lithography, deposition, etch, and related tools), which ALSO includes flat-panel-display machinery and is NOT the chips themselves (integrated circuits are HS-8542, ai_infrastructure.trade) \u2014 by country of origin. NEVER SUM across country rows: Census's groupings (ASIA, APEC, EU, OECD, ASEAN, the continents) overlap each other and the individual countries, and the all-countries TOTAL contains everything. Filter country_level=total for the U.S. national figure; the measure is customs value (USD), not tool counts.",
    "product_spec": "blocks/ai_infrastructure_equipment_trade/card.md",
    "represented_fact": "Census International Trade reports the monthly customs value (USD) of U.S. IMPORTS of HS-8486 \"Machines and apparatus of a kind used solely or principally for the manufacture of semiconductor boules or wafers, semiconductor devices, electronic integrated circuits or flat panel displays\" \u2014 the chip-MAKING equipment (lithography, deposition, etch, and related tools), which INCLUDES flat-panel-display machinery and is NOT the chips themselves \u2014 by country of origin and as Census's own published country GROUPINGS and TOTAL. Served as two value series exactly as Census publishes: general imports value and imports-for-consumption value. Value only. Each row is served verbatim + cited; the country groupings overlap and are never summed.",
    "source_basis": [
      "trade.census.intltrade_equipment_hs"
    ],
    "source_decisions": [
      "docs/sources/trade/census_intltrade_hs_equipment/build-plan.md"
    ]
  },
  "input": {
    "controls": [
      "include_records",
      "include_evidence",
      "limit",
      "order_by",
      "top_n",
      "order",
      "rollup_other"
    ],
    "date_range_params": [
      "data_month_from",
      "data_month_to"
    ],
    "date_ranges": [
      "data_month"
    ],
    "field_metadata": {},
    "filters": [
      "as_of",
      "country",
      "cty_code",
      "country_level",
      "data_month",
      "data_month_from",
      "data_month_to",
      "year"
    ],
    "group_by": [
      "country",
      "cty_code",
      "country_level",
      "data_month",
      "year"
    ],
    "ranking": {
      "no_ranking": "Omit order_by and top_n to return all groups in group-key order.",
      "order": {
        "default": "desc",
        "valid_values": [
          "desc",
          "asc"
        ]
      },
      "order_by": {
        "accepts": "one of output.metrics",
        "note": "Ranks the groups by a metric (a measure). Not a group_by dimension \u2014 rows already come back grouped by each group_by field.",
        "requires": [
          "group_by"
        ],
        "valid_values": [
          "general_value_usd",
          "consumption_value_usd",
          "source_record_count"
        ]
      },
      "top_n": {
        "note": "Keeps the top N groups by order_by; the rest fold into one (other) remainder (additive metrics sum into it, non-additive ones are nulled) so the result still reconciles to summary.totals.",
        "requires": [
          "group_by",
          "order_by"
        ],
        "type": "positive integer"
      }
    }
  },
  "output": {
    "aggregate_citation_fields": [
      "source_id",
      "publisher",
      "source_url",
      "source_file",
      "raw_file_sha256",
      "as_of",
      "source_rows_count",
      "source_rows_sample",
      "verify",
      "lineage_filter"
    ],
    "citation_fields": [
      "source_id",
      "source_url",
      "source_file",
      "sheet",
      "source_row",
      "raw_file_sha256",
      "as_of"
    ],
    "detail_fields": [
      "source_id",
      "sheet_name",
      "source_record_key",
      "report_period",
      "commodity",
      "commodity_desc",
      "cty_code",
      "country",
      "country_level",
      "data_month",
      "year",
      "general_value_usd",
      "consumption_value_usd",
      "source_row_number",
      "as_of",
      "raw_file_sha256",
      "citation"
    ],
    "metric_groups": {
      "consumption_value_usd": [
        "consumption_value_usd"
      ],
      "general_value_usd": [
        "general_value_usd"
      ],
      "records": [
        "source_record_count"
      ]
    },
    "metric_metadata": {
      "consumption_value_usd": {
        "additive_across_groups": false,
        "aggregation": "sum",
        "authoritative_total_path": "summary.totals.consumption_value_usd",
        "category": "consumption_value_usd",
        "definition": "The total customs value (USD) of imports FOR CONSUMPTION of HS-8486 semiconductor-manufacturing equipment for the country row in scope, exactly as Census publishes it (CON_VAL_MO).",
        "description": "Census's OWN published customs value (USD) of U.S. imports of HS-8486 (semiconductor-manufacturing equipment, INCLUDING flat-panel-display machinery \u2014 not the chips) for the country row in scope, served verbatim. NONADDITIVE across country rows: the groupings (ASIA, APEC, EU, OECD, ASEAN, the continents) overlap each other and the individual countries, and the all-countries TOTAL contains everything \u2014 a cross-row sum double-counts. A result spanning more than one country row without grouping by country carries a country_aggregation scope note and ranking remainders omit the metric \u2014 filter country_level=total for the national figure, country_level=country for individual countries, or group_by country for the per-country series.",
        "display_name": "Imports-for-consumption value",
        "display_precision": "Values are in USD, rounded to 6 decimal places in JSON to remove binary floating-point noise.",
        "grain": "commodity country month",
        "null_handling": "A (commodity, country, month) cell Census did not publish is absent (a country with no equipment shipments that month is simply not a row), never zero; an empty-query summary returns zero.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.consumption_value_usd",
        "source_fields": [
          "consumption_value_usd"
        ],
        "unit": "USD"
      },
      "general_value_usd": {
        "additive_across_groups": false,
        "aggregation": "sum",
        "authoritative_total_path": "summary.totals.general_value_usd",
        "category": "general_value_usd",
        "definition": "The total customs value (USD) of GENERAL imports of HS-8486 semiconductor-manufacturing equipment for the country row in scope, exactly as the U.S. Census Bureau publishes it (GEN_VAL_MO).",
        "description": "Census's OWN published customs value (USD) of U.S. imports of HS-8486 (semiconductor-manufacturing equipment, INCLUDING flat-panel-display machinery \u2014 not the chips) for the country row in scope, served verbatim. NONADDITIVE across country rows: the groupings (ASIA, APEC, EU, OECD, ASEAN, the continents) overlap each other and the individual countries, and the all-countries TOTAL contains everything \u2014 a cross-row sum double-counts. A result spanning more than one country row without grouping by country carries a country_aggregation scope note and ranking remainders omit the metric \u2014 filter country_level=total for the national figure, country_level=country for individual countries, or group_by country for the per-country series.",
        "display_name": "General imports value",
        "display_precision": "Values are in USD, rounded to 6 decimal places in JSON to remove binary floating-point noise.",
        "grain": "commodity country month",
        "null_handling": "A (commodity, country, month) cell Census did not publish is absent (a country with no equipment shipments that month is simply not a row), never zero; an empty-query summary returns zero.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.general_value_usd",
        "source_fields": [
          "general_value_usd"
        ],
        "unit": "USD"
      },
      "source_record_count": {
        "additive_across_groups": true,
        "aggregation": "count source records",
        "authoritative_total_path": "summary.totals.source_record_count",
        "category": "records",
        "definition": "Count of normalized source records (commodity \u00d7 country \u00d7 month rows) contributing to the current result scope.",
        "description": "Number of normalized Census import rows (commodity \u00d7 country \u00d7 month) contributing to the value.",
        "display_name": "Source record count",
        "display_precision": "Integer.",
        "grain": "source row",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "additive_partition_metric",
        "row_metric_path": "rows[].metrics.source_record_count",
        "source_fields": [
          "source_record_key"
        ],
        "unit": "count"
      }
    },
    "metrics": [
      "general_value_usd",
      "consumption_value_usd",
      "source_record_count"
    ],
    "summary_fields": [
      "group_count",
      "totals"
    ]
  },
  "primitive": "query_ai_infrastructure_equipment_trade_v1",
  "status": "available"
}