Add BLS client library, example scripts, and usage docs

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

examples/basic_pull.py

@@ -0,0 +1,43 @@
+"""
+Basic example — fetch a few series and print the latest values.
+Run from the bls/ directory:  python3 examples/basic_pull.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.queries import employment, prices, wages
+
+client = BLSClient(BLS_API_KEY)
+
+# ── Single series ────────────────────────────────────────────────────────────
+print("=== National Nonfarm Payrolls ===")
+result = client.fetch_latest(employment.nonfarm_payrolls(), years=1)
+for sid, s in result.items():
+    obs = client.latest_obs(s)
+    print(f"  {obs['periodName']} {obs['year']}: {float(obs['value']):,.0f} thousand jobs")
+
+# ── Named dict pull ──────────────────────────────────────────────────────────
+print("\n=== CPI Dashboard (latest month) ===")
+results = client.fetch_named(prices.cpi_dashboard(), 2025, 2026)
+for label, s in results.items():
+    obs = client.latest_obs(s)
+    if obs:
+        print(f"  {label:<30} {obs['value']:>8}  ({obs['periodName']} {obs['year']})")
+
+# ── DC region unemployment ───────────────────────────────────────────────────
+print("\n=== DC Region Unemployment Rates ===")
+results = client.fetch_named(employment.dc_region_unemployment(), 2025, 2026)
+for label, s in results.items():
+    obs = client.latest_obs(s)
+    if obs:
+        print(f"  {label:<20} {obs['value']}%  ({obs['periodName']} {obs['year']})")
+
+# ── Flatten to rows ──────────────────────────────────────────────────────────
+print("\n=== Raw rows (first 3) ===")
+result = client.fetch_latest(employment.nonfarm_payrolls(), years=1, catalog=True)
+rows = client.to_rows(result)
+for row in rows[:3]:
+    print(f"  {row}")

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']})")