phactor 0.2.0__tar.gz → 0.3.2__tar.gz

{phactor-0.2.0 → phactor-0.3.2}/CHANGELOG.md

@@ -6,6 +6,67 @@ 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.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
+
+- `client.cohorts.analyze` accepts SDK models anywhere inside plain-dict
+  arguments. A `site.as_location()` value in a hand-written proposition or
+  `global_filters` dict used to fail with "Object of type LocationValueInput is
+  not JSON serializable"; it is now sent as a `SITE` value. Plain dict values are
+  sent unchanged.
+
+## [0.3.0] - 2026-09-23
+
+### Added
+
+- **Registry site search: `client.sites`** on both `PhactorClient` and
+  `AsyncPhactorClient`, over the gateway's `searchSites` / `sitesByIds` queries.
+  Results cover the sites visible to the caller's tenant (PUBLIC, plus RESTRICTED
+  sites it owns or was granted) that are active and have coordinates.
+  - `search(query, *, limit=20, cursor=None) -> SitePage` returns one page
+    (`items`, `next_cursor`).
+  - `iter(query, *, max_results=100, page_size=50)` lazily yields `Site`s,
+    fetching the next page only when the consumer asks for it and never past
+    `max_results` (at most 500).
+  - `get(ids) -> SitesByIds` resolves up to 100 distinct IDs and reports the
+    unresolvable ones in `missing_ids`.
+  - Guardrails are checked before any request (`ValueError`): search text 2 to
+    100 characters after trimming, `limit` / `page_size` 1 to 50, at most 100 IDs.
+  - Search pages and by-ID lookups are cached per client for 60 seconds (bounded,
+    thread-safe and asyncio-safe); sites seen in a search also answer `get`.
+  - New models `Site`, `SiteAccess`, `SitePage`, `SitesByIds`.
+- **`LocationTypeEnum.SITE`**: a location value whose `value` is a registry site
+  ID, matching patients within `radius` miles of the site (`radius=0` uses the
+  connector's 10-mile default). `Site.as_location(radius=10)` builds one.
+  `LocationValueInput` rejects `coords` and a negative `radius` on a SITE value,
+  and `LocationInput` accepts at most 25 SITE values.
+- `GraphQLError.missing_site_ids`: the SITE IDs `analyzeCohorts` could not
+  resolve (from `extensions.missingSiteIds`); the whole request fails when any
+  are missing.
+
 ## [0.2.0] - 2026-07-04
 
 ### Breaking

{phactor-0.2.0 → phactor-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: phactor
-Version: 0.2.0
+Version: 0.3.2
 Summary: Python SDK for the Phactor clinical trial feasibility platform
 Project-URL: Homepage, https://phactor.ai
 Project-URL: Documentation, https://docs.phactor.ai
@@ -157,6 +157,53 @@ client = PhactorClient(
 - If an API request returns `401`, the SDK invalidates the cached token, fetches a fresh token, and retries once before raising `AuthenticationError`.
 - `AsyncPhactorClient` should be used through `async with` or closed explicitly with `await client.close()`. Once closed, further use raises `PhactorError`.
 
+## Site Search
+
+`client.sites` searches the global site registry: PUBLIC sites plus the
+RESTRICTED sites your tenant owns or was granted. Only active sites with
+coordinates are returned, and a site ID can be used directly as a cohort
+location criterion.
+
+```python
+from phactor import PhactorClient
+from phactor.cohorts import CohortBuilder, Proposition
+
+with PhactorClient() as client:
+    page = client.sites.search("general hospital", limit=10)  # one page
+    more = client.sites.search("general hospital", limit=10, cursor=page.next_cursor)
+
+    # Lazy: fetches a page only as you consume it, never past max_results.
+    for site in client.sites.iter("boston", max_results=100):
+        print(site.id, site.name, site.city, site.access)
+
+    lookup = client.sites.get(["<site-id>", "<other-site-id>"])
+    print(lookup.missing_ids)  # unknown, not visible to you, inactive, or no coordinates
+
+    site = page.items[0]
+    cohort = (
+        CohortBuilder()
+        .include("Near the site")
+        # Patients within 15 miles of the site; radius=0 means the 10-mile default.
+        .add(Proposition(location={"values": [site.as_location(radius=15)]}))
+        .done()
+        .build()
+    )
+    result = client.cohorts.analyze(providers=["provider-uuid"], cohort_groups=[cohort])
+```
+
+The async client exposes the same methods (`await client.sites.search(...)`,
+`async for site in client.sites.iter(...)`). Criteria exported from the sponsor
+portal carry SITE values as plain dicts
+(`{"type": "SITE", "value": "<site-id>", "radius": 10}`) and can be passed to
+`analyze` unchanged.
+
+Limits, checked before any request is sent (`ValueError`): search text 2 to 100
+characters after trimming, `limit` and `page_size` 1 to 50, `max_results` up to
+500, `get` up to 100 distinct IDs, and at most 25 SITE values per location. A
+SITE value never carries `coords`. Search pages and by-ID lookups are cached per
+client for 60 seconds. If `analyze` names a site the server cannot resolve, the
+whole request fails with a `GraphQLError` whose `missing_site_ids` lists them.
+
 ## Fluent Cohort Builder
 
 ```python

{phactor-0.2.0 → phactor-0.3.2}/README.md

@@ -118,6 +118,53 @@ client = PhactorClient(
 - If an API request returns `401`, the SDK invalidates the cached token, fetches a fresh token, and retries once before raising `AuthenticationError`.
 - `AsyncPhactorClient` should be used through `async with` or closed explicitly with `await client.close()`. Once closed, further use raises `PhactorError`.
 
+## Site Search
+
+`client.sites` searches the global site registry: PUBLIC sites plus the
+RESTRICTED sites your tenant owns or was granted. Only active sites with
+coordinates are returned, and a site ID can be used directly as a cohort
+location criterion.
+
+```python
+from phactor import PhactorClient
+from phactor.cohorts import CohortBuilder, Proposition
+
+with PhactorClient() as client:
+    page = client.sites.search("general hospital", limit=10)  # one page
+    more = client.sites.search("general hospital", limit=10, cursor=page.next_cursor)
+
+    # Lazy: fetches a page only as you consume it, never past max_results.
+    for site in client.sites.iter("boston", max_results=100):
+        print(site.id, site.name, site.city, site.access)
+
+    lookup = client.sites.get(["<site-id>", "<other-site-id>"])
+    print(lookup.missing_ids)  # unknown, not visible to you, inactive, or no coordinates
+
+    site = page.items[0]
+    cohort = (
+        CohortBuilder()
+        .include("Near the site")
+        # Patients within 15 miles of the site; radius=0 means the 10-mile default.
+        .add(Proposition(location={"values": [site.as_location(radius=15)]}))
+        .done()
+        .build()
+    )
+    result = client.cohorts.analyze(providers=["provider-uuid"], cohort_groups=[cohort])
+```
+
+The async client exposes the same methods (`await client.sites.search(...)`,
+`async for site in client.sites.iter(...)`). Criteria exported from the sponsor
+portal carry SITE values as plain dicts
+(`{"type": "SITE", "value": "<site-id>", "radius": 10}`) and can be passed to
+`analyze` unchanged.
+
+Limits, checked before any request is sent (`ValueError`): search text 2 to 100
+characters after trimming, `limit` and `page_size` 1 to 50, `max_results` up to
+500, `get` up to 100 distinct IDs, and at most 25 SITE values per location. A
+SITE value never carries `coords`. Search pages and by-ID lookups are cached per
+client for 60 seconds. If `analyze` names a site the server cannot resolve, the
+whole request fails with a `GraphQLError` whose `missing_site_ids` lists them.
+
 ## Fluent Cohort Builder
 
 ```python

{phactor-0.2.0 → phactor-0.3.2}/src/phactor/__init__.py

@@ -76,6 +76,7 @@ from phactor.exceptions import (
     TimeoutError,
     ValidationError,
 )
+from phactor.sites.models import Site, SiteAccess, SitePage, SitesByIds
 
 __all__ = [
     "__version__",
@@ -149,6 +150,11 @@ __all__ = [
     "GeographicGroup",
     "SiteDistanceBandResult",
     "SiteRadiusResult",
+    # Site search
+    "Site",
+    "SiteAccess",
+    "SitePage",
+    "SitesByIds",
     # Exceptions
     "AuthenticationError",
     "ConnectionError",

phactor-0.3.2/src/phactor/_graphql.py

@@ -0,0 +1,37 @@
+"""Shared GraphQL response handling for every gateway operation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from phactor.exceptions import GraphQLError
+
+
+def extract_field(response: dict[str, Any], field: str) -> Any:
+    """Return ``response["data"][field]``, raising ``GraphQLError`` on any error shape."""
+    if response.get("errors"):
+        errors = response["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 = (response.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 = (response.get("data") or {}).get(field)
+    if payload is None:
+        raise GraphQLError(f"Unexpected response: missing {field} data")
+    return payload

phactor-0.3.2/src/phactor/_version.py

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

{phactor-0.2.0 → phactor-0.3.2}/src/phactor/auth.py

@@ -35,9 +35,7 @@ class TokenManager:
         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
+            f"target-entity:{config.entity_id}:internal:read" if config.entity_id else None
         )
         self._cached: _CachedToken | None = None
         self._lock = threading.Lock()
@@ -105,9 +103,7 @@ class AsyncTokenManager:
         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
+            f"target-entity:{config.entity_id}:internal:read" if config.entity_id else None
         )
         self._cached: _CachedToken | None = None
         self._lock = asyncio.Lock()

{phactor-0.2.0 → phactor-0.3.2}/src/phactor/client.py

@@ -17,6 +17,7 @@ from phactor.cohorts.models import (
 )
 from phactor.config import PhactorConfig
 from phactor.exceptions import PhactorError
+from phactor.sites.client import AsyncSitesClient, SitesClient
 
 
 class PhactorClient:
@@ -25,6 +26,7 @@ class PhactorClient:
     Usage:
         client = PhactorClient(client_id="...", client_secret="...", ...)
         result = client.cohorts.analyze(providers=[...], cohort_groups=[...])
+        sites = client.sites.search("mass general")
         client.close()
 
     Or as a context manager:
@@ -57,6 +59,7 @@ class PhactorClient:
             token_manager, timeout=self._config.timeout, verify=self._config.verify
         )
         self.cohorts = CohortsClient(self._http, self._config.gateway_url)
+        self.sites = SitesClient(self._http, self._config.gateway_url)
 
     def close(self) -> None:
         """Close the underlying HTTP client."""
@@ -109,6 +112,9 @@ class AsyncPhactorClient:
         )
         self._cohorts = AsyncCohortsClient(self._http, self._config.gateway_url)
         self.cohorts = _AsyncCohortsProxy(self)
+        self.sites = AsyncSitesClient(
+            self._http, self._config.gateway_url, ensure_open=self._ensure_open
+        )
 
     async def close(self) -> None:
         """Close the underlying HTTP client."""

{phactor-0.2.0 → phactor-0.3.2}/src/phactor/cohorts/client.py

@@ -8,6 +8,9 @@ import time
 from enum import Enum
 from typing import Any
 
+from pydantic import BaseModel
+
+from phactor._graphql import extract_field
 from phactor._http import AsyncHTTPClient, SyncHTTPClient
 from phactor.cohorts.models import (
     AnalyzeCohortsPayload,
@@ -17,7 +20,6 @@ from phactor.cohorts.models import (
     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
@@ -63,6 +65,24 @@ def _emit_timing(
     )
 
 
+def _to_json(value: Any) -> Any:
+    """Make a request value JSON-ready, whether it is a model or a plain dict.
+
+    SDK models may sit anywhere inside a plain dict or list, e.g. a
+    ``site.as_location()`` value in a hand-written proposition, so they are
+    converted wherever they appear. Plain dict values pass through unchanged.
+    """
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json", by_alias=True, exclude_none=True)
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, dict):
+        return {key: _to_json(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_to_json(item) for item in value]
+    return value
+
+
 def _build_variables(
     providers: list[str],
     cohort_groups: list[CohortGroupInput | dict[str, Any]],
@@ -76,92 +96,29 @@ def _build_variables(
     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,
-        }
+    input_: dict[str, Any] = {
+        "providers": providers,
+        "cohortGroups": _to_json(cohort_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
+    optional = {
+        "cohortGroupOperator": cohort_group_operator,
+        "studyContext": study_context,
+        "includeImpactAnalysis": include_impact_analysis,
+        "includeDemographicBreakdown": include_demographic_breakdown,
+        "ageBuckets": age_buckets,
+        "includeCombinedDemographicBreakdown": include_combined_demographic_breakdown,
+        "grouping": grouping,
+        "globalFilters": global_filters,
+    }
+    for key, value in optional.items():
+        if value is not None:
+            input_[key] = _to_json(value)
+    return {"input": input_}
 
 
 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)
+    return AnalyzeCohortsPayload.model_validate(extract_field(data, "analyzeCohorts"))
 
 
 class CohortsClient:

{phactor-0.2.0 → phactor-0.3.2}/src/phactor/cohorts/models.py

@@ -10,6 +10,7 @@ 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("_")
@@ -82,6 +83,9 @@ class LocationTypeEnum(str, Enum):
     CITY = "CITY"
     STATE = "STATE"
     COORDS = "COORDS"
+    # A registry site ID (see ``client.sites``). The server resolves it to the
+    # site's coordinates, so a SITE value never carries ``coords`` itself.
+    SITE = "SITE"
 
 
 # Code systems mirror the Query API GraphQL schema (ConditionTypeEnum) one-to-one.
@@ -177,14 +181,14 @@ class ImmunizationTypeEnum(str, Enum):
 # 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
+    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)
+    A = "A"  # Abnormal (use when no high/low direction applies)
     AA = "AA"  # Critically abnormal
 
 
@@ -229,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"
@@ -284,20 +300,48 @@ class CoordsInput(BaseModel):
     lng: float
 
 
+# Mirrors the Query API guardrail on SITE values per LocationInput.
+_MAX_SITE_VALUES = 25
+
+
 class LocationValueInput(BaseModel):
     model_config = _MODEL_CONFIG
 
     type: LocationTypeEnum
     value: str
+    # Miles around the location. For SITE, 0 falls back to the connector's
+    # 10-mile default.
     radius: int
     coords: CoordsInput | None = None
 
+    @model_validator(mode="after")
+    def _validate_site_value(self) -> LocationValueInput:
+        if self.type != LocationTypeEnum.SITE:
+            return self
+        if self.coords is not None:
+            raise ValueError(
+                "A SITE location value must not carry coords: the server resolves "
+                "the site ID to its registry coordinates."
+            )
+        if self.radius < 0:
+            raise ValueError(f"A SITE location radius must be >= 0, got {self.radius}.")
+        return self
+
 
 class LocationInput(BaseModel):
     model_config = _MODEL_CONFIG
 
     values: list[LocationValueInput] | None = None
 
+    @model_validator(mode="after")
+    def _limit_site_values(self) -> LocationInput:
+        site_count = sum(1 for v in self.values or [] if v.type == LocationTypeEnum.SITE)
+        if site_count > _MAX_SITE_VALUES:
+            raise ValueError(
+                f"A location accepts at most {_MAX_SITE_VALUES} SITE values, got {site_count}."
+            )
+        return self
+
 
 class ConditionStageInput(BaseModel):
     # FHIR Condition.stage.type — staging vocabulary (e.g. TNM, FIGO,
@@ -459,18 +503,14 @@ class LabValueInput(BaseModel):
         # 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
-        )
+        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."
-            )
+            raise ValueError("LabValueInput requires at least one of test_code or test_name.")
         return self
 
 
@@ -649,10 +689,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
 
 

{phactor-0.2.0 → phactor-0.3.2}/src/phactor/exceptions.py

@@ -22,6 +22,25 @@ class GraphQLError(PhactorError):
         super().__init__(message)
         self.errors = errors or []
 
+    @property
+    def missing_site_ids(self) -> list[str]:
+        """Registry site IDs the server could not resolve for the caller.
+
+        ``analyzeCohorts`` rejects the whole request when a ``SITE`` location value
+        names a site that does not exist, is not visible to the caller's tenant,
+        is inactive, or has no coordinates; those IDs arrive under
+        ``extensions.missingSiteIds``. Empty for every other error.
+        """
+        missing: list[str] = []
+        for error in self.errors:
+            extensions = error.get("extensions")
+            if not isinstance(extensions, dict):
+                continue
+            ids = extensions.get("missingSiteIds")
+            if isinstance(ids, list):
+                missing.extend(str(site_id) for site_id in ids)
+        return missing
+
 
 class ValidationError(PhactorError):
     """Raised when input validation fails (e.g., builder misuse)."""

{phactor-0.2.0 → phactor-0.3.2}/src/phactor/pandas.py

@@ -4,6 +4,7 @@ Install with::
 
     pip install 'phactor[pandas]'
 """
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING
@@ -15,8 +16,7 @@ try:
     import pandas as pd
 except ImportError:
     raise ImportError(
-        "Install phactor[pandas] for DataFrame support: "
-        "pip install 'phactor[pandas]'"
+        "Install phactor[pandas] for DataFrame support: pip install 'phactor[pandas]'"
     ) from None
 
 from phactor.cohorts.models import (

phactor-0.3.2/src/phactor/sites/__init__.py

@@ -0,0 +1,13 @@
+"""Registry site search sub-package."""
+
+from phactor.sites.client import AsyncSitesClient, SitesClient
+from phactor.sites.models import Site, SiteAccess, SitePage, SitesByIds
+
+__all__ = [
+    "SitesClient",
+    "AsyncSitesClient",
+    "Site",
+    "SiteAccess",
+    "SitePage",
+    "SitesByIds",
+]

phactor-0.3.2/src/phactor/sites/client.py

@@ -0,0 +1,353 @@
+"""Registry site search client: sends GraphQL queries to the Phactor gateway.
+
+The registry holds hundreds of thousands of sites, so this client is built to
+keep load off the API: every guardrail the server enforces is checked here
+first (a bad call never leaves the process), ``iter`` fetches a page only when
+the consumer asks for more and never past ``max_results``, and search pages and
+by-ID lookups are held in a small per-client TTL cache.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict
+from collections.abc import AsyncIterator, Callable, Iterator, Sequence
+from enum import Enum
+from typing import Any, Generic, TypeVar
+
+from phactor._graphql import extract_field
+from phactor._http import AsyncHTTPClient, SyncHTTPClient
+from phactor.sites.models import Site, SitePage, SitesByIds
+from phactor.sites.query import SEARCH_SITES_QUERY, SITES_BY_IDS_QUERY
+
+# Guardrails mirrored from the Query API; the server rejects anything outside them.
+_MIN_QUERY_LENGTH = 2
+_MAX_QUERY_LENGTH = 100
+_MAX_PAGE_SIZE = 50
+_MAX_IDS = 100
+# Deepest result the server lets a cursor reach.
+_MAX_RESULTS = 500
+
+_CACHE_TTL_SECONDS = 60.0
+_PAGE_CACHE_SIZE = 256
+_SITE_CACHE_SIZE = 4096
+
+_K = TypeVar("_K")
+_V = TypeVar("_V")
+
+
+class _Miss(Enum):
+    MISS = "MISS"
+
+
+class _TTLCache(Generic[_K, _V]):
+    """Bounded LRU cache whose entries expire ``ttl`` seconds after they are stored.
+
+    Every operation holds a ``threading.Lock`` and never awaits, so one instance
+    is safe to share across threads and across tasks on an event loop.
+    """
+
+    def __init__(self, *, ttl: float, maxsize: int, clock: Callable[[], float]) -> None:
+        self._ttl = ttl
+        self._maxsize = maxsize
+        self._clock = clock
+        self._entries: OrderedDict[_K, tuple[float, _V]] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def get(self, key: _K) -> _V | _Miss:
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is None:
+                return _Miss.MISS
+            expires_at, value = entry
+            if self._clock() >= expires_at:
+                del self._entries[key]
+                return _Miss.MISS
+            self._entries.move_to_end(key)
+            return value
+
+    def set(self, key: _K, value: _V) -> None:
+        with self._lock:
+            self._entries[key] = (self._clock() + self._ttl, value)
+            self._entries.move_to_end(key)
+            while len(self._entries) > self._maxsize:
+                self._entries.popitem(last=False)
+
+
+def _normalize_query(query: str) -> str:
+    text = query.strip()
+    if not _MIN_QUERY_LENGTH <= len(text) <= _MAX_QUERY_LENGTH:
+        raise ValueError(
+            f"query must be {_MIN_QUERY_LENGTH}..{_MAX_QUERY_LENGTH} characters after "
+            f"trimming, got {len(text)}"
+        )
+    return text
+
+
+def _check_range(name: str, value: int, maximum: int) -> None:
+    if not 1 <= value <= maximum:
+        raise ValueError(f"{name} must be between 1 and {maximum}, got {value}")
+
+
+def _site_key(site_id: str) -> str:
+    # The Query API matches IDs case-insensitively after trimming and returns the
+    # stored (lowercase) ID, so requests, cache keys, and results all use this form.
+    return site_id.strip().lower()
+
+
+def _normalize_ids(ids: Sequence[str]) -> list[str]:
+    if isinstance(ids, str):
+        raise ValueError("ids must be a list of site IDs, not a single string")
+    unique = list(dict.fromkeys(_site_key(site_id) for site_id in ids))
+    if len(unique) > _MAX_IDS:
+        raise ValueError(f"ids accepts at most {_MAX_IDS} distinct IDs, got {len(unique)}")
+    return unique
+
+
+_PageKey = tuple[str, int, str | None]
+
+
+class _PendingGet:
+    """A by-ID lookup split into cache hits and the IDs still to fetch."""
+
+    def __init__(self, ids: list[str], known: dict[str, Site | None]) -> None:
+        self.ids = ids
+        self.known = known
+        self.to_fetch = [site_id for site_id in ids if site_id not in known]
+
+    def body(self) -> dict[str, Any]:
+        return {"query": SITES_BY_IDS_QUERY, "variables": {"ids": self.to_fetch}}
+
+
+class _SiteLookups:
+    """Validation, caching, and response parsing shared by the sync and async clients."""
+
+    def __init__(self, *, cache_ttl: float, clock: Callable[[], float]) -> None:
+        self._pages: _TTLCache[_PageKey, SitePage] = _TTLCache(
+            ttl=cache_ttl, maxsize=_PAGE_CACHE_SIZE, clock=clock
+        )
+        # ``None`` records an ID the server reported missing.
+        self._sites: _TTLCache[str, Site | None] = _TTLCache(
+            ttl=cache_ttl, maxsize=_SITE_CACHE_SIZE, clock=clock
+        )
+
+    def page_key(self, query: str, limit: int, cursor: str | None) -> _PageKey:
+        _check_range("limit", limit, _MAX_PAGE_SIZE)
+        return (_normalize_query(query), limit, cursor)
+
+    def cached_page(self, key: _PageKey) -> SitePage | None:
+        page = self._pages.get(key)
+        return None if page is _Miss.MISS else _copy_page(page)
+
+    def search_body(self, key: _PageKey) -> dict[str, Any]:
+        query, limit, cursor = key
+        return {
+            "query": SEARCH_SITES_QUERY,
+            "variables": {"query": query, "first": limit, "after": cursor},
+        }
+
+    def store_page(self, key: _PageKey, response: dict[str, Any]) -> SitePage:
+        payload = extract_field(response, "searchSites")
+        page = SitePage(
+            items=[Site.model_validate(node) for node in payload["nodes"]],
+            next_cursor=payload.get("nextCursor"),
+        )
+        self._pages.set(key, page)
+        # Search and by-ID lookups apply the same visibility rules, so every
+        # site seen in a search also answers a later ``get`` without a request.
+        for site in page.items:
+            self._sites.set(_site_key(site.id), site)
+        return _copy_page(page)
+
+    def plan_get(self, ids: Sequence[str]) -> _PendingGet:
+        unique = _normalize_ids(ids)
+        known: dict[str, Site | None] = {}
+        for site_id in unique:
+            cached = self._sites.get(site_id)
+            if cached is not _Miss.MISS:
+                known[site_id] = cached
+        return _PendingGet(unique, known)
+
+    def finish_get(self, pending: _PendingGet, response: dict[str, Any] | None) -> SitesByIds:
+        resolved = dict(pending.known)
+        if response is not None:
+            payload = extract_field(response, "sitesByIds")
+            for node in payload["sites"]:
+                site = Site.model_validate(node)
+                key = _site_key(site.id)
+                resolved[key] = site
+                self._sites.set(key, site)
+            # Anything the server neither returned nor listed is treated as missing too.
+            for site_id in pending.to_fetch:
+                if site_id not in resolved:
+                    resolved[site_id] = None
+                    self._sites.set(site_id, None)
+        sites = [s for s in (resolved[site_id] for site_id in pending.ids) if s is not None]
+        missing = [site_id for site_id in pending.ids if resolved[site_id] is None]
+        return SitesByIds(sites=sites, missing_ids=missing)
+
+
+def _copy_page(page: SitePage) -> SitePage:
+    # Sites are frozen, but the list is not: hand every caller its own.
+    return SitePage(items=list(page.items), next_cursor=page.next_cursor)
+
+
+def _validate_iter(query: str, max_results: int, page_size: int) -> str:
+    _check_range("max_results", max_results, _MAX_RESULTS)
+    _check_range("page_size", page_size, _MAX_PAGE_SIZE)
+    return _normalize_query(query)
+
+
+class SitesClient:
+    """Synchronous client for the registry site search API."""
+
+    def __init__(
+        self,
+        http_client: SyncHTTPClient,
+        gateway_url: str,
+        *,
+        cache_ttl: float = _CACHE_TTL_SECONDS,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._http = http_client
+        self._gateway_url = gateway_url
+        self._lookups = _SiteLookups(cache_ttl=cache_ttl, clock=clock)
+
+    def search(self, query: str, *, limit: int = 20, cursor: str | None = None) -> SitePage:
+        """Search the sites visible to the caller by name, city, or ZIP prefix.
+
+        Args:
+            query: Search text, 2..100 characters after trimming.
+            limit: Page size, 1..50.
+            cursor: ``next_cursor`` from the previous page.
+
+        Raises:
+            ValueError: An argument is outside the guardrails (no request is sent).
+        """
+        key = self._lookups.page_key(query, limit, cursor)
+        cached = self._lookups.cached_page(key)
+        if cached is not None:
+            return cached
+        response = self._http.post(self._gateway_url, json=self._lookups.search_body(key))
+        return self._lookups.store_page(key, response)
+
+    def iter(self, query: str, *, max_results: int = 100, page_size: int = 50) -> Iterator[Site]:
+        """Lazily yield matching sites, fetching the next page only when it is needed.
+
+        Args:
+            query: Search text, 2..100 characters after trimming.
+            max_results: Stop after this many sites, 1..500. The last request asks
+                for no more than the remaining count.
+            page_size: Sites per request, 1..50.
+
+        Raises:
+            ValueError: An argument is outside the guardrails (raised on the call,
+                before any request).
+        """
+        text = _validate_iter(query, max_results, page_size)
+        return self._iter(text, max_results, page_size)
+
+    def _iter(self, query: str, max_results: int, page_size: int) -> Iterator[Site]:
+        remaining = max_results
+        cursor: str | None = None
+        while True:
+            page = self.search(query, limit=min(page_size, remaining), cursor=cursor)
+            for site in page.items:
+                yield site
+                remaining -= 1
+                if remaining == 0:
+                    return
+            if page.next_cursor is None or not page.items:
+                return
+            cursor = page.next_cursor
+
+    def get(self, ids: Sequence[str]) -> SitesByIds:
+        """Look up sites by registry ID.
+
+        IDs are matched the way the Query API matches them: surrounding whitespace
+        is stripped and case is ignored, so ``" ABC-1 "`` and ``"abc-1"`` name the
+        same site.
+
+        Args:
+            ids: Up to 100 distinct site IDs (distinct after normalization).
+                Duplicates are collapsed.
+
+        Returns:
+            The visible sites in request order, plus the IDs that could not be
+            resolved (unknown, not visible to the caller, inactive, or without
+            coordinates). ``missing_ids`` holds the normalized form of each ID
+            (stripped and lowercased), not the caller's spelling.
+
+        Raises:
+            ValueError: More than 100 distinct IDs (no request is sent).
+        """
+        pending = self._lookups.plan_get(ids)
+        response = (
+            self._http.post(self._gateway_url, json=pending.body()) if pending.to_fetch else None
+        )
+        return self._lookups.finish_get(pending, response)
+
+
+class AsyncSitesClient:
+    """Async client for the registry site search API."""
+
+    def __init__(
+        self,
+        http_client: AsyncHTTPClient,
+        gateway_url: str,
+        *,
+        cache_ttl: float = _CACHE_TTL_SECONDS,
+        clock: Callable[[], float] = time.monotonic,
+        ensure_open: Callable[[], None] | None = None,
+    ) -> None:
+        self._http = http_client
+        self._gateway_url = gateway_url
+        self._lookups = _SiteLookups(cache_ttl=cache_ttl, clock=clock)
+        self._ensure_open = ensure_open or (lambda: None)
+
+    async def search(self, query: str, *, limit: int = 20, cursor: str | None = None) -> SitePage:
+        """Search the sites visible to the caller (async). See ``SitesClient.search``."""
+        self._ensure_open()
+        key = self._lookups.page_key(query, limit, cursor)
+        cached = self._lookups.cached_page(key)
+        if cached is not None:
+            return cached
+        response = await self._http.post(self._gateway_url, json=self._lookups.search_body(key))
+        return self._lookups.store_page(key, response)
+
+    def iter(
+        self, query: str, *, max_results: int = 100, page_size: int = 50
+    ) -> AsyncIterator[Site]:
+        """Lazily yield matching sites (async). See ``SitesClient.iter``.
+
+        Use with ``async for``; arguments are validated on the call itself.
+        """
+        self._ensure_open()
+        text = _validate_iter(query, max_results, page_size)
+        return self._iter(text, max_results, page_size)
+
+    async def _iter(self, query: str, max_results: int, page_size: int) -> AsyncIterator[Site]:
+        remaining = max_results
+        cursor: str | None = None
+        while True:
+            page = await self.search(query, limit=min(page_size, remaining), cursor=cursor)
+            for site in page.items:
+                yield site
+                remaining -= 1
+                if remaining == 0:
+                    return
+            if page.next_cursor is None or not page.items:
+                return
+            cursor = page.next_cursor
+
+    async def get(self, ids: Sequence[str]) -> SitesByIds:
+        """Look up sites by registry ID (async). See ``SitesClient.get``."""
+        self._ensure_open()
+        pending = self._lookups.plan_get(ids)
+        response = (
+            await self._http.post(self._gateway_url, json=pending.body())
+            if pending.to_fetch
+            else None
+        )
+        return self._lookups.finish_get(pending, response)

phactor-0.3.2/src/phactor/sites/models.py

@@ -0,0 +1,66 @@
+"""Pydantic models for the registry site search API."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from phactor.cohorts.models import LocationTypeEnum, LocationValueInput
+
+_MODEL_CONFIG = ConfigDict(populate_by_name=True, alias_generator=to_camel, frozen=True)
+
+
+class SiteAccess(str, Enum):
+    """Why the caller can see a site."""
+
+    OWNED = "OWNED"  # a RESTRICTED site the caller's tenant owns
+    SHARED = "SHARED"  # a RESTRICTED site another tenant granted to the caller
+    GLOBAL = "GLOBAL"  # a PUBLIC site
+
+
+class Site(BaseModel):
+    """A registry site the caller can see. Only active sites with coordinates are returned."""
+
+    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
+    country: str | None = None
+    latitude: float
+    longitude: float
+    # 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.
+
+        ``radius=0`` falls back to the connector's 10-mile default.
+        """
+        return LocationValueInput(type=LocationTypeEnum.SITE, value=self.id, radius=radius)
+
+
+class SitePage(BaseModel):
+    """One page of ``client.sites.search`` results."""
+
+    model_config = _MODEL_CONFIG
+
+    items: list[Site]
+    # Pass back as ``cursor`` to fetch the next page; ``None`` on the last page.
+    next_cursor: str | None
+
+
+class SitesByIds(BaseModel):
+    """Result of ``client.sites.get``, in the order the IDs were requested."""
+
+    model_config = _MODEL_CONFIG
+
+    sites: list[Site]
+    # Requested IDs that do not exist, are not visible to the caller, are
+    # inactive, or have no coordinates, in normalized form (stripped, lowercased).
+    missing_ids: list[str]

phactor-0.3.2/src/phactor/sites/query.py

@@ -0,0 +1,32 @@
+"""GraphQL documents for registry site search."""
+
+_SITE_FIELDS = """
+      id
+      name
+      address
+      city
+      state
+      postalCode
+      country
+      latitude
+      longitude
+      access
+"""
+
+SEARCH_SITES_QUERY = f"""
+query SearchSites($query: String!, $first: Int, $after: String) {{
+  searchSites(query: $query, first: $first, after: $after) {{
+    nodes {{{_SITE_FIELDS}    }}
+    nextCursor
+  }}
+}}
+"""
+
+SITES_BY_IDS_QUERY = f"""
+query SitesByIds($ids: [ID!]!) {{
+  sitesByIds(ids: $ids) {{
+    sites {{{_SITE_FIELDS}    }}
+    missingIds
+  }}
+}}
+"""

phactor-0.2.0/src/phactor/_version.py

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