Add BLS client library, example scripts, and usage docs

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

bls_client/queries/wages.py

@@ -0,0 +1,120 @@
+"""
+Pre-built wage and compensation series IDs — OES, ECI, ECEC, CPS earnings.
+"""
+
+from ..series import oes_national, eci
+
+# ---------------------------------------------------------------------------
+# OES — Occupational Employment & Wage Statistics
+# ---------------------------------------------------------------------------
+def all_occupations_employment() -> str:
+    """National employment across all occupations, all industries."""
+    return oes_national("000000", "000000", "employment")
+
+
+def occupation_annual_median_wage(soc_code: str) -> str:
+    """
+    Annual median wage for a specific occupation (national, all industries).
+
+    Args:
+        soc_code: 6-digit SOC code (e.g. "151132" for software developers,
+                  "291141" for registered nurses, "119021" for construction mgrs)
+    """
+    return oes_national(soc_code, "000000", "annual_median")
+
+
+def occupation_employment(soc_code: str) -> str:
+    """Employment level for a specific occupation (national)."""
+    return oes_national(soc_code, "000000", "employment")
+
+
+# Common occupation codes
+SOC_CODES = {
+    "software_developers":       "151132",
+    "registered_nurses":         "291141",
+    "teachers_elementary":       "252021",
+    "accountants":               "132011",
+    "construction_managers":     "119021",
+    "truck_drivers":             "533032",
+    "janitors":                  "372011",
+    "retail_salespersons":       "412031",
+    "first_line_supervisors_mfg":"511011",
+    "lawyers":                   "231011",
+    "physicians":                "291229",
+    "police_officers":           "333051",
+    "social_workers":            "211029",
+    "financial_analysts":        "132051",
+    "data_scientists":           "152051",
+}
+
+
+# ---------------------------------------------------------------------------
+# ECI — Employment Cost Index
+# ---------------------------------------------------------------------------
+def eci_total_compensation(seasonal: bool = True) -> str:
+    """ECI — civilian workers, all industries, total compensation."""
+    return eci("10", "10", component="A", seasonal=seasonal)
+
+
+def eci_wages(seasonal: bool = True) -> str:
+    """ECI — civilian workers, wages and salaries only."""
+    return eci("10", "10", component="W", seasonal=seasonal)
+
+
+def eci_benefits(seasonal: bool = True) -> str:
+    """ECI — civilian workers, benefit costs only."""
+    return eci("10", "10", component="B", seasonal=seasonal)
+
+
+def eci_private(seasonal: bool = True) -> str:
+    """ECI — private sector, total compensation."""
+    return eci("20", "10", component="A", seasonal=seasonal)
+
+
+def eci_state_local(seasonal: bool = True) -> str:
+    """ECI — state and local government, total compensation."""
+    return eci("30", "10", component="A", seasonal=seasonal)
+
+
+def eci_dashboard() -> dict:
+    return {
+        "Total Compensation (Civilian)": eci_total_compensation(),
+        "Wages & Salaries (Civilian)":   eci_wages(),
+        "Benefits (Civilian)":           eci_benefits(),
+        "Total Comp (Private)":          eci_private(),
+        "Total Comp (State/Local Gov)":  eci_state_local(),
+    }
+
+
+# ---------------------------------------------------------------------------
+# ECEC — Employer Costs for Employee Compensation
+# ---------------------------------------------------------------------------
+def ecec_total_compensation() -> str:
+    """ECEC — civilian workers, total compensation cost per hour."""
+    return "CMU1010000000000D"
+
+
+def ecec_health_insurance() -> str:
+    """ECEC — health insurance cost per hour worked."""
+    return "CMU1010000000000H"
+
+
+def ecec_retirement() -> str:
+    """ECEC — retirement & savings cost per hour worked."""
+    return "CMU1010000000000R"
+
+
+# ---------------------------------------------------------------------------
+# CPS Earnings (LE)
+# ---------------------------------------------------------------------------
+def median_weekly_earnings(seasonal: bool = True) -> str:
+    """Median usual weekly earnings — full-time wage and salary workers."""
+    return "LEU0252881600" if seasonal else "LEU0252881500"
+
+
+def median_weekly_earnings_men() -> str:
+    return "LEU0252882800"
+
+
+def median_weekly_earnings_women() -> str:
+    return "LEU0252882900"