Add BLS client library, example scripts, and usage docs

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

examples/custom_series.py

@@ -0,0 +1,77 @@
+"""
+Custom series example — build series IDs from scratch using the series module.
+Run from the bls/ directory:  python3 examples/custom_series.py
+"""
+
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from config import BLS_API_KEY
+from bls_client import BLSClient
+from bls_client import series
+
+client = BLSClient(BLS_API_KEY)
+
+# ── Build LAUS series for any state ─────────────────────────────────────────
+print("=== LAUS: unemployment rates for New York, Texas, California ===")
+state_series = {
+    "New York":    series.laus_state(36, "rate"),
+    "Texas":       series.laus_state(48, "rate"),
+    "California":  series.laus_state(6,  "rate"),
+}
+results = client.fetch_named(state_series, 2025, 2026)
+for label, s in results.items():
+    obs = client.latest_obs(s)
+    if obs:
+        print(f"  {label:<15} {obs['value']}%")
+
+# ── Build CES for specific industries ───────────────────────────────────────
+print("\n=== CES: employment by sector ===")
+industry_series = {
+    "Healthcare":      series.ces_national("education_health", "employees"),
+    "Retail":          series.ces_national("retail", "employees"),
+    "Manufacturing":   series.ces_national("manufacturing", "employees"),
+    "Leisure/Hosp":    series.ces_national("leisure", "employees"),
+}
+results = client.fetch_named(industry_series, 2025, 2026)
+for label, s in results.items():
+    obs = client.latest_obs(s)
+    if obs:
+        print(f"  {label:<20} {float(obs['value']):>10,.0f}K  ({obs['periodName']} {obs['year']})")
+
+# ── Build CPI for specific items ─────────────────────────────────────────────
+print("\n=== CPI: selected item prices (index, 1982-84=100) ===")
+cpi_series = {
+    "All Items":   series.cpi("all_items"),
+    "Shelter":     series.cpi("shelter"),
+    "Gasoline":    series.cpi("gasoline", seasonal=True),
+    "New Vehicles":series.cpi("new_vehicles"),
+}
+results = client.fetch_named(cpi_series, 2025, 2026)
+for label, s in results.items():
+    obs = client.latest_obs(s)
+    if obs:
+        print(f"  {label:<20} {obs['value']:>8}  ({obs['periodName']} {obs['year']})")
+
+# ── JOLTS: full dashboard ────────────────────────────────────────────────────
+print("\n=== JOLTS: labor market flows ===")
+from bls_client.queries import employment
+results = client.fetch_named(employment.jolts_dashboard(), 2025, 2026)
+for label, s in results.items():
+    obs = client.latest_obs(s)
+    if obs:
+        print(f"  {label:<25} {float(obs['value']):>8,.0f}K  ({obs['periodName']} {obs['year']})")
+
+# ── OES: wages for specific occupations ─────────────────────────────────────
+print("\n=== OES: annual median wages by occupation ===")
+from bls_client.queries import wages
+from bls_client.queries.wages import SOC_CODES
+occ_series = {
+    label.replace("_", " ").title(): wages.occupation_annual_median_wage(code)
+    for label, code in list(SOC_CODES.items())[:5]
+}
+results = client.fetch_named(occ_series, 2023, 2024)
+for label, s in results.items():
+    obs = client.latest_obs(s)
+    if obs:
+        print(f"  {label:<35} ${float(obs['value']):>10,.0f}  ({obs['year']})")