Metadata-Version: 2.4
Name: cms-medicare-analysis-kit
Version: 2.1.1
Summary: CMS Medicare payment analysis data, Federal Register corpus, RUC voting data, and PFS valuation corpus for use with Claude AI
License-Expression: MIT
Keywords: cms,medicare,healthcare,payment,analysis,ruc,valuation
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# cms-medicare-analysis-kit

CMS Medicare payment analysis data, Federal Register corpus, RUC voting data, and PFS valuation corpus for use with Claude AI.

## Installation

```bash
pip install cms-medicare-analysis-kit
```

## Quick Start

```python
from cms_kit import load_code_data, load_pos_data, load_specialty_data, search_fr

# Payment/RVU data for a code (2017–2026)
rows = load_code_data("27130")

# Site-of-service volume
pos_rows = load_pos_data("27130")

# Specialty utilization
spec_rows = load_specialty_data(specialty_cd="20", year=2024)

# Federal Register search
hits = search_fr("27130", synonyms=["total hip arthroplasty", "THA"])
```

## RUC Voting Data (v2.1.0+)

1,397 records from AMA RUC voting tables, CPT 2018–2026. Includes vote tallies, facilitation flags, modification flags, and notes.

```python
from cms_kit.ruc import load_ruc_votes, search_ruc_votes, summarize_ruc_votes

records = load_ruc_votes()

# Longitudinal summary for a code
summary = summarize_ruc_votes(records, "92920")

# Filtered search
results = search_ruc_votes(records, facilitated=True, min_dissent=5)
results = search_ruc_votes(records, notes="3")  # CPT referral codes
```

## PFS Valuation Corpus (v2.1.0+)

455 records covering 840 codes across CY 2018–2026. Structured extractions from every PFS rule's "Potentially Misvalued Services" and "Valuation of Specific Codes" sections.

```python
from cms_kit.valuations import load_valuations, search_valuations

corpus = load_valuations()

# Search by code, tag, year, or free text
hits = search_valuations(corpus, code="27130")
hits = search_valuations(corpus, tags=["CMS-REJECTED-RUC", "HIGH-IMPACT"])
hits = search_valuations(corpus, years=[2025, 2026], tags=["FUTURE-SIGNAL"])
```

## v2.1.1 Bug Fixes

- **FR search `cy` field**: Now returns `int` instead of `str` (fixes `if h['cy'] == 2026` comparisons)
- **Valuation key consistency**: Both `search_valuations()` and `search_valuations_summary()` now return both `text` (full content) and `excerpt` (first 300 chars)

## Data Contents

| Dataset | Records | Coverage |
|---------|---------|----------|
| Longitudinal payment/RVU | 176K rows | CY 2017–2026 (PFS, OPPS, ASC, Part B) |
| Specialty utilization | ~8 MB | CY 2017–2024 (PSPS) |
| Place-of-service volume | ~3 MB | CY 2017–2024 |
| Federal Register corpus | 40 rules | CY 2018–2026 (PFS + OPPS/ASC) |
| RUC voting data | 1,397 records | CPT 2018–2026 |
| PFS valuation corpus | 455 records, 840 codes | CY 2018–2026 |

## License

MIT
