Add BLS client library, example scripts, and usage docs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

bls_client/queries/prices.py

@@ -0,0 +1,124 @@
+"""
+Pre-built price series IDs — CPI, PPI, Import/Export, Average Prices.
+"""
+
+from ..series import cpi, ppi_commodity
+
+# ---------------------------------------------------------------------------
+# CPI-U
+# ---------------------------------------------------------------------------
+def cpi_all_items(seasonal: bool = False) -> str:
+    """CPI-U all items, US city average."""
+    return cpi("all_items", seasonal=seasonal)
+
+
+def cpi_core(seasonal: bool = True) -> str:
+    """CPI-U all items less food and energy (core inflation)."""
+    return cpi("core", seasonal=seasonal)
+
+
+def cpi_food(seasonal: bool = False) -> str:
+    return cpi("food", seasonal=seasonal)
+
+
+def cpi_energy(seasonal: bool = False) -> str:
+    return cpi("energy", seasonal=seasonal)
+
+
+def cpi_shelter(seasonal: bool = False) -> str:
+    return cpi("shelter", seasonal=seasonal)
+
+
+def cpi_gasoline(seasonal: bool = True) -> str:
+    return cpi("gasoline", seasonal=seasonal)
+
+
+def cpi_medical(seasonal: bool = False) -> str:
+    return cpi("medical", seasonal=seasonal)
+
+
+def cpi_dashboard(seasonal: bool = False) -> dict:
+    """Key CPI components as a labeled dict."""
+    return {
+        "All Items":          cpi_all_items(seasonal),
+        "Core (ex food/NRG)": cpi_core(True),
+        "Food":               cpi_food(seasonal),
+        "Energy":             cpi_energy(seasonal),
+        "Shelter":            cpi_shelter(seasonal),
+        "Medical Care":       cpi_medical(seasonal),
+        "Gasoline":           cpi_gasoline(True),
+    }
+
+
+# ---------------------------------------------------------------------------
+# CPI-W
+# ---------------------------------------------------------------------------
+def cpi_w_all_items(seasonal: bool = False) -> str:
+    """CPI-W all items (used for Social Security COLA)."""
+    return cpi("all_items", seasonal=seasonal, series="W")
+
+
+# ---------------------------------------------------------------------------
+# PPI
+# ---------------------------------------------------------------------------
+def ppi_all_commodities() -> str:
+    """PPI — all commodities index."""
+    return ppi_commodity("00000000")
+
+
+def ppi_finished_goods() -> str:
+    """PPI — finished goods."""
+    return ppi_commodity("3")
+
+
+def ppi_energy() -> str:
+    return ppi_commodity("05")
+
+
+def ppi_food() -> str:
+    return ppi_commodity("02")
+
+
+def ppi_dashboard() -> dict:
+    return {
+        "All Commodities": ppi_all_commodities(),
+        "Finished Goods":  ppi_finished_goods(),
+        "Food":            ppi_food(),
+        "Energy":          ppi_energy(),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Average Prices (AP)
+# ---------------------------------------------------------------------------
+def avg_price_electricity() -> str:
+    """Average retail price of electricity per KWh."""
+    return "APU000072610"
+
+
+def avg_price_gasoline_regular() -> str:
+    """Average retail price of regular unleaded gasoline per gallon."""
+    return "APU00007471A"
+
+
+def avg_price_eggs() -> str:
+    """Average retail price of eggs per dozen."""
+    return "APU0000708111"
+
+
+def avg_price_ground_beef() -> str:
+    """Average retail price of ground beef per pound."""
+    return "APU0000703112"
+
+
+# ---------------------------------------------------------------------------
+# Import/Export Price Indexes (EI)
+# ---------------------------------------------------------------------------
+def import_price_index() -> str:
+    """Import price index — all imports."""
+    return "EIUIR"
+
+
+def export_price_index() -> str:
+    """Export price index — all exports."""
+    return "EIUIQ"