phactor 0.2.0__py3-none-any.whl

phactor/__init__.py

@@ -0,0 +1,159 @@
+"""Phactor Python SDK — programmatic access to the Phactor clinical trial feasibility platform."""
+
+from phactor._version import __version__
+from phactor.client import AsyncPhactorClient, PhactorClient
+from phactor.cohorts.builder import CohortBuilder, Proposition
+from phactor.cohorts.models import (
+    AdherenceCriteriaInput,
+    AgeRangeInput,
+    AllergiesInput,
+    AllergyCriticality,
+    AllergyInput,
+    AllergyTypeEnum,
+    AnalyzeCohortsInput,
+    AnalyzeCohortsPayload,
+    ClinicalMeasurementCategory,
+    ClinicalMeasurementInput,
+    CohortGroupInput,
+    CohortGroupOperator,
+    ComparisonOperatorEnum,
+    ConditionClinicalStatus,
+    ConditionInput,
+    ConditionSeverity,
+    ConditionsInput,
+    ConditionStageInput,
+    ConditionTypeEnum,
+    CoordsInput,
+    CriteriaGroupInput,
+    CriteriaGroupOperator,
+    CriteriaGroupResult,
+    CriterionError,
+    CriterionErrorDomain,
+    CriterionErrorReason,
+    DistanceBand,
+    GenderValue,
+    GeographicGroup,
+    GlobalFiltersInput,
+    GroupingInput,
+    ImmunizationInput,
+    ImmunizationsInput,
+    ImmunizationTypeEnum,
+    InclusionGroupOperator,
+    InterpretationCode,
+    LabValueInput,
+    LocationInput,
+    LocationTypeEnum,
+    LocationValueInput,
+    MedicationInput,
+    MedicationsInput,
+    MedicationStatus,
+    MedicationTypeEnum,
+    PdcFilterInput,
+    ProcedureInput,
+    ProcedureOutcome,
+    ProceduresInput,
+    ProcedureTypeEnum,
+    PropositionInput,
+    ProximityMode,
+    RaceValue,
+    ResultGrouping,
+    SiteDistanceBandResult,
+    SiteInput,
+    SiteRadiusResult,
+    StabilityStatusEnum,
+    StableDoseFilterInput,
+    TimingInput,
+    TimingOperator,
+    TimingReference,
+    TimingUnit,
+)
+from phactor.config import PhactorConfig
+from phactor.exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    GraphQLError,
+    PhactorError,
+    TimeoutError,
+    ValidationError,
+)
+
+__all__ = [
+    "__version__",
+    "AsyncPhactorClient",
+    "PhactorClient",
+    "PhactorConfig",
+    "CohortBuilder",
+    "Proposition",
+    # Enums
+    "TimingOperator",
+    "TimingUnit",
+    "TimingReference",
+    "ComparisonOperatorEnum",
+    "GenderValue",
+    "RaceValue",
+    "LocationTypeEnum",
+    "ConditionTypeEnum",
+    "ConditionClinicalStatus",
+    "ConditionSeverity",
+    "MedicationTypeEnum",
+    "MedicationStatus",
+    "ProcedureTypeEnum",
+    "ProcedureOutcome",
+    "AllergyTypeEnum",
+    "AllergyCriticality",
+    "ImmunizationTypeEnum",
+    "InterpretationCode",
+    "ClinicalMeasurementCategory",
+    "StabilityStatusEnum",
+    "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",
+    "SiteInput",
+    "GroupingInput",
+    "GlobalFiltersInput",
+    "AnalyzeCohortsInput",
+    # Response models
+    "AnalyzeCohortsPayload",
+    "CriteriaGroupResult",
+    "CriterionError",
+    "DistanceBand",
+    "GeographicGroup",
+    "SiteDistanceBandResult",
+    "SiteRadiusResult",
+    # Exceptions
+    "AuthenticationError",
+    "ConnectionError",
+    "GraphQLError",
+    "PhactorError",
+    "TimeoutError",
+    "ValidationError",
+]

phactor/_http.py

@@ -0,0 +1,183 @@
+"""HTTP client wrappers with retry, auth injection, and error mapping."""
+
+from __future__ import annotations
+
+import contextlib
+import random
+import time
+from typing import Any
+
+import httpx
+
+from phactor.auth import AsyncTokenManager, TokenManager
+from phactor.exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    NotFoundError,
+    PhactorError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+)
+
+_RETRYABLE_STATUS_CODES = {429, 502, 503, 504}
+_MAX_RETRIES = 3
+_BASE_DELAY = 0.5
+_MAX_JITTER = 0.25
+
+
+def _map_status_error(response: httpx.Response) -> PhactorError:
+    """Map an HTTP error status to the appropriate SDK exception."""
+    status = response.status_code
+    body = response.text
+    if status == 401:
+        return AuthenticationError(f"Authentication failed: {body}", status_code=status)
+    if status == 403:
+        return AuthenticationError(f"Forbidden: {body}", status_code=status)
+    if status == 404:
+        return NotFoundError(f"Not found: {body}", status_code=status)
+    if status == 429:
+        return RateLimitError(f"Rate limited: {body}", status_code=status)
+    if status >= 500:
+        return ServerError(f"Server error ({status}): {body}", status_code=status)
+    return PhactorError(f"HTTP error ({status}): {body}", status_code=status)
+
+
+def _retry_delay(response: httpx.Response | None, attempt: int) -> float:
+    delay: float = _BASE_DELAY * (2**attempt)
+    if response is not None:
+        retry_after = response.headers.get("Retry-After")
+        if retry_after:
+            with contextlib.suppress(ValueError):
+                delay = float(retry_after)
+    return delay + float(random.uniform(0.0, _MAX_JITTER))
+
+
+class SyncHTTPClient:
+    """Synchronous HTTP client with auth injection and retry logic."""
+
+    def __init__(
+        self,
+        token_manager: TokenManager,
+        *,
+        timeout: float = 30.0,
+        verify: str | bool = True,
+    ) -> None:
+        self._token_manager = token_manager
+        self._client = httpx.Client(timeout=timeout, verify=verify)
+
+    def post(self, url: str, *, json: dict[str, Any]) -> dict[str, Any]:
+        """POST JSON with auth headers, retry on transient errors."""
+        attempt = 0
+        refreshed_token = False
+
+        while True:
+            try:
+                headers = self._token_manager.get_auth_headers(self._client)
+                response = self._client.post(url, json=json, headers=headers)
+
+                if response.status_code == 200:
+                    return response.json()  # type: ignore[no-any-return]
+
+                if response.status_code == 401:
+                    if not refreshed_token:
+                        self._token_manager.invalidate()
+                        refreshed_token = True
+                        attempt = 0
+                        continue
+                    raise _map_status_error(response)
+
+                if response.status_code in _RETRYABLE_STATUS_CODES and attempt < _MAX_RETRIES - 1:
+                    time.sleep(_retry_delay(response, attempt))
+                    attempt += 1
+                    continue
+
+                raise _map_status_error(response)
+
+            except httpx.TimeoutException as exc:
+                if attempt < _MAX_RETRIES - 1:
+                    time.sleep(_retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                raise TimeoutError(f"Request timed out: {exc}") from exc
+            except httpx.ConnectError as exc:
+                if attempt < _MAX_RETRIES - 1:
+                    time.sleep(_retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                raise ConnectionError(f"Connection failed: {exc}") from exc
+            except httpx.RequestError as exc:
+                if attempt < _MAX_RETRIES - 1:
+                    time.sleep(_retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                raise ConnectionError(f"Connection failed: {exc}") from exc
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHTTPClient:
+    """Async HTTP client with auth injection and retry logic."""
+
+    def __init__(
+        self,
+        token_manager: AsyncTokenManager,
+        *,
+        timeout: float = 30.0,
+        verify: str | bool = True,
+    ) -> None:
+        self._token_manager = token_manager
+        self._client = httpx.AsyncClient(timeout=timeout, verify=verify)
+
+    async def post(self, url: str, *, json: dict[str, Any]) -> dict[str, Any]:
+        """POST JSON with auth headers, retry on transient errors."""
+        import asyncio
+
+        attempt = 0
+        refreshed_token = False
+
+        while True:
+            try:
+                headers = await self._token_manager.get_auth_headers(self._client)
+                response = await self._client.post(url, json=json, headers=headers)
+
+                if response.status_code == 200:
+                    return response.json()  # type: ignore[no-any-return]
+
+                if response.status_code == 401:
+                    if not refreshed_token:
+                        await self._token_manager.invalidate()
+                        refreshed_token = True
+                        attempt = 0
+                        continue
+                    raise _map_status_error(response)
+
+                if response.status_code in _RETRYABLE_STATUS_CODES and attempt < _MAX_RETRIES - 1:
+                    await asyncio.sleep(_retry_delay(response, attempt))
+                    attempt += 1
+                    continue
+
+                raise _map_status_error(response)
+
+            except httpx.TimeoutException as exc:
+                if attempt < _MAX_RETRIES - 1:
+                    await asyncio.sleep(_retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                raise TimeoutError(f"Request timed out: {exc}") from exc
+            except httpx.ConnectError as exc:
+                if attempt < _MAX_RETRIES - 1:
+                    await asyncio.sleep(_retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                raise ConnectionError(f"Connection failed: {exc}") from exc
+            except httpx.RequestError as exc:
+                if attempt < _MAX_RETRIES - 1:
+                    await asyncio.sleep(_retry_delay(None, attempt))
+                    attempt += 1
+                    continue
+                raise ConnectionError(f"Connection failed: {exc}") from exc
+
+    async def close(self) -> None:
+        await self._client.aclose()

phactor/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

phactor/auth.py

@@ -0,0 +1,167 @@
+"""Token management for FusionAuth client_credentials flow."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from dataclasses import dataclass
+
+import httpx
+import jwt
+
+from phactor.config import PhactorConfig
+from phactor.exceptions import AuthenticationError
+
+# Match gateway's TOKEN_CACHE_TTL_MS = 55_000
+_TOKEN_CACHE_TTL_S = 55
+
+
+def _cache_ttl(expires_in: float) -> float:
+    return max(1.0, min(float(_TOKEN_CACHE_TTL_S), expires_in - 5.0))
+
+
+@dataclass
+class _CachedToken:
+    access_token: str
+    tenant_id: str
+    expires_at: float
+
+
+class TokenManager:
+    """Acquires and caches OAuth2 client_credentials tokens from FusionAuth."""
+
+    def __init__(self, config: PhactorConfig) -> None:
+        self._config = config
+        self._token_url = f"{config.fusionauth_url}/oauth2/token"
+        self._scope = (
+            f"target-entity:{config.entity_id}:internal:read"
+            if config.entity_id
+            else None
+        )
+        self._cached: _CachedToken | None = None
+        self._lock = threading.Lock()
+
+    def _is_valid(self) -> bool:
+        return self._cached is not None and time.monotonic() < self._cached.expires_at
+
+    def _request_token(self, client: httpx.Client) -> _CachedToken:
+        data: dict[str, str] = {
+            "grant_type": "client_credentials",
+            "client_id": self._config.client_id,
+            "client_secret": self._config.client_secret,
+        }
+        if self._scope:
+            data["scope"] = self._scope
+        response = client.post(
+            self._token_url,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        if response.status_code != 200:
+            raise AuthenticationError(
+                f"Token request failed ({response.status_code}): {response.text}",
+                status_code=response.status_code,
+            )
+        data = response.json()
+        access_token = data["access_token"]
+        expires_in = float(data.get("expires_in", _TOKEN_CACHE_TTL_S + 5))
+
+        # Decode JWT without verification to extract tid (tenant ID)
+        decoded = jwt.decode(access_token, options={"verify_signature": False})
+        tenant_id = decoded.get("tid")
+        if not tenant_id:
+            raise AuthenticationError("Service token missing tid (tenant ID) claim")
+
+        ttl = _cache_ttl(expires_in)
+        return _CachedToken(
+            access_token=access_token,
+            tenant_id=tenant_id,
+            expires_at=time.monotonic() + ttl,
+        )
+
+    def get_auth_headers(self, client: httpx.Client) -> dict[str, str]:
+        """Return Authorization and x-tenant-id headers, refreshing if needed."""
+        with self._lock:
+            if not self._is_valid():
+                self._cached = self._request_token(client)
+            token = self._cached
+        assert token is not None
+        return {
+            "Authorization": f"Bearer {token.access_token}",
+            "x-tenant-id": token.tenant_id,
+        }
+
+    def invalidate(self) -> None:
+        """Force token refresh on next call."""
+        with self._lock:
+            self._cached = None
+
+
+class AsyncTokenManager:
+    """Async variant of TokenManager."""
+
+    def __init__(self, config: PhactorConfig) -> None:
+        self._config = config
+        self._token_url = f"{config.fusionauth_url}/oauth2/token"
+        self._scope = (
+            f"target-entity:{config.entity_id}:internal:read"
+            if config.entity_id
+            else None
+        )
+        self._cached: _CachedToken | None = None
+        self._lock = asyncio.Lock()
+
+    def _is_valid(self) -> bool:
+        return self._cached is not None and time.monotonic() < self._cached.expires_at
+
+    async def _request_token(self, client: httpx.AsyncClient) -> _CachedToken:
+        data: dict[str, str] = {
+            "grant_type": "client_credentials",
+            "client_id": self._config.client_id,
+            "client_secret": self._config.client_secret,
+        }
+        if self._scope:
+            data["scope"] = self._scope
+        response = await client.post(
+            self._token_url,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        if response.status_code != 200:
+            raise AuthenticationError(
+                f"Token request failed ({response.status_code}): {response.text}",
+                status_code=response.status_code,
+            )
+        data = response.json()
+        access_token = data["access_token"]
+        expires_in = float(data.get("expires_in", _TOKEN_CACHE_TTL_S + 5))
+
+        decoded = jwt.decode(access_token, options={"verify_signature": False})
+        tenant_id = decoded.get("tid")
+        if not tenant_id:
+            raise AuthenticationError("Service token missing tid (tenant ID) claim")
+
+        ttl = _cache_ttl(expires_in)
+        return _CachedToken(
+            access_token=access_token,
+            tenant_id=tenant_id,
+            expires_at=time.monotonic() + ttl,
+        )
+
+    async def get_auth_headers(self, client: httpx.AsyncClient) -> dict[str, str]:
+        """Return Authorization and x-tenant-id headers, refreshing if needed."""
+        async with self._lock:
+            if not self._is_valid():
+                self._cached = await self._request_token(client)
+            token = self._cached
+        assert token is not None
+        return {
+            "Authorization": f"Bearer {token.access_token}",
+            "x-tenant-id": token.tenant_id,
+        }
+
+    async def invalidate(self) -> None:
+        """Force token refresh on next call."""
+        async with self._lock:
+            self._cached = None

phactor/client.py

@@ -0,0 +1,172 @@
+"""Top-level Phactor SDK clients (sync and async)."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+from phactor._http import AsyncHTTPClient, SyncHTTPClient
+from phactor.auth import AsyncTokenManager, TokenManager
+from phactor.cohorts.client import AsyncCohortsClient, CohortsClient
+from phactor.cohorts.models import (
+    AnalyzeCohortsPayload,
+    CohortGroupInput,
+    CohortGroupOperator,
+    GlobalFiltersInput,
+    StudyContextInput,
+)
+from phactor.config import PhactorConfig
+from phactor.exceptions import PhactorError
+
+
+class PhactorClient:
+    """Synchronous Phactor SDK client.
+
+    Usage:
+        client = PhactorClient(client_id="...", client_secret="...", ...)
+        result = client.cohorts.analyze(providers=[...], cohort_groups=[...])
+        client.close()
+
+    Or as a context manager:
+        with PhactorClient(...) as client:
+            result = client.cohorts.analyze(...)
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        entity_id: str | None = None,
+        fusionauth_url: str | None = None,
+        gateway_url: str | None = None,
+        verify: str | bool | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        self._config = PhactorConfig.from_kwargs(
+            client_id=client_id,
+            client_secret=client_secret,
+            entity_id=entity_id,
+            fusionauth_url=fusionauth_url,
+            gateway_url=gateway_url,
+            verify=verify,
+            timeout=timeout,
+        )
+        token_manager = TokenManager(self._config)
+        self._http = SyncHTTPClient(
+            token_manager, timeout=self._config.timeout, verify=self._config.verify
+        )
+        self.cohorts = CohortsClient(self._http, self._config.gateway_url)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> PhactorClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncPhactorClient:
+    """Async Phactor SDK client.
+
+    Usage:
+        async with AsyncPhactorClient(...) as client:
+            result = await client.cohorts.analyze(...)
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        entity_id: str | None = None,
+        fusionauth_url: str | None = None,
+        gateway_url: str | None = None,
+        verify: str | bool | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        self._config = PhactorConfig.from_kwargs(
+            client_id=client_id,
+            client_secret=client_secret,
+            entity_id=entity_id,
+            fusionauth_url=fusionauth_url,
+            gateway_url=gateway_url,
+            verify=verify,
+            timeout=timeout,
+        )
+        self._closed = False
+        token_manager = AsyncTokenManager(self._config)
+        self._http = AsyncHTTPClient(
+            token_manager, timeout=self._config.timeout, verify=self._config.verify
+        )
+        self._cohorts = AsyncCohortsClient(self._http, self._config.gateway_url)
+        self.cohorts = _AsyncCohortsProxy(self)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        if self._closed:
+            return
+        self._closed = True
+        await self._http.close()
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise PhactorError("AsyncPhactorClient is closed")
+
+    async def __aenter__(self) -> AsyncPhactorClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+
+class _AsyncCohortsProxy:
+    """Guarded async cohorts facade that fails fast after client close."""
+
+    def __init__(self, owner: AsyncPhactorClient) -> None:
+        self._owner = owner
+
+    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:
+        self._owner._ensure_open()
+        return await self._owner._cohorts.analyze(
+            providers,
+            cohort_groups,
+            cohort_group_operator=cohort_group_operator,
+            study_context=study_context,
+            include_impact_analysis=include_impact_analysis,
+            include_demographic_breakdown=include_demographic_breakdown,
+            age_buckets=age_buckets,
+            include_combined_demographic_breakdown=include_combined_demographic_breakdown,
+            grouping=grouping,
+            global_filters=global_filters,
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        self._owner._ensure_open()
+        return getattr(self._owner._cohorts, name)