Add rules-based tax-unit construction engine from policyengine-us-data

Extract the rules-based tax-unit / filing-status construction engine from
policyengine-us-data into microunit (roadmap item 2). The engine is copied
verbatim (no logic changes) and made source-agnostic and self-contained. This
integrates additively with the existing unit-assignment scaffold.

New modules:
- src/microunit/tax_unit_construction.py: core engine. Public entry
  construct_tax_units(person, year, mode) with "policyengine" (default) and
  "census_documented" modes; HEAD/SPOUSE/DEPENDENT role constants. The only
  change vs. the source is the internal import (now microunit.rule_helpers);
  zero non-import edits to the logic.
- src/microunit/rule_helpers.py: dependency/filing rule helpers (renamed from
  tax_unit_rule_helpers). The optional policyengine_us import shim is dropped;
  the qualifying-relative gross income limit now loads from packaged data, so
  the engine no longer depends on policyengine-us.
- src/microunit/data/dependent_gross_income_limit.yaml: vendored IRC 151(d)
  exemption-amount values (through 2026), loaded via importlib.resources.

Integration:
- __init__.py: additively export construct_tax_units, the role constants,
  modes, CPSRelationshipCode, and the rule helpers (existing API unchanged).
- units/tax.py: add construct_tax_partition(), a UnitPartition adapter over
  construct_tax_units, fulfilling the prior "port rules-based tax-unit
  construction here" TODO. assign_tax_partition still preserves native IDs.
- units/__init__.py: export construct_tax_partition.
- pyproject.toml: add numpy and pyyaml deps; ship the YAML as wheel/sdist data.
- uv.lock: regenerated for the new direct dependencies.
- README.md: document the engine, the two modes, the input contract, and the
  ACS-column-mapping boundary.

Tests (60 passing total): test_tax_unit_construction.py ports the full CPS
suite to the microunit namespace; test_tax_partition_adapter.py covers the new
adapter; test_import.py checks the public API and packaged-data resolution.

ACS boundary: acs_to_cps_columns.py (ACS-PUMS-specific RELSHIPP/RELP and
spouse/parent inference) is intentionally NOT included. microunit takes
already-normalized CPS-like person frames; ACS column mapping and the
ACS-specific tests remain in policyengine-us-data.

Extracted from PolicyEngine/policyengine-us-data@f7458313.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: MaxGhenis

README.md

@@ -55,6 +55,86 @@ partition = assign_spm_partition(persons)
 print(partition.to_frame())
 ```
 
+## Rules-based tax-unit construction
+
+`microunit` includes the rules-based tax-unit / filing-status construction
+engine extracted from
+[`policyengine-us-data`](https://github.com/PolicyEngine/policyengine-us-data).
+It applies federal filing and dependency rules to assign people into tax
+units, infer each person's role (head / spouse / dependent), and infer a
+filing status per unit. It is the same engine reused across the CPS and ACS
+pipelines there, and is **source-agnostic**: it operates on
+already-normalized, CPS-like person frames. It is consumed by
+`policyengine-us-data` and `microplex-us`.
+
+```python
+import pandas as pd
+from microunit import construct_tax_units
+
+# person uses CPS-like column names (see "Input contract" below).
+person_assignments, tax_unit = construct_tax_units(person, year=2024)
+```
+
+`construct_tax_units(person, year, mode="policyengine")` returns:
+
+- **`person_assignments`** (indexed like the input): `TAX_ID` (`int64`,
+  dense 1-based id), `tax_unit_role_input` (bytes: `HEAD` / `SPOUSE` /
+  `DEPENDENT`), `is_related_to_head_or_spouse` (bool).
+- **`tax_unit`** (one row per `TAX_ID`): `filing_status_input` (bytes:
+  `JOINT` / `HEAD_OF_HOUSEHOLD` / `SURVIVING_SPOUSE` / `SEPARATE` /
+  `SINGLE`).
+
+The string columns are byte strings (the HDF5-friendly encoding used by the
+source pipeline); decode with `.decode()`.
+
+A `UnitPartition` adapter is also provided:
+
+```python
+from microunit.units import construct_tax_partition
+
+partition = construct_tax_partition(person, year=2024)  # UnitPartition(unit_type="tax")
+```
+
+### Modes
+
+- **`"policyengine"`** (default, `microunit.POLICYENGINE_MODE`): PolicyEngine's
+  dependency/filing-rule flow.
+- **`"census_documented"`** (`microunit.CENSUS_DOCUMENTED_MODE`): the publicly
+  documented Census tax-model flow.
+
+### Input contract
+
+Required CPS columns (raises `KeyError` if missing): `PH_SEQ`, `A_LINENO`,
+`A_AGE`, `A_MARITL`, `A_SPOUSE`, `PEPAR1`, `PEPAR2`, `A_EXPRRP`.
+
+Optional evidence columns (used when present, safely defaulted otherwise):
+income components (`WSAL_VAL`, `SEMP_VAL`, `FRSE_VAL`, `INT_VAL`, `DIV_VAL`,
+`RNT_VAL`, `CAP_VAL`, `UC_VAL`, `OI_VAL`, `ANN_VAL`, `PNSN_VAL`, `SS_VAL`),
+total money income (`PTOTVAL`), enrollment (`A_ENRLW`, `A_FTPT`, `A_HSCOL`),
+and disability flags (`PEDISDRS`, `PEDISEAR`, `PEDISEYE`, `PEDISOUT`,
+`PEDISPHY`, `PEDISREM`). Relationship codes follow the CPS ASEC `A_EXPRRP`
+recode, exposed as `microunit.CPSRelationshipCode`.
+
+### ACS column mapping is the consumer's responsibility
+
+The ACS PUMS -> CPS column mapping (`acs_to_cps_columns.py` in
+`policyengine-us-data`) is **not** part of `microunit`. That ~500-line module
+is ACS-PUMS-specific (`RELSHIPP`/`RELP` translation, marital-status recoding,
+and heuristic spouse/parent-pointer inference, since ACS provides no universal
+spouse or parent pointers) and belongs with the ACS reader. Consumers reading
+ACS should map their PUMS columns onto the CPS-like contract above and then
+call `construct_tax_units`. Accordingly, the ACS-specific tests from
+`policyengine-us-data` remain there; the full CPS construction test suite is
+ported here.
+
+### Packaged data
+
+The qualifying-relative gross income limit (the personal/dependent exemption
+amount under IRC 151(d), used by the IRC 152(d)(1)(B) gross income test) ships
+as package data at `microunit/data/dependent_gross_income_limit.yaml` and is
+loaded via `importlib.resources`, so the engine does not depend on
+`policyengine-us` being installed.
+
 ## Scope
 
 This package should construct unit assignments and explain them. It should not
@@ -65,7 +145,7 @@ Near-term roadmap:
 
 1. Move reusable SPM unit assignment out of `spm-calculator`.
 2. Move reusable tax-unit construction out of `policyengine-us-data` /
-   `policyengine-us`.
+   `policyengine-us`. (Done -- see "Rules-based tax-unit construction" above.)
 3. Add CPS and ACS source adapters for Microplex.
 4. Use SPM units as the temporary simplification for SNAP, Medicaid/MAGI, and
    other program units.

pyproject.toml

@@ -32,7 +32,9 @@ classifiers = [
 ]
 requires-python = ">=3.11"
 dependencies = [
+    "numpy>=1.24",
     "pandas>=2.0",
+    "pyyaml>=6.0",
 ]
 
 [project.optional-dependencies]
@@ -46,6 +48,16 @@ Repository = "https://github.com/PolicyEngine/microunit"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/microunit"]
+# Ship packaged rule data (the qualifying-relative gross income limit YAML)
+# alongside the Python modules.
+artifacts = ["src/microunit/data/*.yaml"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/microunit",
+    "tests",
+    "README.md",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

src/microunit/__init__.py

@@ -3,8 +3,34 @@
 from microunit.core import EgoUnitMembership, UnitPartition
 from microunit.diagnostics import PartitionMatchReport, partition_match_report
 from microunit.registry import UnitKind, UnitScheme, get_scheme, list_schemes
+from microunit.rule_helpers import (
+    REFERENCE_PERSON_CODES,
+    REFERENCE_QUALIFYING_CHILD_CODES,
+    REFERENCE_QUALIFYING_RELATIVE_CODES,
+    REFERENCE_SPOUSE_CODES,
+    CPSRelationshipCode,
+    dependent_gross_income_limit,
+    qualifying_child_age_test,
+    reference_relationship_allows_qualifying_child,
+    reference_relationship_allows_qualifying_relative,
+    related_to_head_or_spouse,
+)
+from microunit.tax_unit_construction import (
+    CENSUS_DOCUMENTED_MODE,
+    DEPENDENT,
+    HEAD,
+    POLICYENGINE_MODE,
+    SPOUSE,
+    SUPPORTED_TAX_UNIT_CONSTRUCTION_MODES,
+    construct_tax_units,
+    estimate_dependent_gross_income,
+)
+
+__version__ = "0.1.0"
 
 __all__ = [
+    "__version__",
+    # Core containers
     "EgoUnitMembership",
     "PartitionMatchReport",
     "UnitKind",
@@ -13,4 +39,23 @@
     "get_scheme",
     "list_schemes",
     "partition_match_report",
+    # Rules-based tax-unit construction engine
+    "construct_tax_units",
+    "estimate_dependent_gross_income",
+    "HEAD",
+    "SPOUSE",
+    "DEPENDENT",
+    "POLICYENGINE_MODE",
+    "CENSUS_DOCUMENTED_MODE",
+    "SUPPORTED_TAX_UNIT_CONSTRUCTION_MODES",
+    "CPSRelationshipCode",
+    "REFERENCE_PERSON_CODES",
+    "REFERENCE_SPOUSE_CODES",
+    "REFERENCE_QUALIFYING_CHILD_CODES",
+    "REFERENCE_QUALIFYING_RELATIVE_CODES",
+    "dependent_gross_income_limit",
+    "qualifying_child_age_test",
+    "reference_relationship_allows_qualifying_child",
+    "reference_relationship_allows_qualifying_relative",
+    "related_to_head_or_spouse",
 ]

src/microunit/data/dependent_gross_income_limit.yaml

@@ -0,0 +1,88 @@
+description: >-
+  Personal and dependent exemption amount under IRC 151(d). TCJA set the
+  deduction to $0 from 2018 (made permanent by OBBB), but the underlying
+  amount continues to be inflation-adjusted and published in annual Rev. Proc.
+  for other provisions that reference it, such as the qualifying relative
+  gross income test under IRC 152(d)(1)(B). The deduction suspension is
+  represented separately in gov.irs.income.exemption.suspended.
+metadata:
+  unit: currency-USD
+  uprating: gov.irs.uprating
+  period: year
+  reference:
+    - title: 26 U.S. Code § 151(d)(1) - Exemption amount
+      href: https://www.law.cornell.edu/uscode/text/26/151#d_1
+    - title: IRS Notice 2018-70 - Guidance on qualifying relative exemption amount
+      href: https://www.irs.gov/pub/irs-drop/n-18-70.pdf
+values:
+  2013-01-01:
+    value: 3_900
+    reference:
+      - title: Rev. Proc. 2013-15
+        href: https://www.irs.gov/pub/irs-drop/rp-13-15.pdf
+  2014-01-01:
+    value: 3_950
+    reference:
+      - title: Rev. Proc. 2013-35
+        href: https://www.irs.gov/pub/irs-drop/rp-13-35.pdf
+  2015-01-01:
+    value: 4_000
+    reference:
+      - title: Rev. Proc. 2014-61
+        href: https://www.irs.gov/pub/irs-drop/rp-14-61.pdf
+  2016-01-01:
+    value: 4_050
+    reference:
+      - title: Rev. Proc. 2015-53
+        href: https://www.irs.gov/pub/irs-drop/rp-15-53.pdf
+  2017-01-01:
+    value: 4_050
+    reference:
+      - title: Rev. Proc. 2016-55
+        href: https://www.irs.gov/pub/irs-drop/rp-16-55.pdf
+  2018-01-01:
+    value: 4_150
+    reference:
+      - title: Rev. Proc. 2017-58
+        href: https://www.irs.gov/pub/irs-drop/rp-17-58.pdf
+  2019-01-01:
+    value: 4_200
+    reference:
+      - title: Rev. Proc. 2018-57
+        href: https://www.irs.gov/pub/irs-drop/rp-18-57.pdf
+  2020-01-01:
+    value: 4_300
+    reference:
+      - title: Rev. Proc. 2019-44
+        href: https://www.irs.gov/pub/irs-drop/rp-19-44.pdf
+  2021-01-01:
+    value: 4_300
+    reference:
+      - title: Rev. Proc. 2020-45
+        href: https://www.irs.gov/pub/irs-drop/rp-20-45.pdf
+  2022-01-01:
+    value: 4_400
+    reference:
+      - title: Rev. Proc. 2021-45
+        href: https://www.irs.gov/pub/irs-drop/rp-21-45.pdf
+  2023-01-01:
+    value: 4_700
+    reference:
+      - title: Rev. Proc. 2022-38
+        href: https://www.irs.gov/pub/irs-drop/rp-22-38.pdf
+  2024-01-01:
+    value: 5_050
+    reference:
+      - title: Rev. Proc. 2023-34
+        href: https://www.irs.gov/pub/irs-drop/rp-23-34.pdf
+  2025-01-01:
+    value: 5_200
+    reference:
+      - title: Rev. Proc. 2024-40
+        href: https://www.irs.gov/pub/irs-drop/rp-24-40.pdf
+  2026-01-01:
+    value: 5_300
+    reference:
+      - title: Rev. Proc. 2025-32
+        href: https://www.irs.gov/pub/irs-drop/rp-25-32.pdf
+