phactor 0.2.0__py3-none-any.whl

phactor/cohorts/query.py

@@ -0,0 +1,98 @@
+"""GraphQL query constant for analyzeCohorts."""
+
+ANALYZE_COHORTS_QUERY = """
+query AnalyzeCohorts($input: AnalyzeCohortsInput!) {
+  analyzeCohorts(input: $input) {
+    id
+    analyses {
+      id
+      provider {
+        id
+        name
+      }
+      totalPatients
+      cohortGroups {
+        totalPatientsInGroup
+        query
+        evaluated
+        criteriaErrors { domain sourceType sourceValue reason message }
+        inclusionGroups {
+          name
+          totalPatientsInGroup
+          query
+          evaluated
+          criteriaErrors { domain sourceType sourceValue reason message }
+          criterionImpacts {
+            propositionIndex propositionLabel matchingCount excludedCount impactPercentage
+          }
+          demographicBreakdown {
+            ageDistribution { rangeFrom rangeTo count percentage }
+            genderDistribution { label count percentage }
+            raceDistribution { label count percentage }
+            geographicDistribution { label count percentage }
+          }
+        }
+        exclusionGroups {
+          name
+          totalPatientsInGroup
+          query
+          evaluated
+          criteriaErrors { domain sourceType sourceValue reason message }
+          criterionImpacts {
+            propositionIndex propositionLabel matchingCount excludedCount impactPercentage
+          }
+          demographicBreakdown {
+            ageDistribution { rangeFrom rangeTo count percentage }
+            genderDistribution { label count percentage }
+            raceDistribution { label count percentage }
+            geographicDistribution { label count percentage }
+          }
+        }
+        demographicBreakdown {
+          ageDistribution {
+            rangeFrom
+            rangeTo
+            count
+            percentage
+          }
+          genderDistribution {
+            label
+            count
+            percentage
+          }
+          raceDistribution {
+            label
+            count
+            percentage
+          }
+          geographicDistribution {
+            label
+            count
+            percentage
+          }
+        }
+      }
+      combinedDemographicBreakdown {
+        ageDistribution { rangeFrom rangeTo count percentage }
+        genderDistribution { label count percentage }
+        raceDistribution { label count percentage }
+        geographicDistribution { label count percentage }
+      }
+      geographicGroups { label count percentage }
+      siteRadiusResults { siteName latitude longitude radiusMiles count percentage }
+      siteDistanceBandResults {
+        siteName latitude longitude
+        bands { label minMiles maxMiles count percentage }
+      }
+    }
+    warnings {
+      provider {
+        id
+        name
+      }
+      code
+      message
+    }
+  }
+}
+"""

phactor/config.py

@@ -0,0 +1,95 @@
+"""Configuration for the Phactor SDK."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from dataclasses import dataclass
+
+# Client-side request ceiling. Deliberately above the server's own budget
+# (connector statement_timeout 420s < query-api fan-out 540s < ALB idle 600s) so
+# the server always wins the race: a slow cohort comes back as a GraphQL error
+# naming the provider, rather than a bare client TimeoutError that is then
+# retried three times and triples the load.
+DEFAULT_TIMEOUT_SECONDS = 600.0
+
+
+@dataclass(frozen=True)
+class PhactorConfig:
+    """Immutable SDK configuration with environment variable fallback.
+
+    Environment variables:
+        PHACTOR_CLIENT_ID
+        PHACTOR_CLIENT_SECRET
+        PHACTOR_ENTITY_ID
+        PHACTOR_FUSIONAUTH_URL
+        PHACTOR_GATEWAY_URL
+        PHACTOR_CA_BUNDLE
+        PHACTOR_TIMEOUT
+    """
+
+    client_id: str
+    client_secret: str
+    entity_id: str | None
+    fusionauth_url: str
+    gateway_url: str
+    verify: str | bool
+    timeout: float = DEFAULT_TIMEOUT_SECONDS
+
+    @classmethod
+    def from_kwargs(
+        cls,
+        *,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        entity_id: str | None = None,  # Optional: omit for plain client_credentials auth
+        fusionauth_url: str | None = None,
+        gateway_url: str | None = None,
+        verify: str | bool | None = None,
+        timeout: float | None = None,
+    ) -> PhactorConfig:
+        """Create config from explicit values with env var fallback."""
+
+        def _resolve(value: str | None, env_key: str, name: str) -> str:
+            result = value or os.environ.get(env_key)
+            if not result:
+                raise ValueError(
+                    f"{name} must be provided or set via {env_key} environment variable"
+                )
+            return result
+
+        def _resolve_timeout(value: float | None) -> float:
+            if value is not None:
+                return value
+            raw = os.environ.get("PHACTOR_TIMEOUT")
+            if not raw:
+                return DEFAULT_TIMEOUT_SECONDS
+            try:
+                return float(raw)
+            except ValueError as exc:
+                raise ValueError(
+                    f"PHACTOR_TIMEOUT must be a number of seconds, got {raw!r}"
+                ) from exc
+
+        def _resolve_verify(value: str | bool | None) -> str | bool:
+            if value is False:
+                warnings.warn(
+                    "TLS certificate verification is disabled. "
+                    "This should only be used for local development.",
+                    stacklevel=3,
+                )
+            if value is not None:
+                return value
+            return os.environ.get("PHACTOR_CA_BUNDLE") or True
+
+        return cls(
+            client_id=_resolve(client_id, "PHACTOR_CLIENT_ID", "client_id"),
+            client_secret=_resolve(client_secret, "PHACTOR_CLIENT_SECRET", "client_secret"),
+            entity_id=entity_id or os.environ.get("PHACTOR_ENTITY_ID"),
+            fusionauth_url=_resolve(
+                fusionauth_url, "PHACTOR_FUSIONAUTH_URL", "fusionauth_url"
+            ).rstrip("/"),
+            gateway_url=_resolve(gateway_url, "PHACTOR_GATEWAY_URL", "gateway_url"),
+            verify=_resolve_verify(verify),
+            timeout=_resolve_timeout(timeout),
+        )

phactor/exceptions.py

@@ -0,0 +1,47 @@
+"""Exception hierarchy for the Phactor SDK."""
+
+from __future__ import annotations
+
+
+class PhactorError(Exception):
+    """Base exception for all Phactor SDK errors."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(PhactorError):
+    """Raised when authentication fails (invalid credentials, expired token, 401)."""
+
+
+class GraphQLError(PhactorError):
+    """Raised when the GraphQL API returns errors in the response body."""
+
+    def __init__(self, message: str, *, errors: list[dict[str, object]] | None = None) -> None:
+        super().__init__(message)
+        self.errors = errors or []
+
+
+class ValidationError(PhactorError):
+    """Raised when input validation fails (e.g., builder misuse)."""
+
+
+class TimeoutError(PhactorError):
+    """Raised when an HTTP request times out."""
+
+
+class ConnectionError(PhactorError):
+    """Raised when the SDK cannot reach the server."""
+
+
+class NotFoundError(PhactorError):
+    """Raised on HTTP 404 responses."""
+
+
+class RateLimitError(PhactorError):
+    """Raised on HTTP 429 responses after retry exhaustion."""
+
+
+class ServerError(PhactorError):
+    """Raised on HTTP 5xx responses after retry exhaustion."""