mphapi 0.1.0__tar.gz

mphapi-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.1
+Name: mphapi
+Version: 0.1.0
+Summary: A Python interface to the MyPriceHealth API
+Author: David Archibald
+Author-email: davidarchibald@myprice.health
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pydantic (>=2.6.4,<3.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)

mphapi-0.1.0/mphapi/__init__.py

@@ -0,0 +1,5 @@
+from .claim import *  # noqa: F403, F401
+from .client import *  # noqa: F403, F401
+from .date import *  # noqa: F403, F401
+from .pricing import *  # noqa: F403, F401
+from .response import *  # noqa: F403, F401

mphapi-0.1.0/mphapi/claim.py

@@ -0,0 +1,332 @@
+from enum import Enum, IntEnum
+from typing import Optional
+
+from pydantic import AliasGenerator, BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from .date import Date
+
+camel_case_model_config = ConfigDict(
+    alias_generator=AliasGenerator(
+        validation_alias=to_camel, serialization_alias=to_camel
+    ),
+    populate_by_name=True,
+)
+
+
+class FormType(str, Enum):
+    """Type of form used to submit the claim. Can be HCFA or UB-04 (from CLM05_02)"""
+
+    HCFA = "HCFA"
+    UB_04 = "UB-04"
+
+
+class BillTypeSequence(str, Enum):
+    """Where the claim is at in its billing lifecycle (e.g. 0: Non-Pay, 1: Admit Through
+    Discharge, 7: Replacement, etc.) (from CLM05_03)
+    """
+
+    NON_PAY = "G"
+    ADMIT_THROUGH_DISCHARGE = "H"
+    FIRST_INTERIM = "I"
+    CONTINUING_INTERIM = "J"
+    LAST_INTERIM = "K"
+    LATE_CHARGE = "M"
+    FIRST_INTERIM_DEPRECATED = "P"
+    REPLACEMENT = "Q"
+    VOID_OR_CANCEL = "0"
+    FINAL_CLAIM = "1"
+    CWF_ADJUSTMENT = "2"
+    CMS_ADJUSTMENT = "3"
+    INTERMEDIARY_ADJUSTMENT = "4"
+    OTHER_ADJUSTMENT = "5"
+    OIG_ADJUSTMENT = "6"
+    MSP_ADJUSTMENT = "7"
+    QIO_ADJUSTMENT = "8"
+    PROVIDER_ADJUSTMENT = "9"
+
+
+class SexType(IntEnum):
+    """Biological sex of the patient for clinical purposes"""
+
+    UNKNOWN = 0
+    MALE = 1
+    FEMALE = 2
+
+
+class Provider(BaseModel):
+    model_config = camel_case_model_config
+
+    npi: str
+    """National Provider Identifier of the provider (from NM109, required)"""
+
+    provider_tax_id: Optional[str] = None
+    """City of the provider (from N401, highly recommended)"""
+
+    provider_phones: Optional[list[str]] = None
+    """Address line 1 of the provider (from N301, highly recommended)"""
+
+    provider_faxes: Optional[list[str]] = None
+    """Commercial number of the provider used by some payers (from REF G2, optional)"""
+
+    provider_emails: Optional[list[str]] = None
+    """State license number of the provider (from REF 0B, optional)"""
+
+    provider_license_number: Optional[str] = None
+    """Last name of the provider (from NM103, highly recommended)"""
+
+    provider_commercial_number: Optional[str] = None
+    """Email addresses of the provider (from PER, optional)"""
+
+    provider_taxonomy: Optional[str] = None
+    """State of the provider (from N402, highly recommended)"""
+
+    provider_first_name: Optional[str] = None
+    """Taxonomy code of the provider (from PRV03, highly recommended)"""
+
+    provider_last_name: Optional[str] = None
+    """First name of the provider (NM104, highly recommended)"""
+
+    provider_org_name: Optional[str] = None
+    """Organization name of the provider (from NM103, highly recommended)"""
+
+    provider_address1: Optional[str] = None
+    """Tax ID of the provider (from REF highly recommended)"""
+
+    provider_address2: Optional[str] = None
+    """Phone numbers of the provider (from PER, optional)"""
+
+    provider_city: Optional[str] = None
+    """Fax numbers of the provider (from PER, optional)"""
+
+    provider_state: Optional[str] = None
+    """Address line 2 of the provider (from N302, optional)"""
+
+    provider_zip: str
+    """ZIP code of the provider (from N403, required)"""
+
+
+class ValueCode(BaseModel):
+    """Code indicating the type of value provided (from HIxx_02)"""
+
+    model_config = camel_case_model_config
+
+    code: str
+
+    """Amount associated with the value code (from HIxx_05)"""
+    amount: float
+
+
+class Diagnosis(BaseModel):
+    """Principal ICD diagnosis for the patient (from HI ABK or BK)"""
+
+    model_config = camel_case_model_config
+
+    code: str
+    """ICD code for the diagnosis"""
+
+    description: Optional[str] = None
+    """Description of the diagnosis"""
+
+
+class Service(BaseModel):
+    model_config = camel_case_model_config
+
+    provider: Optional[Provider] = None
+    """Additional provider information specific to this service item"""
+
+    line_number: Optional[str] = None
+    """Unique line number for the service item (from LX01)"""
+
+    rev_code: Optional[str] = None
+    """Revenue code (from SV2_01)"""
+
+    procedure_code: Optional[str] = None
+    """Procedure code (from SV101_02 / SV202_02)"""
+
+    procedure_modifiers: Optional[str] = None
+    """Procedure modifiers (from SV101_03, 4, 5, 6 / SV202_03, 4, 5, 6)"""
+
+    drug_code: Optional[str] = None
+    """National Drug Code (from LIN03)"""
+
+    date_from: Optional[Date] = None
+    """Begin date of service (from DTP 472)"""
+
+    date_through: Optional[Date] = None
+    """End date of service (from DTP 472)"""
+
+    billed_amount: Optional[float] = None
+    """Billed charge for the service (from SV102 / SV203)"""
+
+    allowed_amount: Optional[float] = None
+    """Plan allowed amount for the service (non-EDI)"""
+
+    paid_amount: Optional[float] = None
+    """Plan paid amount for the service (non-EDI)"""
+
+    quantity: Optional[float] = None
+    """Quantity of the service (from SV104 / SV205)"""
+
+    units: Optional[str] = None
+    """Units connected to the quantity given (from SV103 / SV204)"""
+
+    place_of_service: Optional[str] = None
+    """Place of service code (from SV105)"""
+
+    diagnosis_pointers: Optional[list[int]] = None
+    """Diagnosis pointers (from SV107)"""
+
+    ambulance_pickup_zip: Optional[str] = None
+    """ZIP code where ambulance picked up patient. Supplied if different than claim-level value (from NM1 PW)"""
+
+
+class Claim(Provider, BaseModel):
+    model_config = camel_case_model_config
+
+    claim_id: Optional[str] = None
+    """Unique identifier for the claim (from REF D9)"""
+
+    plan_code: Optional[str] = None
+    """Identifies the subscriber's plan (from SBR03)"""
+
+    patient_sex: Optional[SexType] = None
+    """Biological sex of the patient for clinical purposes (from DMG02). 0:Unknown, 1:Male,
+    2:Female
+    """
+
+    patient_date_of_birth: Optional[Date] = None
+    """Patient date of birth (from DMG03)"""
+
+    patient_height_in_cm: Optional[float] = None
+    """Patient height in centimeters (from HI value A9, MEA value HT)"""
+
+    patient_weight_in_kg: Optional[float] = None
+    """Patient weight in kilograms (from HI value A8, PAT08, CR102 [ambulance only])"""
+
+    ambulance_pickup_zip: Optional[str] = None
+    """Location where patient was picked up in ambulance (from HI with HIxx_01=BE and HIxx_02=A0
+    or NM1 loop with NM1 PW)
+    """
+
+    form_type: Optional[FormType] = None
+    """Type of form used to submit the claim. Can be HCFA or UB-04 (from CLM05_02)"""
+
+    bill_type_or_pos: Optional[str] = None
+    """Describes type of facility where services were rendered (from CLM05_01)"""
+
+    bill_type_sequence: Optional[BillTypeSequence] = None
+    """Where the claim is at in its billing lifecycle (e.g. 0: Non-Pay, 1: Admit Through
+    Discharge, 7: Replacement, etc.) (from CLM05_03)
+    """
+
+    billed_amount: Optional[float] = None
+    """Billed amount from provider (from CLM02)"""
+
+    allowed_amount: Optional[float] = None
+    """Amount allowed by the plan for payment. Both member and plan responsibility (non-EDI)"""
+
+    paid_amount: Optional[float] = None
+    """Amount paid by the plan for the claim (non-EDI)"""
+
+    date_from: Optional[Date] = None
+    """Earliest service date among services, or statement date if not found"""
+
+    date_through: Optional[Date] = None
+    """Latest service date among services, or statement date if not found"""
+
+    discharge_status: Optional[str] = None
+    """Status of the patient at time of discharge (from CL103)"""
+
+    admit_diagnosis: Optional[str] = None
+    """ICD diagnosis at the time the patient was admitted (from HI ABJ or BJ)"""
+
+    principal_diagnosis: Optional[Diagnosis] = None
+    """Principal ICD diagnosis for the patient (from HI ABK or BK)"""
+
+    other_diagnoses: Optional[list[Diagnosis]] = None
+    """Other ICD diagnoses that apply to the patient (from HI ABF or BF)"""
+
+    principal_procedure: Optional[str] = None
+    """Principal ICD procedure for the patient (from HI BBR or BR)"""
+
+    other_procedures: Optional[list[str]] = None
+    """Other ICD procedures that apply to the patient (from HI BBQ or BQ)"""
+
+    condition_codes: Optional[list[str]] = None
+    """Special conditions that may affect payment or other processing (from HI BG)"""
+
+    value_codes: Optional[list[ValueCode]] = None
+    """Numeric values related to the patient or claim (HI BE)"""
+
+    occurrence_codes: Optional[list[str]] = None
+    """Date related occurrences related to the patient or claim (from HI BH)"""
+
+    drg: Optional[str] = None
+    """Diagnosis Related Group for inpatient services (from HI DR)"""
+
+    services: list[Service] = Field(min_length=1)
+    """One or more services provided to the patient (from LX loop)"""
+
+
+class RateSheetService(BaseModel):
+    model_config = camel_case_model_config
+
+    procedure_code: str
+    """Procedure code (from SV101_02 / SV202_02)"""
+
+    procedure_modifiers: list[str]
+    """Procedure modifiers (from SV101_03, 4, 5, 6 / SV202_03, 4, 5, 6)"""
+
+    billed_amount: float
+    """Billed charge for the service (from SV102 / SV203)"""
+
+    allowed_amount: float
+    """Plan allowed amount for the service (non-EDI)"""
+
+
+class RateSheet(BaseModel):
+    npi: str
+    """National Provider Identifier of the provider (from NM109, required)"""
+
+    provider_first_name: str
+    """First name of the provider (NM104, highly recommended)"""
+
+    provider_last_name: str
+    """Last name of the provider (from NM103, highly recommended)"""
+
+    provider_org_name: str
+    """Organization name of the provider (from NM103, highly recommended)"""
+
+    provider_address: str
+    """Address of the provider (from N301, highly recommended)"""
+
+    provider_city: str
+    """City of the provider (from N401, highly recommended)"""
+
+    provider_state: str
+    """State of the provider (from N402, highly recommended)"""
+
+    provider_zip: str
+    """ZIP code of the provider (from N403, required)"""
+
+    form_type: FormType
+    """Type of form used to submit the claim. Can be HCFA or UB-04 (from CLM05_02)"""
+
+    bill_type_or_pos: str
+    """Describes type of facility where services were rendered (from CLM05_01)"""
+
+    drg: str
+    """Diagnosis Related Group for inpatient services (from HI DR)"""
+
+    billed_amount: float
+    """Billed amount from provider (from CLM02)"""
+
+    allowed_amount: float
+    """Amount allowed by the plan for payment. Both member and plan responsibility (non-EDI)"""
+
+    paid_amount: float
+    """Amount paid by the plan for the claim (non-EDI)"""
+
+    services: list[RateSheetService]
+    """One or more services provided to the patient (from LX loop)"""

mphapi-0.1.0/mphapi/client.py

@@ -0,0 +1,215 @@
+import urllib.parse
+from typing import Any, Mapping, Sequence
+
+import requests
+from pydantic import BaseModel, StrictBool, TypeAdapter
+
+from .claim import Claim, RateSheet
+from .pricing import Pricing
+from .response import Response, Responses
+
+Header = Mapping[str, str | bytes | None]
+
+
+class PriceConfig(BaseModel):
+    """PriceConfig is used to configure the behavior of the pricing API"""
+
+    is_commercial: StrictBool
+    """set to true to use commercial code crosswalks"""
+
+    disable_cost_based_reimbursement: StrictBool
+    """by default, the API will use cost-based reimbursement for MAC priced line-items. This is the best estimate we have for this proprietary pricing"""
+
+    use_commercial_synthetic_for_not_allowed: StrictBool
+    """set to true to use a synthetic Medicare price for line-items that are not allowed by Medicare"""
+
+    use_drg_from_grouper: StrictBool
+    """set to true to always use the DRG from the inpatient grouper"""
+
+    use_best_drg_price: StrictBool
+    """set to true to use the best DRG price between the price on the claim and the price from the grouper"""
+
+    override_threshold: float
+    """set to a value greater than 0 to allow the pricer flexibility to override NCCI edits and other overridable errors and return a price"""
+
+    include_edits: StrictBool
+    """set to true to include edit details in the response"""
+
+
+class Client:
+    url: str
+    headers: Header
+
+    def __init__(self, apiKey: str, isTest: bool = False):
+        if isTest:
+            self.url = "https://api-test.myprice.health"
+        else:
+            self.url = "https://api.myprice.health"
+
+        self.headers = {"x-api-key": apiKey}
+
+    def _do_request(
+        self,
+        path: str,
+        json: Any | None,
+        method: str = "POST",
+        headers: Header = {},
+    ) -> requests.Response:
+        return requests.request(
+            method,
+            urllib.parse.urljoin(self.url, path),
+            json=json,
+            headers={**self.headers, **headers},
+        )
+
+    def _receive_response[
+        Model: BaseModel
+    ](
+        self,
+        path: str,
+        body: BaseModel,
+        response_model: type[Model],
+        method: str = "POST",
+        headers: Header = {},
+    ) -> Model:
+        """
+        Raises:
+            ValueError
+                When response cannot be decoded.
+            mphapi.APIError
+                The error returned when the api returns an error.
+        """
+
+        response = self._do_request(
+            path,
+            body.model_dump(mode="json", by_alias=True, exclude_none=True),
+            method,
+            headers,
+        )
+
+        return (
+            Response[response_model]
+            .model_validate_json(response.content, strict=True)
+            .result()
+        )
+
+    def _receive_responses[
+        Model: BaseModel
+    ](
+        self,
+        path: str,
+        body: Sequence[BaseModel],
+        response_model: type[Model],
+        method: str = "POST",
+        headers: Header = {},
+    ) -> list[Model]:
+        """
+        Raises:
+            ValueError
+                When response cannot be decoded.
+            mphapi.APIError
+                The error returned when the api returns an error.
+        """
+
+        response = self._do_request(
+            path,
+            TypeAdapter(type(body)).dump_python(
+                body, mode="json", by_alias=True, exclude_none=True
+            ),
+            method,
+            headers,
+        )
+
+        return (
+            Responses[response_model]
+            .model_validate_json(response.content, strict=True)
+            .results()
+        )
+
+    def estimate_rate_sheet(self, *inputs: RateSheet) -> list[Pricing]:
+        """
+        Raises:
+            ValueError
+                When response cannot be decoded.
+            mphapi.APIError
+                The error returned when the api returns an error.
+        """
+
+        return self._receive_responses(
+            "/v1/medicare/estimate/rate-sheet",
+            inputs,
+            Pricing,
+        )
+
+    def estimate_claims(self, config: PriceConfig, *inputs: Claim) -> list[Pricing]:
+        """
+        Raises:
+            ValueError
+                When response cannot be decoded.
+            mphapi.APIError
+                The error returned when the api returns an error.
+        """
+
+        return self._receive_responses(
+            "/v1/medicare/estimate/claims",
+            inputs,
+            Pricing,
+            headers=self._get_price_headers(config),
+        )
+
+    def price(self, config: PriceConfig, input: Claim) -> Pricing:
+        """
+        Raises:
+            ValueError
+                When response cannot be decoded.
+            mphapi.APIError
+                The error returned when the api returns an error.
+        """
+
+        return self._receive_response(
+            "/v1/medicare/price/claim",
+            input,
+            Pricing,
+            headers=self._get_price_headers(config),
+        )
+
+    def price_batch(self, config: PriceConfig, *input: Claim) -> list[Pricing]:
+        """
+        Raises:
+            ValueError
+                When response cannot be decoded.
+            mphapi.APIError
+                The error returned when the api returns an error.
+        """
+
+        return self._receive_responses(
+            "/v1/medicare/price/claims",
+            input,
+            Pricing,
+            headers=self._get_price_headers(config),
+        )
+
+    def _get_price_headers(self, config: PriceConfig) -> Header:
+        headers: Header = {}
+        if config.is_commercial:
+            headers["is-commercial"] = "true"
+
+        if config.disable_cost_based_reimbursement:
+            headers["disable-cost-based-reimbursement"] = "true"
+
+        if config.use_commercial_synthetic_for_not_allowed:
+            headers["use-commercial-synthetic-for-not-allowed"] = "true"
+
+        if config.override_threshold > 0:
+            headers["override-threshold"] = str(config.override_threshold)
+
+        if config.include_edits:
+            headers["include-edits"] = "true"
+
+        if config.use_drg_from_grouper:
+            headers["use-drg-from-grouper"] = "true"
+
+        if config.use_best_drg_price:
+            headers["use-best-drg-price"] = "true"
+
+        return headers

mphapi-0.1.0/mphapi/date.py

@@ -0,0 +1,51 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+
+
+class Date:
+    """Date is a custom type for representing dates in the format YYYYMMDD"""
+
+    year: int
+    month: int
+    day: int
+
+    def __init__(self, year: int, month: int, day: int):
+        self.year = year
+        self.month = month
+        self.day = day
+
+    def __str__(self):
+        return f"{self.year}{self.month:02d}{self.day:02d}"
+
+    # Based off of this: https://docs.pydantic.dev/2.1/usage/types/custom/#handling-third-party-types
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        def to_date(value: str) -> Date:
+            time = datetime.strptime(value, "%Y%m%d")
+
+            return Date(time.year, time.month, time.day)
+
+        from_str = core_schema.chain_schema(
+            [
+                core_schema.str_schema(),
+                core_schema.no_info_plain_validator_function(to_date),
+            ]
+        )
+
+        return core_schema.json_or_python_schema(
+            json_schema=from_str,
+            python_schema=core_schema.union_schema(
+                [
+                    core_schema.is_instance_schema(Date),
+                    from_str,
+                ]
+            ),
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                lambda date: str(date)
+            ),
+        )

mphapi-0.1.0/mphapi/pricing.py

@@ -0,0 +1,337 @@
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, GetCoreSchemaHandler
+from pydantic_core import core_schema
+
+from .claim import Service, camel_case_model_config
+from .response import ResponseError
+
+
+class ClaimRepricingCode(str, Enum):
+    """claim-level repricing codes"""
+
+    MEDICARE = "MED"
+    CONTRACT_PRICING = "CON"
+    RBP_PRICING = "RBP"
+    SINGLE_CASE_AGREEMENT = "SCA"
+    NEEDS_MORE_INFO = "IFO"
+
+
+class LineRepricingCode(str, Enum):
+    # line-level Medicare repricing codes
+    MEDICARE = "MED"
+    SYNTHETIC_MEDICARE = "SYN"
+    COST_PERCENT = "CST"
+    MEDICARE_PERCENT = "MPT"
+    MEDICARE_NO_OUTLIER = "MNO"
+    BILLED_PERCENT = "BIL"
+    FEE_SCHEDULE = "FSC"
+    PER_DIEM = "PDM"
+    FLAT_RATE = "FLT"
+    LIMITED_TO_BILLED = "LTB"
+
+    # line-level zero dollar repricing explanations
+    NOT_ALLOWED_BY_MEDICARE = "NAM"
+    PACKAGED = "PKG"
+    NEEDS_MORE_INFO = "IFO"
+    PROCEDURE_CODE_PROBLEM = "CPB"
+    NOT_REPRICED_PER_REQUEST = "NRP"
+
+
+class HospitalType(str, Enum):
+    ACUTE_CARE = "Acute Care Hospitals"
+    CRITICAL_ACCESS = "Critical Access Hospitals"
+    CHILDRENS = "Childrens"
+    PSYCHIATRIC = "Psychiatric"
+    ACUTE_CARE_DOD = "Acute Care - Department of Defense"
+
+
+class InpatientPriceDetail(BaseModel):
+    """InpatientPriceDetail contains pricing details for an inpatient claim"""
+
+    model_config = camel_case_model_config
+
+    drg: Optional[str] = None
+    """Diagnosis Related Group (DRG) code used to price the claim"""
+
+    drg_amount: Optional[float] = None
+    """Amount Medicare would pay for the DRG"""
+
+    passthrough_amount: Optional[float] = None
+    """Per diem amount to cover capital-related costs, direct medical education, and other costs"""
+
+    outlier_amount: Optional[float] = None
+    """Additional amount paid for high cost cases"""
+
+    indirect_medical_education_amount: Optional[float] = None
+    """Additional amount paid for teaching hospitals"""
+
+    disproportionate_share_amount: Optional[float] = None
+    """Additional amount paid for hospitals with a high number of low-income patients"""
+
+    uncompensated_care_amount: Optional[float] = None
+    """Additional amount paid for patients who are unable to pay for their care"""
+
+    readmission_adjustment_amount: Optional[float] = None
+    """Adjustment amount for hospitals with high readmission rates"""
+
+    value_based_purchasing_amount: Optional[float] = None
+    """Adjustment for hospitals based on quality measures"""
+
+
+class OutpatientPriceDetail(BaseModel):
+    """OutpatientPriceDetail contains pricing details for an outpatient claim"""
+
+    model_config = camel_case_model_config
+
+    outlier_amount: float
+    """Additional amount paid for high cost cases"""
+
+    first_passthrough_drug_offset_amount: float
+    """Amount built into the APC payment for certain drugs"""
+
+    second_passthrough_drug_offset_amount: float
+    """Amount built into the APC payment for certain drugs"""
+
+    third_passthrough_drug_offset_amount: float
+    """Amount built into the APC payment for certain drugs"""
+
+    first_device_offset_amount: float
+    """Amount built into the APC payment for certain devices"""
+
+    second_device_offset_amount: float
+    """Amount built into the APC payment for certain devices"""
+
+    full_or_partial_device_credit_offset_amount: float
+    """Credit for devices that are supplied for free or at a reduced cost"""
+
+    terminated_device_procedure_offset_amount: float
+    """Credit for devices that are not used due to a terminated procedure"""
+
+
+class RuralIndicator(str, Enum):
+    RURAL = "R"
+    SUPER_RURAL = "B"
+    URBAN = ""
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        _source_type: Any,
+        _handler: GetCoreSchemaHandler,
+    ) -> core_schema.CoreSchema:
+        def from_int(value: int) -> RuralIndicator:
+            if value == 82:
+                return RuralIndicator.RURAL
+            elif value == 66:
+                return RuralIndicator.SUPER_RURAL
+            elif value == 32:
+                return RuralIndicator.URBAN
+            else:
+                raise ValueError(f"Unknown rural indicator value: {value}")
+
+        def to_int(instance: RuralIndicator) -> int:
+            if instance == RuralIndicator.RURAL:
+                return 82
+            elif instance == RuralIndicator.SUPER_RURAL:
+                return 66
+            elif instance == RuralIndicator.URBAN:
+                return 32
+            else:
+                raise ValueError(f"Unknown rural indicator: {instance}")
+
+        from_int_schema = core_schema.chain_schema(
+            [
+                core_schema.int_schema(),
+                core_schema.no_info_plain_validator_function(from_int),
+            ]
+        )
+
+        return core_schema.json_or_python_schema(
+            json_schema=from_int_schema,
+            python_schema=core_schema.union_schema(
+                [
+                    # check if it's an instance first before doing any further work
+                    core_schema.is_instance_schema(RuralIndicator),
+                    from_int_schema,
+                ]
+            ),
+            serialization=core_schema.plain_serializer_function_ser_schema(to_int),
+        )
+
+
+class ProviderDetail(BaseModel):
+    """
+    ProviderDetail contains basic information about the provider and/or locality used for pricing.
+    Not all fields are returned with every pricing request. For example, the CMS Certification
+    Number (CCN) is only returned for facilities which have a CCN such as hospitals.
+    """
+
+    model_config = camel_case_model_config
+
+    ccn: Optional[str] = None
+    """CMS Certification Number for the facility"""
+
+    mac: Optional[int] = None
+    """Medicare Administrative Contractor number"""
+
+    locality: Optional[int] = None
+    """Geographic locality number used for pricing"""
+
+    rural_indicator: Optional[RuralIndicator] = None
+    """Indicates whether provider is Rural (R), Super Rural (B), or Urban (blank)"""
+
+    specialty_type: Optional[str] = None
+    """Medicare provider specialty type"""
+
+    hospital_type: Optional[HospitalType] = None
+    """Type of hospital"""
+
+
+class ClaimEdits(BaseModel):
+    """ClaimEdits contains errors which cause the claim to be denied, rejected, suspended, or returned to the provider."""
+
+    model_config = camel_case_model_config
+
+    claim_overall_disposition: Optional[str] = None
+    claim_rejection_disposition: Optional[str] = None
+    claim_denial_disposition: Optional[str] = None
+    claim_return_to_provider_disposition: Optional[str] = None
+    claim_suspension_disposition: Optional[str] = None
+    line_item_rejection_disposition: Optional[str] = None
+    line_item_denial_disposition: Optional[str] = None
+    claim_rejection_reasons: Optional[list[str]] = None
+    claim_denial_reasons: Optional[list[str]] = None
+    claim_return_to_provider_reasons: Optional[list[str]] = None
+    claim_suspension_reasons: Optional[list[str]] = None
+    line_item_rejection_reasons: Optional[list[str]] = None
+    line_item_denial_reasons: Optional[list[str]] = None
+
+
+class Pricing(BaseModel):
+    """Pricing contains the results of a pricing request"""
+
+    model_config = camel_case_model_config
+
+    claim_id: Optional[str] = None
+    """The unique identifier for the claim (copied from input)"""
+
+    medicare_amount: Optional[float] = None
+    """The amount Medicare would pay for the service"""
+
+    allowed_amount: Optional[float] = None
+    """The allowed amount based on a contract or RBP pricing"""
+
+    allowed_calculation_error: Optional[str] = None
+    """The reason the allowed amount was not calculated"""
+
+    medicare_repricing_code: Optional[ClaimRepricingCode] = None
+    """Explains the methodology used to calculate Medicare (MED or IFO)"""
+
+    medicare_repricing_note: Optional[str] = None
+    """Note explaining approach for pricing or reason for error"""
+
+    allowed_repricing_code: Optional[ClaimRepricingCode] = None
+    """Explains the methodology used to calculate allowed amount (CON, RBP, SCA, or IFO)"""
+
+    allowed_repricing_note: Optional[str] = None
+    """Note explaining approach for pricing or reason for error"""
+
+    medicare_std_dev: Optional[float] = None
+    """The standard deviation of the estimated Medicare amount (estimates service only)"""
+
+    medicare_source: Optional[str] = None
+    """Source of the Medicare amount (e.g. physician fee schedule, OPPS, etc.)"""
+
+    inpatient_price_detail: Optional[InpatientPriceDetail] = None
+    """Details about the inpatient pricing"""
+
+    outpatient_price_detail: Optional[OutpatientPriceDetail] = None
+    """Details about the outpatient pricing"""
+
+    provider_detail: Optional[ProviderDetail] = None
+    """The provider details used when pricing the claim"""
+
+    edit_detail: Optional[ClaimEdits] = None
+    """Errors which cause the claim to be denied, rejected, suspended, or returned to the provider"""
+
+    pricer_result: Optional[str] = None
+    """Pricer return details"""
+
+    services: list[Service] = Field(min_length=1)
+    """Pricing for each service line on the claim"""
+
+    edit_error: Optional[ResponseError] = None
+    """An error that occurred during some step of the pricing process"""
+
+
+class LineEdits(BaseModel):
+    """LineEdits contains errors which cause the line item to be unable to be priced."""
+
+    model_config = camel_case_model_config
+
+    denial_or_rejection_text: str
+    procedure_edits: list[str]
+    modifier1_edits: list[str]
+    modifier2_edits: list[str]
+    modifier3_edits: list[str]
+    modifier4_edits: list[str]
+    modifier5_edits: list[str]
+    data_edits: list[str]
+    revenue_edits: list[str]
+    professional_edits: list[str]
+
+
+class PricedService(BaseModel):
+    """PricedService contains the results of a pricing request for a single service line"""
+
+    model_config = camel_case_model_config
+
+    line_number: str
+    """Number of the service line item (copied from input)"""
+
+    provider_detail: Optional[ProviderDetail] = None
+    """Provider Details used when pricing the service if different than the claim"""
+
+    medicare_amount: float
+    """Amount Medicare would pay for the service"""
+
+    allowed_amount: float
+    """Allowed amount based on a contract or RBP pricing"""
+
+    allowed_calculation_error: str
+    """Reason the allowed amount was not calculated"""
+
+    repricing_code: LineRepricingCode
+    """Explains the methodology used to calculate Medicare"""
+
+    repricing_note: str
+    """Note explaining approach for pricing or reason for error"""
+
+    technical_component_amount: float
+    """Amount Medicare would pay for the technical component"""
+
+    professional_component_amount: float
+    """Amount Medicare would pay for the professional component"""
+
+    medicare_std_dev: float
+    """Standard deviation of the estimated Medicare amount (estimates service only)"""
+
+    medicare_source: str
+    """Source of the Medicare amount (e.g. physician fee schedule, OPPS, etc.)"""
+
+    pricer_result: str
+    """Pricing service return details"""
+
+    status_indicator: str
+    """Code which gives more detail about how Medicare pays for the service"""
+
+    payment_indicator: str
+    """Text which explains the type of payment for Medicare"""
+
+    payment_apc: str
+    """Ambulatory Payment Classification"""
+
+    edit_detail: Optional[LineEdits] = None
+    """Errors which cause the line item to be unable to be priced"""

mphapi-0.1.0/mphapi/response.py

@@ -0,0 +1,124 @@
+from pydantic import BaseModel, RootModel
+from pydantic.dataclasses import dataclass
+
+
+class APIError(Exception):
+    message: str
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+@dataclass
+class ResponseError(APIError):
+    title: str
+    detail: str
+
+    def __post_init__(self):
+        super().__init__(self.__str__())
+
+    def __str__(self) -> str:
+        return f"{self.title}: {self.detail}"
+
+
+class ResponseSuccess[Result: BaseModel](BaseModel):
+    result: Result
+    status: int
+
+
+class ResponseFailure(BaseModel):
+    error: ResponseError
+    status: int
+
+
+@dataclass
+class GatewayError(APIError):
+    message: str
+    code: int
+
+    def __post_init__(self):
+        super().__init__(self.message)
+
+
+class Response[Result: BaseModel](
+    RootModel[ResponseSuccess[Result] | ResponseFailure | GatewayError]
+):
+    """
+    Response contains the standardized API response data used by all My Price Health API's. It is based off of the generalized error handling recommendation found
+    in IETF RFC 7807 https://tools.ietf.org/html/rfc7807 and is a simplification of the Spring Boot error response as described at https://www.baeldung.com/rest-api-error-handling-best-practices
+    """
+
+    """
+    An error response might look like this:
+    {
+        "error: {
+            "title": "Incorrect username or password.",
+            "detail": "Authentication failed due to incorrect username or password.",
+        }
+        "status": 401,
+    }
+
+    A successful response with a single result might look like this:
+    {
+        "result": {
+            "procedureCode": "ABC",
+            "billedAverage": 15.23
+        },
+        "status": 200,
+    }
+    """
+
+    def result(
+        self,
+    ) -> Result:
+        """Returns the result if it's successful, otherwise throws
+
+        Returns
+        -------
+        Result
+            The successful result.
+
+        Raises
+        ------
+        ResponseError
+            The request's error response.
+        """
+
+        if isinstance(self.root, ResponseSuccess):
+            return self.root.result
+        elif isinstance(self.root, ResponseFailure):
+            raise self.root.error
+        else:
+            raise self.root
+
+
+class ResponsesSuccess[Result: BaseModel](BaseModel):
+    results: list[Result]
+    success_count: int
+    error_count: int
+    status_code: int
+
+
+class Responses[Result: BaseModel](
+    RootModel[ResponsesSuccess[Result] | ResponseFailure]
+):
+    def results(
+        self,
+    ) -> list[Result]:
+        """Returns the result if it's successful, otherwise throws
+
+        Returns
+        -------
+        list[Result]
+            The results, although some may still have encountered errors.
+
+        Raises
+        ------
+        ResponseError
+            The request's error response.
+        """
+
+        if isinstance(self.root, ResponsesSuccess):
+            return self.root.results
+        else:
+            raise self.root.error

mphapi-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[tool.poetry]
+name = "mphapi"
+version = "0.1.0"
+description = "A Python interface to the MyPriceHealth API"
+authors = ["David Archibald <davidarchibald@myprice.health>"]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+pydantic = "^2.6.4"
+requests = "^2.31.0"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"