hccinfhir 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

hccinfhir/datamodels.py

@@ -145,4 +145,66 @@ class RAFResult(BaseModel):
     diagnosis_codes: List[str] = Field(default_factory=list, description="Input diagnosis codes")
     service_level_data: Optional[List[ServiceLevelData]] = Field(default=None, description="Processed service records")
     
-    model_config = {"extra": "forbid", "validate_assignment": True}
+    model_config = {"extra": "forbid", "validate_assignment": True}
+
+class EnrollmentData(BaseModel):
+    """
+    Enrollment and demographic data extracted from 834 transactions.
+
+    Focus: Extract data needed for risk adjustment and Medicaid coverage tracking.
+
+    Attributes:
+        member_id: Unique identifier for the member
+        mbi: Medicare Beneficiary Identifier
+        medicaid_id: Medicaid/Medi-Cal ID number
+        dob: Date of birth (YYYY-MM-DD)
+        age: Calculated age
+        sex: Member sex (M/F)
+        maintenance_type: 001=Change, 021=Add, 024=Cancel, 025=Reinstate
+        coverage_start_date: Coverage effective date
+        coverage_end_date: Coverage termination date (critical for Medicaid loss detection)
+        has_medicare: Member has Medicare coverage
+        has_medicaid: Member has Medicaid coverage
+        dual_elgbl_cd: Dual eligibility status code ('00','01'-'08')
+        is_full_benefit_dual: Full Benefit Dual (uses CFA_/CFD_ prefix)
+        is_partial_benefit_dual: Partial Benefit Dual (uses CPA_/CPD_ prefix)
+        medicare_status_code: QMB, SLMB, QI, QDWI, etc.
+        medi_cal_aid_code: California Medi-Cal aid code
+        orec: Original Reason for Entitlement Code
+        crec: Current Reason for Entitlement Code
+        snp: Special Needs Plan enrollment
+        low_income: Low Income Subsidy (Part D)
+        lti: Long-Term Institutionalized
+        new_enrollee: New enrollee status (<= 3 months)
+    """
+    # Identifiers
+    member_id: Optional[str] = None
+    mbi: Optional[str] = None
+    medicaid_id: Optional[str] = None
+
+    # Demographics
+    dob: Optional[str] = None
+    age: Optional[int] = None
+    sex: Optional[str] = None
+
+    # Coverage tracking
+    maintenance_type: Optional[str] = None
+    coverage_start_date: Optional[str] = None
+    coverage_end_date: Optional[str] = None
+
+    # Medicaid/Medicare Status
+    has_medicare: bool = False
+    has_medicaid: bool = False
+    dual_elgbl_cd: Optional[str] = None
+    is_full_benefit_dual: bool = False
+    is_partial_benefit_dual: bool = False
+    medicare_status_code: Optional[str] = None
+    medi_cal_aid_code: Optional[str] = None
+
+    # Risk Adjustment Fields
+    orec: Optional[str] = None
+    crec: Optional[str] = None
+    snp: bool = False
+    low_income: bool = False
+    lti: bool = False
+    new_enrollee: bool = False

hccinfhir/extractor_834.py

@@ -0,0 +1,530 @@
+from typing import List, Optional, Dict
+from pydantic import BaseModel
+from datetime import datetime, date
+from hccinfhir.datamodels import Demographics, EnrollmentData
+
+TRANSACTION_TYPES = {
+    "005010X220A1": "834",  # Benefit Enrollment and Maintenance
+}
+
+# California Medi-Cal Aid Codes mapping to dual eligibility status
+MEDI_CAL_AID_CODES = {
+    # Full Benefit Dual (QMB Plus, SLMB Plus)
+    '4N': '02',  # QMB Plus - Aged
+    '4P': '02',  # QMB Plus - Disabled
+    '5B': '04',  # SLMB Plus - Aged
+    '5D': '04',  # SLMB Plus - Disabled
+
+    # Partial Benefit Dual (QMB Only, SLMB Only, QI)
+    '4M': '01',  # QMB Only - Aged
+    '4O': '01',  # QMB Only - Disabled
+    '5A': '03',  # SLMB Only - Aged
+    '5C': '03',  # SLMB Only - Disabled
+    '5E': '06',  # QI - Aged
+    '5F': '06',  # QI - Disabled
+}
+
+class MemberContext(BaseModel):
+    """Tracks member-level data across segments within 834 transaction"""
+    # Identifiers
+    member_id: Optional[str] = None
+    mbi: Optional[str] = None  # Medicare Beneficiary Identifier
+    medicaid_id: Optional[str] = None
+
+    # Demographics
+    dob: Optional[str] = None
+    sex: Optional[str] = None
+
+    # Coverage Status
+    maintenance_type: Optional[str] = None  # 001=Change, 021=Add, 024=Cancel, 025=Reinstate
+    coverage_start_date: Optional[str] = None
+    coverage_end_date: Optional[str] = None
+
+    # Medicare/Medicaid Status
+    has_medicare: bool = False
+    has_medicaid: bool = False
+    medicare_status_code: Optional[str] = None  # QMB, SLMB, QI, etc.
+    medi_cal_aid_code: Optional[str] = None
+    dual_elgbl_cd: Optional[str] = None
+
+    # Risk Adjustment Fields
+    orec: Optional[str] = None
+    crec: Optional[str] = None
+    snp: bool = False
+    low_income: bool = False
+    lti: bool = False
+
+# Helper methods for EnrollmentData - added as standalone functions
+def enrollment_to_demographics(enrollment: EnrollmentData) -> Demographics:
+    """Convert EnrollmentData to Demographics model for risk calculation"""
+    return Demographics(
+        age=enrollment.age or 0,
+        sex=enrollment.sex or 'M',
+        dual_elgbl_cd=enrollment.dual_elgbl_cd,
+        orec=enrollment.orec or '',
+        crec=enrollment.crec or '',
+        new_enrollee=enrollment.new_enrollee,
+        snp=enrollment.snp,
+        low_income=enrollment.low_income,
+        lti=enrollment.lti
+    )
+
+def is_losing_medicaid(enrollment: EnrollmentData, within_days: int = 90) -> bool:
+    """Check if member will lose Medicaid within specified days
+
+    Args:
+        enrollment: EnrollmentData object
+        within_days: Number of days to look ahead (default 90)
+
+    Returns:
+        True if Medicaid coverage ends within specified days
+    """
+    if not enrollment.coverage_end_date or not enrollment.has_medicaid:
+        return False
+
+    try:
+        end_date = datetime.strptime(enrollment.coverage_end_date, "%Y-%m-%d").date()
+        today = date.today()
+        days_until_end = (end_date - today).days
+
+        return 0 <= days_until_end <= within_days
+    except (ValueError, AttributeError):
+        return False
+
+def is_medicaid_terminated(enrollment: EnrollmentData) -> bool:
+    """Check if Medicaid coverage is being terminated (maintenance type 024)"""
+    return enrollment.maintenance_type == '024'
+
+def medicaid_status_summary(enrollment: EnrollmentData) -> Dict[str, any]:
+    """Get summary of Medicaid coverage status for monitoring
+
+    Args:
+        enrollment: EnrollmentData object
+
+    Returns:
+        Dictionary with Medicaid status, dual eligibility, and loss indicators
+    """
+    return {
+        'member_id': enrollment.member_id,
+        'has_medicaid': enrollment.has_medicaid,
+        'has_medicare': enrollment.has_medicare,
+        'dual_status': enrollment.dual_elgbl_cd,
+        'is_full_benefit_dual': enrollment.is_full_benefit_dual,
+        'is_partial_benefit_dual': enrollment.is_partial_benefit_dual,
+        'coverage_end_date': enrollment.coverage_end_date,
+        'is_termination': is_medicaid_terminated(enrollment),
+        'losing_medicaid_30d': is_losing_medicaid(enrollment, 30),
+        'losing_medicaid_60d': is_losing_medicaid(enrollment, 60),
+        'losing_medicaid_90d': is_losing_medicaid(enrollment, 90)
+    }
+
+def parse_date(date_str: str) -> Optional[str]:
+    """Convert 8-digit date string to ISO format YYYY-MM-DD"""
+    if not isinstance(date_str, str) or len(date_str) != 8:
+        return None
+    try:
+        year, month, day = int(date_str[:4]), int(date_str[4:6]), int(date_str[6:8])
+        if not (1900 <= year <= 2100 and 1 <= month <= 12 and 1 <= day <= 31):
+            return None
+        return f"{year:04d}-{month:02d}-{day:02d}"
+    except (ValueError, IndexError):
+        return None
+
+def calculate_age(dob: str, reference_date: Optional[str] = None) -> Optional[int]:
+    """Calculate age from DOB in YYYY-MM-DD format"""
+    if not dob:
+        return None
+    try:
+        birth_date = datetime.strptime(dob, "%Y-%m-%d").date()
+        if reference_date:
+            ref_date = datetime.strptime(reference_date, "%Y-%m-%d").date()
+        else:
+            ref_date = date.today()
+
+        age = ref_date.year - birth_date.year
+        if (ref_date.month, ref_date.day) < (birth_date.month, birth_date.day):
+            age -= 1
+        return age
+    except (ValueError, AttributeError):
+        return None
+
+def get_segment_value(segment: List[str], index: int, default: Optional[str] = None) -> Optional[str]:
+    """Safely get value from segment at given index"""
+    try:
+        if len(segment) > index and segment[index]:
+            return segment[index]
+    except (IndexError, TypeError):
+        pass
+    return default
+
+def map_medicare_status_to_dual_code(status: Optional[str]) -> Optional[str]:
+    """Map Medicare status codes to dual eligibility codes
+
+    California Medi-Cal uses these status codes:
+    - QMB = Qualified Medicare Beneficiary
+    - QMBPLUS = QMB Plus (Full Benefit)
+    - SLMB = Specified Low-Income Medicare Beneficiary
+    - SLMBPLUS = SLMB Plus (Full Benefit)
+    - QI = Qualifying Individual
+    - QDWI = Qualified Disabled Working Individual
+    """
+    if not status:
+        return None
+
+    status_upper = status.upper().replace(' ', '').replace('-', '')
+
+    mapping = {
+        'QMB': '01',         # QMB Only (Partial)
+        'QMBONLY': '01',
+        'QMBPLUS': '02',     # QMB Plus (Full Benefit)
+        'QMB+': '02',
+        'SLMB': '03',        # SLMB Only (Partial)
+        'SLMBONLY': '03',
+        'SLMBPLUS': '04',    # SLMB Plus (Full Benefit)
+        'SLMB+': '04',
+        'QDWI': '05',
+        'QI': '06',
+        'QI1': '06',
+        'FBDE': '08',        # Full Benefit Dual Eligible (Other)
+        'OTHERFULL': '08',
+    }
+
+    return mapping.get(status_upper)
+
+def map_aid_code_to_dual_status(aid_code: Optional[str]) -> Optional[str]:
+    """Map California Medi-Cal aid code to dual eligibility status"""
+    if not aid_code:
+        return None
+    return MEDI_CAL_AID_CODES.get(aid_code)
+
+def determine_dual_status(member: MemberContext) -> str:
+    """Intelligently derive dual eligibility code from available data
+
+    Priority order:
+    1. Explicit dual_elgbl_cd from REF segment
+    2. California Medi-Cal aid code mapping
+    3. Medicare status code (QMB, SLMB, etc.)
+    4. Presence of both Medicare and Medicaid coverage
+    5. Default to non-dual ('00')
+    """
+    # Priority 1: Explicit dual_elgbl_cd
+    if member.dual_elgbl_cd and member.dual_elgbl_cd in ['01','02','03','04','05','06','08']:
+        return member.dual_elgbl_cd
+
+    # Priority 2: California aid code mapping
+    if member.medi_cal_aid_code:
+        dual_code = map_aid_code_to_dual_status(member.medi_cal_aid_code)
+        if dual_code:
+            return dual_code
+
+    # Priority 3: Medicare status code
+    if member.medicare_status_code:
+        dual_code = map_medicare_status_to_dual_code(member.medicare_status_code)
+        if dual_code:
+            return dual_code
+
+    # Priority 4: Both Medicare and Medicaid coverage present
+    if member.has_medicare and (member.has_medicaid or member.medicaid_id):
+        # Conservative: assign '08' (Other Full Dual) to ensure dual coefficients
+        return '08'
+
+    # Default: Non-dual
+    return '00'
+
+def classify_dual_benefit_level(dual_code: str) -> tuple[bool, bool]:
+    """Classify as Full Benefit Dual (FBD) or Partial Benefit Dual (PBD)
+
+    Full Benefit Dual codes: 02, 04, 08
+    - Uses CFA_ (Community, Full Benefit Dual, Aged) prefix
+    - Uses CFD_ (Community, Full Benefit Dual, Disabled) prefix
+
+    Partial Benefit Dual codes: 01, 03, 05, 06
+    - Uses CPA_ (Community, Partial Benefit Dual, Aged) prefix
+    - Uses CPD_ (Community, Partial Benefit Dual, Disabled) prefix
+    """
+    full_benefit_codes = {'02', '04', '08'}
+    partial_benefit_codes = {'01', '03', '05', '06'}
+
+    is_fbd = dual_code in full_benefit_codes
+    is_pbd = dual_code in partial_benefit_codes
+
+    return is_fbd, is_pbd
+
+def is_new_enrollee(coverage_start_date: Optional[str], reference_date: Optional[str] = None) -> bool:
+    """Determine if member is new enrollee (<= 3 months since coverage start)"""
+    if not coverage_start_date:
+        return False
+
+    try:
+        start_date = datetime.strptime(coverage_start_date, "%Y-%m-%d").date()
+        if reference_date:
+            ref_date = datetime.strptime(reference_date, "%Y-%m-%d").date()
+        else:
+            ref_date = date.today()
+
+        # Calculate months difference
+        months_diff = (ref_date.year - start_date.year) * 12 + (ref_date.month - start_date.month)
+
+        return months_diff <= 3
+    except (ValueError, AttributeError):
+        return False
+
+def parse_834_enrollment(segments: List[List[str]]) -> List[EnrollmentData]:
+    """Extract enrollment and demographic data from 834 transaction
+
+    California DHCS Medi-Cal 834 Structure:
+    Loop 2000 - Member Level
+        INS - Member Level Detail (subscriber/dependent, maintenance type)
+        REF - Member Identifiers (0F, 1L, F6, 6P, ZZ, AB, ABB)
+        DTP - Date Time Periods (303, 348, 349, 338)
+        NM1 - Member Name (IL qualifier)
+        DMG - Demographics (DOB, Sex) ***CRITICAL***
+        HD  - Health Coverage ***CRITICAL FOR DUAL STATUS***
+    """
+    enrollments = []
+    member = MemberContext()
+
+    for i, segment in enumerate(segments):
+        if len(segment) < 2:
+            continue
+
+        seg_id = segment[0]
+
+        # ===== INS - Member Level Detail (Start of 2000 loop) =====
+        if seg_id == 'INS' and len(segment) >= 3:
+            # Save previous member before starting new one
+            if member.member_id or member.has_medicare or member.has_medicaid:
+                enrollments.append(create_enrollment_data(member))
+
+            # Start new member
+            member = MemberContext()
+
+            # INS03 - Maintenance Type Code
+            member.maintenance_type = get_segment_value(segment, 3)
+            # 001=Change, 021=Addition, 024=Cancellation/Term, 025=Reinstatement
+
+        # ===== REF - Reference Identifiers =====
+        elif seg_id == 'REF' and len(segment) >= 3:
+            qualifier = segment[1]
+            value = segment[2] if len(segment) > 2 else None
+
+            if not value:
+                continue
+
+            # Standard REF qualifiers
+            if qualifier == '0F':  # Subscriber Number
+                if not member.member_id:
+                    member.member_id = value
+            elif qualifier == 'ZZ':  # Mutually Defined (often member ID or MBI)
+                if not member.member_id:
+                    member.member_id = value
+
+            # Medicare Identifiers
+            elif qualifier == '6P':  # Medicare MBI (new identifier)
+                member.mbi = value
+                member.has_medicare = True
+            elif qualifier == 'F6':  # Medicare HICN (legacy) or MBI
+                if not member.mbi:
+                    member.mbi = value
+                member.has_medicare = True
+
+            # Medicaid Identifiers
+            elif qualifier == '1D':  # Medicaid/Recipient ID
+                member.medicaid_id = value
+                member.has_medicaid = True
+            elif qualifier == '23':  # Medicaid Recipient ID (alternative)
+                if not member.medicaid_id:
+                    member.medicaid_id = value
+                member.has_medicaid = True
+
+            # California Medi-Cal Specific
+            elif qualifier == 'ABB':  # Medicare Status Code (QMB, SLMB, QI, etc.)
+                member.medicare_status_code = value
+            elif qualifier == 'AB':  # Aid Code (California specific)
+                member.medi_cal_aid_code = value
+
+            # Custom dual eligibility indicators
+            elif qualifier == 'F5':  # Dual Eligibility Code (custom)
+                if value in ['01','02','03','04','05','06','08']:
+                    member.dual_elgbl_cd = value
+            elif qualifier == 'DX':  # OREC (custom)
+                if value in ['0','1','2','3']:
+                    member.orec = value
+            elif qualifier == 'DY':  # CREC (custom)
+                if value in ['0','1','2','3']:
+                    member.crec = value
+            elif qualifier == 'EJ':  # Low Income Subsidy indicator
+                member.low_income = (value.upper() in ['Y', 'YES', '1', 'TRUE'])
+
+        # ===== NM1 - Member Name =====
+        elif seg_id == 'NM1' and len(segment) >= 4:
+            qualifier = segment[1]
+
+            if qualifier == 'IL':  # Insured or Subscriber
+                # NM109 = Identification Code (Member ID)
+                if len(segment) > 9:
+                    id_value = get_segment_value(segment, 9)
+                    if id_value and not member.member_id:
+                        member.member_id = id_value
+
+        # ===== DMG - Demographics ***CRITICAL SEGMENT*** =====
+        elif seg_id == 'DMG' and len(segment) >= 3:
+            # DMG02 = Date of Birth
+            dob_str = get_segment_value(segment, 2)
+            if dob_str:
+                member.dob = parse_date(dob_str)
+
+            # DMG03 = Gender Code
+            sex = get_segment_value(segment, 3)
+            if sex in ['M', 'F', '1', '2']:
+                member.sex = 'M' if sex in ['M', '1'] else 'F'
+
+        # ===== DTP - Date Time Periods =====
+        elif seg_id == 'DTP' and len(segment) >= 4:
+            date_qualifier = segment[1]
+            date_format = segment[2]
+            date_value = segment[3] if len(segment) > 3 else None
+
+            if not date_value or not date_format.endswith('D8'):
+                continue
+
+            parsed_date = parse_date(date_value[:8] if len(date_value) >= 8 else date_value)
+
+            if not parsed_date:
+                continue
+
+            # Date qualifiers
+            if date_qualifier == '348':  # Benefit Begin Date
+                member.coverage_start_date = parsed_date
+            elif date_qualifier == '349':  # Benefit End Date
+                member.coverage_end_date = parsed_date
+            elif date_qualifier == '338':  # Medicare Part A/B Effective Date
+                if not member.coverage_start_date:
+                    member.coverage_start_date = parsed_date
+                member.has_medicare = True
+
+        # ===== HD - Health Coverage ***CRITICAL FOR DUAL STATUS*** =====
+        elif seg_id == 'HD' and len(segment) >= 4:
+            # HD03 = Insurance Line Code
+            insurance_line = get_segment_value(segment, 3, '').upper()
+
+            # HD04 = Plan Coverage Description
+            plan_desc = get_segment_value(segment, 4, '').upper()
+
+            # HD06 = Insurance Type Code
+            insurance_type = get_segment_value(segment, 6, '').upper()
+
+            # Combine all fields for pattern matching
+            combined = f"{insurance_line} {plan_desc} {insurance_type}"
+
+            # Detect Medicare coverage
+            if any(keyword in combined for keyword in [
+                'MEDICARE', 'MA', 'PART A', 'PART B', 'PART C', 'PART D',
+                'MEDICARE ADVANTAGE', 'MA-PD'
+            ]):
+                member.has_medicare = True
+
+            # Detect Medicaid/Medi-Cal coverage
+            if any(keyword in combined for keyword in [
+                'MEDICAID', 'MEDI-CAL', 'MEDI CAL', 'MEDIC-AID'
+            ]):
+                member.has_medicaid = True
+
+            # Detect SNP (Special Needs Plan)
+            if any(keyword in combined for keyword in [
+                'SNP', 'SPECIAL NEEDS', 'D-SNP', 'DSNP', 'DUAL ELIGIBLE SNP'
+            ]):
+                member.snp = True
+                # If it's a D-SNP, they are definitely dual eligible
+                if 'D-SNP' in combined or 'DSNP' in combined or 'DUAL' in combined:
+                    member.has_medicare = True
+                    member.has_medicaid = True
+
+    # Don't forget last member
+    if member.member_id or member.has_medicare or member.has_medicaid:
+        enrollments.append(create_enrollment_data(member))
+
+    return enrollments
+
+def create_enrollment_data(member: MemberContext) -> EnrollmentData:
+    """Convert MemberContext to EnrollmentData with risk adjustment fields"""
+
+    # Calculate age
+    age = calculate_age(member.dob) if member.dob else None
+
+    # Determine dual eligibility status
+    dual_code = determine_dual_status(member)
+
+    # Classify FBD vs PBD
+    is_fbd, is_pbd = classify_dual_benefit_level(dual_code)
+
+    # Determine new enrollee status
+    new_enrollee = is_new_enrollee(member.coverage_start_date)
+
+    return EnrollmentData(
+        # Identifiers
+        member_id=member.member_id,
+        mbi=member.mbi,
+        medicaid_id=member.medicaid_id,
+
+        # Demographics
+        dob=member.dob,
+        age=age,
+        sex=member.sex,
+
+        # Coverage tracking
+        maintenance_type=member.maintenance_type,
+        coverage_start_date=member.coverage_start_date,
+        coverage_end_date=member.coverage_end_date,
+
+        # Dual Eligibility
+        has_medicare=member.has_medicare,
+        has_medicaid=member.has_medicaid,
+        dual_elgbl_cd=dual_code,
+        is_full_benefit_dual=is_fbd,
+        is_partial_benefit_dual=is_pbd,
+        medicare_status_code=member.medicare_status_code,
+        medi_cal_aid_code=member.medi_cal_aid_code,
+
+        # Risk Adjustment
+        orec=member.orec,
+        crec=member.crec,
+        snp=member.snp,
+        low_income=member.low_income,
+        lti=member.lti,
+        new_enrollee=new_enrollee
+    )
+
+def extract_enrollment_834(content: str) -> List[EnrollmentData]:
+    """Main entry point for 834 parsing
+
+    Args:
+        content: Raw X12 834 transaction file content
+
+    Returns:
+        List of EnrollmentData objects with demographic and dual eligibility info
+
+    Raises:
+        ValueError: If content is empty or invalid 834 format
+    """
+    if not content:
+        raise ValueError("Input X12 834 data cannot be empty")
+
+    # Split content into segments
+    segments = [seg.strip().split('*')
+                for seg in content.split('~') if seg.strip()]
+
+    if not segments:
+        raise ValueError("No valid segments found in 834 data")
+
+    # Validate transaction type from GS segment
+    transaction_type = None
+    for segment in segments:
+        if segment[0] == 'GS' and len(segment) > 8:
+            transaction_type = TRANSACTION_TYPES.get(segment[8])
+            break
+
+    if not transaction_type:
+        raise ValueError("Invalid or unsupported 834 format (missing GS segment or wrong version)")
+
+    return parse_834_enrollment(segments)

hccinfhir/extractor_837.py

@@ -7,17 +7,23 @@ CLAIM_TYPES = {
     "005010X223A2": "837I"      # Institutional
 }
 
-class ClaimData(BaseModel):
-    """Container for claim-level data"""
-    claim_id: Optional[str] = None
-    patient_id: Optional[str] = None
-    performing_provider_npi: Optional[str] = None
+class HierarchyContext(BaseModel):
+    """Tracks the current position in the 837 hierarchy"""
     billing_provider_npi: Optional[str] = None
-    provider_specialty: Optional[str] = None
+    subscriber_patient_id: Optional[str] = None
+    patient_patient_id: Optional[str] = None
+    current_hl_level: Optional[str] = None
+    current_hl_id: Optional[str] = None
+
+class ClaimContext(BaseModel):
+    """Claim-level data that resets for each CLM segment"""
+    claim_id: Optional[str] = None
+    dx_lookup: Dict[str, str] = {}
     facility_type: Optional[str] = None
     service_type: Optional[str] = None
-    claim_type: str
-    dx_lookup: Dict[str, str] = {}
+    performing_provider_npi: Optional[str] = None
+    provider_specialty: Optional[str] = None
+    last_nm1_qualifier: Optional[str] = None
 
 def parse_date(date_str: str) -> Optional[str]:
     """Convert 8-digit date string to ISO format YYYY-MM-DD"""
@@ -146,11 +152,16 @@ def parse_837_claim_to_sld(segments: List[List[str]], claim_type: str) -> List[S
                 ├── Service Line 2 (2400)
                 └── Service Line N (2400)
     
+    Properly handles multiple loops at each hierarchy level:
+    - Multiple Billing Providers (2000A)
+    - Multiple Subscribers per Billing Provider (2000B)
+    - Multiple Patients per Subscriber (2000C)
+    - Multiple Claims per Patient/Subscriber (2300)
+    - Multiple Service Lines per Claim (2400)
     """
     slds = []
-    current_data = ClaimData(claim_type=claim_type)
-    in_rendering_provider_loop = False
-    claim_control_number = None
+    hierarchy = HierarchyContext()
+    claim = ClaimContext()
 
     for i, segment in enumerate(segments):
         if len(segment) < 2:
@@ -158,46 +169,89 @@ def parse_837_claim_to_sld(segments: List[List[str]], claim_type: str) -> List[S
             
         seg_id = segment[0]
         
-        # Process NM1 segments (Provider and Patient info)
-        if seg_id == 'ST':
-            claim_control_number = segment[2] if len(segment) > 2 else None
+        # ===== HIERARCHY LEVEL TRACKING (HL segments) =====
+        if seg_id == 'HL' and len(segment) >= 4:
+            hl_id = segment[1]
+            parent_id = segment[2] if segment[2] else None
+            level_code = segment[3]
+            
+            hierarchy.current_hl_id = hl_id
+            hierarchy.current_hl_level = level_code
+            
+            if level_code == '20':  # New Billing Provider
+                hierarchy.billing_provider_npi = None
+                hierarchy.subscriber_patient_id = None
+                hierarchy.patient_patient_id = None
+                claim = ClaimContext()
+                
+            elif level_code == '22':  # New Subscriber
+                hierarchy.subscriber_patient_id = None
+                hierarchy.patient_patient_id = None
+                claim = ClaimContext()
+                
+            elif level_code == '23':  # New Patient
+                hierarchy.patient_patient_id = None
+                claim = ClaimContext()
 
+       # ===== NAME/IDENTIFICATION (NM1 segments) =====
         elif seg_id == 'NM1' and len(segment) > 1:
-            if segment[1] == 'IL':  # Subscriber/Patient
-                current_data.patient_id = get_segment_value(segment, 9)
-                in_rendering_provider_loop = False
-            elif segment[1] == '82' and len(segment) > 8 and segment[8] == 'XX':  # Rendering Provider
-                current_data.performing_provider_npi = get_segment_value(segment, 9)
-                in_rendering_provider_loop = True
-            elif segment[1] == '85' and len(segment) > 8 and segment[8] == 'XX':  # Billing Provider
-                current_data.billing_provider_npi = get_segment_value(segment, 9)
-                
-        # Process Provider Specialty
-        elif seg_id == 'PRV' and len(segment) > 1 and segment[1] == 'PE' and in_rendering_provider_loop:
-            current_data.provider_specialty = get_segment_value(segment, 3)
+            qualifier = segment[1]
+            claim.last_nm1_qualifier = qualifier
             
-        # Process Claim Information
+            # Billing Provider (2010AA in 2000A)
+            if qualifier == '85' and len(segment) > 8 and segment[8] == 'XX':
+                hierarchy.billing_provider_npi = get_segment_value(segment, 9)
+                
+            # Subscriber or Patient (2010BA in 2000B)
+            elif qualifier == 'IL':
+                patient_id = get_segment_value(segment, 9)
+                if hierarchy.current_hl_level == '22':  # Subscriber level
+                    hierarchy.subscriber_patient_id = patient_id
+                    hierarchy.patient_patient_id = None
+                elif hierarchy.current_hl_level == '23':  # Patient level
+                    hierarchy.patient_patient_id = patient_id
+                else:
+                    # Fallback: assume subscriber
+                    hierarchy.subscriber_patient_id = patient_id
+                    
+            # Patient (2010CA in 2000C)
+            elif qualifier == 'QC':
+                hierarchy.patient_patient_id = get_segment_value(segment, 9)
+                
+            # Performing/Rendering Provider (2310D in 2300)
+            elif qualifier == '82' and len(segment) > 8 and segment[8] == 'XX':
+                claim.performing_provider_npi = get_segment_value(segment, 9)
+        
+                
+        # ===== PROVIDER SPECIALTY (PRV segment) =====
+        elif seg_id == 'PRV' and len(segment) > 3 and segment[1] == 'PE':
+            # Only apply if last NM1 was performing provider (82)
+            if claim.last_nm1_qualifier == '82':
+                claim.provider_specialty = get_segment_value(segment, 3)
+           
+        # ===== CLAIM LEVEL (CLM segment - starts 2300 loop) =====
         elif seg_id == 'CLM':
-            in_rendering_provider_loop = False
-            current_data.claim_id = segment[1] if len(segment) > 1 else None
+            claim = ClaimContext()
+            claim.claim_id = segment[1] if len(segment) > 1 else None
             
             # Parse facility and service type for institutional claims
             if claim_type == "837I" and len(segment) > 5 and segment[5] and ':' in segment[5]:
-                current_data.facility_type = segment[5][0] if segment[5] else None
-                current_data.service_type = segment[5][1] if len(segment[5]) > 1 else None
-
-        # Process Diagnosis Codes
-        elif seg_id == 'HI': 
+                claim.facility_type = segment[5][0] if segment[5] else None
+                claim.service_type = segment[5][1] if len(segment[5]) > 1 else None
+        
+        # ===== DIAGNOSIS CODES (HI segment) =====
+        elif seg_id == 'HI':
             # In 837I, there can be multiple HI segments in the claim
             # Also, in 837I, diagnosis position does not matter
             # We will use continuous numbering for diagnosis codes
             # use the last dx_lookup position as the starting position, and update
             hi_segment = parse_diagnosis_codes(segment)
+            # Re-index for multiple HI segments in same claim
             hi_segment_realigned = {
-                str(int(pos) + len(current_data.dx_lookup)): code
+                str(int(pos) + len(claim.dx_lookup)): code
                 for pos, code in hi_segment.items()
             }
-            current_data.dx_lookup.update(hi_segment_realigned)
+            claim.dx_lookup.update(hi_segment_realigned)
             
         # Process Service Lines
         # 
@@ -217,54 +271,56 @@ def parse_837_claim_to_sld(segments: List[List[str]], claim_type: str) -> List[S
         #   SV205 (Required) - Unit Count: Format 9999999.999 (whole numbers only - fractional quantities not recognized)
         #   NOTE: Diagnosis Code Pointer is not supported for SV2
         #
+        # ===== SERVICE LINE (SV1/SV2 segments - 2400 loop) =====
         elif seg_id in ['SV1', 'SV2']:
-            
             linked_diagnoses = []
             
             if seg_id == 'SV1':
-                # SV1 Professional Service: SV101=procedure, SV104=quantity, SV106=place_of_service
+                # SV1 Professional Service
                 proc_info = get_segment_value(segment, 1, '').split(':')
                 procedure_code = proc_info[1] if len(proc_info) > 1 else None
                 modifiers = proc_info[2:] if len(proc_info) > 2 else []
                 quantity = parse_amount(get_segment_value(segment, 4))
                 place_of_service = get_segment_value(segment, 5)
-                # Get diagnosis pointers and linked diagnoses
+                
+                # Get diagnosis pointers and resolve to actual codes
                 dx_pointers = get_segment_value(segment, 7, '')
                 linked_diagnoses = [
-                    current_data.dx_lookup[pointer]
+                    claim.dx_lookup[pointer]
                     for pointer in (dx_pointers.split(':') if dx_pointers else [])
-                    if pointer in current_data.dx_lookup
+                    if pointer in claim.dx_lookup
                 ]
             else:
-                # SV2 Institutional Service: SV201=revenue, SV202=procedure, SV205=quantity
-                # Revenue code in SV201
+                # SV2 Institutional Service
                 revenue_code = get_segment_value(segment, 1)
-                # Procedure code in SV202
                 proc_info = get_segment_value(segment, 2, '').split(':')
                 procedure_code = proc_info[1] if len(proc_info) > 1 else None
                 modifiers = proc_info[2:] if len(proc_info) > 2 else []
-                # Quantity in SV205
                 quantity = parse_amount(get_segment_value(segment, 5))
-                place_of_service = None  # Not applicable for institutional
-                # linked diagnoses are not supported for SV2
-                
+                place_of_service = None
             
-            # Get service line details
+            # Get service line details (NDC, dates) - lookback from current segment index
             ndc, service_date = process_service_line(segments, i)
             
+            # Determine effective patient ID (prefer patient level, fallback to subscriber)
+            effective_patient_id = (
+                hierarchy.patient_patient_id or 
+                hierarchy.subscriber_patient_id
+            )
+            
             # Create service level data
             service_data = ServiceLevelData(
-                claim_id=current_data.claim_id,
+                claim_id=claim.claim_id,
                 procedure_code=procedure_code,
                 linked_diagnosis_codes=linked_diagnoses,
-                claim_diagnosis_codes=list(current_data.dx_lookup.values()), # this is used for risk adjustment
-                claim_type=current_data.claim_type,
-                provider_specialty=current_data.provider_specialty,
-                performing_provider_npi=current_data.performing_provider_npi,
-                billing_provider_npi=current_data.billing_provider_npi,
-                patient_id=current_data.patient_id,
-                facility_type=current_data.facility_type,
-                service_type=current_data.service_type,
+                claim_diagnosis_codes=list(claim.dx_lookup.values()),
+                claim_type=claim_type,
+                provider_specialty=claim.provider_specialty,
+                performing_provider_npi=claim.performing_provider_npi,  # ✅ Correct field
+                billing_provider_npi=hierarchy.billing_provider_npi,
+                patient_id=effective_patient_id,
+                facility_type=claim.facility_type,
+                service_type=claim.service_type,
                 service_date=service_date,
                 place_of_service=place_of_service,
                 quantity=quantity,

hccinfhir/hccinfhir.py

@@ -189,9 +189,7 @@ class HCCInFHIR:
         """
         if not isinstance(diagnosis_codes, list):
             raise ValueError("diagnosis_codes must be a list")
-        if not diagnosis_codes:
-            raise ValueError("diagnosis_codes list cannot be empty")
-
+        
         demographics = self._ensure_demographics(demographics)
         raf_result = self._calculate_raf_from_demographics_and_dx_codes(
             diagnosis_codes, demographics, prefix_override, maci, norm_factor, frailty_score

hccinfhir/model_calculate.py

@@ -124,9 +124,9 @@ def calculate_raf(diagnosis_codes: List[str],
                                                    prefix_override=prefix_override)
     
     # Calculate risk scores
-    print(f"Coefficients: {coefficients}")
+    #print(f"Coefficients: {coefficients}")
     risk_score = sum(coefficients.values())
-    print(f"Risk Score: {risk_score}")
+    #print(f"Risk Score: {risk_score}")
     risk_score_demographics = sum(coefficients_demographics.values())
     risk_score_chronic_only = sum(coefficients_chronic_only.values()) - risk_score_demographics
     risk_score_hcc = risk_score - risk_score_demographics

hccinfhir/sample_files/sample_834_01.txt

@@ -0,0 +1 @@
+ISA*00*          *00*          *ZZ*DHCS           *ZZ*HEALTHPLAN     *250108*1430*^*00501*000000001*0*P*:~GS*BE*DHCS*HEALTHPLAN*20250108*1430*1*X*005010X220A1~ST*834*0001*005010X220A1~BGN*00*12345*20250108*1430****2~REF*38*MEDI-CAL~DTP*007*D8*20250108~N1*P5*CALIFORNIA DHCS*FI*953654321~N1*IN*HEALTH PLAN NAME*FI*987654321~INS*Y*18*021***FT***AC~REF*0F*MBR001~REF*6P*1A23BC456D7~REF*1D*MC123456789~REF*ABB*QMBPLUS~NM1*IL*1*GARCIA*MARIA*R***MI*MBR001~PER*IP**HP*5555551234~N3*123 MAIN ST~N4*LOS ANGELES*CA*90001~DMG*D8*19550315*F~HD*021**HLT*MEDICARE ADVANTAGE D-SNP~DTP*348*D8*20240101~HD*021**HLT*MEDI-CAL~DTP*348*D8*20240101~INS*Y*18*001***FT***AC~REF*0F*MBR002~REF*6P*2B34CD567E8~REF*1D*MC987654321~REF*AB*4M~NM1*IL*1*JOHNSON*ROBERT*L***MI*MBR002~N3*456 OAK AVE~N4*SAN DIEGO*CA*92101~DMG*D8*19600822*M~HD*001**HLT*MEDICARE PART C~DTP*348*D8*20230515~HD*001**HLT*MEDI-CAL~DTP*348*D8*20240101~INS*Y*18*024***FT***TE~REF*0F*MBR003~REF*6P*3C45DE678F9~REF*1D*MC555666777~REF*ABB*SLMBPLUS~NM1*IL*1*RODRIGUEZ*CARMEN****MI*MBR003~N3*789 PINE RD~N4*SACRAMENTO*CA*95814~DMG*D8*19481203*F~HD*024**HLT*MEDICARE PART A~DTP*348*D8*20220101~DTP*349*D8*20250228~HD*024**HLT*MEDI-CAL~DTP*348*D8*20220101~DTP*349*D8*20250228~INS*Y*18*021***FT***AC~REF*0F*MBR004~REF*1D*MC111222333~NM1*IL*1*NGUYEN*THANH*H***MI*MBR004~N3*321 ELM ST~N4*SAN FRANCISCO*CA*94102~DMG*D8*19701015*M~HD*021**HLT*MEDI-CAL~DTP*348*D8*20250101~INS*Y*18*021***FT***AC~REF*0F*MBR005~REF*6P*5E67FG890H1~NM1*IL*1*SMITH*JOHN*A***MI*MBR005~N3*654 MAPLE AVE~N4*FRESNO*CA*93650~DMG*D8*19580710*M~HD*021**HLT*MEDICARE PART C~DTP*348*D8*20250901~SE*68*0001~GE*1*1~IEA*1*000000001~

{hccinfhir-0.1.7.dist-info → hccinfhir-0.1.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hccinfhir
-Version: 0.1.7
+Version: 0.1.9
 Summary: HCC Algorithm for FHIR Resources
 Project-URL: Homepage, https://github.com/mimilabs/hccinfhir
 Project-URL: Issues, https://github.com/mimilabs/hccinfhir/issues

{hccinfhir-0.1.7.dist-info → hccinfhir-0.1.9.dist-info}/RECORD

@@ -1,11 +1,12 @@
 hccinfhir/__init__.py,sha256=G_5m6jm3_BK5NdcZWoi0NEKJEsE_LjAU1RaLaL9xNPU,1043
-hccinfhir/datamodels.py,sha256=EHkuWMhmHBt8GfVP3lrxfSogu-qZQzeforFzp0Bn_bM,7714
+hccinfhir/datamodels.py,sha256=lHDXkCpzafuzF094VoaQXl4MgeFPxPfi25QJxXj4YHk,10010
 hccinfhir/extractor.py,sha256=xL9c2VT-e2I7_c8N8j4Og42UEgVuCzyn9WFp3ntM5Ro,1822
-hccinfhir/extractor_837.py,sha256=Irp0ROWgZv6jru9w5sdkoTSYHDTh0v_I_xYRhWdHOjw,13037
+hccinfhir/extractor_834.py,sha256=vODcD53iU5ZwQsSbBE8Gix9D-0fz-EhwkmjqRO6LML8,19541
+hccinfhir/extractor_837.py,sha256=D60gUFtMk2S0NrJ0iq3ENo35yIwBmBQvF5TurJgRIa8,15327
 hccinfhir/extractor_fhir.py,sha256=wUN3vTm1oTZ-KvfcDebnpQMxAC-7YlRKv12Wrv3p85A,8490
 hccinfhir/filter.py,sha256=j_yD2g6RBXVUV9trKkWzsQ35x3fRvfKUPvEXKUefI64,2007
-hccinfhir/hccinfhir.py,sha256=tgNWGYvsQWOlmcnP-3yH3KfXgZtQ3IdxYfGP9SNSJb0,9879
-hccinfhir/model_calculate.py,sha256=vM0b4BkLafebk7A3yFxsEONRW4GkVbUl4GxNlLz5N8Q,6742
+hccinfhir/hccinfhir.py,sha256=GLTqUHlD2DzU2Xiv6Y_lYXiWHNHXm96WGAoNKd2t_Wg,9786
+hccinfhir/model_calculate.py,sha256=j1XMPaqW2r_pUyiUsLsDBICi56AIKMjVzDMF1EbJ24w,6744
 hccinfhir/model_coefficients.py,sha256=2Y_xCjX4__B1_xkX3pp-XTOW4KEAWo6RCVOOJ7ZZajM,5931
 hccinfhir/model_demographics.py,sha256=CR4WC8XVq-CI1nYJoVFc5-KXTw-pKoVlHkHqfnXlnj0,9121
 hccinfhir/model_dx_to_cc.py,sha256=guJny2Mb9z8YRNWCXGSIE3APbE06zwnA2NRkjAeUs60,1765
@@ -27,6 +28,7 @@ hccinfhir/data/ra_eligible_cpt_hcpcs_2026.csv,sha256=EYGN7k_rgCpJe59lL_yNInUcCkd
 hccinfhir/data/ra_hierarchies_2025.csv,sha256=HQSPNloe6mvvwMgv8ZwYAfWKkT2b2eUvm4JQy6S_mVQ,13045
 hccinfhir/data/ra_hierarchies_2026.csv,sha256=A6ZQZb0rpRWrySBB_KA5S4PGtMxWuzB2guU3aBE09v0,19596
 hccinfhir/sample_files/__init__.py,sha256=SGiSkpGrnxbvtEFMMlk82NFHOE50hFXcgKwKUSuVZUg,45
+hccinfhir/sample_files/sample_834_01.txt,sha256=J2HMXfY6fAFpV36rvLQ3QymRRS2TPqf3TQY6CNS7TrE,1627
 hccinfhir/sample_files/sample_837_0.txt,sha256=eggrD259uHa05z2dfxWBpUDseSDp_AQcLyN_adpHyTw,5295
 hccinfhir/sample_files/sample_837_1.txt,sha256=E155MdemSDYoXokuTXUZ6Br_RGGedYv5t5dh-eMRmuk,1322
 hccinfhir/sample_files/sample_837_10.txt,sha256=zSJXI78vHAksA7FFQEVLvepefdpMM2_AexLyoDimV3Q,1129
@@ -44,7 +46,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.1.7.dist-info/METADATA,sha256=o2Uur5C9layHtKuWQeEQ1THAwMpCLmEkmnVTvrOUWDE,24819
-hccinfhir-0.1.7.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-hccinfhir-0.1.7.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-hccinfhir-0.1.7.dist-info/RECORD,,
+hccinfhir-0.1.9.dist-info/METADATA,sha256=_LWbfnpzjHKIP-T_2cRf0GlvgEY3SnJWKX_UEHkhycE,24819
+hccinfhir-0.1.9.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+hccinfhir-0.1.9.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+hccinfhir-0.1.9.dist-info/RECORD,,