initial

Dockerfile

@@ -0,0 +1,27 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This is used to build a Docker image that includes the necessary dependencies
+# for running the Path Foundation as a microservice.
+
+FROM python:3.12-slim-bullseye
+
+RUN apt-get update && apt-get install -y nano tmux
+
+COPY ./requirements.txt  /
+RUN pip3 install -r requirements.txt
+
+COPY ./ /
+
+ENTRYPOINT ["/bin/bash"]

data_models/__init__.py

@@ -0,0 +1,14 @@
+#
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

data_models/embedding_converter.py

@@ -0,0 +1,445 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Converts Embedding Requests and Responses to json and vice versa."""
+
+import dataclasses
+import json
+from typing import Any, List, Mapping, Sequence
+
+from ez_wsi_dicomweb import patch_embedding_endpoints
+
+import pete_errors
+from data_models import embedding_request
+from data_models import embedding_response
+from data_models import patch_coordinate as patch_coordinate_module
+
+_EndpointJsonKeys = patch_embedding_endpoints.EndpointJsonKeys
+
+
+class ValidationError(Exception):
+  pass
+
+
+class _InvalidCoordinateError(Exception):
+  pass
+
+
+class _InstanceUIDMetadataError(Exception):
+  pass
+
+
+def validate_int(val: Any) -> int:
+  if isinstance(val, float):
+    cast_val = int(val)
+    if cast_val != val:
+      raise ValidationError('coordinate value is not int')
+    val = cast_val
+  elif not isinstance(val, int):
+    raise ValidationError('coordinate value is not int')
+  return val
+
+
+def _get_patch_coord(patch_coordinates: Sequence[Mapping[str, Any]]):
+  """Returns patch coodianates."""
+  result = []
+  if not isinstance(patch_coordinates, list):
+    raise _InvalidCoordinateError('patch_coordinates is not list')
+  for patch_coordinate in patch_coordinates:
+    try:
+      pc = patch_coordinate_module.create_patch_coordinate(**patch_coordinate)
+    except TypeError as exp:
+      if not isinstance(patch_coordinate, dict):
+        raise _InvalidCoordinateError('Patch coordinate is not dict.') from exp
+      keys = ', '.join(
+          list(
+              dataclasses.asdict(
+                  patch_coordinate_module.create_patch_coordinate(0, 0)
+              )
+          )
+      )
+      raise _InvalidCoordinateError(
+          f'Patch coordinate dict has invalid keys; expecting: {keys}'
+      ) from exp
+    try:
+      validate_int(pc.x_origin)
+      validate_int(pc.y_origin)
+      validate_int(pc.width)
+      validate_int(pc.height)
+    except ValidationError as exp:
+      raise _InvalidCoordinateError(
+          f'Invalid patch coordinate; x_origin: {pc.x_origin}, y_origin:'
+          f' {pc.y_origin}, width: {pc.width}, height: {pc.height}'
+      ) from exp
+    result.append(pc)
+  if not result:
+    raise _InvalidCoordinateError('empty patch_coordinates')
+  return result
+
+
+def embedding_response_v1_to_json(
+    response: embedding_response.EmbeddingResponseV1,
+) -> Mapping[str, Any]:
+  """Loads the model artifact.
+
+  Args:
+    response: Structed EmbeddingResponse object.
+
+  Returns:
+    The value of the JSON payload to return in the API.
+  """
+  json_response = dataclasses.asdict(response)
+  if response.error_response:
+    json_response['error_response'][
+        'error_code'
+    ] = response.error_response.error_code.value
+  return {_EndpointJsonKeys.PREDICTIONS: json_response}
+
+
+def embedding_response_v2_to_json(
+    json_response: Sequence[Mapping[str, Any]],
+) -> Mapping[str, Any]:
+  return {_EndpointJsonKeys.PREDICTIONS: json_response}
+
+
+def validate_str_list(val: Any) -> List[str]:
+  if not isinstance(val, List):
+    raise ValidationError('not list')
+  for v in val:
+    if not isinstance(v, str) or not v:
+      raise ValidationError('list contains invalid value')
+  return val
+
+
+def _validate_instance_uids_not_empty_str_list(val: Any) -> List[str]:
+  try:
+    val = validate_str_list(val)
+  except ValidationError as exp:
+    raise _InstanceUIDMetadataError() from exp
+  if not val:
+    raise _InstanceUIDMetadataError('list is empty')
+  return val
+
+
+def validate_str_key_dict(val: Any) -> Mapping[str, Any]:
+  if not isinstance(val, dict):
+    raise ValidationError('not a dict')
+  if val:
+    for k in val:
+      if not isinstance(k, str) or not k:
+        raise ValidationError('dict contains invalid value')
+  return val
+
+
+def validate_str(val: Any) -> str:
+  if not isinstance(val, str):
+    raise ValidationError('not string')
+  return val
+
+
+def _validate_not_empty_str(val: Any) -> str:
+  if not isinstance(val, str) or not val:
+    raise ValidationError('not string or empty')
+  return val
+
+
+def _generate_instance_metadata_error_string(
+    metadata: Mapping[str, Any], *keys: str
+) -> str:
+  """returns instance metadata as a error string."""
+  result = {}
+  for key in keys:
+    if key not in metadata:
+      continue
+    if key == _EndpointJsonKeys.EXTENSIONS:
+      value = metadata[key]
+      if isinstance(value, Mapping):
+        value = dict(value)
+        # Strip ez_wsi_state from output.
+        # Not contributing to validation errors here and may be very large.
+        if _EndpointJsonKeys.EZ_WSI_STATE in value:
+          del value[_EndpointJsonKeys.EZ_WSI_STATE]
+          result[key] = value
+          continue
+    elif key == _EndpointJsonKeys.BEARER_TOKEN:
+      value = metadata[key]
+      # If bearer token is present, and defined strip
+      if isinstance(value, str) and value:
+        result[key] = 'PRESENT'
+        continue
+    # otherwise just associate key and value.
+    result[key] = metadata[key]
+  return json.dumps(result, sort_keys=True)
+
+
+def _validate_instance_list(json_metadata: Mapping[str, Any]) -> List[Any]:
+  val = json_metadata.get(_EndpointJsonKeys.INSTANCES)
+  if isinstance(val, list):
+    return val
+  raise pete_errors.InvalidRequestFieldError(
+      'Invalid input, missing expected'
+      f' key: {_EndpointJsonKeys.INSTANCES} and associated list of values.'
+  )
+
+
+class EmbeddingConverterV1:
+  """Class containing methods for transforming embedding request and responses."""
+
+  def json_to_embedding_request(
+      self, json_metadata: Mapping[str, Any]
+  ) -> embedding_request.EmbeddingRequestV1:
+    """Converts json to embedding request.
+
+    Args:
+      json_metadata: The value of the JSON payload provided to the API.
+
+    Returns:
+      Structured EmbeddingRequest object.
+
+    Raises:
+      InvalidRequestFieldError: If the provided fields are invalid.
+    """
+    instances = []
+    try:
+      model_params = json_metadata[_EndpointJsonKeys.PARAMETERS]
+      try:
+        parameters = embedding_request.EmbeddingParameters(
+            model_size=_validate_not_empty_str(
+                model_params.get(_EndpointJsonKeys.MODEL_SIZE)
+            ),
+            model_kind=_validate_not_empty_str(
+                model_params.get(_EndpointJsonKeys.MODEL_KIND)
+            ),
+        )
+      except ValidationError as exp:
+        raise pete_errors.InvalidRequestFieldError(
+            'Invalid model size and/or kind parameters.'
+        ) from exp
+      for instance in _validate_instance_list(json_metadata):
+        ez_wsi_state = instance.get(_EndpointJsonKeys.EZ_WSI_STATE, {})
+        try:
+          ez_wsi_state = validate_str_key_dict(ez_wsi_state)
+        except ValidationError:
+          try:
+            ez_wsi_state = validate_str(ez_wsi_state)
+          except ValidationError as exp:
+            raise pete_errors.InvalidRequestFieldError(
+                'Invalid EZ-WSI state metadata.'
+            ) from exp
+        try:
+          instances.append(
+              embedding_request.EmbeddingInstanceV1(
+                  dicom_web_store_url=_validate_not_empty_str(
+                      instance.get(_EndpointJsonKeys.DICOM_WEB_STORE_URL)
+                  ),
+                  dicom_study_uid=_validate_not_empty_str(
+                      instance.get(_EndpointJsonKeys.DICOM_STUDY_UID)
+                  ),
+                  dicom_series_uid=_validate_not_empty_str(
+                      instance.get(_EndpointJsonKeys.DICOM_SERIES_UID)
+                  ),
+                  bearer_token=_validate_not_empty_str(
+                      instance.get(_EndpointJsonKeys.BEARER_TOKEN)
+                  ),
+                  ez_wsi_state=ez_wsi_state,
+                  instance_uids=_validate_instance_uids_not_empty_str_list(
+                      instance.get(_EndpointJsonKeys.INSTANCE_UIDS)
+                  ),
+                  patch_coordinates=_get_patch_coord(
+                      instance.get(_EndpointJsonKeys.PATCH_COORDINATES)
+                  ),
+              )
+          )
+        except ValidationError as exp:
+          instance_error_msg = _generate_instance_metadata_error_string(
+              instance,
+              _EndpointJsonKeys.DICOM_WEB_STORE_URL,
+              _EndpointJsonKeys.DICOM_STUDY_UID,
+              _EndpointJsonKeys.DICOM_SERIES_UID,
+              _EndpointJsonKeys.BEARER_TOKEN,
+              _EndpointJsonKeys.INSTANCE_UIDS,
+          )
+          raise pete_errors.InvalidRequestFieldError(
+              f'Invalid instance; {instance_error_msg}'
+          ) from exp
+        except _InstanceUIDMetadataError as exp:
+          instance_error_msg = _generate_instance_metadata_error_string(
+              instance,
+              _EndpointJsonKeys.PATCH_COORDINATES,
+          )
+          raise pete_errors.InvalidRequestFieldError(
+              f'Invalid DICOM SOP Instance UID metadata; {instance_error_msg}'
+          ) from exp
+    except _InvalidCoordinateError as exp:
+      raise pete_errors.InvalidRequestFieldError(
+          f'Invalid patch coordinate; {exp}'
+      ) from exp
+    except (TypeError, ValueError, KeyError) as exp:
+      raise pete_errors.InvalidRequestFieldError(
+          f'Invalid input: {json.dumps(json_metadata)}'
+      ) from exp
+    return embedding_request.EmbeddingRequestV1(
+        parameters=parameters, instances=instances
+    )
+
+
+class EmbeddingConverterV2:
+  """Class containing methods for transforming embedding request and responses."""
+
+  def json_to_embedding_request(
+      self, json_metadata: Mapping[str, Any]
+  ) -> embedding_request.EmbeddingRequestV2:
+    """Converts json to embedding request.
+
+    Args:
+      json_metadata: The value of the JSON payload provided to the API.
+
+    Returns:
+      Structured EmbeddingRequest object.
+
+    Raises:
+      InvalidRequestFieldError: If the provided fields are invalid.
+    """
+    instances = []
+    for instance in _validate_instance_list(json_metadata):
+      try:
+        patch_coordinates = _get_patch_coord(
+            instance.get(_EndpointJsonKeys.PATCH_COORDINATES)
+        )
+      except _InvalidCoordinateError as exp:
+        instance_error_msg = _generate_instance_metadata_error_string(
+            instance,
+            _EndpointJsonKeys.PATCH_COORDINATES,
+        )
+        raise pete_errors.InvalidRequestFieldError(
+            f'Invalid patch coordinate; {exp}; {instance_error_msg}'
+        ) from exp
+      if _EndpointJsonKeys.DICOM_PATH in instance:
+        try:
+          dicom_path = validate_str_key_dict(
+              instance.get(_EndpointJsonKeys.DICOM_PATH)
+          )
+        except ValidationError as exp:
+          raise pete_errors.InvalidRequestFieldError(
+              'Invalid DICOM path.'
+          ) from exp
+        try:
+          instances.append(
+              embedding_request.DicomImageV2(
+                  series_path=_validate_not_empty_str(
+                      dicom_path.get(_EndpointJsonKeys.SERIES_PATH)
+                  ),
+                  bearer_token=validate_str(
+                      instance.get(
+                          _EndpointJsonKeys.BEARER_TOKEN,
+                          '',
+                      )
+                  ),
+                  extensions=validate_str_key_dict(
+                      instance.get(
+                          _EndpointJsonKeys.EXTENSIONS,
+                          {},
+                      )
+                  ),
+                  instance_uids=_validate_instance_uids_not_empty_str_list(
+                      dicom_path.get(_EndpointJsonKeys.INSTANCE_UIDS)
+                  ),
+                  patch_coordinates=patch_coordinates,
+              )
+          )
+        except _InstanceUIDMetadataError as exp:
+          error_msg = _generate_instance_metadata_error_string(
+              instance,
+              _EndpointJsonKeys.SERIES_PATH,
+              _EndpointJsonKeys.BEARER_TOKEN,
+              _EndpointJsonKeys.EXTENSIONS,
+              _EndpointJsonKeys.INSTANCE_UIDS,
+          )
+          raise pete_errors.InvalidRequestFieldError(
+              f'Invalid DICOM SOP Instance UID metadata; {error_msg}'
+          ) from exp
+        except ValidationError as exp:
+          error_msg = _generate_instance_metadata_error_string(
+              instance,
+              _EndpointJsonKeys.SERIES_PATH,
+              _EndpointJsonKeys.BEARER_TOKEN,
+              _EndpointJsonKeys.EXTENSIONS,
+              _EndpointJsonKeys.INSTANCE_UIDS,
+          )
+          raise pete_errors.InvalidRequestFieldError(
+              f'DICOM instance JSON formatting is invalid; {error_msg}'
+          ) from exp
+      elif _EndpointJsonKeys.IMAGE_FILE_URI in instance:
+        try:
+          instances.append(
+              embedding_request.GcsImageV2(
+                  image_file_uri=_validate_not_empty_str(
+                      instance.get(_EndpointJsonKeys.IMAGE_FILE_URI)
+                  ),
+                  bearer_token=validate_str(
+                      instance.get(
+                          _EndpointJsonKeys.BEARER_TOKEN,
+                          '',
+                      )
+                  ),
+                  extensions=validate_str_key_dict(
+                      instance.get(
+                          _EndpointJsonKeys.EXTENSIONS,
+                          {},
+                      )
+                  ),
+                  patch_coordinates=patch_coordinates,
+              )
+          )
+        except ValidationError as exp:
+          error_msg = _generate_instance_metadata_error_string(
+              instance,
+              _EndpointJsonKeys.IMAGE_FILE_URI,
+              _EndpointJsonKeys.BEARER_TOKEN,
+              _EndpointJsonKeys.EXTENSIONS,
+          )
+          raise pete_errors.InvalidRequestFieldError(
+              'Google Cloud Storage instance JSON formatting is invalid;'
+              f' {error_msg}'
+          ) from exp
+      elif _EndpointJsonKeys.RAW_IMAGE_BYTES in instance:
+        try:
+          instances.append(
+              embedding_request.EmbeddedImageV2(
+                  image_bytes=_validate_not_empty_str(
+                      instance.get(_EndpointJsonKeys.RAW_IMAGE_BYTES)
+                  ),
+                  extensions=validate_str_key_dict(
+                      instance.get(
+                          _EndpointJsonKeys.EXTENSIONS,
+                          {},
+                      )
+                  ),
+                  patch_coordinates=patch_coordinates,
+              )
+          )
+        except ValidationError as exp:
+          error_msg = _generate_instance_metadata_error_string(
+              instance,
+              _EndpointJsonKeys.IMAGE_FILE_URI,
+              _EndpointJsonKeys.BEARER_TOKEN,
+              _EndpointJsonKeys.EXTENSIONS,
+          )
+          raise pete_errors.InvalidRequestFieldError(
+              'Embedded image instance JSON formatting is invalid; '
+              f' {error_msg}'
+          ) from exp
+      else:
+        raise pete_errors.InvalidRequestFieldError('unidentified type')
+    return embedding_request.EmbeddingRequestV2(instances)

data_models/embedding_request.py

@@ -0,0 +1,103 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Request dataclasses for Pete."""
+
+import dataclasses
+import enum
+from typing import Any, List, Mapping, Union
+from data_models import patch_coordinate
+
+
+class ModelSize(enum.Enum):
+  UNDEFINED = 0
+  SMALL = 1  # ~1M parameters
+  MEDIUM = 2  # ~20M parameters.
+  LARGE = 3  # ~100M parameters.
+
+
+class ModelKind(enum.Enum):
+  UNDEFINED = 0
+  # Best suited for high magnification images.
+  # Pixel spacings of .002mm, .001mm, .0005mm or 5x, 10x, 20x.
+  LOW_PIXEL_SPACING = 1
+  # Best suited for low magnification images.
+  # Pixel spacings of .004mm, .008mm, .016mm, 5x_div_2, 5x_div4, 5x_div8.
+  HIGH_PIXEL_SPACING = 2
+
+
+@dataclasses.dataclass(frozen=True)
+class EmbeddingInstanceV1:
+  """An instance in a DICOM Embedding Request as described in the schema file."""
+
+  dicom_web_store_url: str
+  dicom_study_uid: str
+  dicom_series_uid: str
+  bearer_token: str
+  ez_wsi_state: Union[str, Mapping[str, Any]]
+  instance_uids: List[str]
+  patch_coordinates: List[patch_coordinate.PatchCoordinate]
+
+
+@dataclasses.dataclass(frozen=True)
+class DicomImageV2:
+  """An instance in a DICOM Embedding Request as described in the schema file."""
+  series_path: str
+  bearer_token: str
+  extensions: Mapping[str, Any]
+  instance_uids: List[str]
+  patch_coordinates: List[patch_coordinate.PatchCoordinate]
+
+
+@dataclasses.dataclass(frozen=True)
+class GcsImageV2:
+  """An instance in a DICOM Embedding Request as described in the schema file."""
+
+  image_file_uri: str
+  bearer_token: str
+  extensions: Mapping[str, Any]
+  patch_coordinates: List[patch_coordinate.PatchCoordinate]
+
+
+@dataclasses.dataclass(frozen=True)
+class EmbeddedImageV2:
+  """An instance in a DICOM Embedding Request as described in the schema file."""
+  image_bytes: str
+  extensions: Mapping[str, Any]
+  patch_coordinates: List[patch_coordinate.PatchCoordinate]
+
+
+EmbeddingInstanceV2 = Union[DicomImageV2, GcsImageV2, EmbeddedImageV2]
+
+
+@dataclasses.dataclass(frozen=True)
+class EmbeddingParameters:
+  """A prediction in a DICOM Embedding Request as described in the schema file."""
+
+  model_size: str
+  model_kind: str
+
+
+@dataclasses.dataclass(frozen=True)
+class EmbeddingRequestV1:
+  """A DICOM Embedding Request is a single parameter and list of instances."""
+  parameters: EmbeddingParameters
+  instances: List[EmbeddingInstanceV1]
+
+
+@dataclasses.dataclass(frozen=True)
+class EmbeddingRequestV2:
+  """A DICOM Embedding Request is a list of instances."""
+
+  instances: List[EmbeddingInstanceV2]

data_models/embedding_response.py

@@ -0,0 +1,143 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Response dataclasses for Pete."""
+
+import dataclasses
+import enum
+from typing import Any, List, Mapping, Optional, Sequence
+
+from ez_wsi_dicomweb import patch_embedding_endpoints
+
+import pete_errors
+from data_models import patch_coordinate
+
+_MAX_ERROR_DESCRIPTION_LENGTH = 1024
+
+
+class ErrorCode(enum.Enum):
+  """The error codes for PeteErrorResponse mapped from PeteErrors."""
+
+  TOO_MANY_PATCHES_ERROR = 'TOO_MANY_PATCHES_ERROR'
+  INVALID_CREDENTIALS_ERROR = (
+      patch_embedding_endpoints.EndpointJsonKeys.INVALID_CREDENTIALS
+  )
+  PATCH_DIMENSIONS_DO_NOT_MATCH_ENDPOINT_INPUT_DIMENSIONS_ERROR = (
+      'PATCH_DIMENSIONS_DO_NOT_MATCH_ENDPOINT_INPUT_DIMENSIONS_ERROR'
+  )
+  INSTANCES_NOT_CONCATENATED_ERROR = 'INSTANCES_NOT_CONCATENATED_ERROR'
+  INVALID_REQUEST_FIELD_ERROR = 'INVALID_REQUEST_FIELD_ERROR'
+  INVALID_RESPONSE_ERROR = 'INVALID_RESPONSE_ERROR'
+  LEVEL_NOT_FOUND_ERROR = 'LEVEL_NOT_FOUND_ERROR'
+  EZ_WSI_STATE_ERROR = 'EZ_WSI_STATE_ERROR'
+  IMAGE_ERROR = 'IMAGE_ERROR'
+  HTTP_ERROR = 'HTTP_ERROR'
+  INVALID_ICC_PROFILE_TRANSFORM_ERROR = 'INVALID_ICC_PROFILE_TRANSFORM_ERROR'
+  IMAGE_DIMENSION_ERROR = 'IMAGE_DIMENSION_ERROR'
+  DICOM_TILED_FULL_ERROR = 'DICOM_TILED_FULL_ERROR'
+  DICOM_ERROR = 'DICOM_ERROR'
+  DICOM_IMAGE_DOWNSAMPLING_TOO_LARGE_ERROR = (
+      'DICOM_IMAGE_DOWNSAMPLING_TOO_LARGE_ERROR'
+  )
+  PATCH_OUTSIDE_OF_IMAGE_DIMENSIONS_ERROR = (
+      'PATCH_OUTSIDE_OF_IMAGE_DIMENSIONS_ERROR'
+  )
+  DICOM_PATH_ERROR = 'DICOM_PATH_ERROR'
+  GCS_IMAGE_PATH_FORMAT_ERROR = 'GCS_IMAGE_PATH_FORMAT_ERROR'
+  UNAPPROVED_DICOM_STORE_ERROR = 'UNAPPROVED_DICOM_STORE_ERROR'
+  UNAPPROVED_GCS_BUCKET_ERROR = 'UNAPPROVED_GCS_BUCKET_ERROR'
+
+
+@dataclasses.dataclass(frozen=True)
+class PeteErrorResponse:
+  """The response when Pete is unable to successfully complete a request."""
+
+  error_code: ErrorCode
+
+
+@dataclasses.dataclass(frozen=True)
+class PatchEmbeddingV1:
+  """A List of embeddings, instance uids, and patch coordinate."""
+
+  embeddings: List[float]
+  patch_coordinate: patch_coordinate.PatchCoordinate
+
+
+@dataclasses.dataclass(frozen=True)
+class PatchEmbeddingV2:
+  """A List of embeddings, instance uids, and patch coordinate."""
+
+  embedding_vector: List[float]
+  patch_coordinate: patch_coordinate.PatchCoordinate
+
+
+@dataclasses.dataclass(frozen=True)
+class EmbeddingResultV1:
+  """The response when Pete is able to successfully complete a request."""
+
+  dicom_study_uid: str
+  dicom_series_uid: str
+  instance_uids: List[str]
+  patch_embeddings: List[PatchEmbeddingV1]
+
+
+@dataclasses.dataclass(frozen=True)
+class EmbeddingResponseV1:
+  """An instance in a Embedding Response as described in the schema file."""
+
+  model_version: str
+  error_response: Optional[PeteErrorResponse]
+  embedding_result: List[EmbeddingResultV1]
+
+  def __post_init__(self):
+    if self.error_response is None and self.embedding_result is None:
+      raise pete_errors.InvalidResponseError(
+          'At least one of error_response or embedding_result must be set.'
+      )
+
+
+def embedding_instance_response_v2(
+    results: Sequence[PatchEmbeddingV2],
+) -> Mapping[str, Any]:
+  """Returns a JSON-serializable embedding instance responses."""
+  return {
+      patch_embedding_endpoints.EndpointJsonKeys.RESULT: {
+          patch_embedding_endpoints.EndpointJsonKeys.PATCH_EMBEDDINGS: [
+              dataclasses.asdict(patch_embedding) for patch_embedding in results
+          ]
+      },
+  }
+
+
+def instance_error_response_v2(
+    error_code: ErrorCode, description: str = ''
+) -> Mapping[str, Any]:
+  error = {
+      patch_embedding_endpoints.EndpointJsonKeys.ERROR_CODE: error_code.value
+  }
+  if description:
+    error[patch_embedding_endpoints.EndpointJsonKeys.ERROR_CODE_DESCRIPTION] = (
+        description[:_MAX_ERROR_DESCRIPTION_LENGTH]
+    )
+  return {
+      patch_embedding_endpoints.EndpointJsonKeys.ERROR: error,
+  }
+
+
+def prediction_error_response_v2(error_code: ErrorCode) -> Mapping[str, Any]:
+  return {
+      patch_embedding_endpoints.EndpointJsonKeys.VERTEXAI_ERROR: (
+          error_code.value
+      )
+  }

data_models/patch_coordinate.py

@@ -0,0 +1,54 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared dataclasses across requests and responses for Pete."""
+
+import dataclasses
+
+import pete_errors
+
+
+@dataclasses.dataclass(frozen=True)
+class PatchCoordinate:
+  """A coordinate of a patch."""
+
+  x_origin: int
+  y_origin: int
+  height: int
+  width: int
+
+  def __post_init__(self):
+    if (self.width != 224 or self.height != 224):
+      raise pete_errors.PatchDimensionsDoNotMatchEndpointInputDimensionsError(
+          'Patch coordinate width and height must be', f' 224x224.'
+      )
+
+
+def create_patch_coordinate(
+    x_origin: int,
+    y_origin: int,
+    width: int = -1,
+    height: int = -1,
+) -> PatchCoordinate:
+  """Creates a patch coordinate."""
+  if width == -1:
+    width = 224
+  if height == -1:
+    height = 224
+  return PatchCoordinate(
+      x_origin=x_origin,
+      y_origin=y_origin,
+      width=width,
+      height=height,
+  )

pete_errors.py

@@ -0,0 +1,119 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Error classes for Pete."""
+
+
+class InternalBugError(Exception):
+  """Internal error capture exceptions which should never happen.
+
+  The exception is purposefully not a child of PeteError to prevent it from
+  being caught by pete exception handling logic. If InternalBugError are
+  raised they should be investigated as bugs. Most internal errors check for
+  expected conditions between the EZ-WSI pete interface.
+  """
+
+
+class PeteError(Exception):
+  """Base error class for Pete Errors."""
+
+  def __init__(self, message: str = '', api_description: str = ''):
+    """Errors with optional alternative descriptions for API echoing."""
+    super().__init__(message if message else api_description)
+    self._api_description = api_description
+
+  @property
+  def api_description(self) -> str:
+    """Returns the API description of the error."""
+    return self._api_description if self._api_description else str(self)
+
+
+class InstancesNotConcatenatedError(PeteError):
+  pass
+
+
+class InvalidRequestFieldError(PeteError):
+  pass
+
+
+class InvalidResponseError(PeteError):
+  pass
+
+
+class InvalidCredentialsError(PeteError):
+  pass
+
+
+class LevelNotFoundError(PeteError):
+  pass
+
+
+class TooManyPatchesError(PeteError):
+  pass
+
+
+class EzWsiStateError(PeteError):
+  pass
+
+
+class GcsImagePathFormatError(PeteError):
+  pass
+
+
+class ImageError(PeteError):
+  pass
+
+
+class PatchOutsideOfImageDimensionsError(PeteError):
+  pass
+
+
+class HttpError(PeteError):
+  pass
+
+
+class InvalidIccProfileTransformError(PeteError):
+  pass
+
+
+class ImageDimensionError(PeteError):
+  pass
+
+
+class DicomTiledFullError(PeteError):
+  pass
+
+
+class DicomPathError(PeteError):
+  pass
+
+
+class DicomError(PeteError):
+  pass
+
+
+class DicomImageDownsamplingTooLargeError(PeteError):
+  pass
+
+
+class UnapprovedDicomStoreError(PeteError):
+  pass
+
+
+class UnapprovedGcsBucketError(PeteError):
+  pass
+
+
+class PatchDimensionsDoNotMatchEndpointInputDimensionsError(PeteError):
+  pass

pete_predictor_v2.py

@@ -0,0 +1,101 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Callable responsible for running Inference on provided patches."""
+
+import functools
+from typing import Any, Mapping
+
+from ez_wsi_dicomweb import credential_factory
+from ez_wsi_dicomweb import dicom_slide
+from ez_wsi_dicomweb import patch_embedding
+from ez_wsi_dicomweb import dicom_web_interface
+from ez_wsi_dicomweb import patch_embedding_endpoints
+from ez_wsi_dicomweb.ml_toolkit import dicom_path
+import numpy as np
+import tensorflow as tf
+
+from data_models import embedding_response
+from data_models import embedding_request
+from data_models import embedding_converter
+
+
+
+def _load_huggingface_model() -> tf.keras.Model:
+  raise ValueError('Liron implement model loader') 
+
+
+def _endpoint_model(ml_model: tf.keras.Model, image: np.ndarray) -> np.ndarray:
+  """Function ez-wsi will use to run local ML model."""
+  result = ml_model.signatures['serving_default'](
+      tf.cast(tf.constant(image), tf.float32)
+  )
+  return result['output_0'].numpy()
+
+
+_ENDPOINT_MODEL = functools.partial(_endpoint_model, _load_huggingface_model())
+
+
+class PetePredictor:
+  """Callable responsible for generating embeddings."""
+
+  def predict(
+      self,
+      prediction_input: Mapping[str, Any],
+  ) -> Mapping[str, Any]:
+    """Runs inference on provided patches.
+
+    Args:
+      prediction_input: JSON formatted input for embedding prediction.
+      model: ModelRunner to handle model step.
+
+    Returns:
+      JSON formatted output.
+
+    Raises:
+      ERROR_LOADING_DICOM: If the provided patches are not concated.
+    """
+    embedding_json_converter = embedding_converter.EmbeddingConverterV2()
+    request = embedding_json_converter.json_to_embedding_request(prediction_input)
+    endpoint =  patch_embedding_endpoints.LocalEndpoint(_ENDPOINT_MODEL)
+
+    embedding_results = []
+    for instance in request.instances:
+      patches = []
+      if not isinstance(instance, embedding_request.DicomImageV2):
+        raise ValueError('unsupported')
+      token = instance.bearer_token
+      if token:
+        cf = credential_factory.TokenPassthroughCredentialFactory(token)
+      else:
+        cf = credential_factory.NoAuthCredentialsFactory()
+      dwi = dicom_web_interface.DicomWebInterface(cf)
+      path = dicom_path.FromString(instance.series_path)
+      ds = dicom_slide.DicomSlide(dwi=dwi, path=path)
+      level = ds.get_instance_level(instance.instance_uids[0])
+      for coor in instance.patch_coordinates:
+        patches.append(ds.get_patch(level, coor.x_origin, coor.y_origin, coor.width, coor.height))
+
+      patch_embeddings = []
+      for index, result in enumerate(patch_embedding.generate_patch_embeddings(endpoint, patches)):
+        embedding = np.array(result.embedding)
+        patch_embeddings.append(
+            embedding_response.PatchEmbeddingV2(
+                embedding_vector=embedding.tolist(),
+                patch_coordinate=instance.patch_coordinates[index],
+            ))
+      embedding_results.append(
+          embedding_response.embedding_instance_response_v2(patch_embeddings)
+      )
+    return embedding_converter.embedding_response_v2_to_json(embedding_results)

requirements.txt

@@ -0,0 +1,7 @@
+absl-py~=2.1.0
+ez-wsi-dicomweb~=6.0.9
+flask~=3.0.3
+gunicorn~=23.0.0
+numpy~=1.26.4
+tensorflow~=2.17.0
+typing-extensions~=4.12.2

server_gunicorn.py

@@ -0,0 +1,100 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Gunicorn application for passing requests through to the executor command.
+
+Provides a thin, subject-agnostic request server for Vertex endpoints which
+handles requests by piping their JSON bodies to the given executor command
+and returning the json output.
+"""
+
+from collections.abc import Mapping
+import http
+import os
+from typing import Any, Optional, Sequence
+
+from absl import app
+from absl import logging
+import flask
+from gunicorn.app import base as gunicorn_base
+
+import pete_predictor_v2 
+
+
+def _create_app() -> flask.Flask:
+  """Creates a Flask app with the given executor."""
+  predictor = pete_predictor_v2.PetePredictor()
+  flask_app = flask.Flask(__name__)
+
+  def predict() -> tuple[dict[str, Any], int]:
+    logging.info("predict route hit")
+    if flask.request.get_json(silent=True) is None:
+      return {"error": "No JSON body."}, http.HTTPStatus.BAD_REQUEST.value
+
+    logging.debug("Dispatching request to executor.")
+    try:
+      exec_result = predictor.predict(flask.request.get_json())
+      logging.debug("Executor returned results.")
+      return (exec_result, http.HTTPStatus.OK.value)
+    except RuntimeError:
+      logging.exception("Internal error handling request: Executor failed.")
+      return {
+          "error": "Internal server error."
+      }, http.HTTPStatus.INTERNAL_SERVER_ERROR.value
+
+  predict_route = os.environ.get("AIP_PREDICT_ROUTE", "/predict")
+  logging.info("predict route: %s", predict_route)
+  flask_app.add_url_rule(predict_route, view_func=predict, methods=["POST"])
+
+  flask_app.config["TRAP_BAD_REQUEST_ERRORS"] = True
+
+  return flask_app
+
+
+class PredictionApplication(gunicorn_base.BaseApplication):
+  """Application to serve predictors on Vertex endpoints using gunicorn."""
+
+  def __init__(
+      self,
+      *,
+      options: Optional[Mapping[str, Any]] = None,
+  ):
+    self.options = options or {}
+    self.options = dict(self.options)
+    self.options["preload_app"] = False
+    self.application = _create_app()
+    super().__init__()
+
+  def load_config(self):
+    config = {
+        key: value
+        for key, value in self.options.items()
+        if key in self.cfg.settings and value is not None
+    }
+    for key, value in config.items():
+      self.cfg.set(key.lower(), value)
+
+  def load(self) -> flask.Flask:
+    return self.application
+
+def main(argv: Sequence[str]) -> None:
+  options = {'bind': f'127.0.0.1:80',
+             'workers': 3,
+             'timeout':600
+            }
+  PredictionApplication(options=options).run()
+
+
+if __name__ == '__main__':
+  app.run(main)

test.py

@@ -0,0 +1,18 @@
+from ez_wsi_dicomweb import credential_factory
+from ez_wsi_dicomweb import dicom_slide
+from ez_wsi_dicomweb import dicom_web_interface
+from ez_wsi_dicomweb import patch_embedding
+from ez_wsi_dicomweb import patch_embedding_endpoints
+from ez_wsi_dicomweb.ml_toolkit import dicom_path
+
+
+if __name__ == '__main__':
+  endpoint = patch_embedding_endpoints.V2PatchEmbeddingEndpoint(credential_factory=credential_factory.NoAuthCredentialsFactory())
+  endpoint._end_point_url = 'http://127.0.0.1/predict'
+
+  dwi = dicom_web_interface.DicomWebInterface(credential_factory.NoAuthCredentialsFactory())
+  path = dicom_path.FromString("https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb/studies/2.25.247578737460869511622147617375340640521/series/1.3.6.1.4.1.5962.99.1.1334257398.450227235.1637716829942.2.0")
+  slide = dicom_slide.DicomSlide(dwi, path)
+  patch = slide.get_patch(slide.native_level, 0,0, 224,224)
+  embedding = patch_embedding.get_patch_embedding(endpoint, patch)
+  print(embedding)