hccinfhir 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

hccinfhir/datamodels.py

@@ -1,5 +1,6 @@
 from pydantic import BaseModel, Field
-from typing import List, Optional, Literal, Dict, Set, TypedDict, Union
+from typing import List, Optional, Literal, Dict, Set, TypedDict, Union, Any
+from datetime import date
 
 # Define Model Name literal type
 ModelName = Literal[
@@ -203,6 +204,21 @@ class HCPCoveragePeriod(BaseModel):
     hcp_status: Optional[str] = None
     aid_codes: Optional[str] = None  # REF*CE composite
 
+    def model_dump_with_dates(self, **kwargs) -> Dict[str, Any]:
+        """Return dict with date fields as date objects instead of strings.
+
+        Args:
+            **kwargs: Additional arguments passed to model_dump()
+
+        Returns:
+            Dict with start_date and end_date as date objects (if present)
+        """
+        data = self.model_dump(**kwargs)
+        for field in ('start_date', 'end_date'):
+            if data.get(field):
+                data[field] = date.fromisoformat(data[field])
+        return data
+
 
 class EnrollmentData(BaseModel):
     """
@@ -287,7 +303,8 @@ class EnrollmentData(BaseModel):
         # HCP (Health Care Plan) Info
         hcp_code: Current HCP code (HD04 first part)
         hcp_status: Current HCP status (HD04 second part)
-        amount: Premium or cost share amount
+        amount_qualifier: AMT qualifier code (e.g., 'D' = premium, 'C1' = copay)
+        amount: Premium or cost share amount (numeric)
 
         # HCP History (multiple coverage periods)
         hcp_history: List of historical HCP coverage periods
@@ -367,7 +384,51 @@ class EnrollmentData(BaseModel):
     # HCP Info
     hcp_code: Optional[str] = None
     hcp_status: Optional[str] = None
-    amount: Optional[str] = None
+    amount_qualifier: Optional[str] = None
+    amount: Optional[float] = None
 
     # HCP History
-    hcp_history: List[HCPCoveragePeriod] = []
+    hcp_history: List[HCPCoveragePeriod] = []
+
+    def model_dump_with_dates(self, **kwargs) -> Dict[str, Any]:
+        """Return dict with date fields as date objects instead of strings.
+
+        Converts all YYYY-MM-DD string date fields to date objects.
+        Also converts dates in nested hcp_history items.
+
+        Args:
+            **kwargs: Additional arguments passed to model_dump()
+
+        Returns:
+            Dict with date fields as date objects (if present)
+
+        Example:
+            >>> enrollment = extract_enrollment_834(content)[0]
+            >>> data = enrollment.model_dump_with_dates()
+            >>> isinstance(data['dob'], date)  # True
+        """
+        data = self.model_dump(**kwargs)
+
+        # EnrollmentData date fields
+        date_fields = (
+            'report_date',
+            'dob',
+            'death_date',
+            'coverage_start_date',
+            'coverage_end_date',
+            'fame_card_issue_date',
+            'fame_redetermination_date',
+            'fame_death_date',
+        )
+        for field in date_fields:
+            if data.get(field):
+                data[field] = date.fromisoformat(data[field])
+
+        # Convert dates in hcp_history items
+        if data.get('hcp_history'):
+            for hcp in data['hcp_history']:
+                for field in ('start_date', 'end_date'):
+                    if hcp.get(field):
+                        hcp[field] = date.fromisoformat(hcp[field])
+
+        return data

hccinfhir/extractor_834.py

@@ -21,6 +21,21 @@ from hccinfhir.constants import (
     map_medicare_status_to_dual_code,
     map_aid_code_to_dual_status,
 )
+from hccinfhir.utils import load_race_ethnicity
+
+# Load race/ethnicity mapping at module level
+_RACE_ETHNICITY_MAPPING: Optional[Dict[str, str]] = None
+
+
+def _get_race_ethnicity_mapping() -> Dict[str, str]:
+    """Lazy load race/ethnicity mapping"""
+    global _RACE_ETHNICITY_MAPPING
+    if _RACE_ETHNICITY_MAPPING is None:
+        try:
+            _RACE_ETHNICITY_MAPPING = load_race_ethnicity()
+        except (FileNotFoundError, RuntimeError):
+            _RACE_ETHNICITY_MAPPING = {}
+    return _RACE_ETHNICITY_MAPPING
 
 # Constants
 TRANSACTION_TYPES = {"005010X220A1": "834"}
@@ -114,7 +129,8 @@ class MemberContext(BaseModel):
     # HCP Info
     hcp_code: Optional[str] = None
     hcp_status: Optional[str] = None
-    amount: Optional[str] = None
+    amount_qualifier: Optional[str] = None
+    amount: Optional[float] = None
 
     # HCP History
     hcp_history: List[HCPContext] = []
@@ -206,6 +222,35 @@ def contains_any_keyword(text: str, keywords: set) -> bool:
     return any(kw in text_upper for kw in keywords)
 
 
+def parse_race_code(raw_value: Optional[str]) -> Optional[str]:
+    """Parse race code from DMG05 and translate to human-readable name.
+
+    Handles formats like:
+    - ":RET:2135-2" -> "Hispanic or Latino"
+    - "2135-2" -> "Hispanic or Latino"
+    - "2106-3" -> "White"
+
+    Args:
+        raw_value: Raw race value from DMG segment
+
+    Returns:
+        Human-readable race/ethnicity name, or original value if not found
+    """
+    if not raw_value:
+        return None
+
+    # Extract code from formats like ":RET:2135-2" or "2135-2"
+    code = raw_value
+    if ':' in raw_value:
+        parts = raw_value.split(':')
+        # Take the last non-empty part which should be the code
+        code = next((p for p in reversed(parts) if p), raw_value)
+
+    # Look up in mapping
+    mapping = _get_race_ethnicity_mapping()
+    return mapping.get(code, raw_value)
+
+
 # ============================================================================
 # Dual Eligibility Logic
 # ============================================================================
@@ -248,7 +293,7 @@ def parse_ref_23(value: str, member: MemberContext) -> None:
     member.cin_check_digit = get_composite_part(value, 0)
     card_date = get_composite_part(value, 1)
     if card_date and len(card_date) >= 8:
-        member.fame_card_issue_date = card_date[:8]
+        member.fame_card_issue_date = parse_date(card_date[:8])
 
 
 def parse_ref_3h(value: str, member: MemberContext) -> None:
@@ -277,7 +322,7 @@ def parse_ref_dx(value: str, member: MemberContext) -> None:
         member.carrier_code = strip_leading_zeros(carrier)
     policy_start = get_composite_part(value, 2)
     if policy_start and len(policy_start) >= 8:
-        member.coverage_start_date = policy_start[:8]
+        member.coverage_start_date = parse_date(policy_start[:8])
 
 
 def parse_ref_17(value: str, member: MemberContext) -> None:
@@ -495,7 +540,8 @@ def _finalize_member(member: MemberContext, source: str, report_date: str) -> En
         res_zip_deliv_code=member.res_zip_deliv_code,
         orec=member.orec, crec=member.crec, snp=member.snp,
         low_income=member.low_income, lti=member.lti, new_enrollee=new_enrollee,
-        hcp_code=member.hcp_code, hcp_status=member.hcp_status, amount=member.amount,
+        hcp_code=member.hcp_code, hcp_status=member.hcp_status,
+        amount_qualifier=member.amount_qualifier, amount=member.amount,
         hcp_history=hcp_history
     )
 
@@ -573,8 +619,8 @@ def parse_834_enrollment(segments: List[List[str]], source: str = None, report_d
             # Strip state suffix from city if embedded
             if city and state and city.upper().endswith(' ' + state.upper()):
                 city = city[:-len(state)-1].strip()
-            member.city = city.lower() if city else None
-            member.state = state.lower() if state else None
+            member.city = city
+            member.state = state
             member.zip = get_segment_value(segment, 3)
             # County code
             if len(segment) > 6 and segment[5] == 'CY' and not member.fame_county_id:
@@ -594,7 +640,7 @@ def parse_834_enrollment(segments: List[List[str]], source: str = None, report_d
             sex = get_segment_value(segment, 3)
             if sex in X12_SEX_CODE_MAPPING:
                 member.sex = X12_SEX_CODE_MAPPING[sex]
-            member.race = get_segment_value(segment, 5)
+            member.race = parse_race_code(get_segment_value(segment, 5))
             death_str = get_segment_value(segment, 6)
             if death_str and len(death_str) >= 8:
                 member.death_date = parse_date(death_str[:8])
@@ -638,7 +684,13 @@ def parse_834_enrollment(segments: List[List[str]], source: str = None, report_d
 
         # AMT - Amount
         elif seg_id == 'AMT' and len(segment) >= 3:
-            member.amount = get_segment_value(segment, 2)
+            member.amount_qualifier = get_segment_value(segment, 1)
+            amt_val = get_segment_value(segment, 2)
+            if amt_val:
+                try:
+                    member.amount = float(amt_val)
+                except ValueError:
+                    pass
 
     # Finalize last member
     if member.member_id or member.has_medicare or member.has_medicaid:
@@ -696,7 +748,7 @@ def extract_enrollment_834(content: str) -> List[EnrollmentData]:
                 source = get_segment_value(segment, 2)
             gs_date = get_segment_value(segment, 4)
             if gs_date and len(gs_date) >= 8:
-                report_date = f"{gs_date[:4]}-{gs_date[4:6]}-{gs_date[6:8]}"
+                report_date = parse_date(gs_date[:8])
             if len(segment) > 8 and segment[8] not in TRANSACTION_TYPES:
                 raise ValueError("Invalid or unsupported 834 format")
             break

hccinfhir/utils.py

@@ -247,6 +247,46 @@ def load_coefficients(file_path: str) -> Dict[Tuple[str, ModelName], float]:
     return coefficients
 
 
+def load_race_ethnicity(file_path: str = "ph_race_and_ethnicity_cdc_v1.3.csv") -> Dict[str, str]:
+    """
+    Load CDC race and ethnicity codes from CSV file.
+    Expected format: Concept Code,Hierarchical Property,Concept Name,...
+
+    Args:
+        file_path: Filename or path to the CSV file
+
+    Returns:
+        Dictionary mapping concept code to concept name
+
+    Raises:
+        FileNotFoundError: If file cannot be found
+        RuntimeError: If file cannot be loaded or parsed
+    """
+    mapping: Dict[str, str] = {}
+
+    try:
+        resolved_path = resolve_data_file(file_path)
+        with open(resolved_path, "r", encoding="utf-8", errors="replace") as file:
+            content = file.read()
+    except FileNotFoundError as e:
+        raise FileNotFoundError(f"Could not load race/ethnicity mapping: {e}")
+    except Exception as e:
+        raise RuntimeError(f"Error loading race/ethnicity file '{file_path}': {e}")
+
+    for line in content.splitlines()[1:]:  # Skip header
+        try:
+            parts = line.split(',')
+            if len(parts) >= 3:
+                concept_code = parts[0].strip()
+                concept_name = parts[2].strip()
+                if concept_code and concept_name:
+                    mapping[concept_code] = concept_name
+        except (ValueError, IndexError):
+            continue  # Skip malformed lines
+
+    return mapping
+
+
 def load_labels(file_path: str) -> Dict[Tuple[str, ModelName], str]:
     """
     Load HCC labels from a CSV file.

{hccinfhir-0.2.3.dist-info → hccinfhir-0.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hccinfhir
-Version: 0.2.3
+Version: 0.2.5
 Summary: HCC Algorithm for FHIR Resources
 Project-URL: Homepage, https://github.com/mimilabs/hccinfhir
 Project-URL: Issues, https://github.com/mimilabs/hccinfhir/issues
@@ -95,6 +95,7 @@ print(f"HCCs: {result.hcc_list}")
 - **Use Case**: Extract dual eligibility status, detect Medicaid coverage loss
 - **Features**: California DHCS aid code mapping, Medicare status codes, coverage tracking
 - **Output**: Demographics with accurate dual eligibility for risk calculations
+- **Architecture**: See [834 Parsing Documentation](./README_PARSING834.md) for transaction structure and parsing logic
 
 ### 3. **FHIR ExplanationOfBenefit Resources**
 - **Input**: FHIR EOB from CMS Blue Button 2.0 / BCDA API
@@ -1073,6 +1074,7 @@ Apache License 2.0. See [LICENSE](LICENSE) for details.
 ## 📞 Support
 
 - **Claude Code Documentation**: [CLAUDE.md](./CLAUDE.md) - Comprehensive developer guide
+- **834 Parsing Architecture**: [README_PARSING834.md](./README_PARSING834.md) - X12 834 transaction structure and parsing logic
 - **Issues**: [GitHub Issues](https://github.com/mimilabs/hccinfhir/issues)
 
 ## 👥 Contributors

{hccinfhir-0.2.3.dist-info → hccinfhir-0.2.5.dist-info}/RECORD

@@ -1,9 +1,9 @@
 hccinfhir/__init__.py,sha256=3aFYtjTklZJg3wIlnMJNgfDBaDCfKXVlYsacdsZ9L4I,1113
 hccinfhir/constants.py,sha256=C4Vyjtzgyd4Jm2I2X6cTYQZLe-jAMC8boUcy-7OXQDQ,8473
-hccinfhir/datamodels.py,sha256=xGh9E5RVi4vONhtIZw2XiaFwVLc5UK027trY31YMUWc,15457
+hccinfhir/datamodels.py,sha256=u-KICO7ODOo8GCsZ0JmyhPauL-irQ9aVjNaiGiVHdks,17592
 hccinfhir/defaults.py,sha256=aKdXPhf9bYUzpGvXM1GIXZaKxqkKInt3v9meLB9fWog,1394
 hccinfhir/extractor.py,sha256=xL9c2VT-e2I7_c8N8j4Og42UEgVuCzyn9WFp3ntM5Ro,1822
-hccinfhir/extractor_834.py,sha256=zH2nOUJvIJvbDLf6HJWmwCw2yAjT-6RCJyuH4kmIKIQ,27862
+hccinfhir/extractor_834.py,sha256=H5756zwjkZN9nXlGHr_V63VgNjQEjIB7nqaoBYazAR8,29526
 hccinfhir/extractor_837.py,sha256=fGsvBTWIj9dsHLGGR67AdlYDSsFi5qnSVlTgwkL1f-E,15334
 hccinfhir/extractor_fhir.py,sha256=wUN3vTm1oTZ-KvfcDebnpQMxAC-7YlRKv12Wrv3p85A,8490
 hccinfhir/filter.py,sha256=j_yD2g6RBXVUV9trKkWzsQ35x3fRvfKUPvEXKUefI64,2007
@@ -15,10 +15,11 @@ hccinfhir/model_dx_to_cc.py,sha256=Yjc6xKI-jMXsbOzS_chc4NI15Bwagb7BwZZ8cKQaTbk,1
 hccinfhir/model_hierarchies.py,sha256=cboUnSHZZfOxA8QZKV4QIE-32duElssML32OqYT-65g,1542
 hccinfhir/model_interactions.py,sha256=g6jK27Xu8RQUHS3lk4sk2v6w6wqd52mdbGn0BsnR7Pk,21394
 hccinfhir/samples.py,sha256=2VSWS81cv9EnaHqK7sd6CjwG6FUI9E--5wHgD000REI,9952
-hccinfhir/utils.py,sha256=hQgHjuOcEQcnxemTZwqFBHWvLC5-C1Gup9cDXEYlZjE,10770
+hccinfhir/utils.py,sha256=WQ2atW0CrdX7sAz_YRLeY4JD-CuH0o-WRusQ_xVVfgY,12152
 hccinfhir/data/__init__.py,sha256=SGiSkpGrnxbvtEFMMlk82NFHOE50hFXcgKwKUSuVZUg,45
 hccinfhir/data/hcc_is_chronic.csv,sha256=Bwd-RND6SdEsKP-assoBaXnjUJAuDXhSkwWlymux72Y,19701
 hccinfhir/data/hcc_is_chronic_without_esrd_model.csv,sha256=eVVI4_8mQNkiBiNO3kattfT_zfcV18XgmiltdzZEXSo,17720
+hccinfhir/data/ph_race_and_ethnicity_cdc_v1.3.csv,sha256=5tw_ATN1mQWVUIahXZyIa5GOX-977PzfhNlGvm43tD8,146970
 hccinfhir/data/ra_coefficients_2025.csv,sha256=I0S2hoJlfig-D0oSFxy0b3Piv7m9AzOGo2CwR6bcQ9w,215191
 hccinfhir/data/ra_coefficients_2026.csv,sha256=0gfjGgVdIEWkBO01NaAbTLMzHCYINA0rf_zl8ojngCY,288060
 hccinfhir/data/ra_dx_to_cc_2025.csv,sha256=4N7vF6VZndkl7d3Fo0cGsbAPAZdCjAizSH8BOKsZNAo,1618924
@@ -54,7 +55,7 @@ hccinfhir/sample_files/sample_eob_1.json,sha256=_NGSVR2ysFpx-DcTvyga6dFCzhQ8Vi9f
 hccinfhir/sample_files/sample_eob_2.json,sha256=FcnJcx0ApOczxjJ_uxVLzCep9THfNf4xs9Yf7hxk8e4,1769
 hccinfhir/sample_files/sample_eob_200.ndjson,sha256=CxpjeQ1DCMUzZILaM68UEhfxO0p45YGhDDoCZeq8PxU,1917986
 hccinfhir/sample_files/sample_eob_3.json,sha256=4BW4wOMBEEU9RDfJR15rBEvk0KNHyuMEh3e055y87Hc,2306
-hccinfhir-0.2.3.dist-info/METADATA,sha256=YHHcOAObdo2gWJtPmP6y05-EXeXHpuE40W1pdUXlydw,37132
-hccinfhir-0.2.3.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-hccinfhir-0.2.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-hccinfhir-0.2.3.dist-info/RECORD,,
+hccinfhir-0.2.5.dist-info/METADATA,sha256=fjqK-VAKUQ_zblUqz4p8qddjSZje16tYVnPGEYyzw4Q,37381
+hccinfhir-0.2.5.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+hccinfhir-0.2.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+hccinfhir-0.2.5.dist-info/RECORD,,