Docs → API reference

AI Infrastructure Production (semiconductor output and utilization) API v1

Generated from core.contract.describe_ai_infrastructure_production_v1() and checked fixture-backed examples. Do not hand-edit the example JSON files.

Capability

• Capability: ai_infrastructure.production
• Primitive: query_ai_infrastructure_production_v1
• Status: available
• Current source: production.fed.g17
• Source publisher: Federal Reserve Board
• Snapshot behavior: as_of = latest resolves to an exact snapshot date in every response.

What It Can Answer

• Monthly industrial-production index (2017=100) for semiconductor & other electronic component manufacturing (NAICS 3344), SA or NSA, cited to the Fed's SDMX observation.
• Monthly capacity utilization (percent, seasonally adjusted) — how hot the domestic fabs and component plants run.
• The capacity index (2017=100) behind the utilization rate.
• The production / utilization trend over any window since 1972 (averages — an index is intensive, never summed).
• Row-level detail records when include_records is true.
• Raw Fed SDMX-observation evidence for any returned row-level citation.

Represented Facts

• Fed G.17 reports the monthly industrial-production index (2017=100, seasonally adjusted and not adjusted) for semiconductor and other electronic component manufacturing (NAICS 3344) — the finest split G.17 publishes for this family, served verbatim and cited to the Board's SDMX observation
• Fed G.17 reports monthly capacity utilization (percent) and the capacity index (2017=100) for the same industry, seasonally adjusted only; an index or a rate is intensive — averaged over a window, never summed

Data Point Contract

• Data point: ai_infrastructure.production
• Product spec: blocks/ai_infrastructure_production/card.md
• Grain: series_monthly
• Source basis: production.fed.g17
• Represented fact: Fed G.17 (Industrial Production and Capacity Utilization) — the Board's monthly industrial-production index (2017=100, seasonally adjusted and not adjusted), capacity index, and capacity utilization (percent, seasonally adjusted) for SEMICONDUCTOR AND OTHER ELECTRONIC COMPONENT manufacturing (NAICS 3344), served exactly as the Board publishes them. NAICS 3344 is the finest split G.17 publishes for this family — broader than semiconductors alone, and NOT the same slice as QCEW's 334413. Public domain; cited to the Board.

Does not answer:

• semiconductors ALONE — NAICS 3344 includes other electronic components; the Fed publishes no finer split in G.17 (and it is NOT the same slice as QCEW's 334413)
• dollars, units shipped, or physical output volume (an index, 2017=100, is relative to the 2017 average — never a dollar or unit count)
• summing an index or a utilization rate across months or series (intensive readings; a multi-month figure is an average, and the Fed publishes its own quarterly/annual series we do not serve)
• not-seasonally-adjusted capacity or utilization (the Fed publishes capacity and utilization seasonally adjusted only — their NSA cells are structurally absent, not suppressed)
• any other G.17 industry, market group, or aggregate (total industry, computers NAICS 3341, the "semiconductors, printed circuit boards, and other" market group, …) — this block pins NAICS 3344
• which fab, company, or state is producing (a national industry aggregate with no place or operator anchor)
• WHY utilization moved (no editorializing; the block serves the Board's published readings)

REST Surface

• GET /v1/health
• GET /v1/capabilities
• GET /v1/ai-infrastructure/production/schema
• POST /v1/ai-infrastructure/production/query
• POST /v1/evidence/source-row

MCP Surface

• list_capabilities_v1
• describe_ai_infrastructure_production_v1
• query_ai_infrastructure_production_v1
• get_source_evidence_v1

Local MCP Setup

Some MCP clients launch servers from the user's home directory or ignore a configured cwd. Use uv run --directory so the server always starts from the repository project.

{
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "/absolute/path/to/OSINT",
    "python",
    "-m",
    "core.mcp_server"
  ]
}

Leave EXASCALE_PARQUET_BASE / EXASCALE_RAW_BASE unset: the one server hosts every data point's tools, and with no override it resolves each block's promoted snapshots and raw archive from the repository layout. Setting either env var points ALL tools at one directory — a per-block path breaks every other block's tools. They exist only for single-source sandboxes and tests.

Request Schema

Filters:

• as_of
• series_name
• series_kind
• basis
• data_month
• data_month_from
• data_month_to
• year

Input field semantics:

Group by:

• series_name
• series_kind
• basis
• data_month
• year

Date range parameters:

• data_month_from
• data_month_to

Controls:

• include_records
• include_evidence
• limit
• order_by
• top_n
• order
• rollup_other

Ranking (how order_by / top_n / order join — order_by ranks groups by a metric, never a group_by dimension; top_n needs both a group_by and an order_by):

{
  "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": [
      "avg_ip_index",
      "min_ip_index",
      "max_ip_index",
      "avg_capacity_index",
      "min_capacity_index",
      "max_capacity_index",
      "avg_capacity_utilization_pct",
      "min_capacity_utilization_pct",
      "max_capacity_utilization_pct",
      "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 Schema

Aggregate metrics:

• avg_ip_index
• min_ip_index
• max_ip_index
• avg_capacity_index
• min_capacity_index
• max_capacity_index
• avg_capacity_utilization_pct
• min_capacity_utilization_pct
• max_capacity_utilization_pct
• source_record_count

Metric groups:

{
  "capacity_index": [
    "avg_capacity_index",
    "min_capacity_index",
    "max_capacity_index"
  ],
  "capacity_utilization": [
    "avg_capacity_utilization_pct",
    "min_capacity_utilization_pct",
    "max_capacity_utilization_pct"
  ],
  "production_index": [
    "avg_ip_index",
    "min_ip_index",
    "max_ip_index"
  ],
  "records": [
    "source_record_count"
  ]
}

Response summary fields:

• group_count
• totals

Accepted fact policy:

• Query responses contain accepted, gate-passed facts only.
• Gate, monitor, and audit quality signals are internal controls, not agent-facing answer caveats.
• If a source snapshot is not fit to serve, the source must fail closed before it reaches this API.

Metric metadata:

Rollup rules:

• summary.totals.<metric> is the authoritative total for the full matched query.
• Grouped row metrics may be summed only when additive_across_groups is true.
• Do not sum grouped values for these non-additive metrics: avg_ip_index, min_ip_index, max_ip_index, avg_capacity_index, min_capacity_index, max_capacity_index, avg_capacity_utilization_pct, min_capacity_utilization_pct, max_capacity_utilization_pct.

Detail record fields returned when include_records is true:

• source_id
• series_name
• source_record_key
• report_period
• series_kind
• basis
• data_month
• year
• time_period_label
• obs_status
• unit_label
• ip_index
• capacity_index
• capacity_utilization_pct
• source_row_number
• as_of
• raw_file_sha256
• citation

Row-level citation fields:

• source_id
• source_url
• source_file
• sheet
• source_row
• time_period
• raw_file_sha256
• as_of

Aggregate citation fields:

• source_id
• publisher
• source_url
• source_file
• raw_file_sha256
• as_of
• source_rows_count
• source_rows_sample
• verify
• lineage_filter

Codebooks

The complete machine-readable codebooks are included in capability-schema.json.

Checked Examples

The checked schema output is capability-schema.json.

Agent Workflow

1. Call list_capabilities_v1 and select ai_infrastructure.production.
2. Call describe_ai_infrastructure_production_v1 to inspect valid filters, groupings, metrics, and citation fields.
3. Call query_ai_infrastructure_production_v1 with bounded JSON params.
4. If the answer needs proof, pass a returned row-level citation object to get_source_evidence_v1.
5. Answer with the resolved as_of and relevant citations. Present returned metrics as authoritative for their declared source, snapshot, grain, and aggregation.