pipeline_api.json

{
  "aca_2025_override": {
    "docstring": "Set 2025 ACA take-up to match APTC enrollment targets.",
    "id": "aca_2025_override",
    "kind": "function",
    "line": 404,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.enhanced_cps.create_aca_2025_takeup_override"
      ],
      "artifacts_in": [
        "extended_cps_2024"
      ],
      "artifacts_out": [
        "aca_2025_takeup"
      ],
      "description": "Adds synthetic 2025 ACA take-up assignments until calibrated person-level APTC enrollment reaches the target.",
      "id": "aca_2025_override",
      "label": "ACA 2025 Take-Up Override",
      "node_type": "process",
      "pathways": [
        "data_build"
      ],
      "pydoc": true,
      "source_file": "policyengine_us_data/datasets/cps/enhanced_cps.py",
      "stability": "moving",
      "status": "transitional"
    },
    "object_path": "policyengine_us_data.datasets.cps.enhanced_cps.create_aca_2025_takeup_override",
    "signature": "def create_aca_2025_takeup_override(base_takeup: np.ndarray, person_enrolled_if_takeup: np.ndarray, person_weights: np.ndarray, person_tax_unit_ids: np.ndarray, tax_unit_ids: np.ndarray, target_people: float = ACA_POST_CALIBRATION_PERSON_TARGETS[2025], person_state_codes: np.ndarray | None = None, target_people_by_state: dict[str, float] | None = None, tax_unit_aca_ptc: np.ndarray | None = None, tax_unit_weights: np.ndarray | None = None, target_spending_by_state: dict[str, float] | None = None) -> np.ndarray",
    "source_file": "policyengine_us_data/datasets/cps/enhanced_cps.py"
  },
  "acs_qrf": {
    "docstring": "Impute rent and real_estate_taxes from ACS with state.\n\nArgs:\n    data: CPS data dict.\n    state_fips: State FIPS per household.\n    time_period: Tax year.\n    dataset_path: Path to CPS h5 for Microsimulation.\n\nReturns:\n    Updated data dict.",
    "id": "acs_qrf",
    "kind": "function",
    "line": 508,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.source_impute._impute_acs"
      ],
      "description": "Impute rent and real estate tax variables from ACS donor data.",
      "id": "acs_qrf",
      "label": "ACS QRF Imputation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/source_impute.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_source_impute.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.source_impute._impute_acs",
    "signature": "def _impute_acs(data: Dict[str, Dict[int, np.ndarray]], state_fips: np.ndarray, time_period: int, dataset_path: Optional[str] = None) -> Dict[str, Dict[int, np.ndarray]]",
    "source_file": "policyengine_us_data/calibration/source_impute.py"
  },
  "add_auto_loan": {
    "docstring": "\"Add auto loan balance, interest and net_worth variable.",
    "id": "add_auto_loan",
    "kind": "function",
    "line": 2938,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_auto_loan_interest_and_net_worth"
      ],
      "description": "Impute auto loan balance, auto loan interest, and net worth from SCF donor data.",
      "id": "add_auto_loan",
      "label": "Auto Loan And Net Worth Imputation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "legacy",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_auto_loan_interest_and_net_worth",
    "signature": "def add_auto_loan_interest_and_net_worth(self, cps: h5py.File) -> None",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_household_variables": {
    "docstring": "Populate household-level geography variables used by PolicyEngine US.\n\nArgs:\n    cps: Output CPS H5 group receiving derived household variables.\n    household: Raw CPS household table.",
    "id": "add_household_variables",
    "kind": "function",
    "line": 1519,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_household_variables"
      ],
      "description": "Populate household geography variables including state, county, and NYC flag.",
      "id": "add_household_variables",
      "label": "Add Household Variables",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_household_variables",
    "signature": "def add_household_variables(cps: h5py.File, household: DataFrame) -> None",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_id_variables": {
    "docstring": "Add basic ID and weight variables.\n\nArgs:\n    cps (h5py.File): The CPS dataset file.\n    person (DataFrame): The person table of the ASEC.\n    tax_unit (DataFrame): The tax unit table created from the person table\n        of the ASEC.\n    family (DataFrame): The family table of the ASEC.\n    spm_unit (DataFrame): The SPM unit table created from the person table\n        of the ASEC.\n    household (DataFrame): The household table of the ASEC.",
    "id": "add_id_variables",
    "kind": "function",
    "line": 988,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_id_variables"
      ],
      "description": "Create person, household, tax-unit, SPM-unit, family, and marital-unit IDs.",
      "id": "add_id_variables",
      "label": "Add ID Variables",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/datasets/test_cps_identification.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_id_variables",
    "signature": "def add_id_variables(cps: h5py.File, person: DataFrame, tax_unit: DataFrame, family: DataFrame, spm_unit: DataFrame, household: DataFrame) -> None",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_org_inputs": {
    "docstring": "Impute ORG-derived wage and union inputs onto CPS persons.",
    "id": "add_org_inputs",
    "kind": "function",
    "line": 2822,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_org_labor_market_inputs"
      ],
      "description": "Impute hourly wage, hourly-pay status, and union coverage from CPS ORG donors.",
      "id": "add_org_inputs",
      "label": "ORG Labor-Market Inputs",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/datasets/test_org.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_org_labor_market_inputs",
    "signature": "def add_org_labor_market_inputs(cps: h5py.File) -> None",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_personal_income_variables": {
    "docstring": "Add income variables.\n\nArgs:\n    cps (h5py.File): The CPS dataset file.\n    person (DataFrame): The CPS person table.\n    year (int): The CPS year",
    "id": "add_personal_income_variables",
    "kind": "function",
    "line": 1194,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_personal_income_variables"
      ],
      "description": "Populate CPS income, transfer, retirement, and QBI-related personal inputs.",
      "id": "add_personal_income_variables",
      "label": "Add Income Variables",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_personal_income_variables",
    "signature": "def add_personal_income_variables(cps: h5py.File, person: DataFrame, year: int)",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_personal_variables": {
    "docstring": "Add personal demographic variables.\n\nArgs:\n    cps (h5py.File): The CPS dataset file.\n    person (DataFrame): The CPS person table.",
    "id": "add_personal_variables",
    "kind": "function",
    "line": 1050,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_personal_variables"
      ],
      "description": "Populate CPS personal demographics and occupation-derived inputs.",
      "id": "add_personal_variables",
      "label": "Add Personal Variables",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_personal_variables",
    "signature": "def add_personal_variables(cps: h5py.File, person: DataFrame) -> None",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_previous_year_income": {
    "docstring": "",
    "id": "add_previous_year_income",
    "kind": "function",
    "line": 1561,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_previous_year_income"
      ],
      "description": "Link CPS records across adjacent years and populate prior-year income inputs.",
      "id": "add_previous_year_income",
      "label": "Previous-Year Income",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_previous_year_income",
    "signature": "def add_previous_year_income(self, cps: h5py.File) -> None",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_rent": {
    "docstring": "",
    "id": "add_rent",
    "kind": "function",
    "line": 362,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_rent"
      ],
      "description": "Impute rent and real estate taxes using ACS donor data.",
      "id": "add_rent",
      "label": "Rent Imputation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "legacy",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_rent",
    "signature": "def add_rent(self, cps: h5py.File, person: DataFrame, household: DataFrame)",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_spm_variables": {
    "docstring": "",
    "id": "add_spm_variables",
    "kind": "function",
    "line": 1480,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_spm_variables"
      ],
      "description": "Populate CPS supplemental poverty measure variables.",
      "id": "add_spm_variables",
      "label": "Add SPM Variables",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_spm_variables",
    "signature": "def add_spm_variables(self, cps: h5py.File, spm_unit: DataFrame) -> None",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_ssn_card_type": {
    "docstring": "Assign SSN card type using PRCITSHP, employment status, and ASEC-UA conditions.\nCodes:\n- 0: \"NONE\" - Likely undocumented immigrants\n- 1: \"CITIZEN\" - US citizens (born or naturalized)\n- 2: \"NON_CITIZEN_VALID_EAD\" - Non-citizens with work/study authorization\n- 3: \"OTHER_NON_CITIZEN\" - Non-citizens with indicators of legal status",
    "id": "add_ssn_card_type",
    "kind": "function",
    "line": 1667,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_ssn_card_type"
      ],
      "description": "Classify SSN card type and immigration-related CPS inputs from ASEC conditions.",
      "id": "add_ssn_card_type",
      "label": "Add SSN Card Type",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_ssn_card_type",
    "signature": "def add_ssn_card_type(cps: h5py.File, person: pd.DataFrame, spm_unit: pd.DataFrame, time_period: int, undocumented_target: float = 13000000.0, undocumented_workers_target: float = 8300000.0, undocumented_students_target: float = 0.21 * 1900000.0) -> np.ndarray",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_takeup": {
    "docstring": "",
    "id": "add_takeup",
    "kind": "function",
    "line": 510,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_takeup"
      ],
      "description": "Apply stochastic takeup and reported-anchor alignment for benefit programs.",
      "id": "add_takeup",
      "label": "Benefit Takeup",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_takeup",
    "signature": "def add_takeup(self)",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "add_tips": {
    "docstring": "",
    "id": "add_tips",
    "kind": "function",
    "line": 2566,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.add_tips"
      ],
      "description": "Impute tip income and household asset inputs from SIPP donor data.",
      "id": "add_tips",
      "label": "Tips And Asset Imputation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "moving",
      "status": "legacy",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.add_tips",
    "signature": "def add_tips(self, cps: h5py.File)",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "atomic_promote": {
    "docstring": "",
    "id": "atomic_promote",
    "kind": "function",
    "line": 141,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.promote_local_h5s.promote"
      ],
      "artifacts_out": [
        "production H5 release",
        "release manifest"
      ],
      "description": "Promote staged H5 files to production storage and publish release manifests.",
      "id": "atomic_promote",
      "label": "Atomic Promote Local H5 Files",
      "node_type": "entrypoint",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/promote_local_h5s.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_promote_local_h5s.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.promote_local_h5s.promote",
    "signature": "def promote(files: list, rel_paths: list, version: str, run_id: str = '')",
    "source_file": "policyengine_us_data/calibration/promote_local_h5s.py"
  },
  "build_areas_worker": {
    "docstring": "Worker function that builds a subset of H5 files.\nUses subprocess to avoid import conflicts with Modal's environment.",
    "id": "build_areas_worker",
    "kind": "function",
    "line": 912,
    "metadata": {
      "api_refs": [
        "modal_app.local_area.build_areas_worker"
      ],
      "artifacts_out": [
        "one or more H5 files"
      ],
      "description": "Modal worker entrypoint for state, district, city, or typed local H5 requests.",
      "id": "build_areas_worker",
      "label": "Build Areas Worker",
      "node_type": "entrypoint",
      "pathways": [
        "local_h5"
      ],
      "source_file": "modal_app/local_area.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_local_area.py",
        "uv run pytest tests/integration/build_outputs/h5_worker_runtime/test_worker_script_tiny_fixture.py"
      ]
    },
    "object_path": "modal_app.local_area.build_areas_worker",
    "signature": "def build_areas_worker(branch: str, run_id: str, scope: str, work_items: List[Dict] | None = None, calibration_inputs: WorkerCalibrationInputs | Mapping[str, object] | None = None, validate: bool = True, scope_fingerprint: str | None = None, request_payloads: List[Dict] | None = None) -> Dict",
    "source_file": "modal_app/local_area.py"
  },
  "build_cities": {
    "docstring": "Build city H5 files with checkpointing, optionally uploading.",
    "id": "build_cities",
    "kind": "function",
    "line": 627,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.publish_local_area.build_cities"
      ],
      "artifacts_out": [
        "cities/*.h5"
      ],
      "description": "Build supported city H5 files with county probability filtering.",
      "id": "build_cities",
      "label": "Build City H5 Files",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/publish_local_area.py",
      "stability": "moving",
      "status": "current"
    },
    "object_path": "policyengine_us_data.calibration.publish_local_area.build_cities",
    "signature": "def build_cities(weights_path: Path, dataset_path: Path, geography, output_dir: Path, completed_cities: set, hf_batch_size: int = 10, takeup_filter: List[str] = None, upload: bool = False)",
    "source_file": "policyengine_us_data/calibration/publish_local_area.py"
  },
  "build_datasets": {
    "docstring": "Build all datasets with preemption-resilient checkpointing.\n\nArgs:\n    upload: Whether to upload completed datasets.\n    branch: Git branch to build from.\n    sequential: Use sequential (non-parallel) execution.\n    clear_checkpoints: Clear existing checkpoints before starting.\n    skip_tests: Skip running the test suite (useful for calibration runs).\n    skip_enhanced_cps: Skip enhanced_cps.py and small_enhanced_cps.py\n        (useful for calibration runs that only need source_imputed H5).\n    skip_stage_5: Skip source-imputed CPS and small enhanced CPS after\n        enhanced_cps_2024.h5 is built.\n    stage_only: Upload to HF staging only, without promoting a release.\n    version: policyengine-us-data package version used for staging and\n        dataset-build contracts.",
    "id": "build_datasets",
    "kind": "function",
    "line": 643,
    "metadata": {
      "api_refs": [
        "modal_app.data_build.build_datasets"
      ],
      "artifacts_out": [
        "dataset_build_output.json",
        "dataset_inventory.json",
        "source_dataset_schema_summary.json",
        "target_database_schema_summary.json",
        "source_imputed_stratified_extended_cps_2024.h5",
        "source_imputed_stratified_extended_cps.h5",
        "policy_data.db"
      ],
      "description": "Build base datasets, source-imputed artifacts, and optional uploads inside the Modal runtime.",
      "id": "build_datasets",
      "label": "Build Datasets On Modal",
      "node_type": "entrypoint",
      "pathways": [
        "data_build",
        "orchestration"
      ],
      "source_file": "modal_app/data_build.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_data_build.py"
      ]
    },
    "object_path": "modal_app.data_build.build_datasets",
    "signature": "def build_datasets(upload: bool = False, branch: str = 'main', sequential: bool = False, clear_checkpoints: bool = False, skip_tests: bool = False, skip_enhanced_cps: bool = False, skip_stage_5: bool = False, stage_only: bool = False, run_id: str = '', version: str = DATA_PACKAGE_VERSION)",
    "source_file": "modal_app/data_build.py"
  },
  "build_districts": {
    "docstring": "Build district H5 files with checkpointing, optionally uploading.",
    "id": "build_districts",
    "kind": "function",
    "line": 540,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.publish_local_area.build_districts"
      ],
      "artifacts_out": [
        "districts/*.h5"
      ],
      "description": "Build congressional-district H5 files from calibrated weights and exact geography.",
      "id": "build_districts",
      "label": "Build District H5 Files",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/publish_local_area.py",
      "stability": "moving",
      "status": "current"
    },
    "object_path": "policyengine_us_data.calibration.publish_local_area.build_districts",
    "signature": "def build_districts(weights_path: Path, dataset_path: Path, geography, output_dir: Path, completed_districts: set, hf_batch_size: int = 10, takeup_filter: List[str] = None, upload: bool = False)",
    "source_file": "policyengine_us_data/calibration/publish_local_area.py"
  },
  "build_h5": {
    "docstring": "Build an H5 file by cloning records for each nonzero weight.\n\nArgs:\n    weights: Clone-level weight vector, shape (n_clones_total * n_hh,).\n    geography: GeographyAssignment from assign_random_geography.\n    dataset_path: Path to base dataset H5 file.\n    output_path: Where to write the output H5 file.\n    cd_subset: If provided, only include clones for these CDs.\n    county_fips_filter: If provided, zero out weights for clones\n        whose county FIPS is not in this set.\n    takeup_filter: List of takeup vars to apply.\n\nReturns:\n    Path to the output H5 file.",
    "id": "build_h5",
    "kind": "function",
    "line": 328,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.publish_local_area.build_h5"
      ],
      "artifacts_in": [
        "calibration_weights.npy",
        "source_imputed_stratified_extended_cps*.h5"
      ],
      "artifacts_out": [
        "states/*.h5",
        "districts/*.h5",
        "cities/*.h5",
        "US.h5"
      ],
      "description": "Expand calibrated clone weights into local-area H5 datasets with geography and takeup updates.",
      "details": "This is the main bundled H5 construction routine and remains a critical transitional waypoint.",
      "id": "build_h5",
      "label": "Build Local Area H5",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/publish_local_area.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_publish_local_area.py",
        "uv run pytest tests/integration/test_tiny_h5_pipeline.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.publish_local_area.build_h5",
    "signature": "def build_h5(weights: np.ndarray, geography, dataset_path: Path, output_path: Path, cd_subset: List[str] = None, county_fips_filter: set = None, takeup_filter: List[str] = None) -> Path",
    "source_file": "policyengine_us_data/calibration/publish_local_area.py"
  },
  "build_matrix": {
    "docstring": "Build sparse calibration matrix.\n\nTwo-phase build: (1) simulate each clone and save\nCOO entries to disk, (2) assemble CSR from caches.\n\nArgs:\n    geography: GeographyAssignment with state_fips,\n        cd_geoid, block_geoid arrays and n_records,\n        n_clones attributes.\n    sim: Microsimulation for parameters and entity\n        relationships.\n    target_filter: Dict for target_overview filtering.\n    hierarchical_domains: Domain names for\n        hierarchical uprating + CD reconciliation.\n    cache_dir: Directory for per-clone COO caches.\n        If None, COO data held in memory.\n    sim_modifier: Optional callback(sim, clone_idx)\n        called per clone after state_fips is set but\n        before cache clearing. Use for takeup\n        re-randomization.\n    rerandomize_takeup: If True, use geo-salted\n        entity-level takeup draws instead of base h5\n        takeup values for takeup-affected targets.\n    county_level: If True (default), iterate counties\n        within each state during precomputation. If\n        False, compute once per state and alias to all\n        counties (faster for county-invariant vars).\n\nReturns:\n    (targets_df, X_sparse, target_names)",
    "id": "build_matrix",
    "kind": "function",
    "line": 2567,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_matrix_builder.UnifiedMatrixBuilder.build_matrix"
      ],
      "artifacts_out": [
        "X_sparse",
        "targets_df",
        "target_names"
      ],
      "description": "Build the in-memory sparse matrix for calibration targets and clone households.",
      "id": "build_matrix",
      "label": "Build Calibration Matrix",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_unified_matrix_builder.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_matrix_builder.UnifiedMatrixBuilder.build_matrix",
    "signature": "def build_matrix(self, geography, sim, target_filter: Optional[dict] = None, hierarchical_domains: Optional[List[str]] = None, cache_dir: Optional[str] = None, sim_modifier = None, rerandomize_takeup: bool = True, county_level: bool = True, workers: int = 1) -> Tuple[pd.DataFrame, sparse.csr_matrix, List[str]]",
    "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py"
  },
  "build_matrix_chunked": {
    "docstring": "Build a sparse matrix by materializing mixed-geography chunks.\n\nThin facade: target querying, uprating, constraint extraction,\nand manifest handling live here; chunking, per-chunk execution,\nand streaming final assembly live in\n:class:`ChunkedMatrixAssembler`.",
    "id": "build_matrix_chunked",
    "kind": "function",
    "line": 3332,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_matrix_builder.UnifiedMatrixBuilder.build_matrix_chunked"
      ],
      "artifacts_out": [
        "chunked COO shards",
        "X_sparse"
      ],
      "description": "Stream matrix construction through clone-household chunks with resumable shard caches.",
      "id": "build_matrix_chunked",
      "label": "Build Calibration Matrix In Chunks",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py",
      "stability": "experimental",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/integration/test_chunked_matrix_builder.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_matrix_builder.UnifiedMatrixBuilder.build_matrix_chunked",
    "signature": "def build_matrix_chunked(self, geography, sim, target_filter: Optional[dict] = None, hierarchical_domains: Optional[List[str]] = None, chunk_size: int = 25000, chunk_dir: Optional[str] = None, keep_chunks: bool = False, resume_chunks: bool = False, rerandomize_takeup: bool = True, parallel: bool = False, num_matrix_workers: int = 50, run_id: str = '') -> Tuple[pd.DataFrame, sparse.csr_matrix, List[str]]",
    "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py"
  },
  "build_publishing_input_bundle": {
    "docstring": "Build the normalized coordinator input bundle for one publish scope.",
    "id": "build_publishing_input_bundle",
    "kind": "function",
    "line": 411,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.fingerprinting.PublishingInputBundle",
        "modal_app.local_area._build_publishing_input_bundle"
      ],
      "description": "Assemble artifact paths and run metadata for scope fingerprinting.",
      "id": "build_publishing_input_bundle",
      "label": "Build Publishing Input Bundle",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "modal_app/local_area.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_local_area.py"
      ]
    },
    "object_path": "modal_app.local_area._build_publishing_input_bundle",
    "signature": "def _build_publishing_input_bundle(*, weights_path: Path, dataset_path: Path, db_path: Path | None, geography_path: Path | None, calibration_package_path: Path | None, run_config_path: Path | None, run_id: str, version: str, n_clones: int | None, seed: int, legacy_blocks_path: Path | None = None) -> PublishingInputBundle",
    "source_file": "modal_app/local_area.py"
  },
  "build_states": {
    "docstring": "Build state H5 files with checkpointing, optionally uploading.",
    "id": "build_states",
    "kind": "function",
    "line": 454,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.publish_local_area.build_states"
      ],
      "artifacts_out": [
        "states/*.h5"
      ],
      "description": "Build state-level H5 files from calibrated weights and exact geography.",
      "id": "build_states",
      "label": "Build State H5 Files",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/publish_local_area.py",
      "stability": "moving",
      "status": "current"
    },
    "object_path": "policyengine_us_data.calibration.publish_local_area.build_states",
    "signature": "def build_states(weights_path: Path, dataset_path: Path, geography, output_dir: Path, completed_states: set, hf_batch_size: int = 10, takeup_filter: List[str] = None, upload: bool = False, state_filter: str = None)",
    "source_file": "policyengine_us_data/calibration/publish_local_area.py"
  },
  "build_worker_bootstrap": {
    "docstring": "Persist optional worker bootstrap artifacts for one local H5 scope.",
    "id": "build_worker_bootstrap",
    "kind": "function",
    "line": 504,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.bootstrap.WorkerBootstrapBuilder",
        "modal_app.local_area._build_worker_bootstrap"
      ],
      "artifacts_out": [
        "bootstrap/{scope}/worker_bootstrap.json",
        "bootstrap/{scope}/entity_graph.npz"
      ],
      "description": "Persist deterministic local H5 worker setup artifacts for one scope.",
      "id": "build_worker_bootstrap",
      "label": "Build Worker Bootstrap",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "modal_app/local_area.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_local_area.py"
      ]
    },
    "object_path": "modal_app.local_area._build_worker_bootstrap",
    "signature": "def _build_worker_bootstrap(*, inputs: PublishingInputBundle, scope: str, artifacts_dir: Path, scope_fingerprint: str | None = None)",
    "source_file": "modal_app/local_area.py"
  },
  "calibration_diagnostics": {
    "docstring": "",
    "id": "calibration_diagnostics",
    "kind": "function",
    "line": 1245,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_calibration.compute_diagnostics"
      ],
      "artifacts_out": [
        "unified_diagnostics.csv"
      ],
      "description": "Compare fitted weighted sums to calibration targets and summarize error.",
      "id": "calibration_diagnostics",
      "label": "Compute Calibration Diagnostics",
      "node_type": "library",
      "pathways": [
        "weight_fit"
      ],
      "source_file": "policyengine_us_data/calibration/unified_calibration.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_unified_calibration.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_calibration.compute_diagnostics",
    "signature": "def compute_diagnostics(weights: np.ndarray, X_sparse, targets_df, target_names: list) -> 'pd.DataFrame'",
    "source_file": "policyengine_us_data/calibration/unified_calibration.py"
  },
  "calibration_geography_loader": {
    "docstring": "Resolve, load, and checksum exact geography artifacts.\n\nThe loader hides compatibility ordering across current saved geography\nbundles, calibration packages, and legacy block arrays. Public callers can\nuse `resolve_source` to inspect what would be loaded or `load` to return the\nnormalized `GeographyAssignment`.",
    "id": "calibration_geography_loader",
    "kind": "class",
    "line": 148,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.geography_loader.CalibrationGeographyLoader"
      ],
      "description": "Resolve and load saved, package-backed, or legacy calibration geography artifacts.",
      "id": "calibration_geography_loader",
      "label": "CalibrationGeographyLoader",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/geography_loader.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_geography_loader.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.geography_loader.CalibrationGeographyLoader",
    "signature": "class CalibrationGeographyLoader",
    "source_file": "policyengine_us_data/build_outputs/geography_loader.py"
  },
  "clone_assembly": {
    "docstring": "Standalone clone-value assembly (no ``self``).\n\nIdentical logic to\n``UnifiedMatrixBuilder._assemble_clone_values`` but usable\nfrom a worker process.",
    "id": "clone_assembly",
    "kind": "function",
    "line": 615,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_matrix_builder._assemble_clone_values_standalone"
      ],
      "artifacts_out": [
        "sparse calibration COO/CSR shards"
      ],
      "description": "Assemble target values for clone-household columns across assigned geographies.",
      "id": "clone_assembly",
      "label": "Clone Value Assembly",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_unified_matrix_builder.py",
        "uv run pytest tests/integration/test_chunked_matrix_builder.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_matrix_builder._assemble_clone_values_standalone",
    "signature": "def _assemble_clone_values_standalone(state_values: dict, clone_states: np.ndarray, person_hh_indices: np.ndarray, target_vars: set, constraint_vars: set, reform_vars: set = None, county_values: dict = None, clone_counties: np.ndarray = None, county_dependent_vars: set = None, allow_state_fallback_for_county_dependent_targets: bool = False) -> tuple",
    "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py"
  },
  "clone_features": {
    "docstring": "Replace clone-half person-level feature variables with donor matches.",
    "id": "clone_features",
    "kind": "function",
    "line": 412,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.extended_cps._splice_clone_feature_predictions"
      ],
      "artifacts_in": [
        "qrf_pass2",
        "record_double"
      ],
      "artifacts_out": [
        "clone_feature_splice"
      ],
      "description": "Replaces clone-half CPS feature variables with donor-matched predictions so doubled records retain plausible demographics and occupation labels.",
      "id": "clone_features",
      "label": "Splice Clone Features",
      "node_type": "process",
      "pathways": [
        "data_build"
      ],
      "pydoc": true,
      "source_file": "policyengine_us_data/datasets/cps/extended_cps.py",
      "stability": "moving",
      "status": "transitional"
    },
    "object_path": "policyengine_us_data.datasets.cps.extended_cps._splice_clone_feature_predictions",
    "signature": "def _splice_clone_feature_predictions(data: dict, predictions: pd.DataFrame, time_period: int) -> dict",
    "source_file": "policyengine_us_data/datasets/cps/extended_cps.py"
  },
  "clone_weight_matrix": {
    "docstring": "Structured view of clone-level household weights.\n\nThe canonical in-memory representation remains the flat vector of length\n``n_records * n_clones``. Matrix views are derived on demand as\n``(n_clones, n_records)`` arrays.\n\nAttributes:\n    values: Flat clone-level weight vector.\n    n_records: Number of base records represented by each clone.\n    n_clones: Number of clone copies represented in the flat vector.",
    "id": "clone_weight_matrix",
    "kind": "class",
    "line": 36,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.weights.CloneWeightMatrix"
      ],
      "artifacts_in": [
        "calibration_weights.npy",
        "national_calibration_weights.npy"
      ],
      "description": "Explicit shape contract for flat clone-level calibration weights.",
      "id": "clone_weight_matrix",
      "label": "CloneWeightMatrix",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/weights.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_weights.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.weights.CloneWeightMatrix",
    "signature": "class CloneWeightMatrix",
    "source_file": "policyengine_us_data/build_outputs/weights.py"
  },
  "computed_export_contract": {
    "docstring": "Assert that final exported variables are leaf inputs.",
    "id": "computed_export_contract",
    "kind": "function",
    "line": 1585,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.extended_cps.ExtendedCPS._assert_no_computed_variables_exported"
      ],
      "artifacts_in": [
        "extended_cps_stage2"
      ],
      "artifacts_out": [
        "validated_extended_cps"
      ],
      "description": "Fails the build if the final export still contains variables computed by policyengine-us formulas, adds, or subtracts.",
      "id": "computed_export_contract",
      "label": "Validate Leaf-Input Export",
      "node_type": "process",
      "pathways": [
        "data_build"
      ],
      "pydoc": true,
      "source_file": "policyengine_us_data/datasets/cps/extended_cps.py",
      "stability": "moving",
      "status": "transitional"
    },
    "object_path": "policyengine_us_data.datasets.cps.extended_cps.ExtendedCPS._assert_no_computed_variables_exported",
    "signature": "def _assert_no_computed_variables_exported(cls, data, time_period)",
    "source_file": "policyengine_us_data/datasets/cps/extended_cps.py"
  },
  "coordinate_publish": {
    "docstring": "Coordinate the full publishing workflow.",
    "id": "coordinate_publish",
    "kind": "function",
    "line": 1275,
    "metadata": {
      "api_refs": [
        "modal_app.local_area.coordinate_publish"
      ],
      "artifacts_in": [
        "calibration_weights.npy",
        "source_imputed_stratified_extended_cps*.h5"
      ],
      "artifacts_out": [
        "staged local-area H5 files"
      ],
      "description": "Coordinate local H5 partitioning, worker phases, validation, staging, and promotion.",
      "id": "coordinate_publish",
      "label": "Coordinate Local H5 Publish",
      "node_type": "entrypoint",
      "pathways": [
        "local_h5",
        "orchestration"
      ],
      "source_file": "modal_app/local_area.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_local_area.py"
      ]
    },
    "object_path": "modal_app.local_area.coordinate_publish",
    "signature": "def coordinate_publish(branch: str = 'main', num_workers: int = 50, skip_upload: bool = False, n_clones: int = 430, validate: bool = True, run_id: str = '', candidate_version: str = '', expected_fingerprint: str = '', work_items_override: List[Dict] | None = None) -> Dict",
    "source_file": "modal_app/local_area.py"
  },
  "coordinate_work_partition": {
    "docstring": "Compatibility wrapper over the extracted pure partitioning seam.",
    "id": "coordinate_work_partition",
    "kind": "function",
    "line": 686,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.partitioning.partition_weighted_work_items",
        "modal_app.local_area.partition_work"
      ],
      "description": "Compatibility wrapper for local H5 weighted work partitioning.",
      "id": "coordinate_work_partition",
      "label": "Coordinate Work Partition",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "modal_app/local_area.py",
      "stability": "moving",
      "status": "legacy",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_local_area.py"
      ]
    },
    "object_path": "modal_app.local_area.partition_work",
    "signature": "def partition_work(work_items: List[Dict], num_workers: int, completed: set) -> List[List[Dict]]",
    "source_file": "modal_app/local_area.py"
  },
  "cps_only": {
    "docstring": "Second-stage QRF: train on CPS, predict for PUF clones.\n\nFor the PUF clone half of the extended CPS we need plausible values\nof CPS-only variables (retirement distributions, transfers, hours,\nSPM components, etc.) that are consistent with the clone's\nPUF-imputed income -- not just naively copied from the CPS donor.\n\nWe train a QRF on CPS person-level data where:\n  * predictors = demographics + key income variables\n  * outputs    = CPS-only variables listed in\n                 ``CPS_ONLY_IMPUTED_VARIABLES``\n\nFor PUF clone prediction we use the PUF-imputed income values\nfrom the second half of ``data`` (the clone half, which already\nhas PUF-imputed income from stage 1).\n\nUses ``fit_predict()`` with ``max_train_samples`` instead of\nmanual sampling + separate fit/predict.\n\nArgs:\n    data: Extended dataset dict after ``puf_clone_dataset()`` --\n        already doubled, with PUF-imputed income in the second half.\n    time_period: Tax year.\n    dataset_path: Path to the CPS h5 file for Microsimulation.\n\nReturns:\n    DataFrame with one column per CPS-only variable, containing\n    predicted values for the PUF clone half (person-level).",
    "id": "cps_only",
    "kind": "function",
    "line": 451,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.extended_cps._impute_cps_only_variables"
      ],
      "artifacts_in": [
        "record_double",
        "preprocess_cps"
      ],
      "artifacts_out": [
        "cps_only_predictions"
      ],
      "description": "Runs the second-stage CPS-only QRF imputation for PUF clone records inside the extended CPS build.",
      "id": "cps_only",
      "label": "Impute CPS-Only Variables",
      "node_type": "process",
      "pathways": [
        "data_build"
      ],
      "pydoc": true,
      "source_file": "policyengine_us_data/datasets/cps/extended_cps.py",
      "stability": "moving",
      "status": "transitional"
    },
    "object_path": "policyengine_us_data.datasets.cps.extended_cps._impute_cps_only_variables",
    "signature": "def _impute_cps_only_variables(data: dict, time_period: int, dataset_path: str) -> pd.DataFrame",
    "source_file": "policyengine_us_data/datasets/cps/extended_cps.py"
  },
  "cps_puf_build_phase": {
    "docstring": "Build CPS before PUF because PUF pension imputation loads CPS_2024.",
    "id": "cps_puf_build_phase",
    "kind": "function",
    "line": 500,
    "metadata": {
      "api_refs": [
        "modal_app.data_build.run_cps_then_puf_phase"
      ],
      "description": "Build CPS before PUF to avoid shared raw-cache and fixture races.",
      "id": "cps_puf_build_phase",
      "label": "CPS Then PUF Build Phase",
      "node_type": "entrypoint",
      "pathways": [
        "data_build"
      ],
      "source_file": "modal_app/data_build.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_data_build.py"
      ]
    },
    "object_path": "modal_app.data_build.run_cps_then_puf_phase",
    "signature": "def run_cps_then_puf_phase(branch: str, volume: modal.Volume, *, env: dict, log_file: IO = None, checkpoint_stats: CheckpointStats | None = None, coordinator: Stage1Coordinator | None = None) -> None",
    "source_file": "modal_app/data_build.py"
  },
  "create_stratified": {
    "docstring": "Create a stratified sample of CPS data preserving high-income households\nwhile maintaining low-income diversity for poverty analysis.\n\nArgs:\n    target_households: Target number of households in output (approximate)\n    oversample_poor: If True, boost sampling rate for bottom 25% by 1.5x\n    seed: Random seed for reproducibility (default: None for random)\n    base_dataset: Path to source h5 file (default: extended_cps_2024.h5)\n    output_path: Where to save the stratified h5 file\n    high_agi_brackets: List of (lo, hi, cap) tuples defining per-bracket\n        caps for the high-AGI tail. Defaults to HIGH_AGI_BRACKETS.",
    "id": "create_stratified",
    "kind": "function",
    "line": 85,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.create_stratified_cps.create_stratified_cps_dataset"
      ],
      "artifacts_in": [
        "extended_cps_2024.h5"
      ],
      "artifacts_out": [
        "stratified_extended_cps_2024.h5"
      ],
      "description": "Create a calibration-sized stratified CPS sample while preserving high-AGI tail records.",
      "id": "create_stratified",
      "label": "Create Stratified CPS Dataset",
      "node_type": "entrypoint",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/create_stratified_cps.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_create_stratified_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.create_stratified_cps.create_stratified_cps_dataset",
    "signature": "def create_stratified_cps_dataset(target_households = 30000, oversample_poor = False, seed = None, base_dataset = None, output_path = None, high_agi_brackets = None)",
    "source_file": "policyengine_us_data/calibration/create_stratified_cps.py"
  },
  "downsample": {
    "docstring": "Subsample the loaded CPS dataset and preserve downsampled arrays.\n\nArgs:\n    frac: Fraction of records to retain.",
    "id": "downsample",
    "kind": "function",
    "line": 329,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.cps.CPS.downsample"
      ],
      "description": "Subsample CPS arrays for released CPS vintages while full variants skip this step.",
      "id": "downsample",
      "label": "Downsample CPS",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/cps/cps.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest validation/stage_1/test_cps.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.cps.cps.CPS.downsample",
    "signature": "def downsample(self, frac: float) -> None",
    "source_file": "policyengine_us_data/datasets/cps/cps.py"
  },
  "fit_model": {
    "docstring": "Fit L0-regularized calibration weights.\n\nArgs:\n    X_sparse: Sparse matrix (targets x records).\n    targets: Target values array.\n    lambda_l0: L0 regularization strength.\n    epochs: Training epochs.\n    device: Torch device.\n    verbose_freq: Print frequency. Defaults to 10%.\n    beta: L0 gate temperature.\n    lambda_l2: L2 regularization strength.\n    learning_rate: Optimizer learning rate.\n    log_freq: Epochs between per-target CSV logs.\n        None disables logging.\n    log_path: Path for the per-target calibration log CSV.\n    target_names: Human-readable target names for the log.\n    initial_weights: Pre-computed initial weights. If None,\n        computed from targets_df age targets.\n    targets_df: Targets DataFrame, used to compute\n        initial_weights when not provided.\n    target_groups: Optional group ID per target row for balanced loss.\n    resume_from: Path to a `.checkpoint.pt` file or `.npy`\n        weights file to continue fitting from.\n    checkpoint_path: Where to save resumable fit checkpoints.\n\nReturns:\n    Weight array of shape (n_records,).",
    "id": "fit_model",
    "kind": "function",
    "line": 889,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_calibration.fit_l0_weights"
      ],
      "artifacts_in": [
        "calibration_package.pkl"
      ],
      "artifacts_out": [
        "calibration_weights.npy",
        "unified_diagnostics.csv"
      ],
      "description": "Optimize sparse calibration weights with HardConcrete gates and diagnostics.",
      "id": "fit_model",
      "label": "Fit L0 Calibration Weights",
      "node_type": "library",
      "pathways": [
        "weight_fit"
      ],
      "source_file": "policyengine_us_data/calibration/unified_calibration.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_unified_calibration.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_calibration.fit_l0_weights",
    "signature": "def fit_l0_weights(X_sparse, targets: np.ndarray, lambda_l0: float, epochs: int = DEFAULT_EPOCHS, device: str = 'cpu', verbose_freq: Optional[int] = None, beta: float = BETA, lambda_l2: float = LAMBDA_L2, learning_rate: float = LEARNING_RATE, log_freq: int = None, log_path: str = None, target_names: list = None, initial_weights: np.ndarray = None, targets_df: 'pd.DataFrame' = None, achievable: np.ndarray = None, target_groups: Optional[np.ndarray] = None, resume_from: str = None, checkpoint_path: str = None) -> np.ndarray",
    "source_file": "policyengine_us_data/calibration/unified_calibration.py"
  },
  "fitted_weights_artifacts": {
    "docstring": "Return canonical fitted-weight artifacts for a regional or national scope.",
    "id": "fitted_weights_artifacts",
    "kind": "function",
    "line": 184,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.fit_weights.artifacts.fit_artifacts_for_scope"
      ],
      "artifacts_in": [
        "remote fit result bytes"
      ],
      "artifacts_out": [
        "calibration_weights.npy",
        "geography_assignment.npz",
        "unified_run_config.json",
        "national_calibration_weights.npy",
        "national_geography_assignment.npz",
        "national_unified_run_config.json"
      ],
      "description": "Canonical regional and national fitted-weight artifact filenames.",
      "id": "fitted_weights_artifacts",
      "label": "Fitted Weights Artifacts",
      "node_type": "library",
      "pathways": [
        "fit_weights",
        "artifact_identity"
      ],
      "source_file": "policyengine_us_data/fit_weights/artifacts.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/fit_weights/test_artifacts.py"
      ]
    },
    "object_path": "policyengine_us_data.fit_weights.artifacts.fit_artifacts_for_scope",
    "signature": "def fit_artifacts_for_scope(scope: FitScope | str) -> ScopedFitArtifacts",
    "source_file": "policyengine_us_data/fit_weights/artifacts.py"
  },
  "fitted_weights_output_bundle": {
    "docstring": "Scoped output bundle created before Stage 3 bytes become files.",
    "id": "fitted_weights_output_bundle",
    "kind": "class",
    "line": 113,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.fit_weights.bundles.FittedWeightsOutputBundle"
      ],
      "artifacts_in": [
        "remote fit result bytes"
      ],
      "artifacts_out": [
        "scoped fitted-weight artifact writes"
      ],
      "description": "Scoped Stage 3 result bytes before artifact file writes.",
      "id": "fitted_weights_output_bundle",
      "label": "Fitted Weights Output Bundle",
      "node_type": "library",
      "pathways": [
        "fit_weights",
        "artifact_identity"
      ],
      "source_file": "policyengine_us_data/fit_weights/bundles.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/fit_weights/test_bundles.py"
      ]
    },
    "object_path": "policyengine_us_data.fit_weights.bundles.FittedWeightsOutputBundle",
    "signature": "class FittedWeightsOutputBundle",
    "source_file": "policyengine_us_data/fit_weights/bundles.py"
  },
  "fitted_weights_spec": {
    "docstring": "Return the current fitted-weight spec for a regional or national scope.",
    "id": "fitted_weights_spec",
    "kind": "function",
    "line": 178,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.fit_weights.specs.fitted_weights_spec_for_scope"
      ],
      "artifacts_in": [
        "calibration_package.pkl"
      ],
      "artifacts_out": [
        "fit_parameter_identity"
      ],
      "description": "Scoped Stage 3 fit parameters and deterministic reuse identity.",
      "id": "fitted_weights_spec",
      "label": "Fitted Weights Spec",
      "node_type": "library",
      "pathways": [
        "fit_weights",
        "reuse_identity"
      ],
      "source_file": "policyengine_us_data/fit_weights/specs.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/fit_weights/test_specs.py"
      ]
    },
    "object_path": "policyengine_us_data.fit_weights.specs.fitted_weights_spec_for_scope",
    "signature": "def fitted_weights_spec_for_scope(scope: FitScope | str) -> FittedWeightsSpec",
    "source_file": "policyengine_us_data/fit_weights/specs.py"
  },
  "full_promotion_result": {
    "docstring": "Typed result for a full Stage 5 release promotion transaction.",
    "id": "full_promotion_result",
    "kind": "class",
    "line": 63,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.results.FullPromotionResult",
        "policyengine_us_data.release_promotion.results.full.FullPromotionResult"
      ],
      "artifacts_in": [
        "release promotion transaction output"
      ],
      "artifacts_out": [
        "typed promotion result"
      ],
      "description": "Typed Stage 5 result model for full release promotion outcomes.",
      "id": "full_promotion_result",
      "label": "FullPromotionResult",
      "node_type": "library",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/results/full.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_results.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.results.full.FullPromotionResult",
    "signature": "class FullPromotionResult",
    "source_file": "policyengine_us_data/release_promotion/results/full.py"
  },
  "geo_assign": {
    "docstring": "Assign random census block geography to cloned\nCPS records.\n\nEach of n_records * n_clones total records gets a\nrandom census block sampled from the global\npopulation-weighted distribution. State and CD are\nderived from the block GEOID.\n\nArgs:\n    n_records: Number of households in the base CPS\n        dataset.\n    n_clones: Number of clones (default 10).\n    seed: Random seed for reproducibility.\n    fixed_state_fips: Optional state FIPS per base record. Positive\n        values constrain every clone of that record to blocks in the\n        requested state; zero or missing values remain unrestricted.\n\nReturns:\n    GeographyAssignment with arrays of length\n    n_records * n_clones.",
    "id": "geo_assign",
    "kind": "function",
    "line": 163,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.clone_and_assign.assign_random_geography"
      ],
      "artifacts_out": [
        "GeographyAssignment"
      ],
      "description": "Assign cloned CPS records to population-weighted blocks, counties, states, and congressional districts.",
      "id": "geo_assign",
      "label": "Assign Random Geography",
      "node_type": "library",
      "pathways": [
        "data_build",
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/clone_and_assign.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_clone_and_assign.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.clone_and_assign.assign_random_geography",
    "signature": "def assign_random_geography(n_records: int, n_clones: int = 10, seed: int = 42, household_agi: np.ndarray = None, cd_agi_targets: dict = None, agi_threshold_pctile: float = 90.0, fixed_state_fips: np.ndarray = None) -> GeographyAssignment",
    "source_file": "policyengine_us_data/calibration/clone_and_assign.py"
  },
  "geo_derive": {
    "docstring": "Derive all geography from pre-assigned block GEOIDs.\n\nGiven an array of block GEOIDs (already assigned by\ncalibration), derives county, tract, state, CBSA, SLDU,\nSLDL, place, VTD, PUMA, ZCTA, and county enum index.\n\nArgs:\n    block_geoids: Array of 15-char block GEOID strings.\n\nReturns:\n    Dict with same keys as assign_geography_for_cd.",
    "id": "geo_derive",
    "kind": "function",
    "line": 582,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.block_assignment.derive_geography_from_blocks"
      ],
      "description": "Derive state, county, tract, PUMA, place, district, and other geography from block GEOIDs.",
      "id": "geo_derive",
      "label": "Derive Geography From Blocks",
      "node_type": "library",
      "pathways": [
        "local_h5",
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/block_assignment.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_clone_and_assign.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.block_assignment.derive_geography_from_blocks",
    "signature": "def derive_geography_from_blocks(block_geoids: np.ndarray) -> Dict[str, np.ndarray]",
    "source_file": "policyengine_us_data/calibration/block_assignment.py"
  },
  "housing_assistance_microsim_validation": {
    "docstring": "Check formula-reconstructed housing assistance before export.\n\nThe final H5 must not export formula outputs such as ``housing_assistance``.\nThis guard verifies that the remaining leaf inputs still make those\nformulas produce nonzero values before the export contract strips or\nrejects computed variables.",
    "id": "housing_assistance_microsim_validation",
    "kind": "function",
    "line": 1355,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.extended_cps.ExtendedCPS._validate_housing_assistance_microsimulation"
      ],
      "artifacts_in": [
        "extended_cps_stage2"
      ],
      "artifacts_out": [
        "housing_validated_extended_cps"
      ],
      "description": "Runs a temporary microsimulation before final export to ensure housing-assistance leaf inputs reconstruct nonzero modeled housing assistance and capped SPM housing subsidy.",
      "id": "housing_assistance_microsim_validation",
      "label": "Validate Housing Assistance Microsimulation",
      "node_type": "process",
      "pathways": [
        "data_build"
      ],
      "pydoc": true,
      "source_file": "policyengine_us_data/datasets/cps/extended_cps.py",
      "stability": "moving",
      "status": "transitional"
    },
    "object_path": "policyengine_us_data.datasets.cps.extended_cps.ExtendedCPS._validate_housing_assistance_microsimulation",
    "signature": "def _validate_housing_assistance_microsimulation(cls, data, time_period, microsimulation_cls = None)",
    "source_file": "policyengine_us_data/datasets/cps/extended_cps.py"
  },
  "impute_puf_demographics": {
    "docstring": "",
    "id": "impute_puf_demographics",
    "kind": "function",
    "line": 474,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.puf.puf.impute_missing_demographics"
      ],
      "description": "Impute missing PUF demographics from demographic donor records.",
      "id": "impute_puf_demographics",
      "label": "Impute PUF Demographics",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/puf/puf.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/datasets/test_irs_puf.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.puf.puf.impute_missing_demographics",
    "signature": "def impute_missing_demographics(puf: pd.DataFrame, demographics: pd.DataFrame) -> pd.DataFrame",
    "source_file": "policyengine_us_data/datasets/puf/puf.py"
  },
  "impute_puf_pension": {
    "docstring": "",
    "id": "impute_puf_pension",
    "kind": "function",
    "line": 418,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.puf.puf.impute_pension_contributions_to_puf"
      ],
      "description": "Impute pre-tax retirement contributions onto PUF tax units from CPS donors.",
      "id": "impute_puf_pension",
      "label": "Impute PUF Pension Contributions",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/puf/puf.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/datasets/test_irs_puf.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.puf.puf.impute_pension_contributions_to_puf",
    "signature": "def impute_pension_contributions_to_puf(puf_df)",
    "source_file": "policyengine_us_data/datasets/puf/puf.py"
  },
  "init_weights": {
    "docstring": "Compute population-based initial weights from age targets.\n\nFor each congressional district, sums person_count targets where\ndomain_variable == \"age\" to get district population, then divides\nby the number of columns (households) active in that district.\n\nArgs:\n    X_sparse: Sparse matrix (targets x records).\n    targets_df: Targets DataFrame with columns: variable,\n        domain_variable, geo_level, geographic_id, value.\n\nReturns:\n    Weight array of shape (n_records,).",
    "id": "init_weights",
    "kind": "function",
    "line": 810,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_calibration.compute_initial_weights"
      ],
      "artifacts_in": [
        "calibration_package.pkl"
      ],
      "description": "Build population-proportional initial weights from geography and targets.",
      "id": "init_weights",
      "label": "Compute Initial Weights",
      "node_type": "library",
      "pathways": [
        "weight_fit"
      ],
      "source_file": "policyengine_us_data/calibration/unified_calibration.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_unified_calibration.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_calibration.compute_initial_weights",
    "signature": "def compute_initial_weights(X_sparse, targets_df: 'pd.DataFrame') -> np.ndarray",
    "source_file": "policyengine_us_data/calibration/unified_calibration.py"
  },
  "legacy_release_candidate_bundle_builder": {
    "docstring": "Build a candidate bundle from the current legacy staged relative paths.",
    "id": "legacy_release_candidate_bundle_builder",
    "kind": "function",
    "line": 38,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.candidate_builders.build_legacy_release_candidate_bundle"
      ],
      "description": "Compatibility builder for Stage 5 candidates from legacy staged path sets.",
      "id": "legacy_release_candidate_bundle_builder",
      "label": "Legacy Release Candidate Bundle Builder",
      "node_type": "library",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/candidate_builders.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_candidate.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.candidate_builders.build_legacy_release_candidate_bundle",
    "signature": "def build_legacy_release_candidate_bundle(*, context: ReleasePromotionContext, rel_paths: Sequence[str], artifact_metadata_by_path: Mapping[str, Mapping[str, Any]] | None = None, validation_report_paths: Sequence[str] = (), validation_report_refs: Sequence[DiagnosticRef] = (), source_output_contract_path: str | None = None, diagnostics_manifest_path: str | None = None) -> ReleaseCandidateInputBundle",
    "source_file": "policyengine_us_data/release_promotion/candidate_builders.py"
  },
  "load_calibration_geography": {
    "docstring": "",
    "id": "load_calibration_geography",
    "kind": "function",
    "line": 137,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.geography_loader.CalibrationGeographyLoader",
        "policyengine_us_data.calibration.publish_local_area.load_calibration_geography"
      ],
      "artifacts_in": [
        "calibration_weights.npy",
        "geography_assignment.npz",
        "stacked_blocks.npy"
      ],
      "description": "Resolve exact geography from saved bundles, package metadata, or legacy block artifacts.",
      "id": "load_calibration_geography",
      "label": "Load Calibration Geography",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/publish_local_area.py",
      "stability": "moving",
      "status": "legacy",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_geography_loader.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.publish_local_area.load_calibration_geography",
    "signature": "def load_calibration_geography(weights_path: Path, n_records: int, n_clones: Optional[int] = None, geography_path: Optional[Path] = None, blocks_path: Optional[Path] = None, calibration_package_path: Optional[Path] = None)",
    "source_file": "policyengine_us_data/calibration/publish_local_area.py"
  },
  "local_h5_area_catalog": {
    "docstring": "Construct typed H5 build requests for supported US geographies.\n\n`USAreaCatalog` translates calibration geography arrays and legacy worker\nitem dictionaries into `AreaBuildRequest` values. It owns US-specific\nnaming rules, including state abbreviations, congressional district friendly\nnames, at-large district normalization, and the current NYC city rule.",
    "id": "local_h5_area_catalog",
    "kind": "class",
    "line": 48,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.area_catalog.USAreaCatalog"
      ],
      "description": "Build typed local H5 requests from US states, districts, and supported city rules.",
      "id": "local_h5_area_catalog",
      "label": "USAreaCatalog",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/area_catalog.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_area_catalog.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.area_catalog.USAreaCatalog",
    "signature": "class USAreaCatalog",
    "source_file": "policyengine_us_data/build_outputs/area_catalog.py"
  },
  "local_h5_area_filter": {
    "docstring": "Predicate used to select calibrated clones for one H5 output.\n\n`AreaFilter` is intentionally small so it can move across process\nboundaries as JSON. It describes one boolean condition over a geography\nvector, such as selecting all clones in a set of congressional districts or\ncounties.\n\nAttributes:\n    geography_field: Name of the geography vector to inspect. Current\n        callers use fields from `GeographyAssignment`, such as `cd_geoid` or\n        `county_fips`.\n    op: Predicate operator. Use `\"eq\"` for one scalar value and `\"in\"` for\n        membership in a tuple of values.\n    value: Scalar comparison value for `\"eq\"` or tuple of allowed values for\n        `\"in\"`.",
    "id": "local_h5_area_filter",
    "kind": "class",
    "line": 73,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.requests.AreaFilter"
      ],
      "description": "Typed geography predicate for local H5 output selection.",
      "id": "local_h5_area_filter",
      "label": "AreaFilter",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/requests.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_requests.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.requests.AreaFilter",
    "signature": "class AreaFilter",
    "source_file": "policyengine_us_data/build_outputs/requests.py"
  },
  "local_h5_area_request": {
    "docstring": "Complete request for one local-area or national H5 file.\n\nThe request is the stable library-level contract between orchestration code\nand H5 worker code. It names the output, carries the geography filters used\nto zero irrelevant clone weights, and records the target geography IDs used\nby validation.\n\nAttributes:\n    area_type: Output family, such as `\"state\"`, `\"district\"`, `\"city\"`, or\n        `\"national\"`.\n    area_id: Stable identifier for the requested area, for example `\"CA\"`,\n        `\"NY-12\"`, `\"NYC\"`, or `\"US\"`.\n    display_name: Human-readable label used in logs and validation output.\n    output_relative_path: Path below the worker output directory where the\n        H5 should be written.\n    filters: Geography predicates that select clones for this area.\n    validation_geo_level: Target table geography level used to validate the\n        output, when validation is available.\n    validation_geographic_ids: Target geography IDs expected during\n        validation.\n    metadata: Additional non-control metadata for downstream tooling.",
    "id": "local_h5_area_request",
    "kind": "class",
    "line": 149,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.requests.AreaBuildRequest"
      ],
      "description": "Typed request contract for one national, state, district, city, or custom H5 output.",
      "id": "local_h5_area_request",
      "label": "AreaBuildRequest",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/requests.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_requests.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.requests.AreaBuildRequest",
    "signature": "class AreaBuildRequest",
    "source_file": "policyengine_us_data/build_outputs/requests.py"
  },
  "local_h5_area_selector": {
    "docstring": "Apply request geography filters to clone-level calibration weights.",
    "id": "local_h5_area_selector",
    "kind": "class",
    "line": 30,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.selection.AreaSelector"
      ],
      "description": "Select active clone-household rows for one local H5 output.",
      "id": "local_h5_area_selector",
      "label": "AreaSelector",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/selection.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_selection.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.selection.AreaSelector",
    "signature": "class AreaSelector",
    "source_file": "policyengine_us_data/build_outputs/selection.py"
  },
  "local_h5_area_validation_service": {
    "docstring": "Build validation state for all H5 requests handled by one worker.",
    "id": "local_h5_area_validation_service",
    "kind": "class",
    "line": 127,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.validation.AreaValidationService"
      ],
      "artifacts_in": [
        "policy_data.db",
        "target_config.yaml",
        "target_config_full.yaml"
      ],
      "description": "Prepare local H5 validation targets once per worker session.",
      "id": "local_h5_area_validation_service",
      "label": "AreaValidationService",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/validation.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_validation.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.validation.AreaValidationService",
    "signature": "class AreaValidationService",
    "source_file": "policyengine_us_data/build_outputs/validation.py"
  },
  "local_h5_artifact_identity": {
    "docstring": "Stable identity for an input artifact used by traceability.\n\nAttributes:\n    logical_name: Semantic artifact name, such as `\"weights\"` or\n        `\"source_dataset\"`.\n    path: Physical artifact path when the artifact exists in the local\n        runtime.\n    sha256: Content digest prefixed with `\"sha256:\"`.\n    size_bytes: Artifact size in bytes, when available.\n    metadata: Additional normalized metadata, for example canonical\n        geography checksum or source kind.",
    "id": "local_h5_artifact_identity",
    "kind": "class",
    "line": 92,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.fingerprinting.ArtifactIdentity"
      ],
      "description": "Stable content identity for one local H5 publication input artifact.",
      "id": "local_h5_artifact_identity",
      "label": "ArtifactIdentity",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/fingerprinting.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_fingerprinting.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.fingerprinting.ArtifactIdentity",
    "signature": "class ArtifactIdentity",
    "source_file": "policyengine_us_data/build_outputs/fingerprinting.py"
  },
  "local_h5_build_result": {
    "docstring": "In-memory output from building one local H5 area.",
    "id": "local_h5_build_result",
    "kind": "class",
    "line": 83,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.builder.LocalAreaBuildResult"
      ],
      "description": "In-memory local H5 payload and diagnostics for one area.",
      "id": "local_h5_build_result",
      "label": "LocalAreaBuildResult",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/builder.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_builder.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.builder.LocalAreaBuildResult",
    "signature": "class LocalAreaBuildResult",
    "source_file": "policyengine_us_data/build_outputs/builder.py"
  },
  "local_h5_calibration_geography_index": {
    "docstring": "Clone geography fields needed for coordinator-side request planning.",
    "id": "local_h5_calibration_geography_index",
    "kind": "class",
    "line": 81,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.geography_loader.CalibrationGeographyIndex"
      ],
      "description": "Lightweight clone geography index used by H5 coordinators.",
      "id": "local_h5_calibration_geography_index",
      "label": "CalibrationGeographyIndex",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/geography_loader.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_geography_loader.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.geography_loader.CalibrationGeographyIndex",
    "signature": "class CalibrationGeographyIndex",
    "source_file": "policyengine_us_data/build_outputs/geography_loader.py"
  },
  "local_h5_clone_selection": {
    "docstring": "Active clone rows selected for one H5 output.",
    "id": "local_h5_clone_selection",
    "kind": "class",
    "line": 113,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.selection.CloneSelection"
      ],
      "description": "Selected clone-household rows for one local H5 output.",
      "id": "local_h5_clone_selection",
      "label": "CloneSelection",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/selection.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_selection.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.selection.CloneSelection",
    "signature": "class CloneSelection",
    "source_file": "policyengine_us_data/build_outputs/selection.py"
  },
  "local_h5_coordinator_worker_result": {
    "docstring": "Normalized worker response with explicit fatal and nonfatal issue classes.",
    "id": "local_h5_coordinator_worker_result",
    "kind": "class",
    "line": 30,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_responses.CoordinatorWorkerResult"
      ],
      "description": "Coordinator-normalized view of one local H5 worker response.",
      "id": "local_h5_coordinator_worker_result",
      "label": "CoordinatorWorkerResult",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_responses.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_responses.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_responses.CoordinatorWorkerResult",
    "signature": "class CoordinatorWorkerResult",
    "source_file": "policyengine_us_data/build_outputs/worker_responses.py"
  },
  "local_h5_dataset_builder": {
    "docstring": "Coordinate clone selection, reindexing, variable cloning, and postprocessing.",
    "id": "local_h5_dataset_builder",
    "kind": "class",
    "line": 151,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.builder.LocalAreaDatasetBuilder"
      ],
      "description": "Build the in-memory payload for one local-area or national H5 output.",
      "id": "local_h5_dataset_builder",
      "label": "LocalAreaDatasetBuilder",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/builder.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_builder.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.builder.LocalAreaDatasetBuilder",
    "signature": "class LocalAreaDatasetBuilder",
    "source_file": "policyengine_us_data/build_outputs/builder.py"
  },
  "local_h5_entity_graph": {
    "docstring": "Structural relationships between source dataset entities.\n\n`EntityGraph` is the canonical in-memory shape for the source entity spine.\nIt stores raw ID arrays plus derived household-membership maps so later H5\nbuilder seams can select households without rebuilding joins.\n\nAttributes:\n    household_ids: Source household IDs, one per household row.\n    person_household_ids: Household ID for each source person row.\n    subentity_ids: Entity IDs by subentity key, such as `tax_unit`.\n    person_subentity_ids: Entity ID for each source person row by subentity.\n    household_to_person_indices: Household row index to person row indices.\n    household_to_subentity_indices: Subentity key to household row index to\n        subentity row indices.",
    "id": "local_h5_entity_graph",
    "kind": "class",
    "line": 77,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.source_dataset.EntityGraph"
      ],
      "description": "Explicit source-dataset entity spine for local H5 worker setup.",
      "id": "local_h5_entity_graph",
      "label": "EntityGraph",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/source_dataset.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_source_dataset.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.source_dataset.EntityGraph",
    "signature": "class EntityGraph",
    "source_file": "policyengine_us_data/build_outputs/source_dataset.py"
  },
  "local_h5_entity_reindexer": {
    "docstring": "Build sequential entity IDs and relationship arrays after clone selection.",
    "id": "local_h5_entity_reindexer",
    "kind": "class",
    "line": 31,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.reindexing.EntityReindexer"
      ],
      "description": "Reindex selected household, person, and subentity rows for local H5 outputs.",
      "id": "local_h5_entity_reindexer",
      "label": "EntityReindexer",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/reindexing.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_reindexing.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.reindexing.EntityReindexer",
    "signature": "class EntityReindexer",
    "source_file": "policyengine_us_data/build_outputs/reindexing.py"
  },
  "local_h5_input_fingerprint": {
    "docstring": "",
    "id": "local_h5_input_fingerprint",
    "kind": "function",
    "line": 78,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.fingerprinting.FingerprintingService",
        "policyengine_us_data.calibration.publish_local_area.compute_input_fingerprint"
      ],
      "description": "Compute a scope fingerprint for local H5 checkpoint and resume decisions.",
      "id": "local_h5_input_fingerprint",
      "label": "Compute Local H5 Input Fingerprint",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/publish_local_area.py",
      "stability": "moving",
      "status": "legacy",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_fingerprinting.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.publish_local_area.compute_input_fingerprint",
    "signature": "def compute_input_fingerprint(weights_path: Path, dataset_path: Path, n_clones: Optional[int] = None, seed: int = 42, geography_path: Optional[Path] = None, blocks_path: Optional[Path] = None, target_db_path: Optional[Path] = None, run_config_path: Optional[Path] = None, calibration_package_path: Optional[Path] = None, scope: str = 'regional') -> str",
    "source_file": "policyengine_us_data/calibration/publish_local_area.py"
  },
  "local_h5_legacy_work_item_partition": {
    "docstring": "Partition remaining H5 work across worker chunks.\n\nThe function uses longest-processing-time scheduling: uncompleted work items\nare sorted by descending `weight`, then assigned to the currently lightest\nworker chunk. This keeps expensive state or district builds from clustering\non one worker.\n\nArgs:\n    work_items: Candidate work items. Each item must contain `type`, `id`,\n        and numeric `weight` keys.\n    num_workers: Maximum number of worker chunks to produce.\n    completed: Stable completion keys, formatted as `\"{type}:{id}\"`, that\n        should be skipped.\n\nReturns:\n    Non-empty worker chunks. Returns an empty list when `num_workers <= 0` or\n    every item is already completed.",
    "id": "local_h5_legacy_work_item_partition",
    "kind": "function",
    "line": 108,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.partitioning.partition_weighted_work_items"
      ],
      "description": "Compatibility wrapper for assigning legacy local H5 work items to workers.",
      "id": "local_h5_legacy_work_item_partition",
      "label": "Partition Legacy Local H5 Work Items",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/partitioning.py",
      "stability": "moving",
      "status": "legacy",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_partitioning.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.partitioning.partition_weighted_work_items",
    "signature": "def partition_weighted_work_items(work_items: WorkItems, num_workers: int, completed: set[str] | None = None) -> WorkChunks",
    "source_file": "policyengine_us_data/build_outputs/partitioning.py"
  },
  "local_h5_microsimulation_variable_provider": {
    "docstring": "Lazy holder-backed variable reader for a source microsimulation.\n\nThe provider intentionally reads arrays only when callers request a\nvariable/period pair. It caches the normalized array for repeated access\nwhile keeping construction lightweight.\n\nAttributes:\n    simulation: Source `policyengine_us.Microsimulation` or a compatible\n        test double with `input_variables` and `get_holder(...)`.",
    "id": "local_h5_microsimulation_variable_provider",
    "kind": "class",
    "line": 384,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.source_dataset.MicrosimulationVariableProvider"
      ],
      "description": "Lazy source variable access wrapper for local H5 source snapshots.",
      "id": "local_h5_microsimulation_variable_provider",
      "label": "MicrosimulationVariableProvider",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/source_dataset.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_source_dataset.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.source_dataset.MicrosimulationVariableProvider",
    "signature": "class MicrosimulationVariableProvider",
    "source_file": "policyengine_us_data/build_outputs/source_dataset.py"
  },
  "local_h5_partition": {
    "docstring": "Partition remaining typed H5 requests across worker chunks.",
    "id": "local_h5_partition",
    "kind": "function",
    "line": 81,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.partitioning.partition_weighted_area_requests"
      ],
      "description": "Assign weighted area work items to worker batches using longest-processing-time scheduling.",
      "id": "local_h5_partition",
      "label": "Partition Local H5 Work",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/partitioning.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_partitioning.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.partitioning.partition_weighted_area_requests",
    "signature": "def partition_weighted_area_requests(requests: Sequence[WeightedAreaRequest], num_workers: int, completed: set[str] | None = None) -> WeightedAreaRequestChunks",
    "source_file": "policyengine_us_data/build_outputs/partitioning.py"
  },
  "local_h5_payload": {
    "docstring": "Period-grouped arrays ready to write to a local-area H5 file.\n\n`entity_lengths` records the row count expected for each entity in this\npayload. Shape validation intentionally covers the stable structural\nvariables first; formula variables that do not encode their entity in the\nvariable name are left to existing source-variable and runtime checks.",
    "id": "local_h5_payload",
    "kind": "class",
    "line": 55,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.payload.H5Payload"
      ],
      "description": "Validated in-memory period-grouped payload for one local H5 output.",
      "id": "local_h5_payload",
      "label": "H5Payload",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/payload.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_payload.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.payload.H5Payload",
    "signature": "class H5Payload",
    "source_file": "policyengine_us_data/build_outputs/payload.py"
  },
  "local_h5_payload_build_context": {
    "docstring": "Context available to country-specific local H5 payload postprocessors.",
    "id": "local_h5_payload_build_context",
    "kind": "class",
    "line": 134,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.payload.PayloadBuildContext"
      ],
      "description": "Context passed to payload postprocessors during one H5 build.",
      "id": "local_h5_payload_build_context",
      "label": "PayloadBuildContext",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/payload.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_payload.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.payload.PayloadBuildContext",
    "signature": "class PayloadBuildContext",
    "source_file": "policyengine_us_data/build_outputs/payload.py"
  },
  "local_h5_policyengine_dataset_reader": {
    "docstring": "Read PolicyEngine source H5 files into `SourceDatasetSnapshot` objects.",
    "id": "local_h5_policyengine_dataset_reader",
    "kind": "class",
    "line": 560,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.source_dataset.PolicyEngineDatasetReader"
      ],
      "description": "PolicyEngine H5 dataset adapter for local H5 source snapshots.",
      "id": "local_h5_policyengine_dataset_reader",
      "label": "PolicyEngineDatasetReader",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/source_dataset.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/integration/build_outputs/h5_worker_runtime/test_worker_script_tiny_fixture.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.source_dataset.PolicyEngineDatasetReader",
    "signature": "class PolicyEngineDatasetReader",
    "source_file": "policyengine_us_data/build_outputs/source_dataset.py"
  },
  "local_h5_publishing_input_bundle": {
    "docstring": "Input artifact bundle for one local H5 publication scope.\n\nThe bundle is the library-level contract used by coordinators before\nfingerprinting. Paths point to local files already materialized in the\nworker or orchestration environment.\n\nAttributes:\n    weights_path: Path to `calibration_weights.npy`.\n    source_dataset_path: Path to the source-imputed dataset H5.\n    target_db_path: Optional `policy_data.db` path used for validation.\n    exact_geography_path: Optional saved `geography_assignment.npz` path.\n    calibration_package_path: Optional `calibration_package.pkl` path used\n        as a geography fallback.\n    run_config_path: Optional run configuration JSON with code and model\n        build metadata.\n    run_id: Pipeline run identifier.\n    version: Package or release version associated with the publish.\n    n_clones: Expected clone count, when known.\n    seed: Geography assignment seed used by the build.\n    legacy_blocks_path: Optional legacy `stacked_blocks.npy` fallback.",
    "id": "local_h5_publishing_input_bundle",
    "kind": "class",
    "line": 42,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.fingerprinting.PublishingInputBundle"
      ],
      "description": "Input artifact and run metadata bundle for one local H5 publish scope.",
      "id": "local_h5_publishing_input_bundle",
      "label": "PublishingInputBundle",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/fingerprinting.py",
      "stability": "moving",
      "status": "current"
    },
    "object_path": "policyengine_us_data.build_outputs.fingerprinting.PublishingInputBundle",
    "signature": "class PublishingInputBundle",
    "source_file": "policyengine_us_data/build_outputs/fingerprinting.py"
  },
  "local_h5_regional_target_universe": {
    "docstring": "Congressional district target universe for regional H5 outputs.",
    "id": "local_h5_regional_target_universe",
    "kind": "class",
    "line": 31,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.target_universe.RegionalTargetUniverse"
      ],
      "description": "Target congressional district universe used to enumerate regional local H5 outputs.",
      "id": "local_h5_regional_target_universe",
      "label": "RegionalTargetUniverse",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/target_universe.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_target_universe.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.target_universe.RegionalTargetUniverse",
    "signature": "class RegionalTargetUniverse",
    "source_file": "policyengine_us_data/build_outputs/target_universe.py"
  },
  "local_h5_reindexed_entities": {
    "docstring": "Entity IDs, relationship arrays, and source indices for one H5 output.",
    "id": "local_h5_reindexed_entities",
    "kind": "class",
    "line": 123,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.reindexing.ReindexedEntities"
      ],
      "description": "Output entity IDs and source row indices after local H5 clone selection.",
      "id": "local_h5_reindexed_entities",
      "label": "ReindexedEntities",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/reindexing.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_reindexing.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.reindexing.ReindexedEntities",
    "signature": "class ReindexedEntities",
    "source_file": "policyengine_us_data/build_outputs/reindexing.py"
  },
  "local_h5_resolved_geography_source": {
    "docstring": "Resolved physical source used to recover calibration geography.\n\nAttributes:\n    kind: Source format selected by `CalibrationGeographyLoader`.\n    path: Path to the selected source artifact.",
    "id": "local_h5_resolved_geography_source",
    "kind": "class",
    "line": 55,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.geography_loader.ResolvedGeographySource"
      ],
      "description": "Resolved physical source used to recover exact calibration geography.",
      "id": "local_h5_resolved_geography_source",
      "label": "ResolvedGeographySource",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/geography_loader.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_geography_loader.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.geography_loader.ResolvedGeographySource",
    "signature": "class ResolvedGeographySource",
    "source_file": "policyengine_us_data/build_outputs/geography_loader.py"
  },
  "local_h5_source_dataset_snapshot": {
    "docstring": "Explicit in-memory worker view of a source H5 dataset.\n\nThe snapshot groups source dataset structure and lazy variable access. It\ndoes not serialize artifacts or change current worker execution paths.\n\nAttributes:\n    dataset_path: Source H5 dataset path.\n    time_period: Default source calculation period.\n    entity_graph: Source entity relationship graph.\n    input_variables: Input variable names available from the source.\n    variable_provider: Lazy variable reader for the source simulation.",
    "id": "local_h5_source_dataset_snapshot",
    "kind": "class",
    "line": 483,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.source_dataset.SourceDatasetSnapshot"
      ],
      "description": "In-memory source H5 dataset contract for local H5 worker setup.",
      "id": "local_h5_source_dataset_snapshot",
      "label": "SourceDatasetSnapshot",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/source_dataset.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_source_dataset.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.source_dataset.SourceDatasetSnapshot",
    "signature": "class SourceDatasetSnapshot",
    "source_file": "policyengine_us_data/build_outputs/source_dataset.py"
  },
  "local_h5_target_universe_reader": {
    "docstring": "Adapter from the Stage 1 target database artifact to H5 target contracts.",
    "id": "local_h5_target_universe_reader",
    "kind": "class",
    "line": 57,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.target_universe.TargetUniverseReader"
      ],
      "description": "Read local H5 target-universe contracts from the staged target database.",
      "id": "local_h5_target_universe_reader",
      "label": "TargetUniverseReader",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/target_universe.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_target_universe.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.target_universe.TargetUniverseReader",
    "signature": "class TargetUniverseReader",
    "source_file": "policyengine_us_data/build_outputs/target_universe.py"
  },
  "local_h5_traceability": {
    "docstring": "Build traceability bundles and derive deterministic scope fingerprints.\n\nThe service centralizes provenance rules for local H5 publishing. It avoids\nimporting heavy simulation machinery until a fallback record-count inference\nis needed.",
    "id": "local_h5_traceability",
    "kind": "class",
    "line": 201,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.fingerprinting.FingerprintingService"
      ],
      "description": "Build traceability bundles and deterministic scope fingerprints for local H5 publication.",
      "id": "local_h5_traceability",
      "label": "FingerprintingService",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/fingerprinting.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_fingerprinting.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.fingerprinting.FingerprintingService",
    "signature": "class FingerprintingService",
    "source_file": "policyengine_us_data/build_outputs/fingerprinting.py"
  },
  "local_h5_traceability_bundle": {
    "docstring": "Full provenance record for one local H5 publish scope.\n\nAttributes:\n    scope: Publish scope being fingerprinted, currently `\"regional\"` or\n        `\"national\"`.\n    weights: Identity of the calibration weights artifact.\n    source_dataset: Identity of the source-imputed H5 artifact.\n    exact_geography: Identity of the geography source used for clone\n        selection, if available.\n    target_db: Optional target database identity.\n    calibration_package: Optional calibration package identity.\n    run_config: Optional run configuration identity.\n    code_version: Normalized code version metadata extracted from run\n        config.\n    model_build: Normalized model build metadata extracted from run config.\n    metadata: Scope-level metadata such as run ID, version, clone count, and\n        seed.",
    "id": "local_h5_traceability_bundle",
    "kind": "class",
    "line": 127,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.fingerprinting.TraceabilityBundle"
      ],
      "description": "Provenance and resumability material for one local H5 publish scope.",
      "id": "local_h5_traceability_bundle",
      "label": "TraceabilityBundle",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/fingerprinting.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_fingerprinting.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.fingerprinting.TraceabilityBundle",
    "signature": "class TraceabilityBundle",
    "source_file": "policyengine_us_data/build_outputs/fingerprinting.py"
  },
  "local_h5_us_entity_postprocessor": {
    "docstring": "Apply US entity IDs and calibrated household weights.",
    "id": "local_h5_us_entity_postprocessor",
    "kind": "class",
    "line": 151,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.us_augmentations.USEntityPostProcessor"
      ],
      "description": "Apply US entity ID and household-weight fields to local H5 payloads.",
      "id": "local_h5_us_entity_postprocessor",
      "label": "USEntityPostProcessor",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/us_augmentations.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_us_augmentations.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.us_augmentations.USEntityPostProcessor",
    "signature": "class USEntityPostProcessor",
    "source_file": "policyengine_us_data/build_outputs/us_augmentations.py"
  },
  "local_h5_us_entity_postprocessor_result": {
    "docstring": "Payload after US entity ID and household-weight fields are applied.",
    "id": "local_h5_us_entity_postprocessor_result",
    "kind": "class",
    "line": 71,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.us_augmentations.USEntityPostProcessorResult"
      ],
      "description": "US entity ID and household-weight local H5 payload data.",
      "id": "local_h5_us_entity_postprocessor_result",
      "label": "USEntityPostProcessorResult",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/us_augmentations.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_us_augmentations.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.us_augmentations.USEntityPostProcessorResult",
    "signature": "class USEntityPostProcessorResult",
    "source_file": "policyengine_us_data/build_outputs/us_augmentations.py"
  },
  "local_h5_us_geography_postprocessor": {
    "docstring": "Apply block-derived US geography overrides.",
    "id": "local_h5_us_geography_postprocessor",
    "kind": "class",
    "line": 204,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.us_augmentations.USGeographyPostProcessor"
      ],
      "description": "Apply US geography fields to local H5 payloads.",
      "id": "local_h5_us_geography_postprocessor",
      "label": "USGeographyPostProcessor",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/us_augmentations.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_us_augmentations.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.us_augmentations.USGeographyPostProcessor",
    "signature": "class USGeographyPostProcessor",
    "source_file": "policyengine_us_data/build_outputs/us_augmentations.py"
  },
  "local_h5_us_geography_postprocessor_result": {
    "docstring": "Payload after US geography fields are applied.",
    "id": "local_h5_us_geography_postprocessor_result",
    "kind": "class",
    "line": 97,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.us_augmentations.USGeographyPostProcessorResult"
      ],
      "description": "US geography local H5 payload data and block-derived geography.",
      "id": "local_h5_us_geography_postprocessor_result",
      "label": "USGeographyPostProcessorResult",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/us_augmentations.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_us_augmentations.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.us_augmentations.USGeographyPostProcessorResult",
    "signature": "class USGeographyPostProcessorResult",
    "source_file": "policyengine_us_data/build_outputs/us_augmentations.py"
  },
  "local_h5_us_takeup_postprocessor": {
    "docstring": "Apply US take-up draws after entity and geography postprocessing.",
    "id": "local_h5_us_takeup_postprocessor",
    "kind": "class",
    "line": 309,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.us_augmentations.USTakeupPostProcessor"
      ],
      "description": "Apply US take-up fields to local H5 payloads.",
      "id": "local_h5_us_takeup_postprocessor",
      "label": "USTakeupPostProcessor",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/us_augmentations.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_us_augmentations.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.us_augmentations.USTakeupPostProcessor",
    "signature": "class USTakeupPostProcessor",
    "source_file": "policyengine_us_data/build_outputs/us_augmentations.py"
  },
  "local_h5_us_takeup_postprocessor_result": {
    "docstring": "Payload after US take-up fields are applied.",
    "id": "local_h5_us_takeup_postprocessor_result",
    "kind": "class",
    "line": 124,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.us_augmentations.USTakeupPostProcessorResult"
      ],
      "description": "US take-up local H5 payload data and generated take-up variables.",
      "id": "local_h5_us_takeup_postprocessor_result",
      "label": "USTakeupPostProcessorResult",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/us_augmentations.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_us_augmentations.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.us_augmentations.USTakeupPostProcessorResult",
    "signature": "class USTakeupPostProcessorResult",
    "source_file": "policyengine_us_data/build_outputs/us_augmentations.py"
  },
  "local_h5_validation_context": {
    "docstring": "Prepared validation data reused across all requests in one worker.",
    "id": "local_h5_validation_context",
    "kind": "class",
    "line": 53,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.validation.ValidationContext"
      ],
      "description": "Prepared per-worker local H5 validation target context.",
      "id": "local_h5_validation_context",
      "label": "ValidationContext",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/validation.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_validation.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.validation.ValidationContext",
    "signature": "class ValidationContext",
    "source_file": "policyengine_us_data/build_outputs/validation.py"
  },
  "local_h5_validation_policy": {
    "docstring": "Validation switch for a local H5 worker session.",
    "id": "local_h5_validation_policy",
    "kind": "class",
    "line": 35,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.validation.ValidationPolicy"
      ],
      "description": "Worker-scoped local H5 validation policy contract.",
      "id": "local_h5_validation_policy",
      "label": "ValidationPolicy",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/validation.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_validation.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.validation.ValidationPolicy",
    "signature": "class ValidationPolicy",
    "source_file": "policyengine_us_data/build_outputs/validation.py"
  },
  "local_h5_variable_clone_payload": {
    "docstring": "Cloned source variable arrays before H5-specific overrides.",
    "id": "local_h5_variable_clone_payload",
    "kind": "class",
    "line": 138,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.variables.VariableClonePayload"
      ],
      "description": "Period-grouped cloned source variables for one local H5 output.",
      "id": "local_h5_variable_clone_payload",
      "label": "VariableClonePayload",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/variables.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_variables.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.variables.VariableClonePayload",
    "signature": "class VariableClonePayload",
    "source_file": "policyengine_us_data/build_outputs/variables.py"
  },
  "local_h5_variable_cloner": {
    "docstring": "Clone source variable arrays using selected and reindexed entity rows.\n\nThe skip/error policy intentionally mirrors the first local H5 pipeline\nimplementation. Variables outside the local-H5 allowlist are skipped before\nholder access. Allowed variables are skipped when they have no known periods\nor belong to an entity that local H5s do not clone. Malformed metadata for\nan allowed variable is not skipped; it should fail so incomplete outputs are\nnot produced silently.",
    "id": "local_h5_variable_cloner",
    "kind": "class",
    "line": 49,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.variables.VariableCloner"
      ],
      "description": "Clone selected source variables into period-grouped local H5 payloads.",
      "id": "local_h5_variable_cloner",
      "label": "VariableCloner",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/variables.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_variables.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.variables.VariableCloner",
    "signature": "class VariableCloner",
    "source_file": "policyengine_us_data/build_outputs/variables.py"
  },
  "local_h5_weighted_area_request": {
    "docstring": "Area build request plus scheduling weight for coordinator partitioning.",
    "id": "local_h5_weighted_area_request",
    "kind": "class",
    "line": 40,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.partitioning.WeightedAreaRequest"
      ],
      "description": "Typed local H5 request with coordinator scheduling weight.",
      "id": "local_h5_weighted_area_request",
      "label": "WeightedAreaRequest",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/partitioning.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_partitioning.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.partitioning.WeightedAreaRequest",
    "signature": "class WeightedAreaRequest",
    "source_file": "policyengine_us_data/build_outputs/partitioning.py"
  },
  "local_h5_worker_area_result": {
    "docstring": "Structured result for one area handled by a worker.",
    "id": "local_h5_worker_area_result",
    "kind": "class",
    "line": 117,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_service.WorkerAreaResult"
      ],
      "description": "Structured result for one local H5 worker request.",
      "id": "local_h5_worker_area_result",
      "label": "WorkerAreaResult",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_service.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_service.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_service.WorkerAreaResult",
    "signature": "class WorkerAreaResult",
    "source_file": "policyengine_us_data/build_outputs/worker_service.py"
  },
  "local_h5_worker_bootstrap_builder": {
    "docstring": "Build and persist one scope's local H5 worker bootstrap artifacts.",
    "id": "local_h5_worker_bootstrap_builder",
    "kind": "class",
    "line": 280,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.bootstrap.WorkerBootstrapBuilder"
      ],
      "artifacts_in": [
        "calibration_weights.npy",
        "source_imputed_stratified_extended_cps.h5",
        "geography_assignment.npz",
        "policy_data.db"
      ],
      "artifacts_out": [
        "bootstrap/{scope}/worker_bootstrap.json",
        "bootstrap/{scope}/entity_graph.npz"
      ],
      "description": "Materialize deterministic local H5 worker bootstrap artifacts.",
      "id": "local_h5_worker_bootstrap_builder",
      "label": "WorkerBootstrapBuilder",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/bootstrap.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_bootstrap.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.bootstrap.WorkerBootstrapBuilder",
    "signature": "class WorkerBootstrapBuilder",
    "source_file": "policyengine_us_data/build_outputs/bootstrap.py"
  },
  "local_h5_worker_bootstrap_bundle": {
    "docstring": "Manifest-backed bootstrap bundle for one worker setup scope.\n\nThe bundle is an introduced artifact contract only. It records the\ndeterministic source, weight, geography, and traceability facts that later\nworker-session code can load instead of rebuilding inside every worker.\n\nAttributes:\n    run_id: GitHub-created pipeline run identifier.\n    scope: Bootstrap scope, currently ``\"regional\"`` or ``\"national\"``.\n    root_dir: Directory containing this scope's bootstrap artifacts.\n    manifest_path: Path to ``worker_bootstrap.json``.\n    entity_graph_path: Path to ``entity_graph.npz``.\n    inputs: Manifest artifact identity map.\n    source_dataset: Source dataset summary payload.\n    weights: Clone-weight summary payload.\n    geography: Geography summary payload.\n    traceability: Scope fingerprint and resumability payload.\n    artifacts: Relative bootstrap artifact filenames.\n    schema_version: Bootstrap schema version.",
    "id": "local_h5_worker_bootstrap_bundle",
    "kind": "class",
    "line": 74,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.bootstrap.WorkerBootstrapBundle"
      ],
      "artifacts_in": [
        "calibration_weights.npy",
        "source_imputed_stratified_extended_cps.h5",
        "geography_assignment.npz",
        "policy_data.db"
      ],
      "artifacts_out": [
        "worker_bootstrap.json",
        "entity_graph.npz"
      ],
      "description": "Persisted deterministic worker setup facts for one local H5 scope.",
      "id": "local_h5_worker_bootstrap_bundle",
      "label": "WorkerBootstrapBundle",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/bootstrap.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_bootstrap.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.bootstrap.WorkerBootstrapBundle",
    "signature": "class WorkerBootstrapBundle",
    "source_file": "policyengine_us_data/build_outputs/bootstrap.py"
  },
  "local_h5_worker_bootstrap_store": {
    "docstring": "Filesystem adapter for scope-specific bootstrap bundle paths.",
    "id": "local_h5_worker_bootstrap_store",
    "kind": "class",
    "line": 214,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.bootstrap.WorkerBootstrapStore"
      ],
      "artifacts_out": [
        "bootstrap/{scope}/worker_bootstrap.json",
        "bootstrap/{scope}/entity_graph.npz"
      ],
      "description": "Filesystem path adapter for run-scoped local H5 bootstrap artifacts.",
      "id": "local_h5_worker_bootstrap_store",
      "label": "WorkerBootstrapStore",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/bootstrap.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_bootstrap.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.bootstrap.WorkerBootstrapStore",
    "signature": "class WorkerBootstrapStore",
    "source_file": "policyengine_us_data/build_outputs/bootstrap.py"
  },
  "local_h5_worker_calibration_inputs": {
    "docstring": "Input artifact paths and runtime settings for one H5 worker batch.\n\nThis is the typed library contract. Modal entrypoints may still exchange the\n`to_wire_dict()` representation because it is easier to serialize and\ninspect, but all producers and consumers should normalize through this\nclass before using field values.",
    "id": "local_h5_worker_calibration_inputs",
    "kind": "class",
    "line": 64,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_inputs.WorkerCalibrationInputs"
      ],
      "description": "Normalized worker-execution input payload for local H5 builds.",
      "id": "local_h5_worker_calibration_inputs",
      "label": "WorkerCalibrationInputs",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_inputs.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_inputs.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_inputs.WorkerCalibrationInputs",
    "signature": "class WorkerCalibrationInputs",
    "source_file": "policyengine_us_data/build_outputs/worker_inputs.py"
  },
  "local_h5_worker_execution_config": {
    "docstring": "Execution policy for one worker chunk.",
    "id": "local_h5_worker_execution_config",
    "kind": "class",
    "line": 49,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_service.WorkerExecutionConfig"
      ],
      "description": "Runtime policy for one local H5 worker-service execution.",
      "id": "local_h5_worker_execution_config",
      "label": "WorkerExecutionConfig",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_service.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_service.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_service.WorkerExecutionConfig",
    "signature": "class WorkerExecutionConfig",
    "source_file": "policyengine_us_data/build_outputs/worker_service.py"
  },
  "local_h5_worker_issue": {
    "docstring": "Structured worker issue for request, build, write, or validation failures.",
    "id": "local_h5_worker_issue",
    "kind": "class",
    "line": 80,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_service.WorkerIssue"
      ],
      "description": "Structured issue reported by one local H5 worker request.",
      "id": "local_h5_worker_issue",
      "label": "WorkerIssue",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_service.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_service.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_service.WorkerIssue",
    "signature": "class WorkerIssue",
    "source_file": "policyengine_us_data/build_outputs/worker_service.py"
  },
  "local_h5_worker_result": {
    "docstring": "Structured result for a worker chunk.",
    "id": "local_h5_worker_result",
    "kind": "class",
    "line": 170,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_service.WorkerResult"
      ],
      "description": "Structured result for one local H5 worker chunk.",
      "id": "local_h5_worker_result",
      "label": "WorkerResult",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_service.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_service.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_service.WorkerResult",
    "signature": "class WorkerResult",
    "source_file": "policyengine_us_data/build_outputs/worker_service.py"
  },
  "local_h5_worker_service": {
    "docstring": "Execute typed local H5 requests for one prepared worker session.",
    "id": "local_h5_worker_service",
    "kind": "class",
    "line": 230,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_service.LocalH5WorkerService"
      ],
      "description": "Execute one worker chunk of local H5 build requests.",
      "id": "local_h5_worker_service",
      "label": "LocalH5WorkerService",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_service.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_service.py",
        "uv run pytest tests/integration/build_outputs/h5_worker_runtime/test_worker_script_tiny_fixture.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_service.LocalH5WorkerService",
    "signature": "class LocalH5WorkerService",
    "source_file": "policyengine_us_data/build_outputs/worker_service.py"
  },
  "local_h5_worker_session": {
    "docstring": "Prepared local H5 state for one worker process.",
    "id": "local_h5_worker_session",
    "kind": "class",
    "line": 55,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_session.WorkerSession"
      ],
      "artifacts_in": [
        "calibration_weights.npy",
        "source_imputed_stratified_extended_cps.h5",
        "geography_assignment.npz",
        "policy_data.db",
        "worker_bootstrap.json"
      ],
      "description": "Worker-scoped local H5 setup state reused across queued requests.",
      "id": "local_h5_worker_session",
      "label": "WorkerSession",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_session.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_session.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_session.WorkerSession",
    "signature": "class WorkerSession",
    "source_file": "policyengine_us_data/build_outputs/worker_session.py"
  },
  "local_h5_worker_session_factory": {
    "docstring": "Build worker-scoped setup from raw inputs or persisted bootstrap facts.",
    "id": "local_h5_worker_session_factory",
    "kind": "class",
    "line": 99,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_session.WorkerSessionFactory"
      ],
      "artifacts_in": [
        "calibration_weights.npy",
        "source_imputed_stratified_extended_cps.h5",
        "geography_assignment.npz",
        "policy_data.db",
        "bootstrap/{scope}/worker_bootstrap.json",
        "bootstrap/{scope}/entity_graph.npz"
      ],
      "description": "Load local H5 source, weights, geography, and validation context once per worker.",
      "id": "local_h5_worker_session_factory",
      "label": "WorkerSessionFactory",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_session.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_session.py",
        "uv run pytest tests/integration/build_outputs/h5_worker_runtime/test_worker_script_tiny_fixture.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_session.WorkerSessionFactory",
    "signature": "class WorkerSessionFactory",
    "source_file": "policyengine_us_data/build_outputs/worker_session.py"
  },
  "local_h5_write_result": {
    "docstring": "Summary of one H5 write and lightweight verification pass.",
    "id": "local_h5_write_result",
    "kind": "class",
    "line": 30,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.writer.H5WriteResult"
      ],
      "description": "Post-write verification summary for one local H5 file.",
      "id": "local_h5_write_result",
      "label": "H5WriteResult",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/writer.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_writer.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.writer.H5WriteResult",
    "signature": "class H5WriteResult",
    "source_file": "policyengine_us_data/build_outputs/writer.py"
  },
  "local_h5_writer": {
    "docstring": "Write period-grouped local H5 payloads and verify key output counts.",
    "id": "local_h5_writer",
    "kind": "class",
    "line": 52,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.writer.H5Writer"
      ],
      "description": "Write one period-grouped local H5 payload to disk.",
      "id": "local_h5_writer",
      "label": "H5Writer",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/writer.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_writer.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.writer.H5Writer",
    "signature": "class H5Writer",
    "source_file": "policyengine_us_data/build_outputs/writer.py"
  },
  "local_stage_upload": {
    "docstring": "",
    "id": "local_stage_upload",
    "kind": "function",
    "line": 121,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.promote_local_h5s.stage"
      ],
      "artifacts_in": [
        "local_area_build/**/*.h5"
      ],
      "description": "Upload locally built H5 files into Hugging Face staging paths.",
      "id": "local_stage_upload",
      "label": "Stage Local H5 Files",
      "node_type": "entrypoint",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/promote_local_h5s.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_promote_local_h5s.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.promote_local_h5s.stage",
    "signature": "def stage(files: list, version: str, run_id: str = '')",
    "source_file": "policyengine_us_data/calibration/promote_local_h5s.py"
  },
  "mortgage_convert": {
    "docstring": "Replace formula-level mortgage inputs with structural mortgage data.\n\nThe current us-data calibration pipeline imputes a person-level\n``deductible_mortgage_interest`` and a tax-unit-level\n``interest_deduction``. That short-circuits structural MID reforms in\npolicyengine-us, so this converts those imputed amounts into:\n\n* tax-unit mortgage balances, interest, and origination years\n* person-level ``home_mortgage_interest`` for within-tax-unit allocation\n* person-level ``investment_interest_expense`` for the residual non-mortgage\n  interest share of ``interest_deduction``\n\nThe conversion is intentionally conservative:\n* current-law deductible mortgage interest is preserved exactly\n  unless a QRF-imputed outlier exceeds a high-rate bound\n* current-law total interest deduction is preserved exactly\n* SCF-imputed first-lien and HELOC splits are preserved when available\n* weak balance hints are lifted to a conservative lower bound implied by\n  the observed deductible mortgage interest\n* itemizer balances are capped at the current-law debt cap when needed so\n  the conversion cannot create implausible gross interest to preserve a\n  noisy formula-level imputation\n* the origination year is heuristic, because the current public pipeline\n  does not carry a mortgage-vintage input\n\nThe structural model has two mortgage slots. In public data, we use those\nslots for \"first-lien\" and \"secondary acquisition debt\" rather than trying\nto identify literal primary-residence versus second-home mortgages.",
    "id": "mortgage_convert",
    "kind": "function",
    "line": 141,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.utils.mortgage_interest.convert_mortgage_interest_to_structural_inputs"
      ],
      "description": "Convert deductible mortgage interest into structural mortgage balances, interest, and origination-year inputs.",
      "id": "mortgage_convert",
      "label": "Structural Mortgage Conversion",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/utils/mortgage_interest.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_mortgage_interest.py"
      ]
    },
    "object_path": "policyengine_us_data.utils.mortgage_interest.convert_mortgage_interest_to_structural_inputs",
    "signature": "def convert_mortgage_interest_to_structural_inputs(data: Dict[str, Dict[int, np.ndarray]], time_period: int) -> Dict[str, Dict[int, np.ndarray]]",
    "source_file": "policyengine_us_data/utils/mortgage_interest.py"
  },
  "mortgage_hints": {
    "docstring": "Impute tax-unit mortgage balance hints from SCF data.\n\nThe output variables are not policyengine-us inputs. They are auxiliary\ndata-layer hints that let the structural MID conversion reuse an SCF-like\nmortgage balance distribution without forcing the baseline to use mortgage\ninterest for non-itemizers.\n\nThe second hint is a generic secondary acquisition-debt slot. In the\npublic SCF, HELOC balances are the best observable proxy for that slot even\nthough the downstream ``second_home_mortgage_*`` variables in\npolicyengine-us are named around a second home.",
    "id": "mortgage_hints",
    "kind": "function",
    "line": 60,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.utils.mortgage_interest.impute_tax_unit_mortgage_balance_hints"
      ],
      "description": "Impute SCF-backed tax-unit mortgage balance hints for structural mortgage conversion.",
      "id": "mortgage_hints",
      "label": "Mortgage Balance Hint Imputation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/utils/mortgage_interest.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_mortgage_interest.py"
      ]
    },
    "object_path": "policyengine_us_data.utils.mortgage_interest.impute_tax_unit_mortgage_balance_hints",
    "signature": "def impute_tax_unit_mortgage_balance_hints(data: Dict[str, Dict[int, np.ndarray]], time_period: int) -> Dict[str, Dict[int, np.ndarray]]",
    "source_file": "policyengine_us_data/utils/mortgage_interest.py"
  },
  "normalize_local_h5_worker_response": {
    "docstring": "Normalize worker JSON into explicit fatal and nonfatal coordinator issues.",
    "id": "normalize_local_h5_worker_response",
    "kind": "function",
    "line": 148,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.worker_responses.normalize_worker_response"
      ],
      "description": "Normalize legacy worker JSON into explicit coordinator severity classes.",
      "id": "normalize_local_h5_worker_response",
      "label": "Normalize Local H5 Worker Response",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/build_outputs/worker_responses.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/build_outputs/test_worker_responses.py"
      ]
    },
    "object_path": "policyengine_us_data.build_outputs.worker_responses.normalize_worker_response",
    "signature": "def normalize_worker_response(*, worker_index: int, result: object) -> CoordinatorWorkerResult",
    "source_file": "policyengine_us_data/build_outputs/worker_responses.py"
  },
  "preprocess_puf": {
    "docstring": "",
    "id": "preprocess_puf",
    "kind": "function",
    "line": 633,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.puf.puf.preprocess_puf"
      ],
      "description": "Rename IRS variables and derive PolicyEngine-ready PUF tax inputs.",
      "id": "preprocess_puf",
      "label": "Preprocess PUF",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/puf/puf.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/datasets/test_irs_puf.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.puf.puf.preprocess_puf",
    "signature": "def preprocess_puf(puf: pd.DataFrame) -> pd.DataFrame",
    "source_file": "policyengine_us_data/datasets/puf/puf.py"
  },
  "promote_pipeline_run": {
    "docstring": "Promote a completed pipeline run to production.\n\n1. Verify run status is \"completed\"\n2. Promote every staged artifact in one Hugging Face commit\n3. Upload/copy every artifact to GCS\n4. Finalize release_manifest.json, tag the release, and update\n   version_manifest.json\n5. Update run status to \"promoted\"\n\nArgs:\n    run_id: The run ID to promote.\n    candidate_version: Candidate staging scope used for staged source files.\n    release_version: Stable version used for final release metadata.\n\nReturns:\n    Summary message.",
    "id": "promote_pipeline_run",
    "kind": "function",
    "line": 2091,
    "metadata": {
      "api_refs": [
        "modal_app.pipeline.promote_run"
      ],
      "artifacts_in": [
        "staged H5 files",
        "run metadata"
      ],
      "artifacts_out": [
        "production H5 release"
      ],
      "description": "Promote a completed staged pipeline run without re-running computation.",
      "id": "promote_pipeline_run",
      "label": "Promote Pipeline Run",
      "node_type": "entrypoint",
      "pathways": [
        "orchestration",
        "local_h5"
      ],
      "source_file": "modal_app/pipeline.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_pipeline.py"
      ]
    },
    "object_path": "modal_app.pipeline.promote_run",
    "signature": "def promote_run(run_id: str, candidate_version: str = '', release_version: str = '') -> str",
    "source_file": "modal_app/pipeline.py"
  },
  "puf_qrf_pass": {
    "docstring": "Run QRF imputation for PUF variables.\n\nStratified-subsamples PUF records (top 0.5% by AGI kept,\nrest randomly sampled to ~20K total), trains QRF, and\npredicts on CPS data.\n\nArgs:\n    data: CPS data dict.\n    time_period: Tax year.\n    puf_dataset: PUF dataset class or path.\n    dataset_path: Path to CPS h5 for computing\n        demographic predictors via Microsimulation.\n\nReturns:\n    Tuple of (y_full_imputations, y_override_imputations)\n    as dicts of {variable: np.ndarray}.",
    "id": "puf_qrf_pass",
    "kind": "function",
    "line": 914,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.puf_impute._run_qrf_imputation"
      ],
      "description": "Run Quantile Random Forest imputation from PUF tax variables onto CPS clone records.",
      "id": "puf_qrf_pass",
      "label": "PUF QRF Imputation Pass",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/puf_impute.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_calibration_puf_impute.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.puf_impute._run_qrf_imputation",
    "signature": "def _run_qrf_imputation(data: Dict[str, Dict[int, np.ndarray]], time_period: int, puf_dataset, dataset_path: Optional[str] = None) -> tuple",
    "source_file": "policyengine_us_data/calibration/puf_impute.py"
  },
  "qrf_pass2": {
    "docstring": "Replace PUF clone half of CPS-only variables with QRF predictions.\n\nAfter ``puf_clone_dataset()`` the CPS-only variables in the second\nhalf are naive copies of the CPS donor values. This function\nreplaces them with the second-stage QRF predictions that are\nconsistent with the clone's PUF-imputed income.\n\nArgs:\n    data: Extended dataset dict (already doubled).\n    predictions: DataFrame from ``_impute_cps_only_variables()``.\n    time_period: Tax year.\n    dataset_path: Path to CPS h5 file for entity mapping.\n\nReturns:\n    Modified data dict with CPS-only variables spliced in.",
    "id": "qrf_pass2",
    "kind": "function",
    "line": 825,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.extended_cps._splice_cps_only_predictions"
      ],
      "artifacts_in": [
        "cps_only_predictions"
      ],
      "artifacts_out": [
        "extended_cps_stage2"
      ],
      "description": "Writes second-stage CPS-only QRF predictions back into the PUF clone half of the extended CPS record set.",
      "id": "qrf_pass2",
      "label": "Splice CPS-Only Predictions",
      "node_type": "process",
      "pathways": [
        "data_build"
      ],
      "pydoc": true,
      "source_file": "policyengine_us_data/datasets/cps/extended_cps.py",
      "stability": "moving",
      "status": "transitional"
    },
    "object_path": "policyengine_us_data.datasets.cps.extended_cps._splice_cps_only_predictions",
    "signature": "def _splice_cps_only_predictions(data: dict, predictions: pd.DataFrame, time_period: int, dataset_path: str) -> dict",
    "source_file": "policyengine_us_data/datasets/cps/extended_cps.py"
  },
  "record_double": {
    "docstring": "Clone CPS data 2x and impute PUF variables on one half.\n\nThe first half keeps CPS values when CPS reports the variable.\nVariables absent from CPS get PUF QRF predictions on both halves\nso positive-weight CPS rows can support those calibration targets.\nThe second half still gets full PUF QRF imputation and starts with\nhousehold weights set to zero.\n\nArgs:\n    data: CPS dataset dict {variable: {time_period: array}}.\n    state_fips: State FIPS per household, shape (n_households,).\n    block_geoid: Optional 15-character Census block GEOID per household.\n    cd_geoid: Optional congressional district GEOID per household.\n    county_fips: Optional 5-digit county FIPS per household.\n    time_period: Tax year.\n    puf_dataset: PUF dataset class or path for QRF training.\n        If None, skips QRF (same as skip_qrf=True).\n    skip_qrf: If True, skip QRF imputation (for testing).\n    dataset_path: Path to CPS h5 file (needed for QRF to\n        compute demographic predictors via Microsimulation).\n\nReturns:\n    New data dict with doubled records.",
    "id": "record_double",
    "kind": "function",
    "line": 475,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.puf_impute.puf_clone_dataset"
      ],
      "artifacts_out": [
        "extended_cps_2024.h5"
      ],
      "description": "Double CPS records and populate the clone half with PUF-imputed tax variables.",
      "id": "record_double",
      "label": "PUF Clone Dataset",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/puf_impute.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_calibration_puf_impute.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.puf_impute.puf_clone_dataset",
    "signature": "def puf_clone_dataset(data: Dict[str, Dict[int, np.ndarray]], state_fips: np.ndarray, block_geoid: Optional[np.ndarray] = None, cd_geoid: Optional[np.ndarray] = None, county_fips: Optional[np.ndarray] = None, time_period: int = 2024, puf_dataset = None, skip_qrf: bool = False, dataset_path: Optional[str] = None) -> Dict[str, Dict[int, np.ndarray]]",
    "source_file": "policyengine_us_data/calibration/puf_impute.py"
  },
  "release_artifact_spec": {
    "docstring": "Normalized identity for one artifact in a Stage 5 release candidate.",
    "id": "release_artifact_spec",
    "kind": "class",
    "line": 61,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.artifacts.ReleaseArtifactSpec"
      ],
      "description": "Normalized per-artifact identity for a Stage 5 release candidate.",
      "id": "release_artifact_spec",
      "label": "ReleaseArtifactSpec",
      "node_type": "library",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/artifacts.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_candidate.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.artifacts.ReleaseArtifactSpec",
    "signature": "class ReleaseArtifactSpec",
    "source_file": "policyengine_us_data/release_promotion/artifacts.py"
  },
  "release_candidate_input_bundle": {
    "docstring": "Typed Stage 5 input bundle describing a candidate ready for promotion.",
    "id": "release_candidate_input_bundle",
    "kind": "class",
    "line": 50,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.candidate.ReleaseCandidateInputBundle"
      ],
      "description": "Typed Stage 5 input bundle describing artifacts eligible for release promotion.",
      "id": "release_candidate_input_bundle",
      "label": "ReleaseCandidateInputBundle",
      "node_type": "library",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/candidate.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_candidate.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.candidate.ReleaseCandidateInputBundle",
    "signature": "class ReleaseCandidateInputBundle",
    "source_file": "policyengine_us_data/release_promotion/candidate.py"
  },
  "release_candidate_shape_report": {
    "docstring": "Describe candidate-bundle shape using the shared validation schema.",
    "id": "release_candidate_shape_report",
    "kind": "function",
    "line": 103,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.validation.build_release_candidate_shape_report"
      ],
      "description": "Adapt Stage 5 release-candidate shape checks into the canonical validation report schema.",
      "id": "release_candidate_shape_report",
      "label": "Release Candidate Shape Report",
      "node_type": "validation",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/validation.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_candidate.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.validation.build_release_candidate_shape_report",
    "signature": "def build_release_candidate_shape_report(bundle: ReleaseCandidateInputBundle) -> ValidationReport",
    "source_file": "policyengine_us_data/release_promotion/validation.py"
  },
  "release_candidate_validator": {
    "docstring": "Validate a Stage 5 release candidate before public release writes.",
    "id": "release_candidate_validator",
    "kind": "class",
    "line": 166,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.validation.ReleaseCandidateValidator"
      ],
      "artifacts_in": [
        "ReleaseCandidateInputBundle",
        "staged release artifacts"
      ],
      "artifacts_out": [
        "ValidationReport"
      ],
      "description": "Stage 5 validation-core adapter for release candidates before promotion side effects.",
      "id": "release_candidate_validator",
      "label": "ReleaseCandidateValidator",
      "node_type": "validation",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/validation.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_validation.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.validation.ReleaseCandidateValidator",
    "signature": "class ReleaseCandidateValidator",
    "source_file": "policyengine_us_data/release_promotion/validation.py"
  },
  "release_promotion_context": {
    "docstring": "Canonical run, candidate, release, and destination identity for Stage 5.",
    "id": "release_promotion_context",
    "kind": "class",
    "line": 44,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.context.ReleasePromotionContext"
      ],
      "description": "Typed Stage 5 run, candidate, release, and destination identity.",
      "id": "release_promotion_context",
      "label": "ReleasePromotionContext",
      "node_type": "library",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/context.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_candidate.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.context.ReleasePromotionContext",
    "signature": "class ReleasePromotionContext",
    "source_file": "policyengine_us_data/release_promotion/context.py"
  },
  "release_promotion_contract_builder": {
    "docstring": "Build a Stage 5 contract from candidate identity and promotion results.",
    "id": "release_promotion_contract_builder",
    "kind": "class",
    "line": 71,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.contract.ReleasePromotionContractBuilder"
      ],
      "artifacts_in": [
        "release candidate bundle",
        "typed promotion result"
      ],
      "artifacts_out": [
        "release_promotion_contract.json"
      ],
      "description": "Build the canonical Stage 5 release promotion contract.",
      "id": "release_promotion_contract_builder",
      "label": "ReleasePromotionContractBuilder",
      "node_type": "library",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/contract.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_contract.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.contract.ReleasePromotionContractBuilder",
    "signature": "class ReleasePromotionContractBuilder",
    "source_file": "policyengine_us_data/release_promotion/contract.py"
  },
  "resolve_scope_fingerprint": {
    "docstring": "Compute the scope fingerprint while preserving pinned resume values.",
    "id": "resolve_scope_fingerprint",
    "kind": "function",
    "line": 458,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_outputs.fingerprinting.FingerprintingService",
        "modal_app.local_area._resolve_scope_fingerprint"
      ],
      "description": "Compute the regional or national local H5 fingerprint from publishing inputs.",
      "id": "resolve_scope_fingerprint",
      "label": "Resolve Scope Fingerprint",
      "node_type": "library",
      "pathways": [
        "local_h5"
      ],
      "source_file": "modal_app/local_area.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_local_area.py"
      ]
    },
    "object_path": "modal_app.local_area._resolve_scope_fingerprint",
    "signature": "def _resolve_scope_fingerprint(*, inputs: PublishingInputBundle, scope: str, expected_fingerprint: str = '') -> str",
    "source_file": "modal_app/local_area.py"
  },
  "retire_impute": {
    "docstring": "Impute retirement contributions for the PUF half using QRF.\n\nTrains on CPS data (which has realistic income-to-contribution\nrelationships) and predicts onto PUF clone records using\nPUF-imputed income as input features.\n\nNote: ``pre_tax_contributions`` is separately imputed from PUF\nvia OVERRIDDEN_IMPUTED_VARIABLES.  In PolicyEngine it is a\nformula (``adds`` of traditional_401k + traditional_403b + \u2026),\nso the stored value is only used when the formula is bypassed.\nA future improvement could reconcile or drop the stored\npre_tax_contributions in favour of the formula sum.\n\nArgs:\n    data: CPS data dict.\n    puf_imputations: Dict of PUF-imputed variable arrays.\n    time_period: Tax year.\n    dataset_path: Path to CPS h5 for Microsimulation.\n\nReturns:\n    Dict mapping retirement variable names to imputed arrays.\n    Returns all-zeros on QRF failure.",
    "id": "retire_impute",
    "kind": "function",
    "line": 769,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.puf_impute._impute_retirement_contributions"
      ],
      "description": "Impute and constrain retirement contribution inputs on the PUF clone half.",
      "id": "retire_impute",
      "label": "Retirement Contribution Imputation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/puf_impute.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_calibration_puf_impute.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.puf_impute._impute_retirement_contributions",
    "signature": "def _impute_retirement_contributions(data: Dict[str, Dict[int, np.ndarray]], puf_imputations: Dict[str, np.ndarray], time_period: int, dataset_path: str) -> Dict[str, np.ndarray]",
    "source_file": "policyengine_us_data/calibration/puf_impute.py"
  },
  "reweight": {
    "docstring": "",
    "id": "reweight",
    "kind": "function",
    "line": 487,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.cps.enhanced_cps.reweight"
      ],
      "artifacts_in": [
        "loss_matrix",
        "calibration_targets"
      ],
      "artifacts_out": [
        "enhanced_cps_weights"
      ],
      "description": "Fits enhanced CPS weights against calibration targets with the hard-concrete loss machinery.",
      "id": "reweight",
      "label": "Enhanced CPS Reweighting",
      "node_type": "process",
      "pathways": [
        "data_build"
      ],
      "pydoc": true,
      "source_file": "policyengine_us_data/datasets/cps/enhanced_cps.py",
      "stability": "moving",
      "status": "transitional"
    },
    "object_path": "policyengine_us_data.datasets.cps.enhanced_cps.reweight",
    "signature": "def reweight(original_weights, loss_matrix, targets_array, log_path = 'calibration_log.csv', epochs = 500, l0_lambda = 2.6445e-07, init_mean = 0.999, temperature = 0.25, seed = 1456)",
    "source_file": "policyengine_us_data/datasets/cps/enhanced_cps.py"
  },
  "run_calibration": {
    "docstring": "Run unified calibration pipeline.\n\nArgs:\n    dataset_path: Path to CPS h5 file.\n    db_path: Path to policy_data.db.\n    n_clones: Number of dataset clones.\n    lambda_l0: L0 regularization strength.\n    epochs: Training epochs.\n    device: Torch device.\n    seed: Random seed.\n    domain_variables: Filter targets by domain variable.\n    hierarchical_domains: Domains for hierarchical\n        uprating + CD reconciliation.\n    skip_takeup_rerandomize: Skip takeup step.\n    skip_source_impute: Skip ACS/SIPP/SCF imputations.\n    target_config: Parsed target config dict.\n    target_config_path: Path to target config, for provenance.\n    target_config_identity: Resolved target config path/checksum identity.\n    build_only: If True, save package and skip fitting.\n    package_path: Load pre-built package (skip build).\n    package_output_path: Where to save calibration package.\n    beta: L0 gate temperature.\n    lambda_l2: L2 regularization strength.\n    learning_rate: Optimizer learning rate.\n    log_freq: Epochs between per-target CSV logs.\n    log_path: Path for per-target calibration log CSV.\n    resume_from: Path to a checkpoint or weights file to\n        continue fitting from.\n    checkpoint_path: Where to save resumable fit checkpoints.\n    chunked_matrix: Build matrix in clone-household chunks.\n    chunk_size: Clone-household columns per chunk.\n    chunk_dir: Directory for chunked COO/H5 artifacts.\n    keep_chunks: Keep temporary chunk H5 files.\n    resume_chunks: Reuse existing chunk COO files.\n\nReturns:\n    (weights, targets_df, X_sparse, target_names, geography_info)\n    weights is None when build_only=True.\n    geography_info is a dict with cd_geoid and base_n_records.",
    "id": "run_calibration",
    "kind": "function",
    "line": 1371,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_calibration.run_calibration"
      ],
      "artifacts_in": [
        "source_imputed_stratified_extended_cps*.h5",
        "policy_data.db"
      ],
      "artifacts_out": [
        "calibration_package.pkl",
        "calibration_weights.npy",
        "unified_diagnostics.csv",
        "unified_run_config.json"
      ],
      "description": "Build or load the calibration package, fit sparse weights, and write diagnostics.",
      "details": "This remains a bundled orchestration function; decorators document the semantic pathway until the implementation is further decomposed.",
      "id": "run_calibration",
      "label": "Run Unified Calibration",
      "node_type": "entrypoint",
      "pathways": [
        "calibration_package",
        "weight_fit"
      ],
      "source_file": "policyengine_us_data/calibration/unified_calibration.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_unified_calibration.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_calibration.run_calibration",
    "signature": "def run_calibration(dataset_path: str, db_path: str, n_clones: int = DEFAULT_N_CLONES, lambda_l0: float = 1e-08, epochs: int = DEFAULT_EPOCHS, device: str = 'cpu', seed: int = 42, domain_variables: list = None, hierarchical_domains: list = None, skip_takeup_rerandomize: bool = False, skip_source_impute: bool = True, skip_county: bool = True, target_config: dict = None, target_config_path: str = None, target_config_identity: TargetConfigIdentity | None = None, build_only: bool = False, package_path: str = None, package_output_path: str = None, beta: float = BETA, lambda_l2: float = LAMBDA_L2, learning_rate: float = LEARNING_RATE, log_freq: int = None, log_path: str = None, workers: int = 1, resume_from: str = None, checkpoint_path: str = None, chunked_matrix: bool = False, chunk_size: int = 25000, chunk_dir: str = None, keep_chunks: bool = False, resume_chunks: bool = False, parallel: bool = False, num_matrix_workers: int = 50, run_id: str = '')",
    "source_file": "policyengine_us_data/calibration/unified_calibration.py"
  },
  "run_local_h5_phase": {
    "docstring": "Run a single build phase, spawning workers and collecting results.\n\nReturns:\n    A tuple of (volume_completed, phase_errors, validation_rows)\n    where phase_errors is a list of error dicts from workers\n    and crashes, and validation_rows is a list of per-target\n    validation result dicts.",
    "id": "run_local_h5_phase",
    "kind": "function",
    "line": 754,
    "metadata": {
      "api_refs": [
        "modal_app.local_area.run_phase"
      ],
      "artifacts_out": [
        "staged phase outputs"
      ],
      "description": "Spawn local H5 workers for one partitioned build phase and record completed outputs.",
      "id": "run_local_h5_phase",
      "label": "Run Local H5 Worker Phase",
      "node_type": "entrypoint",
      "pathways": [
        "local_h5"
      ],
      "source_file": "modal_app/local_area.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_local_area.py"
      ]
    },
    "object_path": "modal_app.local_area.run_phase",
    "signature": "def run_phase(phase_name: str, weighted_requests: Sequence[WeightedAreaRequest] | None, num_workers: int, completed: set, branch: str, run_id: str, calibration_inputs: WorkerCalibrationInputs | Mapping[str, object], run_dir: Path, validate: bool = True, scope_fingerprint: str | None = None, work_items: List[Dict] | None = None) -> tuple",
    "source_file": "modal_app/local_area.py"
  },
  "run_modal_pipeline": {
    "docstring": "Run the full pipeline end-to-end.\n\nArgs:\n    branch: Git branch to build from.\n    gpu: GPU type for regional calibration.\n    epochs: Training epochs for regional calibration.\n    national_gpu: GPU type for national calibration.\n    national_epochs: Training epochs for national.\n    num_workers: Number of parallel H5 workers.\n    n_clones: Number of clones for H5 building.\n    skip_national: Skip national calibration/H5.\n    resume_run_id: Resume a previously failed run.\n    clear_checkpoints: Wipe ALL checkpoints before building\n        (default False). Normally not needed \u2014 checkpoints are\n        scoped by commit SHA, so stale ones from other commits\n        are cleaned automatically. Use True only to force a\n        full rebuild of the current commit.\n    candidate_version: Candidate staging scope used for HF staging.\n    release_version: Final stable release version. Usually empty until\n        promotion.\n    base_release_version: Stable release current when this candidate was\n        built.\n    release_bump: Intended SemVer bump for this candidate.\n    sha_override: Exact source SHA deployed by GitHub Actions. When\n        provided, this is recorded instead of reading the current\n        branch tip.\n    run_id: Cross-system run ID created by GitHub.\n    run_context: Serialized run context from the launcher workflow.\n    modal_app_name: Deployed Modal app name for this run.\n    modal_environment: Modal environment used for this run.\n    chunked_matrix: Build the calibration matrix in clone-household\n        chunks instead of the non-chunked path. Opt-in; default off.\n    chunk_size: Clone-household columns per chunk when\n        ``chunked_matrix`` is True.\n    parallel_matrix: Fan chunked matrix building across Modal\n        workers via ``build_matrix_chunk_worker``. Only meaningful\n        when ``chunked_matrix`` is True; ignored otherwise.\n    num_matrix_workers: Number of Modal workers when\n        ``parallel_matrix`` is True.\n\nReturns:\n    The run ID for use with promote.",
    "id": "run_modal_pipeline",
    "kind": "function",
    "line": 1113,
    "metadata": {
      "api_refs": [
        "modal_app.pipeline.run_pipeline"
      ],
      "artifacts_out": [
        "run metadata",
        "diagnostics",
        "published H5 artifacts"
      ],
      "description": "Coordinate data build, calibration package, weight fit, local H5 publishing, validation, and promotion.",
      "details": "This is the current production orchestration surface. It remains documented as a bundled pathway while lower-level seams are migrated.",
      "id": "run_modal_pipeline",
      "label": "Run Modal Pipeline",
      "node_type": "entrypoint",
      "pathways": [
        "orchestration"
      ],
      "source_file": "modal_app/pipeline.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_pipeline.py",
        "uv run pytest tests/integration/test_modal_pipeline_seams.py"
      ]
    },
    "object_path": "modal_app.pipeline.run_pipeline",
    "signature": "def run_pipeline(branch: str = 'main', gpu: str = 'T4', epochs: int = 1000, national_gpu: str = 'T4', national_epochs: int = 1000, num_workers: int = 50, n_clones: int = 430, skip_national: bool = False, resume_run_id: str = None, clear_checkpoints: bool = False, candidate_version: str = '', release_version: str = '', base_release_version: str = '', release_bump: str = '', sha_override: str = '', run_id: str = '', run_context: dict | None = None, modal_app_name: str = '', modal_environment: str = '', chunked_matrix: bool = False, chunk_size: int = 25000, parallel_matrix: bool = False, num_matrix_workers: int = 50) -> str",
    "source_file": "modal_app/pipeline.py"
  },
  "sanity_checks": {
    "docstring": "Run structural integrity checks on an H5 file.\n\nArgs:\n    h5_path: Path to the H5 dataset file.\n    period: Tax year (used for variable keys).\n\nReturns:\n    List of {check, status, detail} dicts.",
    "id": "sanity_checks",
    "kind": "function",
    "line": 331,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.sanity_checks.run_sanity_checks"
      ],
      "description": "Check calibrated H5 structure, weights, IDs, mappings, takeup, and aggregate sanity.",
      "id": "sanity_checks",
      "label": "Run H5 Sanity Checks",
      "node_type": "validation",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/sanity_checks.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_validate_staging.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.sanity_checks.run_sanity_checks",
    "signature": "def run_sanity_checks(h5_path: str, period: int = 2024) -> List[dict]",
    "source_file": "policyengine_us_data/calibration/sanity_checks.py"
  },
  "scf_qrf": {
    "docstring": "Impute net_worth and auto_loan from SCF.\n\nArgs:\n    data: CPS data dict.\n    state_fips: State FIPS per household.\n    time_period: Tax year.\n    dataset_path: Path to CPS h5 for Microsimulation.\n\nReturns:\n    Updated data dict.",
    "id": "scf_qrf",
    "kind": "function",
    "line": 1092,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.source_impute._impute_scf"
      ],
      "description": "Impute net worth and auto-loan variables from SCF donor data.",
      "id": "scf_qrf",
      "label": "SCF QRF Imputation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/source_impute.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_source_impute.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.source_impute._impute_scf",
    "signature": "def _impute_scf(data: Dict[str, Dict[int, np.ndarray]], state_fips: np.ndarray, time_period: int, dataset_path: Optional[str] = None) -> Dict[str, Dict[int, np.ndarray]]",
    "source_file": "policyengine_us_data/calibration/source_impute.py"
  },
  "simulate_qbi": {
    "docstring": "Simulate two Section 199A guard-rail quantities for every record\n  - W-2 wages paid by the business\n  - Unadjusted basis immediately after acquisition (UBIA) of property\n\nParameters\n----------\npuf : pandas.DataFrame\n    Must contain the income columns created in your preprocessing block.\nseed : int, optional\n    For reproducible random draws.\ndiagnostics : bool, default True\n    Print high-level checks after the simulation runs.\n\nReturns\n-------\nw2_wages : 1-D NumPy array\nubia     : 1-D NumPy array",
    "id": "simulate_qbi",
    "kind": "function",
    "line": 314,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.datasets.puf.puf.simulate_w2_and_ubia_from_puf"
      ],
      "description": "Simulate Section 199A W-2 wage and UBIA guardrail quantities from PUF income.",
      "id": "simulate_qbi",
      "label": "QBI Simulation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/datasets/puf/puf.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/datasets/test_irs_puf.py"
      ]
    },
    "object_path": "policyengine_us_data.datasets.puf.puf.simulate_w2_and_ubia_from_puf",
    "signature": "def simulate_w2_and_ubia_from_puf(puf, *, seed = None, diagnostics = True)",
    "source_file": "policyengine_us_data/datasets/puf/puf.py"
  },
  "sipp_qrf": {
    "docstring": "Impute tip_income, liquid assets, and vehicle signals from SIPP.\n\nArgs:\n    data: CPS data dict.\n    state_fips: State FIPS per household.\n    time_period: Tax year.\n    dataset_path: Path to CPS h5 for Microsimulation.\n\nReturns:\n    Updated data dict.",
    "id": "sipp_qrf",
    "kind": "function",
    "line": 633,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.source_impute._impute_sipp"
      ],
      "description": "Impute tips, liquid assets, and vehicle assets from SIPP donor data.",
      "id": "sipp_qrf",
      "label": "SIPP QRF Imputation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/source_impute.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_source_impute.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.source_impute._impute_sipp",
    "signature": "def _impute_sipp(data: Dict[str, Dict[int, np.ndarray]], state_fips: np.ndarray, time_period: int, dataset_path: Optional[str] = None) -> Dict[str, Dict[int, np.ndarray]]",
    "source_file": "policyengine_us_data/calibration/source_impute.py"
  },
  "source_impute": {
    "docstring": "Re-impute ACS/SIPP/ORG/SCF variables from donor surveys.\n\nOverwrites existing imputed values in data. ACS uses\nstate_fips as a QRF predictor; ORG uses state plus labor-market\npredictors; SIPP and SCF use only demographic and financial\npredictors (no state data).\n\nArgs:\n    data: CPS dataset dict {variable: {time_period: array}}.\n    state_fips: State FIPS per household.\n    time_period: Tax year.\n    dataset_path: Path to CPS h5 for Microsimulation.\n    skip_acs: Skip ACS imputation.\n    skip_sipp: Skip SIPP imputation.\n    skip_org: Skip ORG imputation.\n    skip_scf: Skip SCF imputation.\n\nReturns:\n    Updated data dict with re-imputed variables.",
    "id": "source_impute",
    "kind": "function",
    "line": 203,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.source_impute.impute_source_variables"
      ],
      "artifacts_in": [
        "stratified_extended_cps_2024.h5"
      ],
      "artifacts_out": [
        "source_imputed_stratified_extended_cps_2024.h5"
      ],
      "description": "Apply ACS, SIPP, ORG, and SCF donor imputations to the stratified CPS calibration input.",
      "id": "source_impute",
      "label": "Source-Impute Stratified CPS",
      "node_type": "entrypoint",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/source_impute.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_source_impute.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.source_impute.impute_source_variables",
    "signature": "def impute_source_variables(data: Dict[str, Dict[int, np.ndarray]], state_fips: np.ndarray, time_period: int = 2024, dataset_path: Optional[str] = None, skip_acs: bool = False, skip_sipp: bool = False, skip_org: bool = False, skip_scf: bool = False) -> Dict[str, Dict[int, np.ndarray]]",
    "source_file": "policyengine_us_data/calibration/source_impute.py"
  },
  "ss_reconcile": {
    "docstring": "Predict SS sub-components for PUF half from demographics.\n\nThe CPS-PUF link is statistical (not identity-based), so the\npaired CPS record's sub-component split is just one noisy draw.\nA QRF trained on all CPS SS recipients gives a better expected\nprediction by pooling across the full training set.\n\nFor all PUF records with positive social_security, this function\npredicts shares via QRF (falling back to an age heuristic) and\nscales them to match the imputed total. PUF records with zero\nSS get all sub-components cleared to zero.\n\nModifies ``data`` in place. Only the PUF half (indices\nn_cps .. 2*n_cps) is changed.\n\nArgs:\n    data: Dataset dict {variable: {time_period: array}}.\n    n_cps: Number of records in the CPS half.\n    time_period: Tax year key into data dicts.",
    "id": "ss_reconcile",
    "kind": "function",
    "line": 407,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.puf_impute.reconcile_ss_subcomponents"
      ],
      "description": "Scale imputed Social Security subcomponents so they reconcile to total Social Security.",
      "id": "ss_reconcile",
      "label": "Social Security Subcomponent Reconciliation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/puf_impute.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_calibration_puf_impute.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.puf_impute.reconcile_ss_subcomponents",
    "signature": "def reconcile_ss_subcomponents(data: Dict[str, Dict[int, np.ndarray]], n_cps: int, time_period: int) -> None",
    "source_file": "policyengine_us_data/calibration/puf_impute.py"
  },
  "stage2_artifact_specs": {
    "docstring": "Return canonical Stage 2 paths rooted in an artifacts directory.",
    "id": "stage2_artifact_specs",
    "kind": "function",
    "line": 488,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration_package.specs.calibration_package_artifact_paths"
      ],
      "artifacts_in": "[SOURCE_DATASET_FILENAME, TARGET_DATABASE_FILENAME]",
      "artifacts_out": "[CALIBRATION_PACKAGE_FILENAME, CALIBRATION_PACKAGE_METADATA_FILENAME, CALIBRATION_PACKAGE_CONTRACT_FILENAME]",
      "description": "Centralize Stage 2 input, package, contract, metadata, report, and matrix-build artifact names.",
      "id": "stage2_artifact_specs",
      "label": "Stage 2 Artifact Specs",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration_package/specs.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration_package/test_specs.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration_package.specs.calibration_package_artifact_paths",
    "signature": "def calibration_package_artifact_paths(artifacts_dir: str | Path) -> CalibrationPackageOutputBundle",
    "source_file": "policyengine_us_data/calibration_package/specs.py"
  },
  "stage2_build_context": {
    "docstring": "Return Stage 2 run context, preferring the Stage 1 handoff contract.",
    "id": "stage2_build_context",
    "kind": "function",
    "line": 431,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration_package.specs.stage2_build_context_for_run"
      ],
      "artifacts_in": "[DATASET_BUILD_OUTPUT_CONTRACT_FILENAME, SOURCE_DATASET_FILENAME, TARGET_DATABASE_FILENAME]",
      "artifacts_out": "[CALIBRATION_PACKAGE_FILENAME, CALIBRATION_PACKAGE_CONTRACT_FILENAME]",
      "description": "Bind one run_id to canonical Stage 2 input and output bundles before remote package construction starts.",
      "id": "stage2_build_context",
      "label": "Stage 2 Build Context",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration_package/specs.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration_package/test_specs.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration_package.specs.stage2_build_context_for_run",
    "signature": "def stage2_build_context_for_run(pipeline_mount: str | Path, run_id: str | None = '', *, stage1_contract_path: str | Path | None = None) -> Stage2BuildContext",
    "source_file": "policyengine_us_data/calibration_package/specs.py"
  },
  "stage2_calibration_package_contract_validator": {
    "docstring": "Validate that a Stage 2 sidecar describes the calibration package.",
    "id": "stage2_calibration_package_contract_validator",
    "kind": "function",
    "line": 252,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.stage_contracts.calibration_package.validate_calibration_package_contract"
      ],
      "artifacts_in": "['calibration_package.pkl', CALIBRATION_PACKAGE_CONTRACT_FILENAME]",
      "description": "Validate that the persisted Stage 2 contract describes the calibration package and inputs.",
      "id": "stage2_calibration_package_contract_validator",
      "label": "Stage 2 Contract Validator",
      "node_type": "validation",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/stage_contracts/calibration_package.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_calibration_package_stage_contract.py"
      ]
    },
    "object_path": "policyengine_us_data.stage_contracts.calibration_package.validate_calibration_package_contract",
    "signature": "def validate_calibration_package_contract(*, package_path: Path, contract_path: Path | None = None, package: CalibrationPackagePayload | Mapping[str, Any] | None = None, dataset_path: Path | None = None, db_path: Path | None = None) -> StageContract",
    "source_file": "policyengine_us_data/stage_contracts/calibration_package.py"
  },
  "stage2_calibration_package_contract_writer": {
    "docstring": "Write and return the Stage 2 calibration-package contract.",
    "id": "stage2_calibration_package_contract_writer",
    "kind": "function",
    "line": 195,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.stage_contracts.calibration_package.write_calibration_package_contract"
      ],
      "artifacts_in": [
        "calibration_package.pkl"
      ],
      "artifacts_out": "[CALIBRATION_PACKAGE_CONTRACT_FILENAME]",
      "description": "Write the Stage 2 calibration-package handoff contract next to the package artifact.",
      "id": "stage2_calibration_package_contract_writer",
      "label": "Stage 2 Contract Writer",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/stage_contracts/calibration_package.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_calibration_package_stage_contract.py"
      ]
    },
    "object_path": "policyengine_us_data.stage_contracts.calibration_package.write_calibration_package_contract",
    "signature": "def write_calibration_package_contract(*, package_path: Path, dataset_path: Path, db_path: Path, package: CalibrationPackagePayload | Mapping[str, Any], parameters: CalibrationPackageParameters | Mapping[str, Any], run_id: str | None, completed_at: str, started_at: str | None = None, duration_s: float | None = None, code_sha: str | None = None, package_version: str | None = None, contract_path: Path | None = None) -> StageContract",
    "source_file": "policyengine_us_data/stage_contracts/calibration_package.py"
  },
  "stage2_calibration_package_writer": {
    "docstring": "Save calibration package to pickle.\n\nArgs:\n    path: Output file path.\n    X_sparse: Sparse matrix.\n    targets_df: Targets DataFrame.\n    target_names: Target name list.\n    metadata: Run metadata dict.\n    initial_weights: Pre-computed initial weight array.\n    cd_geoid: CD GEOID array from geography assignment.\n    block_geoid: Block GEOID array from geography assignment.",
    "id": "stage2_calibration_package_writer",
    "kind": "function",
    "line": 663,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_calibration.save_calibration_package"
      ],
      "artifacts_out": [
        "calibration_package.pkl"
      ],
      "description": "Persist the Stage 2 sparse matrix, target rows, target names, geography arrays, and provenance metadata.",
      "id": "stage2_calibration_package_writer",
      "label": "Stage 2 Package Writer",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/unified_calibration.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_unified_calibration.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_calibration.save_calibration_package",
    "signature": "def save_calibration_package(path: str, X_sparse, targets_df: 'pd.DataFrame', target_names: list, metadata: dict, initial_weights: np.ndarray = None, cd_geoid: np.ndarray = None, block_geoid: np.ndarray = None) -> None",
    "source_file": "policyengine_us_data/calibration/unified_calibration.py"
  },
  "stage2_input_bundle": {
    "docstring": "Return a compatibility Stage 2 input bundle from canonical filenames.",
    "id": "stage2_input_bundle",
    "kind": "function",
    "line": 331,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration_package.specs.stage2_input_bundle_from_artifacts_dir"
      ],
      "artifacts_in": "[DATASET_BUILD_OUTPUT_CONTRACT_FILENAME, SOURCE_DATASET_FILENAME, TARGET_DATABASE_FILENAME]",
      "description": "Resolve the source-imputed dataset and policy target database from a Stage 1 contract or compatibility filename fallback.",
      "id": "stage2_input_bundle",
      "label": "Stage 2 Input Bundle",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration_package/specs.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration_package/test_specs.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration_package.specs.stage2_input_bundle_from_artifacts_dir",
    "signature": "def stage2_input_bundle_from_artifacts_dir(artifacts_dir: str | Path) -> Stage2InputBundle",
    "source_file": "policyengine_us_data/calibration_package/specs.py"
  },
  "stage2_payload_boundary": {
    "docstring": "Typed access to the dictionary persisted in `calibration_package.pkl`.",
    "id": "stage2_payload_boundary",
    "kind": "class",
    "line": 114,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration_package.payload.CalibrationPackagePayload"
      ],
      "artifacts_in": "[CALIBRATION_PACKAGE_FILENAME]",
      "description": "Typed access to the calibration_package.pkl matrix, targets, metadata, geography arrays, and compatibility warnings.",
      "id": "stage2_payload_boundary",
      "label": "Stage 2 Package Payload",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration_package/payload.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration_package/test_payload.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration_package.payload.CalibrationPackagePayload",
    "signature": "class CalibrationPackagePayload",
    "source_file": "policyengine_us_data/calibration_package/payload.py"
  },
  "stage2_payload_reader": {
    "docstring": "Read typed Stage 2 package payloads from disk.",
    "id": "stage2_payload_reader",
    "kind": "class",
    "line": 328,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration_package.payload.CalibrationPackageReader"
      ],
      "artifacts_in": "[CALIBRATION_PACKAGE_FILENAME]",
      "description": "Load calibration_package.pkl through the typed Stage 2 payload boundary and expose checksum/summary material.",
      "id": "stage2_payload_reader",
      "label": "Stage 2 Payload Reader",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration_package/payload.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration_package/test_payload.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration_package.payload.CalibrationPackageReader",
    "signature": "class CalibrationPackageReader",
    "source_file": "policyengine_us_data/calibration_package/payload.py"
  },
  "stage2_payload_writer": {
    "docstring": "Write typed Stage 2 package payloads and metadata sidecars.",
    "id": "stage2_payload_writer",
    "kind": "class",
    "line": 385,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration_package.payload.CalibrationPackageWriter"
      ],
      "artifacts_out": "[CALIBRATION_PACKAGE_FILENAME, CALIBRATION_PACKAGE_METADATA_FILENAME]",
      "description": "Persist calibration_package.pkl and derive calibration_package_meta.json from typed payload and contract material.",
      "id": "stage2_payload_writer",
      "label": "Stage 2 Payload Writer",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration_package/payload.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration_package/test_payload.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration_package.payload.CalibrationPackageWriter",
    "signature": "class CalibrationPackageWriter",
    "source_file": "policyengine_us_data/calibration_package/payload.py"
  },
  "stage2_target_config_apply": {
    "docstring": "Filter target rows before matrix construction.",
    "id": "stage2_target_config_apply",
    "kind": "function",
    "line": 633,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_calibration.apply_target_config_to_targets"
      ],
      "description": "Apply Stage 2 target include/exclude rules before matrix construction.",
      "id": "stage2_target_config_apply",
      "label": "Apply Stage 2 Target Config",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/unified_calibration.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_target_config.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_calibration.apply_target_config_to_targets",
    "signature": "def apply_target_config_to_targets(targets_df: 'pd.DataFrame', config: dict) -> 'pd.DataFrame'",
    "source_file": "policyengine_us_data/calibration/unified_calibration.py"
  },
  "stage2_target_config_identity": {
    "docstring": "Resolve the target config identity used by Stage 2 package construction.",
    "id": "stage2_target_config_identity",
    "kind": "function",
    "line": 520,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration_package.specs.resolve_target_config_identity"
      ],
      "artifacts_in": "[DEFAULT_TARGET_CONFIG_PATH]",
      "description": "Resolve the effective Stage 2 target config path and checksum before package reuse or rebuild.",
      "id": "stage2_target_config_identity",
      "label": "Stage 2 Target Config Identity",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration_package/specs.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration_package/test_specs.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration_package.specs.resolve_target_config_identity",
    "signature": "def resolve_target_config_identity(target_config_path: str | Path | None = None, *, all_active_targets: bool = False, repo_root: str | Path | None = None) -> TargetConfigIdentity",
    "source_file": "policyengine_us_data/calibration_package/specs.py"
  },
  "stage2_target_config_load": {
    "docstring": "Load target include/exclude config from YAML.\n\nArgs:\n    path: Path to YAML config file.\n\nReturns:\n    Parsed config dict with include and exclude lists.",
    "id": "stage2_target_config_load",
    "kind": "function",
    "line": 527,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_calibration.load_target_config"
      ],
      "artifacts_in": "[DEFAULT_TARGET_CONFIG_RELATIVE_PATH]",
      "description": "Load the YAML include/exclude target-selection config used by Stage 2 package construction.",
      "id": "stage2_target_config_load",
      "label": "Load Stage 2 Target Config",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/unified_calibration.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_target_config.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_calibration.load_target_config",
    "signature": "def load_target_config(path: str) -> dict",
    "source_file": "policyengine_us_data/calibration/unified_calibration.py"
  },
  "stage4_release_candidate_bundle_builder": {
    "docstring": "Build a candidate bundle from a Stage 4 output contract shape.",
    "id": "stage4_release_candidate_bundle_builder",
    "kind": "function",
    "line": 48,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.stage4_reader.build_release_candidate_bundle_from_stage4_contract"
      ],
      "description": "Build a Stage 5 candidate bundle from Stage 4 contract and inventory records.",
      "id": "stage4_release_candidate_bundle_builder",
      "label": "Stage 4 Release Candidate Bundle Builder",
      "node_type": "library",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/stage4_reader.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_candidate.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.stage4_reader.build_release_candidate_bundle_from_stage4_contract",
    "signature": "def build_release_candidate_bundle_from_stage4_contract(*, context: ReleasePromotionContext, output_contract: StageContract, inventory_records: Iterable[Mapping[str, Any]] = (), source_output_contract_path: str | None = None, validation_report_paths: Sequence[str] = (), validation_report_refs: Sequence[DiagnosticRef] = (), diagnostics_manifest_path: str | None = None) -> ReleaseCandidateInputBundle",
    "source_file": "policyengine_us_data/release_promotion/stage4_reader.py"
  },
  "stage4_release_candidate_bundle_reader": {
    "docstring": "Read a candidate bundle from Stage 4 contract and optional inventory files.",
    "id": "stage4_release_candidate_bundle_reader",
    "kind": "function",
    "line": 126,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.release_promotion.stage4_reader.read_stage4_release_candidate_bundle"
      ],
      "description": "Read Stage 4 output contract and inventory files into a Stage 5 candidate bundle.",
      "id": "stage4_release_candidate_bundle_reader",
      "label": "Stage 4 Release Candidate Bundle Reader",
      "node_type": "library",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/release_promotion/stage4_reader.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_candidate.py"
      ]
    },
    "object_path": "policyengine_us_data.release_promotion.stage4_reader.read_stage4_release_candidate_bundle",
    "signature": "def read_stage4_release_candidate_bundle(*, context: ReleasePromotionContext, output_contract_path: str | Path, output_inventory_path: str | Path | None = None, source_output_contract_path: str | None = None, validation_report_paths: Sequence[str] = (), validation_report_refs: Sequence[DiagnosticRef] = (), diagnostics_manifest_path: str | None = None) -> ReleaseCandidateInputBundle",
    "source_file": "policyengine_us_data/release_promotion/stage4_reader.py"
  },
  "stage_1_dataset_artifact_specs": {
    "docstring": "Return all artifact specs known to the Stage 1 dataset build.",
    "id": "stage_1_dataset_artifact_specs",
    "kind": "function",
    "line": 285,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_datasets.artifacts.stage_1_artifact_specs"
      ],
      "artifacts_out": [
        "uprating_factors.csv",
        "acs_2022.h5",
        "irs_puf_2015.h5",
        "cps_2024.h5",
        "puf_2024.h5",
        "extended_cps_2024.h5",
        "enhanced_cps_2024.h5",
        "enhanced_cps_2024.clone_diagnostics.json",
        "calibration_log.csv",
        "stratified_extended_cps_2024.h5",
        "source_imputed_stratified_extended_cps_2024.h5",
        "small_enhanced_cps_2024.h5",
        "source_imputed_stratified_extended_cps.h5",
        "policy_data.db",
        "calibration_weights.npy",
        "build_log.txt",
        "data_build_checkpoint_stats.json",
        "dataset_inventory.json",
        "source_dataset_schema_summary.json",
        "target_database_schema_summary.json"
      ],
      "description": "Canonical artifact inventory for Stage 1 dataset-build outputs.",
      "id": "stage_1_dataset_artifact_specs",
      "label": "Stage 1 Dataset Artifact Specs",
      "node_type": "library",
      "pathways": [
        "data_build",
        "stage_contracts",
        "pipeline_docs"
      ],
      "source_file": "policyengine_us_data/build_datasets/artifacts.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_build_dataset_specs.py"
      ]
    },
    "object_path": "policyengine_us_data.build_datasets.artifacts.stage_1_artifact_specs",
    "signature": "def stage_1_artifact_specs() -> tuple[DatasetArtifactSpec, ...]",
    "source_file": "policyengine_us_data/build_datasets/artifacts.py"
  },
  "stage_1_dataset_build_specs": {
    "docstring": "Return the canonical Stage 1 dataset-build substage specs.",
    "id": "stage_1_dataset_build_specs",
    "kind": "function",
    "line": 87,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.build_datasets.specs.stage_1_step_specs"
      ],
      "description": "Canonical substage taxonomy for Stage 1 dataset-build contracts, step manifests, and pipeline documentation.",
      "id": "stage_1_dataset_build_specs",
      "label": "Stage 1 Dataset Build Specs",
      "node_type": "library",
      "pathways": [
        "data_build",
        "stage_contracts",
        "pipeline_docs"
      ],
      "source_file": "policyengine_us_data/build_datasets/specs.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_build_dataset_specs.py"
      ]
    },
    "object_path": "policyengine_us_data.build_datasets.specs.stage_1_step_specs",
    "signature": "def stage_1_step_specs() -> tuple[DatasetBuildStepSpec, ...]",
    "source_file": "policyengine_us_data/build_datasets/specs.py"
  },
  "staging_upload": {
    "docstring": "Upload files to HuggingFace staging only.\n\nGCS is updated during promote_publish, not here.\nPromote must be run separately via promote_publish.",
    "id": "staging_upload",
    "kind": "function",
    "line": 1103,
    "metadata": {
      "api_refs": [
        "modal_app.local_area.upload_to_staging"
      ],
      "artifacts_in": [
        "staged local-area H5 files"
      ],
      "description": "Upload completed local H5 outputs to staging storage before promotion.",
      "id": "staging_upload",
      "label": "Upload Local H5s To Staging",
      "node_type": "entrypoint",
      "pathways": [
        "local_h5"
      ],
      "source_file": "modal_app/local_area.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_local_area.py"
      ]
    },
    "object_path": "modal_app.local_area.upload_to_staging",
    "signature": "def upload_to_staging(branch: str, version: str, manifest: Dict, run_id: str = '', candidate_version: str = '') -> str",
    "source_file": "modal_app/local_area.py"
  },
  "state_precomp": {
    "docstring": "Compute household/person/entity values for one state.\n\nTop-level function (not a method) so it is picklable for\n``ProcessPoolExecutor``.\n\nArgs:\n    dataset_path: Path to the base CPS h5 file.\n    time_period: Tax year for simulation.\n    state: State FIPS code.\n    n_hh: Number of household records.\n    target_vars: Target variable names (list for determinism).\n    constraint_vars: Constraint variable names (list).\n    rerandomize_takeup: Force takeup=True if True.\n    affected_targets: Takeup-affected target info dict.\n\nReturns:\n    (state_fips, {\"hh\": {...}, \"person\": {...}, \"entity\": {...}})",
    "id": "state_precomp",
    "kind": "function",
    "line": 234,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_matrix_builder._compute_single_state"
      ],
      "description": "Run state-specific Microsimulations used to assemble calibration matrix columns.",
      "id": "state_precomp",
      "label": "Per-State Simulation Precomputation",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_unified_matrix_builder.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_matrix_builder._compute_single_state",
    "signature": "def _compute_single_state(dataset_path: str, time_period: int, state: int, n_hh: int, target_vars: list, constraint_vars: list, variable_entity_map: dict, reform_vars: list, rerandomize_takeup: bool, affected_targets: dict)",
    "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py"
  },
  "target_validation": {
    "docstring": "",
    "id": "target_validation",
    "kind": "function",
    "line": 319,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.validate_staging.validate_area"
      ],
      "description": "Run microsimulation target comparisons for one staged area.",
      "id": "target_validation",
      "label": "Validate Area Against Targets",
      "node_type": "validation",
      "pathways": [
        "local_h5"
      ],
      "source_file": "policyengine_us_data/calibration/validate_staging.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_validate_staging.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.validate_staging.validate_area",
    "signature": "def validate_area(sim, targets_df: pd.DataFrame, engine, area_type: str, area_id: str, display_id: str, dataset_path: str, period: int, training_mask: np.ndarray, variable_entity_map: dict, constraints_map: Optional[dict] = None) -> list",
    "source_file": "policyengine_us_data/calibration/validate_staging.py"
  },
  "typed_full_release_promotion": {
    "docstring": "Run the existing transaction engine and wrap its output in a typed result.",
    "id": "typed_full_release_promotion",
    "kind": "function",
    "line": 171,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.utils.release_promotion.promote_full_release_with_result"
      ],
      "artifacts_in": [
        "staged release artifacts",
        "release manifest inputs"
      ],
      "artifacts_out": [
        "FullPromotionResult"
      ],
      "description": "Compatibility wrapper that returns typed Stage 5 promotion results from the existing transaction engine.",
      "id": "typed_full_release_promotion",
      "label": "Typed Full Release Promotion",
      "node_type": "library",
      "pathways": [
        "5_validate_and_promote_release"
      ],
      "source_file": "policyengine_us_data/utils/release_promotion.py",
      "stability": "moving",
      "status": "transitional",
      "validation_commands": [
        "uv run pytest tests/unit/release_promotion/test_results.py"
      ]
    },
    "object_path": "policyengine_us_data.utils.release_promotion.promote_full_release_with_result",
    "signature": "def promote_full_release_with_result(config: FullReleasePromotionConfig, deps: FullReleasePromotionDependencies) -> 'FullPromotionResult'",
    "source_file": "policyengine_us_data/utils/release_promotion.py"
  },
  "unified_matrix_builder": {
    "docstring": "Build sparse calibration matrix for cloned CPS records.\n\nProcesses clone-by-clone: each clone's records get their\nassigned geography, are simulated, and the results fill\nthe corresponding columns.\n\nArgs:\n    db_uri: SQLAlchemy database URI.\n    time_period: Tax year for calibration (e.g. 2024).\n    dataset_path: Path to the base extended CPS h5 file.",
    "id": "unified_matrix_builder",
    "kind": "class",
    "line": 1450,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.unified_matrix_builder.UnifiedMatrixBuilder"
      ],
      "description": "Database-backed sparse matrix builder for national and local-area calibration.",
      "id": "unified_matrix_builder",
      "label": "UnifiedMatrixBuilder",
      "node_type": "library",
      "pathways": [
        "calibration_package"
      ],
      "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_unified_matrix_builder.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.unified_matrix_builder.UnifiedMatrixBuilder",
    "signature": "class UnifiedMatrixBuilder",
    "source_file": "policyengine_us_data/calibration/unified_matrix_builder.py"
  },
  "validate_staging": {
    "docstring": "Validate all expected files and generate manifest.",
    "id": "validate_staging",
    "kind": "function",
    "line": 1033,
    "metadata": {
      "api_refs": [
        "modal_app.local_area.validate_staging"
      ],
      "description": "Run staged H5 validation before upload and promotion.",
      "id": "validate_staging",
      "label": "Validate Staged H5 Files",
      "node_type": "validation",
      "pathways": [
        "local_h5"
      ],
      "source_file": "modal_app/local_area.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_modal_local_area.py"
      ]
    },
    "object_path": "modal_app.local_area.validate_staging",
    "signature": "def validate_staging(branch: str, run_id: str, version: str = '') -> Dict",
    "source_file": "modal_app/local_area.py"
  },
  "validation_core_artifact_resolver": {
    "docstring": "Resolve logical validation artifact names to stage-contract references.",
    "id": "validation_core_artifact_resolver",
    "kind": "class",
    "line": 71,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.validation_core.context.ValidationArtifactResolver"
      ],
      "description": "Resolve logical validation artifact names to canonical stage-contract artifact references.",
      "id": "validation_core_artifact_resolver",
      "label": "ValidationArtifactResolver",
      "node_type": "library",
      "pathways": [
        "cross_stage_validation"
      ],
      "source_file": "policyengine_us_data/validation_core/context.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_validation_core.py"
      ]
    },
    "object_path": "policyengine_us_data.validation_core.context.ValidationArtifactResolver",
    "signature": "class ValidationArtifactResolver",
    "source_file": "policyengine_us_data/validation_core/context.py"
  },
  "validation_core_check": {
    "docstring": "One executable validation check with stable identity and dependencies.",
    "id": "validation_core_check",
    "kind": "class",
    "line": 63,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.validation_core.checks.ValidationCheck"
      ],
      "description": "Stable declaration for one executable validation check and its artifact dependencies.",
      "id": "validation_core_check",
      "label": "ValidationCheck",
      "node_type": "library",
      "pathways": [
        "cross_stage_validation"
      ],
      "source_file": "policyengine_us_data/validation_core/checks.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_validation_core.py"
      ]
    },
    "object_path": "policyengine_us_data.validation_core.checks.ValidationCheck",
    "signature": "class ValidationCheck",
    "source_file": "policyengine_us_data/validation_core/checks.py"
  },
  "validation_core_context": {
    "docstring": "Read-only context passed to validation checks.",
    "id": "validation_core_context",
    "kind": "class",
    "line": 119,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.validation_core.context.ValidationContext"
      ],
      "description": "Read-only cross-stage validation context with canonical stage identity.",
      "id": "validation_core_context",
      "label": "ValidationContext",
      "node_type": "library",
      "pathways": [
        "cross_stage_validation"
      ],
      "source_file": "policyengine_us_data/validation_core/context.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_validation_core.py"
      ]
    },
    "object_path": "policyengine_us_data.validation_core.context.ValidationContext",
    "signature": "class ValidationContext",
    "source_file": "policyengine_us_data/validation_core/context.py"
  },
  "validation_core_report_writer": {
    "docstring": "Write validation report outputs generated by output strategies.",
    "id": "validation_core_report_writer",
    "kind": "class",
    "line": 171,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.validation_core.writers.ValidationReportWriter"
      ],
      "artifacts_in": [
        "ValidationReport"
      ],
      "artifacts_out": [
        "validation_report.json",
        "validation_findings.jsonl"
      ],
      "description": "Write canonical validation artifacts using configurable output strategies.",
      "id": "validation_core_report_writer",
      "label": "ValidationReportWriter",
      "node_type": "library",
      "pathways": [
        "cross_stage_validation"
      ],
      "source_file": "policyengine_us_data/validation_core/writers.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_validation_core.py"
      ]
    },
    "object_path": "policyengine_us_data.validation_core.writers.ValidationReportWriter",
    "signature": "class ValidationReportWriter",
    "source_file": "policyengine_us_data/validation_core/writers.py"
  },
  "validation_core_runner": {
    "docstring": "Run validation suites and aggregate canonical stage-contract reports.",
    "id": "validation_core_runner",
    "kind": "class",
    "line": 35,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.validation_core.runner.ValidationRunner"
      ],
      "artifacts_out": [
        "ValidationReport"
      ],
      "description": "Shared runner that executes validation suites and aggregates canonical ValidationReport output.",
      "id": "validation_core_runner",
      "label": "ValidationRunner",
      "node_type": "library",
      "pathways": [
        "cross_stage_validation"
      ],
      "source_file": "policyengine_us_data/validation_core/runner.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_validation_core.py"
      ]
    },
    "object_path": "policyengine_us_data.validation_core.runner.ValidationRunner",
    "signature": "class ValidationRunner",
    "source_file": "policyengine_us_data/validation_core/runner.py"
  },
  "validation_core_suite": {
    "docstring": "Ordered validation checks for one stage or substage boundary.",
    "id": "validation_core_suite",
    "kind": "class",
    "line": 116,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.validation_core.checks.ValidationSuite"
      ],
      "description": "Ordered cross-stage validation suite for a canonical stage or substage boundary.",
      "id": "validation_core_suite",
      "label": "ValidationSuite",
      "node_type": "library",
      "pathways": [
        "cross_stage_validation"
      ],
      "source_file": "policyengine_us_data/validation_core/checks.py",
      "stability": "stable",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_validation_core.py"
      ]
    },
    "object_path": "policyengine_us_data.validation_core.checks.ValidationSuite",
    "signature": "class ValidationSuite",
    "source_file": "policyengine_us_data/validation_core/checks.py"
  },
  "verify_runtime_seams": {
    "docstring": "Verify deployed-image imports and subprocess seams.",
    "id": "verify_runtime_seams",
    "kind": "function",
    "line": 739,
    "metadata": {
      "api_refs": [
        "modal_app.pipeline.verify_runtime_seams"
      ],
      "description": "Check import, subprocess, baked-file, and Modal function seams before heavy pipeline execution.",
      "id": "verify_runtime_seams",
      "label": "Verify Modal Runtime Seams",
      "node_type": "validation",
      "pathways": [
        "orchestration"
      ],
      "source_file": "modal_app/pipeline.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/test_pipeline.py"
      ]
    },
    "object_path": "modal_app.pipeline.verify_runtime_seams",
    "signature": "def verify_runtime_seams() -> dict",
    "source_file": "modal_app/pipeline.py"
  },
  "weeks_impute": {
    "docstring": "Impute weeks_unemployed for the PUF half using QRF.\n\nUses CPS as training data and imputed PUF demographics as\ntest data, preserving the joint distribution of weeks with\nunemployment compensation.\n\nArgs:\n    data: CPS data dict.\n    puf_imputations: Dict of PUF-imputed variable arrays.\n    time_period: Tax year.\n    dataset_path: Path to CPS h5 for Microsimulation.\n\nReturns:\n    Array of imputed weeks for PUF half.",
    "id": "weeks_impute",
    "kind": "function",
    "line": 661,
    "metadata": {
      "api_refs": [
        "policyengine_us_data.calibration.puf_impute._impute_weeks_unemployed"
      ],
      "description": "Impute weeks unemployed for the clone half using CPS donor relationships.",
      "id": "weeks_impute",
      "label": "Weeks Unemployed Imputation",
      "node_type": "library",
      "pathways": [
        "data_build"
      ],
      "source_file": "policyengine_us_data/calibration/puf_impute.py",
      "stability": "moving",
      "status": "current",
      "validation_commands": [
        "uv run pytest tests/unit/calibration/test_calibration_puf_impute.py"
      ]
    },
    "object_path": "policyengine_us_data.calibration.puf_impute._impute_weeks_unemployed",
    "signature": "def _impute_weeks_unemployed(data: Dict[str, Dict[int, np.ndarray]], puf_imputations: Dict[str, np.ndarray], time_period: int, dataset_path: str) -> np.ndarray",
    "source_file": "policyengine_us_data/calibration/puf_impute.py"
  }
}