""" CBO data source configuration. Maps each dataset to its CBO publication ID, URL patterns, and available vintages. """ from pathlib import Path # Repository root REPO_ROOT = Path(__file__).resolve().parent.parent DATA_DIR = REPO_ROOT / "data" RAW_DIR = REPO_ROOT / "raw" SCHEMAS_DIR = REPO_ROOT / "schemas" # --------------------------------------------------------------------------- # Dataset definitions # --------------------------------------------------------------------------- DATASETS = { "historical_economic": { "publication_id": "55022", "title": "Historical Data and Economic Projections", "description": ( "Data on output, prices, labor market measures, interest rates, " "income, potential GDP, and its underlying inputs from 1949 through " "the most recent year completed." ), "source_url": "https://www.cbo.gov/publication/55022", "frequency": "quarterly", "file_format": "zip", # ZIP containing CSVs "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "55022-{year}-{month:02d}-Historical-Economic-Data.zip" ), "data_dir": DATA_DIR / "economic" / "historical_economic", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02"}, {"year": 2025, "month": 1, "label": "2025-01", "custom_url": "https://www.cbo.gov/system/files/2025-04/55022-2025-01-Historical-Economic-Data.zip"}, {"year": 2024, "month": 6, "label": "2024-06"}, {"year": 2024, "month": 2, "label": "2024-02"}, {"year": 2023, "month": 7, "label": "2023-07"}, {"year": 2023, "month": 2, "label": "2023-02"}, {"year": 2022, "month": 5, "label": "2022-05"}, ], }, "economic_projections": { "publication_id": "51135", "title": "Economic Projections", "description": ( "Projections of output, prices, labor market measures, interest " "rates, and income." ), "source_url": "https://www.cbo.gov/publication/51135", "frequency": "quarterly", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "51135-{year}-{month:02d}-Economic-Projections.xlsx" ), "data_dir": DATA_DIR / "economic" / "economic_projections", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02"}, {"year": 2025, "month": 9, "label": "2025-09"}, {"year": 2025, "month": 1, "label": "2025-01"}, {"year": 2024, "month": 6, "label": "2024-06"}, {"year": 2024, "month": 2, "label": "2024-02"}, ], }, "long_term_economic": { "publication_id": "57054", "title": "Long-Term Economic Projections", "description": ( "Extensions of 10-year economic projections for additional decades." ), "source_url": "https://www.cbo.gov/publication/57054", "frequency": "annual", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "57054-{year}-{month:02d}-LTBO-econ.xlsx" ), "data_dir": DATA_DIR / "economic" / "long_term_economic", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02"}, {"year": 2025, "month": 3, "label": "2025-03"}, {"year": 2024, "month": 3, "label": "2024-03"}, ], }, "potential_gdp": { "publication_id": "51137", "title": "Potential GDP and Underlying Inputs", "description": ( "Estimates of potential GDP and its underlying inputs. " "Post-2020, these are included in historical_economic (55022) " "and economic_projections (51135)." ), "source_url": "https://www.cbo.gov/publication/51137", "frequency": "quarterly", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "51137-{year}-{month:02d}-potentialgdp.xlsx" ), "data_dir": DATA_DIR / "economic" / "potential_gdp", "vintages": [ {"year": 2019, "month": 8, "label": "2019-08"}, {"year": 2019, "month": 1, "label": "2019-01", "custom_url": "https://www.cbo.gov/system/files/2019-03/51137-2019-01-potentialgdp.xlsx"}, ], }, "demographic": { "publication_id": "57059", "title": "Demographic Projections", "description": ( "Projections of the size of the population, immigration, " "emigration, mortality, and fertility." ), "source_url": "https://www.cbo.gov/publication/57059", "frequency": "annual", "file_format": "zip", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "57059-{year}-{month:02d}-Demographic-Projections.zip" ), "data_dir": DATA_DIR / "economic" / "demographic", "vintages": [ {"year": 2026, "month": 1, "label": "2026-01"}, {"year": 2025, "month": 9, "label": "2025-09"}, {"year": 2025, "month": 1, "label": "2025-01"}, ], }, # ----------------------------------------------------------------------- # Budget datasets (Phase 07+) # ----------------------------------------------------------------------- "historical_budget": { "publication_id": "51134", "title": "Historical Budget Data", "description": ( "Data on revenues, outlays, and the deficit or surplus " "from 1962 through the most recent year completed." ), "source_url": "https://www.cbo.gov/publication/51134", "frequency": "annual_fy", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "51134-{year}-{month:02d}-Historical-Budget-Data.xlsx" ), "data_dir": DATA_DIR / "budget" / "historical_budget", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02"}, {"year": 2025, "month": 1, "label": "2025-01"}, {"year": 2024, "month": 2, "label": "2024-02"}, ], }, "ten_year_budget": { "publication_id": "51118", "title": "10-Year Budget Projections", "description": ( "Projections of spending and revenues by category and " "of deficits and debt held by the public." ), "source_url": "https://www.cbo.gov/publication/51118", "frequency": "annual_fy", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "51118-{year}-{month:02d}-Budget-Projections.xlsx" ), "data_dir": DATA_DIR / "budget" / "ten_year_budget", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02"}, {"year": 2025, "month": 1, "label": "2025-01"}, {"year": 2024, "month": 6, "label": "2024-06"}, ], }, "long_term_budget": { "publication_id": "51119", "title": "Long-Term Budget Projections", "description": ( "Extensions of 10-year budget projections for additional " "decades." ), "source_url": "https://www.cbo.gov/publication/51119", "frequency": "annual_fy", "file_format": "xlsx", # URL pattern is inconsistent across vintages; use custom_urls "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "51119-{year}-{month:02d}-LTBO-budget.xlsx" ), "data_dir": DATA_DIR / "budget" / "long_term_budget", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02", "custom_url": "https://www.cbo.gov/system/files/2026-02/51119-2026-02-25-LTBO-Budget.xlsx"}, {"year": 2025, "month": 3, "label": "2025-03"}, ], }, # ----------------------------------------------------------------------- # Budget datasets (Phase 08) # ----------------------------------------------------------------------- "trust_fund": { "publication_id": "51136", "title": "10-Year Trust Fund Projections", "description": ( "Trust fund balances projected in CBO's baseline." ), "source_url": "https://www.cbo.gov/publication/51136", "frequency": "annual_fy", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "51136-{year}-{month:02d}-Trust-Fund.xlsx" ), "data_dir": DATA_DIR / "budget" / "trust_fund", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02"}, {"year": 2025, "month": 1, "label": "2025-01", "custom_url": "https://www.cbo.gov/system/files/2025-03/51136-2025-01-Trust-Fund.xlsx"}, {"year": 2024, "month": 6, "label": "2024-06"}, ], }, "revenue_detail": { "publication_id": "51138", "title": "Revenue Projections, by Category", "description": ( "Projections of revenues by category, estimates of the effects " "of extending tax provisions scheduled to expire within ten years, " "and estimates of selected policy options affecting revenues." ), "source_url": "https://www.cbo.gov/publication/51138", "frequency": "annual_fy", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "51138-{year}-{month:02d}-Revenue.xlsx" ), "data_dir": DATA_DIR / "budget" / "revenue_detail", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02"}, {"year": 2025, "month": 1, "label": "2025-01", "custom_url": "https://www.cbo.gov/system/files/2025-01/51138-2025-01-Revenue-Projections.xlsx"}, {"year": 2024, "month": 6, "label": "2024-06"}, ], }, "spending_detail": { "publication_id": "51142", "title": "Spending Projections, by Budget Account", "description": ( "Projections of budget authority and outlays at the budget " "account level, organized by Treasury Identification Number." ), "source_url": "https://www.cbo.gov/publication/51142", "frequency": "annual_fy", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "51142-{year}-{month:02d}-Spending-Projections.xlsx" ), "data_dir": DATA_DIR / "budget" / "spending_detail", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02"}, {"year": 2025, "month": 1, "label": "2025-01"}, {"year": 2024, "month": 6, "label": "2024-06"}, ], }, # ------------------------------------------------------------------ # Phase 09 – Analytical & Tax Parameters # ------------------------------------------------------------------ "automatic_stabilizers": { "publication_id": "51139", "title": "Estimates of Automatic Stabilizers", "description": ( "Deficit or surplus with and without CBO's estimate of automatic " "stabilizers, and related estimates of GDP and unemployment gaps." ), "source_url": "https://www.cbo.gov/publication/51139", "frequency": "annual_fy", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "51139-{year}-{month:02d}-AutomaticStabilizers.xlsx" ), "data_dir": DATA_DIR / "budget" / "automatic_stabilizers", "vintages": [ {"year": 2024, "month": 11, "label": "2024-11"}, {"year": 2023, "month": 6, "label": "2023-06"}, ], }, "tax_parameters": { "publication_id": "53724", "title": "Tax Parameters and Effective Marginal Tax Rates", "description": ( "Parameters used in CBO's microsimulation tax model and effective " "marginal tax rates on labor and capital." ), "source_url": "https://www.cbo.gov/publication/53724", "frequency": "annual_cy", "file_format": "xlsx", "url_template": ( "https://www.cbo.gov/system/files/{year}-{month:02d}/" "53724-{year}-{month:02d}-Tax-Parameters.xlsx" ), "data_dir": DATA_DIR / "budget" / "tax_parameters", "vintages": [ {"year": 2026, "month": 2, "label": "2026-02"}, {"year": 2025, "month": 1, "label": "2025-01"}, {"year": 2024, "month": 6, "label": "2024-06"}, ], }, } def get_download_url(dataset_key: str, vintage_label: str) -> str: """Build the download URL for a specific dataset vintage.""" ds = DATASETS[dataset_key] vintage = next(v for v in ds["vintages"] if v["label"] == vintage_label) # Some vintages have non-standard URLs if "custom_url" in vintage: return vintage["custom_url"] return ds["url_template"].format(year=vintage["year"], month=vintage["month"]) def get_raw_path(dataset_key: str, vintage_label: str) -> Path: """Return the local cache path for a downloaded raw file.""" ds = DATASETS[dataset_key] ext = ds["file_format"] return RAW_DIR / dataset_key / f"{dataset_key}_{vintage_label}.{ext}" def get_output_path(dataset_key: str, vintage_label: str, prefix: str = "quarterly") -> Path: """Return the canonical output CSV path for a dataset vintage.""" ds = DATASETS[dataset_key] return ds["data_dir"] / f"{prefix}_{vintage_label}.csv"