phactor 0.2.0__py3-none-any.whl

phactor/cohorts/__init__.py

@@ -0,0 +1,143 @@
+"""Cohort analysis sub-package."""
+
+from phactor.cohorts.builder import CohortBuilder, GroupBuilder, Proposition
+from phactor.cohorts.client import AsyncCohortsClient, CohortsClient
+from phactor.cohorts.models import (
+    AdherenceCriteriaInput,
+    AgeRangeInput,
+    AllergiesInput,
+    AllergyCriticality,
+    AllergyInput,
+    AllergyTypeEnum,
+    AnalyzeCohortsInput,
+    AnalyzeCohortsPayload,
+    ClinicalMeasurementCategory,
+    ClinicalMeasurementInput,
+    CohortGroupInput,
+    CohortGroupOperator,
+    CohortGroupResult,
+    ComparisonOperatorEnum,
+    ConditionClinicalStatus,
+    ConditionInput,
+    ConditionSeverity,
+    ConditionsInput,
+    ConditionStageInput,
+    ConditionTypeEnum,
+    CoordsInput,
+    CriteriaGroupInput,
+    CriteriaGroupOperator,
+    CriteriaGroupResult,
+    CriterionError,
+    CriterionErrorDomain,
+    CriterionErrorReason,
+    GenderValue,
+    GlobalFiltersInput,
+    GroupingInput,
+    ImmunizationInput,
+    ImmunizationsInput,
+    ImmunizationTypeEnum,
+    InclusionGroupOperator,
+    InterpretationCode,
+    LabValueInput,
+    LocationInput,
+    LocationTypeEnum,
+    LocationValueInput,
+    MedicationInput,
+    MedicationsInput,
+    MedicationStatus,
+    MedicationTypeEnum,
+    PdcFilterInput,
+    ProcedureInput,
+    ProcedureOutcome,
+    ProceduresInput,
+    ProcedureTypeEnum,
+    PropositionInput,
+    ProviderCohortAnalysis,
+    ProviderMeta,
+    ProximityMode,
+    RaceValue,
+    ResultGrouping,
+    SiteInput,
+    StabilityStatusEnum,
+    StableDoseFilterInput,
+    StudyContextInput,
+    TimingInput,
+    TimingOperator,
+    TimingReference,
+    TimingUnit,
+)
+
+__all__ = [
+    # Builder + clients
+    "CohortBuilder",
+    "GroupBuilder",
+    "Proposition",
+    "CohortsClient",
+    "AsyncCohortsClient",
+    # Enums
+    "TimingOperator",
+    "TimingUnit",
+    "TimingReference",
+    "ComparisonOperatorEnum",
+    "GenderValue",
+    "RaceValue",
+    "LocationTypeEnum",
+    "ConditionTypeEnum",
+    "ConditionClinicalStatus",
+    "ConditionSeverity",
+    "MedicationTypeEnum",
+    "MedicationStatus",
+    "ProcedureTypeEnum",
+    "ProcedureOutcome",
+    "AllergyTypeEnum",
+    "AllergyCriticality",
+    "ImmunizationTypeEnum",
+    "InterpretationCode",
+    "ClinicalMeasurementCategory",
+    "StabilityStatusEnum",
+    "CohortGroupOperator",
+    "CriteriaGroupOperator",
+    "InclusionGroupOperator",
+    "CohortGroupOperator",
+    "CriterionErrorDomain",
+    "CriterionErrorReason",
+    "ResultGrouping",
+    "ProximityMode",
+    # Input models
+    "TimingInput",
+    "AgeRangeInput",
+    "CoordsInput",
+    "LocationValueInput",
+    "LocationInput",
+    "ConditionStageInput",
+    "ConditionInput",
+    "ConditionsInput",
+    "PdcFilterInput",
+    "StableDoseFilterInput",
+    "AdherenceCriteriaInput",
+    "MedicationInput",
+    "MedicationsInput",
+    "ProcedureInput",
+    "ProceduresInput",
+    "AllergyInput",
+    "AllergiesInput",
+    "ImmunizationInput",
+    "ImmunizationsInput",
+    "LabValueInput",
+    "ClinicalMeasurementInput",
+    "PropositionInput",
+    "CriteriaGroupInput",
+    "CohortGroupInput",
+    "StudyContextInput",
+    "SiteInput",
+    "GroupingInput",
+    "GlobalFiltersInput",
+    "AnalyzeCohortsInput",
+    # Response models
+    "AnalyzeCohortsPayload",
+    "CohortGroupResult",
+    "CriteriaGroupResult",
+    "CriterionError",
+    "ProviderCohortAnalysis",
+    "ProviderMeta",
+]

phactor/cohorts/builder.py

@@ -0,0 +1,156 @@
+"""Fluent builder API for constructing cohort analysis inputs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from phactor.cohorts.models import (
+    CohortGroupInput,
+    CriteriaGroupInput,
+    CriteriaGroupOperator,
+    InclusionGroupOperator,
+    PropositionInput,
+)
+from phactor.exceptions import ValidationError
+
+
+class Proposition:
+    """Convenience wrapper for building PropositionInput from keyword arguments.
+
+    Accepts the same fields as PropositionInput but also plain dicts
+    for nested types (age, conditions, medications, etc.).
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._data = kwargs
+
+    def to_model(self) -> PropositionInput:
+        return PropositionInput.model_validate(self._data)
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.to_model().model_dump(by_alias=True, exclude_none=True)
+
+
+class GroupBuilder:
+    """Builds a single inclusion or exclusion criteria group."""
+
+    def __init__(
+        self,
+        parent: CohortBuilder,
+        name: str | None,
+        operator: CriteriaGroupOperator,
+        *,
+        is_exclusion: bool = False,
+        some_threshold: int | None = None,
+    ) -> None:
+        self._parent = parent
+        self._name = name
+        self._operator = operator
+        self._is_exclusion = is_exclusion
+        self._some_threshold = some_threshold
+        self._propositions: list[PropositionInput] = []
+
+    def add(self, proposition: Proposition | PropositionInput | dict[str, Any]) -> GroupBuilder:
+        """Add a proposition to this criteria group."""
+        if isinstance(proposition, Proposition):
+            self._propositions.append(proposition.to_model())
+        elif isinstance(proposition, dict):
+            self._propositions.append(PropositionInput.model_validate(proposition))
+        else:
+            self._propositions.append(proposition)
+        return self
+
+    def done(self) -> CohortBuilder:
+        """Finalize this group and return to the parent builder."""
+        group = CriteriaGroupInput(
+            name=self._name,
+            operator=self._operator,
+            some_threshold=self._some_threshold,
+            propositions=self._propositions,
+        )
+        if self._is_exclusion:
+            self._parent._exclusion_groups.append(group)
+        else:
+            self._parent._inclusion_groups.append(group)
+        return self._parent
+
+
+class CohortBuilder:
+    """Fluent API for building a CohortGroupInput.
+
+    Usage:
+        cohort = (
+            CohortBuilder(inclusion_operator="AND")
+            .include("Demographics", operator="AND")
+                .add(Proposition(age={"from": 18, "to": 65}))
+                .done()
+            .exclude("Exclusions", operator="OR")
+                .add(Proposition(conditions={"values": [...]}))
+                .done()
+            .build()
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        inclusion_operator: str | InclusionGroupOperator = InclusionGroupOperator.AND,
+    ) -> None:
+        self._inclusion_operator = (
+            InclusionGroupOperator(inclusion_operator)
+            if isinstance(inclusion_operator, str)
+            else inclusion_operator
+        )
+        self._inclusion_groups: list[CriteriaGroupInput] = []
+        self._exclusion_groups: list[CriteriaGroupInput] = []
+
+    def include(
+        self,
+        name: str | None = None,
+        *,
+        operator: str | CriteriaGroupOperator = CriteriaGroupOperator.AND,
+        some_threshold: int | None = None,
+    ) -> GroupBuilder:
+        """Start building an inclusion criteria group."""
+        op = CriteriaGroupOperator(operator) if isinstance(operator, str) else operator
+        return GroupBuilder(self, name, op, is_exclusion=False, some_threshold=some_threshold)
+
+    def exclude(
+        self,
+        name: str | None = None,
+        *,
+        operator: str | CriteriaGroupOperator = CriteriaGroupOperator.AND,
+        some_threshold: int | None = None,
+    ) -> GroupBuilder:
+        """Start building an exclusion criteria group."""
+        op = CriteriaGroupOperator(operator) if isinstance(operator, str) else operator
+        return GroupBuilder(self, name, op, is_exclusion=True, some_threshold=some_threshold)
+
+    def build(self) -> dict[str, Any]:
+        """Validate and return the cohort group as a camelCase dict."""
+        if not self._inclusion_groups and not self._exclusion_groups:
+            raise ValidationError("Cohort must have at least one inclusion or exclusion group")
+
+        for group in [*self._inclusion_groups, *self._exclusion_groups]:
+            if not group.propositions:
+                raise ValidationError(
+                    f"Criteria group '{group.name or '(unnamed)'}' has no propositions"
+                )
+
+        cohort = CohortGroupInput(
+            inclusion_group_operator=self._inclusion_operator,
+            inclusion_groups=self._inclusion_groups or None,
+            exclusion_groups=self._exclusion_groups or None,
+        )
+        return cohort.model_dump(by_alias=True, exclude_none=True)
+
+    def build_model(self) -> CohortGroupInput:
+        """Validate and return as a CohortGroupInput model."""
+        if not self._inclusion_groups and not self._exclusion_groups:
+            raise ValidationError("Cohort must have at least one inclusion or exclusion group")
+
+        return CohortGroupInput(
+            inclusion_group_operator=self._inclusion_operator,
+            inclusion_groups=self._inclusion_groups or None,
+            exclusion_groups=self._exclusion_groups or None,
+        )

phactor/cohorts/client.py

@@ -0,0 +1,283 @@
+"""Cohort analysis client — sends GraphQL queries to the Phactor gateway."""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from enum import Enum
+from typing import Any
+
+from phactor._http import AsyncHTTPClient, SyncHTTPClient
+from phactor.cohorts.models import (
+    AnalyzeCohortsPayload,
+    CohortGroupInput,
+    CohortGroupOperator,
+    GlobalFiltersInput,
+    StudyContextInput,
+)
+from phactor.cohorts.query import ANALYZE_COHORTS_QUERY
+from phactor.exceptions import GraphQLError
+
+# Opt-in instrumentation: when PHACTOR_TIMING is set to a truthy value, every
+# analyzeCohorts call emits one line to stderr summarizing the wire round-trip
+# time and the request shape. The QA harness in .local/qa-verify-dev.sh sets
+# this so each captured `jan_*.txt` file contains timing alongside cohort
+# sizes — diffing two runs surfaces perf regressions / wins without any
+# script-level instrumentation. Off by default; SDK consumers see no change.
+_TIMING_ENV_VAR = "PHACTOR_TIMING"
+
+
+def _timing_enabled() -> bool:
+    """True when PHACTOR_TIMING is set to anything truthy."""
+    return os.environ.get(_TIMING_ENV_VAR, "").lower() in ("1", "true", "yes", "on")
+
+
+def _emit_timing(
+    elapsed_ms: float,
+    variables: dict[str, Any],
+    error: BaseException | None = None,
+) -> None:
+    """Write a single line to stderr describing the call."""
+    payload = variables.get("input", {})
+    providers = len(payload.get("providers") or [])
+    cohort_groups = len(payload.get("cohortGroups") or [])
+    flags: list[str] = []
+    if payload.get("includeImpactAnalysis"):
+        flags.append("impact")
+    if payload.get("includeDemographicBreakdown"):
+        flags.append("demo")
+    if payload.get("includeCombinedDemographicBreakdown"):
+        flags.append("combined-demo")
+    if payload.get("grouping"):
+        flags.append("grouping")
+    if payload.get("globalFilters"):
+        flags.append("global-filters")
+    extras = f" flags={','.join(flags)}" if flags else ""
+    suffix = f" error={type(error).__name__}" if error is not None else ""
+    print(
+        f"[phactor-sdk timing] analyzeCohorts elapsed_ms={elapsed_ms:.0f}"
+        f" providers={providers} cohort_groups={cohort_groups}{extras}{suffix}",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+def _build_variables(
+    providers: list[str],
+    cohort_groups: list[CohortGroupInput | dict[str, Any]],
+    cohort_group_operator: CohortGroupOperator | str | None = None,
+    study_context: StudyContextInput | dict[str, Any] | None = None,
+    include_impact_analysis: bool | None = None,
+    include_demographic_breakdown: bool | None = None,
+    age_buckets: list[dict[str, int]] | None = None,
+    include_combined_demographic_breakdown: bool | None = None,
+    grouping: dict[str, Any] | None = None,
+    global_filters: GlobalFiltersInput | dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build the GraphQL variables dict, accepting both models and dicts."""
+    serialized_groups = []
+    for group in cohort_groups:
+        if isinstance(group, CohortGroupInput):
+            serialized_groups.append(group.model_dump(by_alias=True, exclude_none=True))
+        else:
+            serialized_groups.append(group)
+
+    variables: dict[str, Any] = {
+        "input": {
+            "providers": providers,
+            "cohortGroups": serialized_groups,
+        }
+    }
+
+    if cohort_group_operator is not None:
+        variables["input"]["cohortGroupOperator"] = (
+            cohort_group_operator.value
+            if isinstance(cohort_group_operator, Enum)
+            else cohort_group_operator
+        )
+
+    if study_context is not None:
+        if isinstance(study_context, StudyContextInput):
+            variables["input"]["studyContext"] = study_context.model_dump(
+                by_alias=True, exclude_none=True
+            )
+        else:
+            variables["input"]["studyContext"] = study_context
+
+    if include_impact_analysis is not None:
+        variables["input"]["includeImpactAnalysis"] = include_impact_analysis
+
+    if include_demographic_breakdown is not None:
+        variables["input"]["includeDemographicBreakdown"] = include_demographic_breakdown
+
+    if age_buckets is not None:
+        variables["input"]["ageBuckets"] = age_buckets
+
+    if include_combined_demographic_breakdown is not None:
+        variables["input"]["includeCombinedDemographicBreakdown"] = (
+            include_combined_demographic_breakdown
+        )
+
+    if grouping is not None:
+        variables["input"]["grouping"] = grouping
+
+    if global_filters is not None:
+        if isinstance(global_filters, GlobalFiltersInput):
+            variables["input"]["globalFilters"] = global_filters.model_dump(
+                by_alias=True, exclude_none=True
+            )
+        else:
+            variables["input"]["globalFilters"] = global_filters
+
+    return variables
+
+
+def _parse_response(data: dict[str, Any]) -> AnalyzeCohortsPayload:
+    """Parse GraphQL response, raising on errors."""
+    if data.get("errors"):
+        errors = data["errors"]
+        messages = [e.get("message", str(e)) for e in errors]
+        raise GraphQLError(
+            f"GraphQL errors: {'; '.join(messages)}",
+            errors=errors,
+        )
+
+    # A non-nullable field violation nullifies the whole `data` tree and reports the
+    # cause under `extensions.valueCompletion` (Apollo Router / graphql-js value
+    # completion), NOT under top-level `errors`. Surface those messages instead of
+    # blindly dereferencing a null `data` (which raised an opaque AttributeError).
+    value_completion = (data.get("extensions") or {}).get("valueCompletion")
+    if value_completion:
+        messages = [e.get("message", str(e)) for e in value_completion]
+        raise GraphQLError(
+            f"GraphQL value-completion errors: {'; '.join(messages)}",
+            errors=value_completion,
+        )
+
+    # `data` may be present-but-null (see above) — `or {}` handles that, unlike a
+    # default that only applies when the key is absent.
+    payload = (data.get("data") or {}).get("analyzeCohorts")
+    if payload is None:
+        raise GraphQLError("Unexpected response: missing analyzeCohorts data")
+
+    return AnalyzeCohortsPayload.model_validate(payload)
+
+
+class CohortsClient:
+    """Synchronous client for cohort analysis queries."""
+
+    def __init__(self, http_client: SyncHTTPClient, gateway_url: str) -> None:
+        self._http = http_client
+        self._gateway_url = gateway_url
+
+    def analyze(
+        self,
+        providers: list[str],
+        cohort_groups: list[CohortGroupInput | dict[str, Any]],
+        *,
+        cohort_group_operator: CohortGroupOperator | str | None = None,
+        study_context: StudyContextInput | dict[str, Any] | None = None,
+        include_impact_analysis: bool | None = None,
+        include_demographic_breakdown: bool | None = None,
+        age_buckets: list[dict[str, int]] | None = None,
+        include_combined_demographic_breakdown: bool | None = None,
+        grouping: dict[str, Any] | None = None,
+        global_filters: GlobalFiltersInput | dict[str, Any] | None = None,
+    ) -> AnalyzeCohortsPayload:
+        """Run a cohort feasibility analysis.
+
+        Args:
+            providers: List of provider UUIDs to query.
+            cohort_groups: Cohort group definitions (Pydantic models or dicts).
+            cohort_group_operator: Optional top-level operator (AND/OR) combining
+                multiple cohort_groups. Defaults to the server's behavior when
+                omitted.
+            study_context: Optional study context metadata.
+            include_impact_analysis: Include per-criterion impact analysis.
+            include_demographic_breakdown: Include demographic breakdowns.
+            age_buckets: Custom age range buckets for demographic breakdown.
+            include_combined_demographic_breakdown:
+                Include combined-population demographic breakdown.
+            grouping: Geographic grouping configuration dict.
+            global_filters: Optional global filters applied to all cohort groups
+                (e.g. restrict the study to specific states or geographies).
+        Returns:
+            AnalyzeCohortsPayload with analysis results.
+        """
+        variables = _build_variables(
+            providers,
+            cohort_groups,
+            cohort_group_operator,
+            study_context,
+            include_impact_analysis,
+            include_demographic_breakdown,
+            age_buckets,
+            include_combined_demographic_breakdown,
+            grouping,
+            global_filters,
+        )
+        body = {"query": ANALYZE_COHORTS_QUERY, "variables": variables}
+        if _timing_enabled():
+            t0 = time.perf_counter()
+            error: BaseException | None = None
+            try:
+                response = self._http.post(self._gateway_url, json=body)
+            except BaseException as exc:
+                error = exc
+                raise
+            finally:
+                _emit_timing((time.perf_counter() - t0) * 1000.0, variables, error)
+            return _parse_response(response)
+        response = self._http.post(self._gateway_url, json=body)
+        return _parse_response(response)
+
+
+class AsyncCohortsClient:
+    """Async client for cohort analysis queries."""
+
+    def __init__(self, http_client: AsyncHTTPClient, gateway_url: str) -> None:
+        self._http = http_client
+        self._gateway_url = gateway_url
+
+    async def analyze(
+        self,
+        providers: list[str],
+        cohort_groups: list[CohortGroupInput | dict[str, Any]],
+        *,
+        cohort_group_operator: CohortGroupOperator | str | None = None,
+        study_context: StudyContextInput | dict[str, Any] | None = None,
+        include_impact_analysis: bool | None = None,
+        include_demographic_breakdown: bool | None = None,
+        age_buckets: list[dict[str, int]] | None = None,
+        include_combined_demographic_breakdown: bool | None = None,
+        grouping: dict[str, Any] | None = None,
+        global_filters: GlobalFiltersInput | dict[str, Any] | None = None,
+    ) -> AnalyzeCohortsPayload:
+        """Run a cohort feasibility analysis (async)."""
+        variables = _build_variables(
+            providers,
+            cohort_groups,
+            cohort_group_operator,
+            study_context,
+            include_impact_analysis,
+            include_demographic_breakdown,
+            age_buckets,
+            include_combined_demographic_breakdown,
+            grouping,
+            global_filters,
+        )
+        body = {"query": ANALYZE_COHORTS_QUERY, "variables": variables}
+        if _timing_enabled():
+            t0 = time.perf_counter()
+            error: BaseException | None = None
+            try:
+                response = await self._http.post(self._gateway_url, json=body)
+            except BaseException as exc:
+                error = exc
+                raise
+            finally:
+                _emit_timing((time.perf_counter() - t0) * 1000.0, variables, error)
+            return _parse_response(response)
+        response = await self._http.post(self._gateway_url, json=body)
+        return _parse_response(response)