hccinfhir: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Information

Current Version: 0.1.5 Package Name: hccinfhir Description: A Python library for calculating HCC (Hierarchical Condition Category) risk adjustment scores from healthcare claims data License: Apache 2.0 Python Requirements: 3.9+

What This Library Does

HCCInFHIR processes healthcare data to calculate Medicare risk adjustment scores used for payment calculations. It supports multiple input formats:

1. FHIR ExplanationOfBenefit resources - from CMS Blue Button 2.0 API
2. X12 837 claim files - from clearinghouses and encounter data
3. X12 834 enrollment files - for extracting dual eligibility and demographic data
4. Direct diagnosis codes - for quick calculations
5. Service-level data - standardized internal format

The library implements the official CMS-HCC risk adjustment methodology, including:

• Diagnosis code to HCC mapping
• Hierarchical condition category rules
• Demographic coefficients and interactions
• RAF (Risk Adjustment Factor) score calculations

Development Commands

Testing

hatch shell                    # Activate virtual environment
pip install -e .              # Install package in development mode
pytest tests/*                # Run all tests
pytest tests/test_filter.py   # Run specific test file

Building and Publishing

hatch build                    # Build package
hatch publish                  # Publish to PyPI (maintainers only)

Dependencies

• Install new dependencies by updating pyproject.toml dependencies
• Core dependency: pydantic >= 2.10.3
• Development dependency: pytest

How Scripts and Modules Work

Main Entry Points

1. HCCInFHIR Class (hccinfhir.py)

The main processor class with three execution methods:

from hccinfhir import HCCInFHIR, Demographics

# Initialize processor
processor = HCCInFHIR(
    filter_claims=True,  # Apply CMS filtering rules
    model_name="CMS-HCC Model V28",  # HCC model to use
    proc_filtering_filename="ra_eligible_cpt_hcpcs_2026.csv",  # CPT/HCPCS filtering
    dx_cc_mapping_filename="ra_dx_to_cc_2026.csv"  # Diagnosis mapping
)