phactor 0.3.1__tar.gz → 0.4.0__tar.gz

{phactor-0.3.1 → phactor-0.4.0}/CHANGELOG.md

@@ -6,6 +6,50 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 While the SDK is pre-1.0 (`0.x`), breaking changes may accompany a minor version bump.
 
+## [0.4.0] - 2026-10-06
+
+### Added
+
+- **Nearby provider sites.** A `PROXIMITY` grouping can set
+  `"includeNearbyProviderSites": True` (`GroupingInput.include_nearby_provider_sites`)
+  to also get your subscribed providers' sites inside each radius or distance
+  band. The result is `AnalyzeCohortsPayload.nearby_provider_sites`, `None`
+  when not requested.
+  - New models `NearbyProviderSites` (`status`, `truncated`, `sites`),
+    `NearbyProviderSite` (address, coordinates, `providers`, `matches`),
+    `NearbyProviderRef` (`id`, `name`, `provider_type`, `color`) and
+    `NearbyProviderSiteMatch` (`site_name`, coordinates, `distance_miles`).
+  - New enums `NearbyProviderSitesStatus` (`AVAILABLE`, `UNAVAILABLE`) and
+    `DataProviderType`. Like the 0.3.2 response enums, an unknown value from
+    the API is kept as a plain string.
+  - At most 500 sites are returned, nearest first; `truncated` is `True` when
+    more matched.
+  - With the option on, the server rejects the request (`GraphQLError`) when it
+    has more than 50 distinct providers, more than 25 grouping sites, or a radius
+    or distance band outside 1-250 miles. Without it these limits do not apply.
+
+## [0.3.2] - 2026-09-24
+
+### Fixed
+
+- `client.cohorts.analyze` no longer fails when a provider reports a criterion
+  error reason other than `NO_TRANSLATION` / `NO_PATH`. 0.3.1 raised a pydantic
+  `ValidationError` for `UNSUPPORTED_SEMANTICS` (returned today, for example,
+  for exact product codes a provider cannot match), so one unevaluated criterion
+  made the whole result unreadable.
+
+### Added
+
+- `CriterionErrorReason.UNSUPPORTED_SEMANTICS`, `INSUFFICIENT_DATA`,
+  `MATERIALIZATION_NOT_READY` and `CriterionErrorDomain.AGE`, `MEASUREMENT`,
+  `ENCOUNTER`, matching the API.
+
+### Changed
+
+- Response values this SDK version does not know yet (`CriterionError.reason`,
+  `CriterionError.domain`, `Site.access`) are kept as plain strings instead of
+  failing validation, so a value the API adds later cannot break parsing.
+
 ## [0.3.1] - 2026-09-24
 
 ### Fixed

{phactor-0.3.1 → phactor-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: phactor
-Version: 0.3.1
+Version: 0.4.0
 Summary: Python SDK for the Phactor clinical trial feasibility platform
 Project-URL: Homepage, https://phactor.ai
 Project-URL: Documentation, https://docs.phactor.ai
@@ -282,3 +282,57 @@ There are three independent operator levels:
 Exclusion groups are always unioned and subtracted from the pathway's combined
 inclusion result. For example, an `OR` pathway with inclusion groups `A` and `B`
 and exclusion group `E` evaluates as `(A OR B) EXCEPT E`.
+
+## Geographic Grouping
+
+Group cohort results by geography using PROXIMITY and RADIUS or DISTANCE_BANDS mode:
+
+```python
+result = client.cohorts.analyze(
+    providers=[...],
+    cohort_groups=[...],
+    grouping={
+        "type": "PROXIMITY",
+        "proximityMode": "RADIUS",
+        "sites": [
+            {"name": "Johns Hopkins", "latitude": 39.2963, "longitude": -76.5927, "radiusMiles": 25}
+        ],
+    },
+)
+for analysis in result.analyses:
+    for group in analysis.site_radius_results or []:
+        print(group.site_name, group.count, group.percentage)
+```
+
+### Provider sites near each grouping site
+
+```python
+from phactor import NearbyProviderSitesStatus
+
+result = client.cohorts.analyze(
+    providers=[...],
+    cohort_groups=[...],
+    grouping={
+        "type": "PROXIMITY",
+        "proximityMode": "RADIUS",
+        "sites": [
+            {"name": "Johns Hopkins", "latitude": 39.2963, "longitude": -76.5927, "radiusMiles": 25}
+        ],
+        "includeNearbyProviderSites": True,
+    },
+)
+nearby = result.nearby_provider_sites
+if nearby and nearby.status == NearbyProviderSitesStatus.AVAILABLE:
+    for site in nearby.sites:
+        print(site.name, [p.name for p in site.providers], [m.distance_miles for m in site.matches])
+```
+
+Only sites of subscribed providers you included in `providers` are returned. Each provider
+carries its `provider_type` (a `DataProviderType`) and its display `color` (`#rrggbb`).
+`NearbyProviderSitesStatus.UNAVAILABLE` means the site lookup failed; the cohort counts are
+still valid. At most the nearest 500 sites are returned; `truncated` is `True` when there were
+more.
+
+With `includeNearbyProviderSites` on, the request is rejected with a `GraphQLError` when it has
+more than 50 distinct providers, more than 25 grouping sites, or a radius or distance band outside
+1-250 miles.

{phactor-0.3.1 → phactor-0.4.0}/README.md

@@ -243,3 +243,57 @@ There are three independent operator levels:
 Exclusion groups are always unioned and subtracted from the pathway's combined
 inclusion result. For example, an `OR` pathway with inclusion groups `A` and `B`
 and exclusion group `E` evaluates as `(A OR B) EXCEPT E`.
+
+## Geographic Grouping
+
+Group cohort results by geography using PROXIMITY and RADIUS or DISTANCE_BANDS mode:
+
+```python
+result = client.cohorts.analyze(
+    providers=[...],
+    cohort_groups=[...],
+    grouping={
+        "type": "PROXIMITY",
+        "proximityMode": "RADIUS",
+        "sites": [
+            {"name": "Johns Hopkins", "latitude": 39.2963, "longitude": -76.5927, "radiusMiles": 25}
+        ],
+    },
+)
+for analysis in result.analyses:
+    for group in analysis.site_radius_results or []:
+        print(group.site_name, group.count, group.percentage)
+```
+
+### Provider sites near each grouping site
+
+```python
+from phactor import NearbyProviderSitesStatus
+
+result = client.cohorts.analyze(
+    providers=[...],
+    cohort_groups=[...],
+    grouping={
+        "type": "PROXIMITY",
+        "proximityMode": "RADIUS",
+        "sites": [
+            {"name": "Johns Hopkins", "latitude": 39.2963, "longitude": -76.5927, "radiusMiles": 25}
+        ],
+        "includeNearbyProviderSites": True,
+    },
+)
+nearby = result.nearby_provider_sites
+if nearby and nearby.status == NearbyProviderSitesStatus.AVAILABLE:
+    for site in nearby.sites:
+        print(site.name, [p.name for p in site.providers], [m.distance_miles for m in site.matches])
+```
+
+Only sites of subscribed providers you included in `providers` are returned. Each provider
+carries its `provider_type` (a `DataProviderType`) and its display `color` (`#rrggbb`).
+`NearbyProviderSitesStatus.UNAVAILABLE` means the site lookup failed; the cohort counts are
+still valid. At most the nearest 500 sites are returned; `truncated` is `True` when there were
+more.
+
+With `includeNearbyProviderSites` on, the request is rejected with a `GraphQLError` when it has
+more than 50 distinct providers, more than 25 grouping sites, or a radius or distance band outside
+1-250 miles.

{phactor-0.3.1 → phactor-0.4.0}/src/phactor/__init__.py

@@ -30,6 +30,7 @@ from phactor.cohorts.models import (
     CriterionError,
     CriterionErrorDomain,
     CriterionErrorReason,
+    DataProviderType,
     DistanceBand,
     GenderValue,
     GeographicGroup,
@@ -48,6 +49,11 @@ from phactor.cohorts.models import (
     MedicationsInput,
     MedicationStatus,
     MedicationTypeEnum,
+    NearbyProviderRef,
+    NearbyProviderSite,
+    NearbyProviderSiteMatch,
+    NearbyProviderSites,
+    NearbyProviderSitesStatus,
     PdcFilterInput,
     ProcedureInput,
     ProcedureOutcome,
@@ -113,6 +119,8 @@ __all__ = [
     "CriterionErrorReason",
     "ResultGrouping",
     "ProximityMode",
+    "NearbyProviderSitesStatus",
+    "DataProviderType",
     # Input models
     "TimingInput",
     "AgeRangeInput",
@@ -148,6 +156,10 @@ __all__ = [
     "CriterionError",
     "DistanceBand",
     "GeographicGroup",
+    "NearbyProviderRef",
+    "NearbyProviderSite",
+    "NearbyProviderSiteMatch",
+    "NearbyProviderSites",
     "SiteDistanceBandResult",
     "SiteRadiusResult",
     # Site search

phactor-0.4.0/src/phactor/_version.py

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

{phactor-0.3.1 → phactor-0.4.0}/src/phactor/cohorts/client.py

@@ -156,7 +156,11 @@ class CohortsClient:
             age_buckets: Custom age range buckets for demographic breakdown.
             include_combined_demographic_breakdown:
                 Include combined-population demographic breakdown.
-            grouping: Geographic grouping configuration dict.
+            grouping: Geographic grouping configuration dict. With
+                ``includeNearbyProviderSites`` on, the server rejects the request
+                (``GraphQLError``) when it has more than 50 distinct providers,
+                more than 25 grouping sites, or a radius or distance band outside
+                1-250 miles.
             global_filters: Optional global filters applied to all cohort groups
                 (e.g. restrict the study to specific states or geographies).
         Returns:

{phactor-0.3.1 → phactor-0.4.0}/src/phactor/cohorts/models.py

@@ -233,11 +233,23 @@ class CohortGroupOperator(str, Enum):
 
 
 class CriterionErrorReason(str, Enum):
-    NO_TRANSLATION = "NO_TRANSLATION"
-    NO_PATH = "NO_PATH"
+    """Why a provider could not evaluate a criterion. Values the server adds
+    later reach ``CriterionError.reason`` as plain strings instead of failing."""
+
+    UNSUPPORTED_SEMANTICS = "UNSUPPORTED_SEMANTICS"
+    INSUFFICIENT_DATA = "INSUFFICIENT_DATA"
+    MATERIALIZATION_NOT_READY = "MATERIALIZATION_NOT_READY"
+    NO_TRANSLATION = "NO_TRANSLATION"  # a crosswalk route exists but this code has no entry
+    NO_PATH = "NO_PATH"  # no translation route from the source system to the provider's
 
 
 class CriterionErrorDomain(str, Enum):
+    """The criterion type a ``CriterionError`` is about. Values the server adds
+    later reach ``CriterionError.domain`` as plain strings instead of failing."""
+
+    AGE = "AGE"
+    MEASUREMENT = "MEASUREMENT"
+    ENCOUNTER = "ENCOUNTER"
     CONDITION = "CONDITION"
     PROCEDURE = "PROCEDURE"
     ALLERGY = "ALLERGY"
@@ -596,6 +608,9 @@ class GroupingInput(BaseModel):
     # Opt-in exact radius / distance-band counts (PostGIS ST_DWithin
     # refine over the approximate H3 hex cover). Default None (approximate).
     exact: bool | None = None
+    # Opt-in: also return subscribed providers' sites inside each grouping radius
+    # (AnalyzeCohortsPayload.nearby_provider_sites). PROXIMITY only.
+    include_nearby_provider_sites: bool | None = None
 
 
 class GlobalFiltersInput(BaseModel):
@@ -677,10 +692,12 @@ class DemographicBreakdown(BaseModel):
 class CriterionError(BaseModel):
     model_config = _MODEL_CONFIG
 
-    domain: CriterionErrorDomain
+    # Response enums fall back to the raw string for values this SDK version
+    # does not know yet, so a new server value never breaks parsing a result.
+    domain: CriterionErrorDomain | str = Field(union_mode="left_to_right")
     source_type: str
     source_value: str
-    reason: CriterionErrorReason
+    reason: CriterionErrorReason | str = Field(union_mode="left_to_right")
     message: str | None = None
 
 
@@ -759,9 +776,75 @@ class ProviderCohortAnalysis(BaseModel):
     site_distance_band_results: list[SiteDistanceBandResult] | None = None
 
 
+class NearbyProviderSitesStatus(str, Enum):
+    """Whether the nearby provider site lookup succeeded. Values the server adds
+    later reach ``NearbyProviderSites.status`` as plain strings instead of failing."""
+
+    AVAILABLE = "AVAILABLE"
+    UNAVAILABLE = "UNAVAILABLE"
+
+
+class DataProviderType(str, Enum):
+    """The kind of data a provider holds. Values the server adds later reach
+    ``NearbyProviderRef.provider_type`` as plain strings instead of failing."""
+
+    PHARMACY = "PHARMACY"
+    HOSPITAL = "HOSPITAL"
+    LABORATORY = "LABORATORY"
+    EHR_SYSTEM = "EHR_SYSTEM"
+    CLAIMS = "CLAIMS"
+    GENOMICS = "GENOMICS"
+    OTHER = "OTHER"
+
+
+class NearbyProviderRef(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    id: str
+    name: str
+    # A value this SDK version does not know yet stays a plain string.
+    provider_type: DataProviderType | str = Field(union_mode="left_to_right")
+    # The provider's display color as a ``#rrggbb`` hex string.
+    color: str
+
+
+class NearbyProviderSiteMatch(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    site_name: str
+    latitude: float
+    longitude: float
+    distance_miles: float
+
+
+class NearbyProviderSite(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    id: str
+    name: str
+    address: str | None = None
+    city: str | None = None
+    state: str | None = None
+    postal_code: str | None = None
+    latitude: float
+    longitude: float
+    providers: list[NearbyProviderRef]
+    matches: list[NearbyProviderSiteMatch]
+
+
+class NearbyProviderSites(BaseModel):
+    model_config = _MODEL_CONFIG
+
+    # A value this SDK version does not know yet stays a plain string.
+    status: NearbyProviderSitesStatus | str = Field(union_mode="left_to_right")
+    truncated: bool
+    sites: list[NearbyProviderSite]
+
+
 class AnalyzeCohortsPayload(BaseModel):
     model_config = _MODEL_CONFIG
 
     id: str
     analyses: list[ProviderCohortAnalysis]
     warnings: list[AnalysisWarning] | None = None
+    nearby_provider_sites: NearbyProviderSites | None = None

{phactor-0.3.1 → phactor-0.4.0}/src/phactor/cohorts/query.py

@@ -93,6 +93,14 @@ query AnalyzeCohorts($input: AnalyzeCohortsInput!) {
       code
       message
     }
+    nearbyProviderSites {
+      status truncated
+      sites {
+        id name address city state postalCode latitude longitude
+        providers { id name providerType color }
+        matches { siteName latitude longitude distanceMiles }
+      }
+    }
   }
 }
 """

{phactor-0.3.1 → phactor-0.4.0}/src/phactor/sites/models.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from enum import Enum
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 from pydantic.alias_generators import to_camel
 
 from phactor.cohorts.models import LocationTypeEnum, LocationValueInput
@@ -34,7 +34,8 @@ class Site(BaseModel):
     country: str | None = None
     latitude: float
     longitude: float
-    access: SiteAccess
+    # A value this SDK version does not know yet stays a plain string.
+    access: SiteAccess | str = Field(union_mode="left_to_right")
 
     def as_location(self, *, radius: int = 10) -> LocationValueInput:
         """A SITE location value matching patients within ``radius`` miles of this site.

phactor-0.3.1/src/phactor/_version.py

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