phactor 0.2.0__py3-none-any.whl

phactor/cohorts/models.py

@@ -0,0 +1,739 @@
+"""Pydantic models mirroring the Phactor GraphQL schema for cohort analysis."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+# ---------------------------------------------------------------------------
+# Helper config for all models: camelCase aliasing
+# ---------------------------------------------------------------------------
+
+def _alias_generator(field_name: str) -> str:
+    """Convert snake_case to camelCase."""
+    parts = field_name.split("_")
+    return parts[0] + "".join(w.capitalize() for w in parts[1:])
+
+
+_MODEL_CONFIG = ConfigDict(
+    populate_by_name=True,
+    alias_generator=_alias_generator,
+    use_enum_values=True,
+)
+
+
+# ============================================================================
+# ENUMS
+# ============================================================================
+
+
+class TimingOperator(str, Enum):
+    WITHIN = "WITHIN"
+    BEFORE = "BEFORE"
+    AFTER = "AFTER"
+    GREATER_THAN_OR_EQUALS = "GREATER_THAN_OR_EQUALS"
+    LESS_THAN_OR_EQUALS = "LESS_THAN_OR_EQUALS"
+    BETWEEN = "BETWEEN"
+
+
+class TimingUnit(str, Enum):
+    DAYS = "DAYS"
+    WEEKS = "WEEKS"
+    MONTHS = "MONTHS"
+    YEARS = "YEARS"
+
+
+class TimingReference(str, Enum):
+    SCREENING = "SCREENING"
+    RANDOMIZATION = "RANDOMIZATION"
+    ENROLLMENT = "ENROLLMENT"
+    BASELINE = "BASELINE"
+    INDEX_DATE = "INDEX_DATE"
+    NOW = "NOW"
+
+
+class ComparisonOperatorEnum(str, Enum):
+    EQUALS = "EQUALS"
+    GREATER_THAN = "GREATER_THAN"
+    LESS_THAN = "LESS_THAN"
+    GREATER_THAN_OR_EQUALS = "GREATER_THAN_OR_EQUALS"
+    LESS_THAN_OR_EQUALS = "LESS_THAN_OR_EQUALS"
+    BETWEEN = "BETWEEN"
+
+
+class GenderValue(str, Enum):
+    MALE = "MALE"
+    FEMALE = "FEMALE"
+    OTHER = "OTHER"
+
+
+class RaceValue(str, Enum):
+    UNKNOWN = "UNKNOWN"
+    WHITE = "WHITE"
+    ASIAN = "ASIAN"
+    BLACK = "BLACK"
+    NATIVE_HAWAIIAN = "NATIVE_HAWAIIAN"
+    AMERICAN_INDIAN = "AMERICAN_INDIAN"
+
+
+class LocationTypeEnum(str, Enum):
+    ZIP = "ZIP"
+    CITY = "CITY"
+    STATE = "STATE"
+    COORDS = "COORDS"
+
+
+# Code systems mirror the Query API GraphQL schema (ConditionTypeEnum) one-to-one.
+class ConditionTypeEnum(str, Enum):
+    DBCONDID = "DBCONDID"  # DrugBank condition identifier
+    ICD10 = "ICD10"
+    SNOMED = "SNOMED"
+    ICD10CM = "ICD10CM"
+    ICD9 = "ICD9"
+    ICD11 = "ICD11"
+    MEDDRA = "MEDDRA"
+
+
+# Clinical status qualifier — mirrors the Query API GraphQL schema
+# (ConditionClinicalStatus) one-to-one.
+class ConditionClinicalStatus(str, Enum):
+    ACTIVE = "ACTIVE"
+    RECURRENCE = "RECURRENCE"
+    RELAPSE = "RELAPSE"
+    INACTIVE = "INACTIVE"
+    REMISSION = "REMISSION"
+    RESOLVED = "RESOLVED"
+
+
+# Severity qualifier — mirrors the Query API GraphQL schema
+# (ConditionSeverity) one-to-one.
+class ConditionSeverity(str, Enum):
+    MILD = "MILD"
+    MODERATE = "MODERATE"
+    SEVERE = "SEVERE"
+
+
+# Code systems mirror the Query API GraphQL schema (MedicationTypeEnum) one-to-one.
+class MedicationTypeEnum(str, Enum):
+    PCID = "PCID"  # DrugBank product concept ID
+    RXCUI = "RXCUI"
+    NDC = "NDC"
+    ATC = "ATC"
+
+
+# FHIR MedicationStatement.status filter — mirrors the Query API GraphQL
+# schema (MedicationStatus) one-to-one.
+class MedicationStatus(str, Enum):
+    ACTIVE = "ACTIVE"
+    COMPLETED = "COMPLETED"
+    ENTERED_IN_ERROR = "ENTERED_IN_ERROR"
+    INTENDED = "INTENDED"
+    STOPPED = "STOPPED"
+    ON_HOLD = "ON_HOLD"
+    UNKNOWN = "UNKNOWN"
+    NOT_TAKEN = "NOT_TAKEN"
+
+
+# Code systems mirror the Query API GraphQL schema (ProcedureTypeEnum) one-to-one.
+class ProcedureTypeEnum(str, Enum):
+    CPT = "CPT"
+    SNOMED = "SNOMED"
+    HCPCS = "HCPCS"
+    ICD10PCS = "ICD10PCS"
+
+
+# FHIR Procedure.outcome filter — mirrors the Query API GraphQL schema
+# (ProcedureOutcome) one-to-one.
+class ProcedureOutcome(str, Enum):
+    SUCCESSFUL = "SUCCESSFUL"
+    PARTIALLY_SUCCESSFUL = "PARTIALLY_SUCCESSFUL"
+    UNSUCCESSFUL = "UNSUCCESSFUL"
+
+
+# Code systems mirror the Query API GraphQL schema (AllergyTypeEnum) one-to-one.
+class AllergyTypeEnum(str, Enum):
+    RXCUI = "RXCUI"
+    NDC = "NDC"
+    SNOMED = "SNOMED"
+
+
+# FHIR AllergyIntolerance.criticality filter — mirrors the Query API GraphQL
+# schema (AllergyCriticality) one-to-one.
+class AllergyCriticality(str, Enum):
+    LOW = "LOW"
+    HIGH = "HIGH"
+    UNABLE_TO_ASSESS = "UNABLE_TO_ASSESS"
+
+
+# Code systems mirror the Query API GraphQL schema (ImmunizationTypeEnum) one-to-one.
+class ImmunizationTypeEnum(str, Enum):
+    CVX = "CVX"
+    NDC = "NDC"
+    SNOMED = "SNOMED"
+
+
+# HL7 v3 Observation Interpretation codes (subset of Table 0078 that FHIR
+# Observation.interpretation binds to) — mirrors the Query API GraphQL schema
+# (InterpretationCode) one-to-one.
+class InterpretationCode(str, Enum):
+    N = "N"    # Normal
+    H = "H"    # High
+    L = "L"    # Low
+    HH = "HH"  # Critically high (panic high)
+    LL = "LL"  # Critically low (panic low)
+    HU = "HU"  # Significantly above upper limit
+    LU = "LU"  # Significantly below lower limit
+    A = "A"    # Abnormal (use when no high/low direction applies)
+    AA = "AA"  # Critically abnormal
+
+
+class ClinicalMeasurementCategory(str, Enum):
+    EXAMINATION = "EXAMINATION"
+    FUNCTIONAL_TEST = "FUNCTIONAL_TEST"
+    CLINICAL_SCORE = "CLINICAL_SCORE"
+    BIOMARKER = "BIOMARKER"
+    VITAL_SIGN = "VITAL_SIGN"
+    BODY_MEASUREMENT = "BODY_MEASUREMENT"
+    SOCIAL_HISTORY = "SOCIAL_HISTORY"
+    DEVICE = "DEVICE"
+
+
+class StabilityStatusEnum(str, Enum):
+    ACTIVE = "ACTIVE"
+    INTERRUPTED = "INTERRUPTED"
+    ENDED = "ENDED"
+
+
+class CriteriaGroupOperator(str, Enum):
+    AND = "AND"
+    OR = "OR"
+    SOME = "SOME"
+
+
+# Top-level operator combining multiple cohort_groups (mirrors the Query API
+# GraphQL schema's CohortGroupOperator). Distinct from CriteriaGroupOperator,
+# which combines criteria groups *within* a single cohort group.
+class InclusionGroupOperator(str, Enum):
+    """Relationship between inclusion criteria groups inside one pathway."""
+
+    AND = "AND"
+    OR = "OR"
+
+
+class CohortGroupOperator(str, Enum):
+    """Relationship between complete cohort pathways."""
+
+    AND = "AND"
+    OR = "OR"
+
+
+class CriterionErrorReason(str, Enum):
+    NO_TRANSLATION = "NO_TRANSLATION"
+    NO_PATH = "NO_PATH"
+
+
+class CriterionErrorDomain(str, Enum):
+    CONDITION = "CONDITION"
+    PROCEDURE = "PROCEDURE"
+    ALLERGY = "ALLERGY"
+    IMMUNIZATION = "IMMUNIZATION"
+    MEDICATION = "MEDICATION"
+
+
+class ResultGrouping(str, Enum):
+    NONE = "NONE"
+    STATE = "STATE"
+    CITY = "CITY"
+    PROXIMITY = "PROXIMITY"
+
+
+class ProximityMode(str, Enum):
+    RADIUS = "RADIUS"
+    DISTANCE_BANDS = "DISTANCE_BANDS"
+
+
+# ============================================================================
+# INPUT MODELS
+# ============================================================================
+
+
+class TimingInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    operator: TimingOperator
+    value: int | None = None
+    value_to: int | None = None
+    unit: TimingUnit
+    reference: TimingReference
+    reference_end: TimingReference | None = None
+    reference_date: str | None = None
+
+
+class AgeRangeInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    from_: int | None = Field(None, alias="from")
+    to: int | None = None
+
+
+class CoordsInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    lat: float
+    lng: float
+
+
+class LocationValueInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    type: LocationTypeEnum
+    value: str
+    radius: int
+    coords: CoordsInput | None = None
+
+
+class LocationInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    values: list[LocationValueInput] | None = None
+
+
+class ConditionStageInput(BaseModel):
+    # FHIR Condition.stage.type — staging vocabulary (e.g. TNM, FIGO,
+    # AnnArbor). `value` is meaningless without naming the `system`.
+    model_config = _MODEL_CONFIG
+
+    system: str
+    value: str
+
+
+class ConditionInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    type: ConditionTypeEnum
+    values: list[str]
+    timing: TimingInput | None = None
+    # Clinical qualifier filters (all optional). Supplying any narrows
+    # categorically, AND-combined with the base type/value/timing match.
+    status: list[ConditionClinicalStatus] | None = None
+    severity: list[ConditionSeverity] | None = None
+    stage: list[ConditionStageInput] | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_renamed_value_field(cls, data: object) -> object:
+        # 0.1.x used a singular `value: str`. Without this check the stray
+        # key is silently ignored and the error surfaces as an opaque
+        # "values: Field required" — point at the rename instead.
+        if isinstance(data, dict) and "value" in data and "values" not in data:
+            raise ValueError(
+                "`value` was renamed to `values` (a list of strings) in 0.2.0 "
+                "— pass values=[...] instead. See CHANGELOG.md."
+            )
+        return data
+
+
+class ConditionsInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    values: list[ConditionInput] | None = None
+
+
+class PdcFilterInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    min_pdc: float
+    window_days: int | None = None
+
+
+class StableDoseFilterInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    min_daily_dose_mg: float | None = None
+    min_consecutive_days: int | None = None
+
+
+class AdherenceCriteriaInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    therapy_status: list[StabilityStatusEnum] | None = None
+    pdc: PdcFilterInput | None = None
+    stable_dose: StableDoseFilterInput | None = None
+    gap_threshold_days: int | None = None
+
+
+class MedicationInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    type: MedicationTypeEnum
+    values: list[str]
+    last_ordered: str | None = None
+    timing: TimingInput | None = None
+    duration: int | None = None
+    duration_unit: TimingUnit | None = None
+    adherence: AdherenceCriteriaInput | None = None
+    # FHIR MedicationStatement.status filter (optional). Connector codegen
+    # routes to bitmap_medications_by_status.
+    status: list[MedicationStatus] | None = None
+
+
+class MedicationsInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    values: list[MedicationInput] | None = None
+
+
+class ProcedureInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    type: ProcedureTypeEnum
+    values: list[str]
+    timing: TimingInput | None = None
+    # FHIR Procedure.outcome filter (optional) — clinical result of the
+    # procedure, distinct from its lifecycle status.
+    outcome: list[ProcedureOutcome] | None = None
+
+
+class ProceduresInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    # `criteriaErrors` is an internal forwarding field the connector
+    # populates; the SDK omits it, mirroring ConditionsInput.
+    values: list[ProcedureInput] | None = None
+
+
+class AllergyInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    type: AllergyTypeEnum
+    values: list[str]
+    timing: TimingInput | None = None
+    # FHIR AllergyIntolerance.criticality filter (optional) — patient risk
+    # assessment, distinct from the reaction severity column.
+    criticality: list[AllergyCriticality] | None = None
+
+
+class AllergiesInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    # `criteriaErrors` is an internal forwarding field the connector
+    # populates; the SDK omits it, mirroring ConditionsInput.
+    values: list[AllergyInput] | None = None
+
+
+class ImmunizationInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    type: ImmunizationTypeEnum
+    values: list[str]
+    timing: TimingInput | None = None
+
+
+class ImmunizationsInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    # `criteriaErrors` is an internal forwarding field the connector
+    # populates; the SDK omits it, mirroring ConditionsInput.
+    values: list[ImmunizationInput] | None = None
+
+
+class LabValueInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    test_code: str | None = None
+    test_name: str | None = None
+    # operator/value/unit are optional so a categorical-only query
+    # (interpretation + testCode, no numeric comparison) is legal.
+    operator: ComparisonOperatorEnum | None = None
+    value: float | None = None
+    value_to: float | None = None
+    unit: str | None = None
+    timing: TimingInput | None = None
+    # Categorical filter on the HL7 v3 interpretation flag.
+    interpretation: list[InterpretationCode] | None = None
+
+    @model_validator(mode="after")
+    def _require_numeric_or_interpretation(self) -> LabValueInput:
+        # The connector silently skips a lab criterion that carries neither a
+        # complete numeric comparison nor an interpretation, inflating counts;
+        # fail fast here instead. A lab value's numeric triple is operator +
+        # value + unit.
+        has_numeric = (
+            self.operator is not None and self.value is not None and self.unit is not None
+        )
+        if not has_numeric and not self.interpretation:
+            raise ValueError(
+                "LabValueInput requires either a complete numeric comparison "
+                "(operator AND value AND unit) or a non-empty interpretation."
+            )
+        if self.test_code is None and self.test_name is None:
+            raise ValueError(
+                "LabValueInput requires at least one of test_code or test_name."
+            )
+        return self
+
+
+class ClinicalMeasurementInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    category: ClinicalMeasurementCategory
+    code: str | None = None
+    name: str | None = None
+    # operator/value are optional so a categorical-only query
+    # (interpretation + code) is legal.
+    operator: ComparisonOperatorEnum | None = None
+    value: float | None = None
+    value_to: float | None = None
+    unit: str | None = None
+    timing: TimingInput | None = None
+    # Categorical filter on the HL7 v3 interpretation flag.
+    interpretation: list[InterpretationCode] | None = None
+
+    @model_validator(mode="after")
+    def _require_numeric_or_interpretation(self) -> ClinicalMeasurementInput:
+        # Mirrors LabValueInput, but the clinical-measurement numeric pair is
+        # operator + value only — unit is NOT part of the pair (connector
+        # asymmetry, base-query-builder.ts `_clinicalMeasurementsWhereBody`).
+        # Same silent-skip hazard.
+        has_numeric = self.operator is not None and self.value is not None
+        if not has_numeric and not self.interpretation:
+            raise ValueError(
+                "ClinicalMeasurementInput requires either a numeric comparison "
+                "(operator AND value) or a non-empty interpretation."
+            )
+        return self
+
+
+class PropositionInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    age: AgeRangeInput | None = None
+    gender: list[GenderValue] | None = None
+    race: list[RaceValue] | None = None
+    medications: MedicationsInput | None = None
+    location: LocationInput | None = None
+    conditions: ConditionsInput | None = None
+    procedures: ProceduresInput | None = None
+    allergies: AllergiesInput | None = None
+    immunizations: ImmunizationsInput | None = None
+    lab_values: list[LabValueInput] | None = None
+    clinical_measurements: list[ClinicalMeasurementInput] | None = None
+
+
+class CriteriaGroupInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    name: str | None = None
+    operator: CriteriaGroupOperator
+    some_threshold: int | None = None
+    propositions: list[PropositionInput]
+
+
+class CohortGroupInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    inclusion_group_operator: InclusionGroupOperator
+    inclusion_groups: list[CriteriaGroupInput] | None = None
+    exclusion_groups: list[CriteriaGroupInput] | None = None
+
+
+class StudyContextInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    nct_id: str | None = None
+    study_title: str | None = None
+    study_phase: str | None = None
+    therapeutic_area: str | None = None
+
+
+class SiteInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    name: str
+    latitude: float
+    longitude: float
+    radius_miles: int | None = None
+
+
+class GroupingInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    type: ResultGrouping
+    proximity_mode: ProximityMode | None = None
+    sites: list[SiteInput] | None = None
+    default_radius_miles: int | None = None
+    distance_bands_miles: list[int] | None = None
+    max_groups: int | None = None
+    # Opt-in exact radius / distance-band counts (PostGIS ST_DWithin
+    # refine over the approximate H3 hex cover). Default None (approximate).
+    exact: bool | None = None
+
+
+class GlobalFiltersInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    geography: LocationInput | None = None
+
+
+class AnalyzeCohortsInput(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    providers: list[str]
+    cohort_groups: list[CohortGroupInput]
+    cohort_group_operator: CohortGroupOperator | None = None
+    study_context: StudyContextInput | None = None
+    include_impact_analysis: bool | None = None
+    include_demographic_breakdown: bool | None = None
+    include_combined_demographic_breakdown: bool | None = None
+    grouping: GroupingInput | None = None
+    global_filters: GlobalFiltersInput | None = None
+
+
+# ============================================================================
+# RESPONSE MODELS
+# ============================================================================
+
+
+class ProviderMeta(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    id: str
+    name: str
+
+
+class AnalysisWarning(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    provider: ProviderMeta
+    code: str
+    message: str
+
+
+class CriterionImpact(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    proposition_index: int
+    proposition_label: str
+    matching_count: int
+    excluded_count: int
+    impact_percentage: float
+
+
+class BucketCount(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    range_from: int
+    range_to: int
+    count: int
+    percentage: float
+
+
+class LabeledCount(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    label: str
+    count: int
+    percentage: float
+
+
+class DemographicBreakdown(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    age_distribution: list[BucketCount] | None = None
+    gender_distribution: list[LabeledCount] | None = None
+    race_distribution: list[LabeledCount] | None = None
+    geographic_distribution: list[LabeledCount] | None = None
+
+
+class CriterionError(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    domain: CriterionErrorDomain
+    source_type: str
+    source_value: str
+    reason: CriterionErrorReason
+    message: str | None = None
+
+
+class CriteriaGroupResult(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    name: str
+    total_patients_in_group: int | None
+    query: str
+    evaluated: bool
+    criteria_errors: list[CriterionError]
+    criterion_impacts: list[CriterionImpact] | None = None
+    demographic_breakdown: DemographicBreakdown | None = None
+
+
+class CohortGroupResult(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    total_patients_in_group: int | None
+    query: str
+    evaluated: bool
+    criteria_errors: list[CriterionError]
+    inclusion_groups: list[CriteriaGroupResult]
+    exclusion_groups: list[CriteriaGroupResult]
+    demographic_breakdown: DemographicBreakdown | None = None
+
+
+class GeographicGroup(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    label: str
+    count: int
+    percentage: float
+
+
+class SiteRadiusResult(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    site_name: str
+    latitude: float
+    longitude: float
+    radius_miles: int
+    count: int
+    percentage: float
+
+
+class DistanceBand(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    label: str
+    min_miles: int
+    max_miles: int | None = None
+    count: int
+    percentage: float
+
+
+class SiteDistanceBandResult(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    site_name: str
+    latitude: float
+    longitude: float
+    bands: list[DistanceBand]
+
+
+class ProviderCohortAnalysis(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    id: str
+    provider: ProviderMeta
+    total_patients: int | None
+    cohort_groups: list[CohortGroupResult]
+    combined_demographic_breakdown: DemographicBreakdown | None = None
+    geographic_groups: list[GeographicGroup] | None = None
+    site_radius_results: list[SiteRadiusResult] | None = None
+    site_distance_band_results: list[SiteDistanceBandResult] | None = None
+
+
+class AnalyzeCohortsPayload(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    id: str
+    analyses: list[ProviderCohortAnalysis]
+    warnings: list[AnalysisWarning] | None = None