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

src/microunit/__init__.py

@@ -3,8 +3,40 @@
 from microunit.core import EgoUnitMembership, UnitPartition
 from microunit.diagnostics import PartitionMatchReport, partition_match_report
 from microunit.registry import UnitKind, UnitScheme, get_scheme, list_schemes
+<<<<<<< Updated upstream
+=======
+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,
+)
+>>>>>>> Stashed changes
+
+__version__ = "0.1.0"
 
 __all__ = [
+<<<<<<< Updated upstream
+=======
+    "__version__",
+    # Core containers
+>>>>>>> Stashed changes
     "EgoUnitMembership",
     "PartitionMatchReport",
     "UnitKind",

src/microunit/rule_helpers.py

@@ -0,0 +1,155 @@
+"""Rules-based helpers for tax-unit construction.
+
+These helpers encode the federal dependency and filing rules used to assign
+people into tax units: the qualifying-child age test, the
+relationship-to-reference-person tests for qualifying children and qualifying
+relatives, and the qualifying-relative gross income limit (the personal- and
+dependent-exemption amount under IRC 151(d), used by the IRC 152(d)(1)(B)
+gross income test).
+
+The CPS relationship codes mirror the Census ``A_EXPRRP`` recode used in the
+ASEC. Consumers that start from a different relationship coding (for example
+ACS ``RELSHIPP``) are expected to map onto these codes before calling
+:func:`microunit.construct_tax_units`.
+
+The gross income limit is read from package data
+(``data/dependent_gross_income_limit.yaml``) so the package is self-contained
+and does not depend on ``policyengine-us`` being installed.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from functools import cache
+from importlib import resources
+
+import yaml
+
+
+class CPSRelationshipCode(IntEnum):
+    """CPS ASEC relationship-to-reference-person recode (``A_EXPRRP``)."""
+
+    REFERENCE_PERSON_WITH_RELATIVES = 1
+    REFERENCE_PERSON_WITHOUT_RELATIVES = 2
+    HUSBAND = 3
+    WIFE = 4
+    OWN_CHILD = 5
+    GRANDCHILD = 7
+    PARENT = 8
+    SIBLING = 9
+    OTHER_RELATIVE = 10
+    FOSTER_CHILD = 11
+    NONRELATIVE_WITH_RELATIVES = 12
+    PARTNER_OR_ROOMMATE = 13
+    NONRELATIVE_WITHOUT_RELATIVES = 14
+
+
+REFERENCE_PERSON_CODES = frozenset(
+    {
+        CPSRelationshipCode.REFERENCE_PERSON_WITH_RELATIVES,
+        CPSRelationshipCode.REFERENCE_PERSON_WITHOUT_RELATIVES,
+    }
+)
+
+REFERENCE_SPOUSE_CODES = frozenset(
+    {
+        CPSRelationshipCode.HUSBAND,
+        CPSRelationshipCode.WIFE,
+    }
+)
+
+REFERENCE_QUALIFYING_CHILD_CODES = frozenset(
+    {
+        CPSRelationshipCode.OWN_CHILD,
+        CPSRelationshipCode.GRANDCHILD,
+        CPSRelationshipCode.SIBLING,
+        CPSRelationshipCode.FOSTER_CHILD,
+    }
+)
+
+REFERENCE_QUALIFYING_RELATIVE_CODES = frozenset(
+    {
+        CPSRelationshipCode.OWN_CHILD,
+        CPSRelationshipCode.GRANDCHILD,
+        CPSRelationshipCode.PARENT,
+        CPSRelationshipCode.SIBLING,
+        CPSRelationshipCode.OTHER_RELATIVE,
+        CPSRelationshipCode.FOSTER_CHILD,
+    }
+)
+
+
+def qualifying_child_age_test(
+    age: int | float,
+    is_full_time_student: bool = False,
+    is_permanently_disabled: bool = False,
+    non_student_age_limit: int = 19,
+    student_age_limit: int = 24,
+) -> bool:
+    if is_permanently_disabled:
+        return True
+    age_limit = student_age_limit if is_full_time_student else non_student_age_limit
+    return float(age) < age_limit
+
+
+def _relationship_from_code(relationship_code: int | None):
+    if relationship_code is None:
+        return None
+    try:
+        return CPSRelationshipCode(int(relationship_code))
+    except ValueError:
+        return None
+
+
+def reference_relationship_allows_qualifying_child(
+    relationship_code: int | None,
+) -> bool:
+    relationship = _relationship_from_code(relationship_code)
+    return relationship in REFERENCE_QUALIFYING_CHILD_CODES
+
+
+def reference_relationship_allows_qualifying_relative(
+    relationship_code: int | None,
+) -> bool:
+    relationship = _relationship_from_code(relationship_code)
+    return relationship in REFERENCE_QUALIFYING_RELATIVE_CODES
+
+
+def related_to_head_or_spouse(relationship_code: int | None) -> bool:
+    relationship = _relationship_from_code(relationship_code)
+    return relationship in (
+        REFERENCE_PERSON_CODES
+        | REFERENCE_SPOUSE_CODES
+        | REFERENCE_QUALIFYING_RELATIVE_CODES
+    )
+
+
+@cache
+def _gross_income_limit_values() -> dict:
+    parameter_path = (
+        resources.files("microunit") / "data" / "dependent_gross_income_limit.yaml"
+    )
+    with parameter_path.open("r", encoding="utf-8") as f:
+        return yaml.safe_load(f)["values"]
+
+
+@cache
+def dependent_gross_income_limit(year: int) -> float:
+    values = _gross_income_limit_values()
+
+    def _period_year(period) -> int:
+        if hasattr(period, "year"):
+            return int(period.year)
+        return int(str(period)[:4])
+
+    applicable_years = sorted(
+        _period_year(period) for period in values if _period_year(period) <= year
+    )
+    if not applicable_years:
+        raise ValueError(f"No dependent gross income limit configured for {year}.")
+
+    selected_year = applicable_years[-1]
+    for period, entry in values.items():
+        if _period_year(period) == selected_year:
+            return float(entry["value"])
+    raise ValueError(f"No dependent gross income limit configured for {year}.")