intersect-sdk 0.8.0__tar.gz → 0.8.1__tar.gz

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: intersect-sdk
-Version: 0.8.0
+Version: 0.8.1
 Summary: Python SDK to interact with INTERSECT
 Keywords: intersect
 Author-Email: Lance Drane <dranelt@ornl.gov>, Marshall McDonnell <mcdonnellmt@ornl.gov>, Seth Hitefield <hitefieldsd@ornl.gov>, Andrew Ayres <ayresaf@ornl.gov>, Gregory Cage <cagege@ornl.gov>, Jesse McGaha <mcgahajr@ornl.gov>, Robert Smith <smithrw@ornl.gov>, Gavin Wiggins <wigginsg@ornl.gov>, Michael Brim <brimmj@ornl.gov>, Rick Archibald <archibaldrk@ornl.gov>, Addi Malviya Thakur <malviyaa@ornl.gov>
@@ -21,13 +21,15 @@ Requires-Dist: paho-mqtt<2.0.0,>=1.6.1
 Requires-Dist: minio>=7.2.3
 Requires-Dist: jsonschema[format-nongpl]>=4.21.1
 Requires-Dist: eval-type-backport>=0.1.3; python_version < "3.10"
+Provides-Extra: amqp
 Requires-Dist: pika<2.0.0,>=1.3.2; extra == "amqp"
+Provides-Extra: docs
 Requires-Dist: sphinx>=5.3.0; extra == "docs"
 Requires-Dist: furo>=2023.3.27; extra == "docs"
-Provides-Extra: amqp
-Provides-Extra: docs
 Description-Content-Type: text/markdown
 
+[![Static Badge](https://img.shields.io/badge/DOI-10.11578%2Fdc.20240927.1-blue)](https://doi.org/10.11578/dc.20240927.1)
+
 # INTERSECT-SDK
 
 The INTERSECT-SDK is a framework for microservices to integrate themselves into the wider Interconnected Science Ecosystem (INTERSECT).
@@ -37,6 +39,8 @@ Please note that this README is currently a work in progress.
 ## What is INTERSECT?
 [INTERSECT](https://www.ornl.gov/intersect) was designed as a specific usecase - as an open federated hardware/software architecture for the laboratory of the future, which connects scientific instruments, robot-controlled laboratories and edge/center computing/data resources to enable autonomous experiments, self-driving laboratories, smart manufacturing, and AI-driven design, discovery and evaluation.
 
+For a high-level overview, please see [the architecture website.](https://intersect-architecture.readthedocs.io/en/latest/)
+
 ## What are the core design philosophies of the SDK?
 
 - Event-driven architecture

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/README.md

@@ -1,3 +1,5 @@
+[![Static Badge](https://img.shields.io/badge/DOI-10.11578%2Fdc.20240927.1-blue)](https://doi.org/10.11578/dc.20240927.1)
+
 # INTERSECT-SDK
 
 The INTERSECT-SDK is a framework for microservices to integrate themselves into the wider Interconnected Science Ecosystem (INTERSECT).
@@ -7,6 +9,8 @@ Please note that this README is currently a work in progress.
 ## What is INTERSECT?
 [INTERSECT](https://www.ornl.gov/intersect) was designed as a specific usecase - as an open federated hardware/software architecture for the laboratory of the future, which connects scientific instruments, robot-controlled laboratories and edge/center computing/data resources to enable autonomous experiments, self-driving laboratories, smart manufacturing, and AI-driven design, discovery and evaluation.
 
+For a high-level overview, please see [the architecture website.](https://intersect-architecture.readthedocs.io/en/latest/)
+
 ## What are the core design philosophies of the SDK?
 
 - Event-driven architecture

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
     "jsonschema[format-nongpl]>=4.21.1",
     "eval-type-backport>=0.1.3;python_version<'3.10'",
 ]
-version = "0.8.0"
+version = "0.8.1"
 
 [project.license]
 text = "BSD-3-Clause"
@@ -55,42 +55,6 @@ docs = [
     "furo>=2023.3.27",
 ]
 
-[tool.pdm.dev-dependencies]
-lint = [
-    "pre-commit>=3.3.1",
-    "ruff==0.5.7",
-    "mypy>=1.10.0",
-    "types-paho-mqtt>=1.6.0.20240106",
-]
-test = [
-    "pytest>=7.3.2",
-    "pytest-cov>=4.1.0",
-    "httpretty>=1.1.4",
-]
-
-[tool.pdm.scripts]
-test-all = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml"
-test-all-debug = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml -s"
-test-unit = "pytest tests/unit --cov=src/intersect_sdk/"
-test-e2e = "pytest tests/e2e --cov=src/intersect_sdk/"
-lint-format = "ruff format"
-lint-ruff = "ruff check --fix"
-lint-mypy = "mypy src/intersect_sdk/"
-
-[tool.pdm.scripts.lint]
-composite = [
-    "lint-format",
-    "lint-ruff",
-    "lint-mypy",
-]
-
-[tool.pdm.build]
-package-dir = "src"
-
-[tool.pdm.version]
-source = "file"
-path = "src/intersect_sdk/version.py"
-
 [tool.ruff]
 line-length = 100
 
@@ -144,8 +108,6 @@ ignore = [
     "COM812",
     "ISC001",
     "SIM105",
-    "ANN101",
-    "ANN102",
     "ANN401",
     "PLR2004",
 ]
@@ -231,6 +193,51 @@ exclude_also = [
     "except.* ImportError",
 ]
 
+[tool.pdm.dev-dependencies]
+lint = [
+    "pre-commit>=3.3.1",
+    "ruff==0.9.4",
+    "mypy>=1.10.0",
+    "types-paho-mqtt>=1.6.0.20240106",
+    "codespell>=2.3.0",
+]
+test = [
+    "pytest>=7.3.2",
+    "pytest-cov>=4.1.0",
+    "httpretty>=1.1.4",
+]
+
+[tool.pdm.scripts]
+test-all = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml"
+test-all-debug = "pytest tests/ --cov=src/intersect_sdk/ --cov-fail-under=80 --cov-report=html:reports/htmlcov/ --cov-report=xml:reports/coverage_report.xml --junitxml=reports/junit.xml -s"
+test-unit = "pytest tests/unit --cov=src/intersect_sdk/"
+test-e2e = "pytest tests/e2e --cov=src/intersect_sdk/"
+lint-docs = "sphinx-build -W --keep-going docs docs/_build"
+lint-format = "ruff format"
+lint-ruff = "ruff check --fix"
+lint-mypy = "mypy src/intersect_sdk/"
+lint-spelling = "codespell -w docs examples src tests *.md -S docs/_build"
+
+[tool.pdm.scripts.lint]
+composite = [
+    "lint-format",
+    "lint-ruff",
+    "lint-mypy",
+    "lint-spelling",
+    "lint-docs",
+]
+
+[tool.pdm.build]
+package-dir = "src"
+
+[tool.pdm.version]
+source = "file"
+path = "src/intersect_sdk/version.py"
+
+[tool.codespell]
+skip = ".git*,*.lock,.venv,.*cache/*,./docs/_build/*"
+check-hidden = true
+
 [build-system]
 requires = [
     "pdm-backend",

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/_internal/control_plane/brokers/amqp_client.py

@@ -254,7 +254,7 @@ class AMQPClient(BrokerClient):
         if self._should_disconnect:
             connection.ioloop.stop()
         else:
-            logger.warn('Connection closed, reopening in 5 seconds: %s', reason)
+            logger.warning('Connection closed, reopening in 5 seconds: %s', reason)
             connection.ioloop.call_later(5, connection.ioloop.stop)
         self._channel_flags.unset_all()
         self._channel_out = None

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/_internal/control_plane/brokers/mqtt_client.py

@@ -113,7 +113,7 @@ class MQTTClient(BrokerClient):
             topic: The topic on which to publish the message as a string.
             payload: The message to publish, as raw bytes.
             persist: Determine if the message should live until queue consumers or available (True), or
-              if it should be removed immediatedly (False)
+              if it should be removed immediately (False)
         """
         # NOTE: RabbitMQ only works with QOS of 1 and 0, and seems to convert QOS2 to QOS1
         self._connection.publish(topic, payload, qos=2 if persist else 0)

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/_internal/data_plane/data_plane_manager.py

@@ -32,7 +32,7 @@ class DataPlaneManager:
 
         # warn users about missing data plane
         if not self._minio_providers:
-            logger.warn('WARNING: This service cannot support any MINIO instances')
+            logger.warning('WARNING: This service cannot support any MINIO instances')
 
     def incoming_message_data_handler(self, message: UserspaceMessage | EventMessage) -> bytes:
         """Get data from the request data provider.

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/_internal/event_metadata.py

@@ -42,7 +42,7 @@ def definition_metadata_differences(
 ) -> list[tuple[str, str, str]]:
     """Return a list of differences between 'definition' and 'metadata'.
 
-    First tuple value = defintion key
+    First tuple value = definition key
     Second tuple value = second value
     Third tuple value = already cached value
     """

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/_internal/interfaces.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
-from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Protocol
 
 if TYPE_CHECKING:
     from uuid import UUID
 
+    from ..client_callback_definitions import INTERSECT_CLIENT_EVENT_CALLBACK_TYPE
+    from ..config.shared import HierarchyConfig
     from ..service_callback_definitions import (
         INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
     )
@@ -14,13 +15,12 @@ if TYPE_CHECKING:
     )
 
 
-class IntersectEventObserver(ABC):
+class IntersectEventObserver(Protocol):
     """Abstract definition of an entity which observes an INTERSECT event (i.e. IntersectService).
 
     Used as the common interface for event emitters (i.e. CapabilityImplementations).
     """
 
-    @abstractmethod
     def _on_observe_event(self, event_name: str, event_value: Any, operation: str) -> None:
         """How to react to an event being fired.
 
@@ -31,17 +31,16 @@ class IntersectEventObserver(ABC):
         """
         ...
 
-    @abstractmethod
     def create_external_request(
         self,
         request: IntersectDirectMessageParams,
         response_handler: INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None = None,
         timeout: float = 300.0,
     ) -> UUID:
-        """Observed entity (capabilitiy) tells observer (i.e. service) to send an external request.
+        """Observed entity (capability) tells observer (i.e. service) to send an external request.
 
         Params:
-          - request: the request we want to send out, encapsulated as an IntersectClientMessageParams object
+          - request: the request we want to send out, encapsulated as an IntersectDirectMessageParams object
           - response_handler: optional callback for how we want to handle the response from this request.
           - timeout: optional value for how long we should wait on the request, in seconds (default: 300 seconds)
 
@@ -49,3 +48,18 @@ class IntersectEventObserver(ABC):
           - generated RequestID associated with your request
         """
         ...
+
+    def register_event(
+        self,
+        service: HierarchyConfig,
+        event_name: str,
+        response_handler: INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,
+    ) -> None:
+        """Observed entity (capability) tells observer (i.e. service) to subscribe to a specific event.
+
+        Params:
+          - service: HierarchyConfig of the service we want to talk to
+          - event_name: name of event to subscribe to
+          - response_handler: callback for how to handle the reception of an event
+        """
+        ...

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/_internal/messages/userspace.py

@@ -25,13 +25,13 @@ from typing import Any, Union
 from pydantic import AwareDatetime, Field, TypeAdapter
 from typing_extensions import Annotated, TypedDict
 
-from ...constants import SYSTEM_OF_SYSTEM_REGEX  # noqa: TCH001 (this is runtime checked)
-from ...core_definitions import (  # noqa: TCH001 (this is runtime checked)
+from ...constants import SYSTEM_OF_SYSTEM_REGEX
+from ...core_definitions import (
     IntersectDataHandler,
     IntersectMimeType,
 )
 from ...version import version_string
-from ..data_plane.minio_utils import MinioPayload  # noqa: TCH001 (this is runtime checked)
+from ..data_plane.minio_utils import MinioPayload  # noqa: TC001 (this is runtime checked)
 
 
 class UserspaceMessageHeader(TypedDict):

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/_internal/schema.py

@@ -557,7 +557,7 @@ def get_schema_and_functions_from_capability_implementations(
         if cap_status_fn_name and cap_status_schema and cap_status_type_adapter:
             if status_function_name is not None:
                 # TODO may want to change this later
-                die('Only one capabilitiy may have an @intersect_status function')
+                die('Only one capability may have an @intersect_status function')
             status_function_cap = capability_type
             status_function_name = cap_status_fn_name
             status_function_schema = cap_status_schema

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/app_lifecycle.py

@@ -82,7 +82,7 @@ class SignalHandler:
         ----------
         signal (int): signal code.
         """
-        logger.warning('shutting down and handling signal %d' % signal)
+        logger.warning('shutting down and handling signal %s', signal)
         if self._cleanup_callback:
             self._cleanup_callback(signal)
         self._exit.set()

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/capability/base.py

@@ -14,6 +14,8 @@ if TYPE_CHECKING:
     from uuid import UUID
 
     from .._internal.interfaces import IntersectEventObserver
+    from ..client_callback_definitions import INTERSECT_CLIENT_EVENT_CALLBACK_TYPE
+    from ..config.shared import HierarchyConfig
     from ..service_callback_definitions import (
         INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
     )
@@ -137,8 +139,10 @@ class IntersectBaseCapabilityImplementation:
     ) -> list[UUID]:
         """Create an external request that we'll send to a different Service.
 
+        Note: You should generally NOT call this function until after you have initialized the IntersectService class.
+
         Params:
-          - request: the request we want to send out, encapsulated as an IntersectClientMessageParams object
+          - request: the request we want to send out, encapsulated as an IntersectDirectMessageParams object
           - response_handler: optional callback for how we want to handle the response from this request.
           - timeout: optional value for how long we should wait on the request, in seconds (default: 300 seconds)
 
@@ -153,3 +157,27 @@ class IntersectBaseCapabilityImplementation:
             observer.create_external_request(request, response_handler, timeout)
             for observer in self.__intersect_sdk_observers__
         ]
+
+    @final
+    def intersect_sdk_listen_for_service_event(
+        self,
+        service: HierarchyConfig,
+        event_name: str,
+        response_handler: INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,
+    ) -> None:
+        """Start listening to events from a specific Service.
+
+        Note: You should generally NOT call this function until after you have initialized the IntersectService class.
+
+        Params:
+          - service: The system-of-system hierarchy which points to the specific service
+          - event_name: The name of the event we want to listen for
+          - response_handler: callback for how to handle the reception of an event
+            The callback submits these parameters:
+            1) message source
+            2) name of operation
+            3) name of event
+            4) payload
+        """
+        for observer in self.__intersect_sdk_observers__:
+            observer.register_event(service, event_name, response_handler)

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/client.py

@@ -129,7 +129,7 @@ class IntersectClient:
             if user_callback:
                 # Do not persist, as we use the temporary client information to build this.
                 self._control_plane_manager.add_subscription_channel(
-                    f"{self._hierarchy.hierarchy_string('/')}/response",
+                    f'{self._hierarchy.hierarchy_string("/")}/response',
                     {self._handle_userspace_message_raw},
                     persist=False,
                 )
@@ -140,7 +140,7 @@ class IntersectClient:
                     service
                 ) in config.initial_message_event_config.services_to_start_listening_for_events:
                     self._control_plane_manager.add_subscription_channel(
-                        f"{service.replace('.', '/')}/events",
+                        f'{service.replace(".", "/")}/events',
                         {self._handle_event_message_raw},
                         persist=False,
                     )
@@ -390,13 +390,13 @@ class IntersectClient:
         if self._event_callback:
             for add_event in validated_result.services_to_start_listening_for_events:
                 self._control_plane_manager.add_subscription_channel(
-                    f"{add_event.replace('.', '/')}/events",
+                    f'{add_event.replace(".", "/")}/events',
                     {self._handle_event_message_raw},
                     persist=False,
                 )
             for remove_event in validated_result.services_to_stop_listening_for_events:
                 self._control_plane_manager.remove_subscription_channel(
-                    f"{remove_event.replace('.', '/')}/events"
+                    f'{remove_event.replace(".", "/")}/events'
                 )
 
         # sending userspace messages without the callback is okay, we just won't get the response
@@ -431,7 +431,7 @@ class IntersectClient:
             payload=out_payload,
         )
         logger.debug(f'Send userspace message:\n{msg}')
-        channel = f"{params.destination.replace('.', '/')}/request"
+        channel = f'{params.destination.replace(".", "/")}/request'
         # WARNING: If both the Service and the Client drop, the Service will execute the command
         # but cannot communicate the response to the Client.
         # in experiment controllers or production, you'll want to set persist to True

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/config/shared.py

@@ -28,7 +28,7 @@ ControlProvider = Literal['mqtt3.1.1', 'amqp0.9.1']
 
 
 class HierarchyConfig(BaseModel):
-    """Configuration for registring this service in a system-of-system architecture."""
+    """Configuration for registering this service in a system-of-system architecture."""
 
     service: Annotated[str, Field(pattern=HIERARCHY_REGEX)]
     """

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/schema.py

@@ -48,11 +48,11 @@ def get_schema_from_capability_implementations(
 
     The generated schema is currently not a complete replica of the AsyncAPI spec. See https://www.asyncapi.com/docs/reference/specification/v2.6.0 for the complete specification.
     Some key differences:
-      - We utilize three custom fields: "capabilities", "events", and "status".
-      - "capabilities" contains a dictionary: the keys of this dictionary are capability names. The values are dictionaries with the "description" property being a string which describes the capability,
-        and a "channels" property which more closely follows the AsyncAPI specification of the top-level value "channels".
-      - "events" is a key-value dictionary: the keys represent the event name, the values represent the associated schema of the event type. Events are currently shared across all capabilities.
-      - "status" will have a value of the status schema - if no status has been defined, a null schema is used.
+    - We utilize three custom fields: "capabilities", "events", and "status".
+    - "capabilities" contains a dictionary: the keys of this dictionary are capability names. The values are dictionaries with the "description" property being a string which describes the capability,
+    and a "channels" property which more closely follows the AsyncAPI specification of the top-level value "channels".
+    - "events" is a key-value dictionary: the keys represent the event name, the values represent the associated schema of the event type. Events are currently shared across all capabilities.
+    - "status" will have a value of the status schema - if no status has been defined, a null schema is used.
 
     Params:
       - capability_types - list of classes (not objects) of capabilities. We do not require capabilities to be instantiated here, in case the instantiation of a capability has external dependencies.

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/service.py

@@ -17,6 +17,7 @@ Most useful definitions and typings will be found in the service_definitions mod
 from __future__ import annotations
 
 import time
+from collections import defaultdict
 from threading import Lock
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Callable, Literal, Union
@@ -40,7 +41,10 @@ from ._internal.data_plane.data_plane_manager import DataPlaneManager
 from ._internal.exceptions import IntersectApplicationError, IntersectError
 from ._internal.interfaces import IntersectEventObserver
 from ._internal.logger import logger
-from ._internal.messages.event import create_event_message
+from ._internal.messages.event import (
+    create_event_message,
+    deserialize_and_validate_event_message,
+)
 from ._internal.messages.lifecycle import LifecycleType, create_lifecycle_message
 from ._internal.messages.userspace import (
     UserspaceMessage,
@@ -52,19 +56,24 @@ from ._internal.stoppable_thread import StoppableThread
 from ._internal.utils import die
 from ._internal.version_resolver import resolve_user_version
 from .capability.base import IntersectBaseCapabilityImplementation
+from .client_callback_definitions import (
+    INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,  # noqa: TC001 (runtime-checked-annotation)
+)
 from .config.service import IntersectServiceConfig
+from .config.shared import HierarchyConfig
 from .core_definitions import IntersectDataHandler, IntersectMimeType
 from .service_callback_definitions import (
-    INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,  # noqa: TCH001 (runtime-checked annotation)
+    INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,  # noqa: TC001 (runtime-checked annotation)
 )
 from .shared_callback_definitions import (
-    INTERSECT_JSON_VALUE,  # noqa: TCH001 (runtime-checked annotation)
-    IntersectDirectMessageParams,  # noqa: TCH001 (runtime-checked annotation)
+    INTERSECT_JSON_VALUE,  # noqa: TC001 (runtime-checked annotation)
+    IntersectDirectMessageParams,  # noqa: TC001 (runtime-checked annotation)
 )
 from .version import version_string
 
 if TYPE_CHECKING:
     from ._internal.function_metadata import FunctionMetadata
+    from .config.shared import HierarchyConfig
 
 
 @final
@@ -241,7 +250,9 @@ class IntersectService(IntersectEventObserver):
         self._status_retrieval_fn: Callable[[], bytes] = (
             (
                 lambda: status_type_adapter.dump_json(
-                    getattr(status_fn_capability, status_fn_name)(), by_alias=True, warnings='error'
+                    getattr(status_fn_capability, status_fn_name)(),
+                    by_alias=True,
+                    warnings='error',
                 )
             )
             if status_type_adapter and status_fn_name
@@ -255,25 +266,49 @@ class IntersectService(IntersectEventObserver):
         self._external_requests: dict[str, IntersectService._ExternalRequest] = {}
         self._external_request_ctr = 0
 
+        self._svc2svc_events: defaultdict[
+            str, defaultdict[str, set[INTERSECT_CLIENT_EVENT_CALLBACK_TYPE]]
+        ] = defaultdict(lambda: defaultdict(set))
+        """
+        tree of other service events we're subscribed to, and what we need to call when we get an event
+
+        i.e.
+
+        {
+          "org.fac.sys1.subsys.service": {
+            "event_name_1": [
+              # user_function_1,
+              # user_function_2
+            ]
+          }
+        }
+        """
+
         self._startup_messages: list[
-            tuple[IntersectDirectMessageParams, INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None]
+            tuple[
+                IntersectDirectMessageParams,
+                INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None,
+            ]
         ] = []
         self._resend_startup_messages = True
         self._sent_startup_messages = False
 
         self._shutdown_messages: list[
-            tuple[IntersectDirectMessageParams, INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None]
+            tuple[
+                IntersectDirectMessageParams,
+                INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None,
+            ]
         ] = []
 
         self._data_plane_manager = DataPlaneManager(self._hierarchy, config.data_stores)
         # we PUBLISH messages on this channel
-        self._lifecycle_channel_name = f"{config.hierarchy.hierarchy_string('/')}/lifecycle"
+        self._lifecycle_channel_name = f'{config.hierarchy.hierarchy_string("/")}/lifecycle'
         # we PUBLISH event messages on this channel
-        self._events_channel_name = f"{config.hierarchy.hierarchy_string('/')}/events"
+        self._events_channel_name = f'{config.hierarchy.hierarchy_string("/")}/events'
         # we SUBSCRIBE to messages on this channel to receive requests
-        self._service_channel_name = f"{config.hierarchy.hierarchy_string('/')}/request"
+        self._service_channel_name = f'{config.hierarchy.hierarchy_string("/")}/request'
         # we SUBSCRIBE to messages on this channel to receive responses
-        self._client_channel_name = f"{config.hierarchy.hierarchy_string('/')}/response"
+        self._client_channel_name = f'{config.hierarchy.hierarchy_string("/")}/response'
 
         self._control_plane_manager = ControlPlaneManager(
             control_configs=config.brokers,
@@ -323,7 +358,8 @@ class IntersectService(IntersectEventObserver):
         # Start the status thread if it doesn't already exist
         if self._status_thread is None:
             self._status_thread = StoppableThread(
-                target=self._status_ticker, name=f'IntersectService_{self._uuid}_status_thread'
+                target=self._status_ticker,
+                name=f'IntersectService_{self._uuid}_status_thread',
             )
             self._status_thread.start()
 
@@ -483,7 +519,10 @@ class IntersectService(IntersectEventObserver):
     def add_startup_messages(
         self,
         messages: list[
-            tuple[IntersectDirectMessageParams, INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None]
+            tuple[
+                IntersectDirectMessageParams,
+                INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None,
+            ]
         ],
     ) -> None:
         """Add request messages to send out to various microservices when this service starts.
@@ -497,7 +536,10 @@ class IntersectService(IntersectEventObserver):
     def add_shutdown_messages(
         self,
         messages: list[
-            tuple[IntersectDirectMessageParams, INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None]
+            tuple[
+                IntersectDirectMessageParams,
+                INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None,
+            ]
         ],
     ) -> None:
         """Add request messages to send out to various microservices on shutdown.
@@ -508,6 +550,67 @@ class IntersectService(IntersectEventObserver):
         """
         self._shutdown_messages.extend(messages)
 
+    @validate_call(config=ConfigDict(revalidate_instances='always'))
+    def register_event(
+        self,
+        service: HierarchyConfig,
+        event_name: str,
+        response_handler: INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,
+    ) -> None:
+        """Begin subscribing to events from a different Service.
+
+        Params:
+          - service: HierarchyConfig of the service we want to talk to
+          - event_name: name of event to subscribe to
+          - response_handler: callback for how to handle the reception of an event
+        """
+        hierarchy = service.hierarchy_string('.')
+        self._svc2svc_events[hierarchy][event_name].add(response_handler)
+
+        self._control_plane_manager.add_subscription_channel(
+            f'{service.hierarchy_string("/")}/events',
+            {self._svc2svc_event_callback},
+            persist=True,
+        )
+
+    def _svc2svc_event_callback(self, raw: bytes) -> None:
+        """Callback received when this service gets an event from another service.
+
+        Deserializes and validates an EventMessage, will call a userspace function accordingly.
+        """
+        try:
+            message = deserialize_and_validate_event_message(raw)
+        except ValidationError as e:
+            logger.warning(
+                "Invalid message received from another service's events channel, ignoring. Full message:\n{}",
+                e,
+            )
+            return
+        logger.debug('Received event message:\n{}', message)
+        try:
+            payload = GENERIC_MESSAGE_SERIALIZER.validate_json(
+                self._data_plane_manager.incoming_message_data_handler(message)
+            )
+        except ValidationError as e:
+            logger.warning(
+                'Invalid payload message received as an event, ignoring. Full message: {}',
+                e,
+            )
+            return
+        source = message['headers']['source']
+        event_name = message['headers']['event_name']
+        for user_callback in self._svc2svc_events[source][event_name]:
+            try:
+                user_callback(source, message['operationId'], event_name, payload)
+            except Exception as e:  # noqa: BLE001 (need to catch any possible user exception)
+                logger.warning(
+                    '!!! INTERSECT: event callback function "%s" produced uncaught exception when handling event "%s" from "%s"',
+                    user_callback.__name__,
+                    event_name,
+                    source,
+                )
+                logger.warning(e)
+
     @validate_call(config=ConfigDict(revalidate_instances='always'))
     def create_external_request(
         self,
@@ -518,7 +621,7 @@ class IntersectService(IntersectEventObserver):
         """Create an external request that we'll send to a different Service.
 
         Params:
-          - request: the request we want to send out, encapsulated as an IntersectClientMessageParams object
+          - request: the request we want to send out, encapsulated as an IntersectDirectMessageParams object
           - response_handler: optional callback for how we want to handle the response from this request.
           - timeout: optional value for how long we should wait on the request, in seconds (default: 300 seconds)
 
@@ -625,7 +728,7 @@ class IntersectService(IntersectEventObserver):
                     'error' if response_msg['headers']['has_error'] else 'userspace',
                     response_msg,
                 )
-                response_channel = f"{message['headers']['source'].replace('.', '/')}/response"
+                response_channel = f'{message["headers"]["source"].replace(".", "/")}/response'
                 # Persistent userspace messages may be useful for orchestration.
                 # Persistence will not hurt anything.
                 self._control_plane_manager.publish_message(
@@ -796,7 +899,7 @@ class IntersectService(IntersectEventObserver):
             message_id=request_id,
         )
         logger.debug(f'Sending client message:\n{msg}')
-        request_channel = f"{params.destination.replace('.', '/')}/request"
+        request_channel = f'{params.destination.replace(".", "/")}/request'
         self._control_plane_manager.publish_message(request_channel, msg, persist=True)
         return True
 
@@ -923,8 +1026,7 @@ class IntersectService(IntersectEventObserver):
             event_name=event_name,
             payload=response_payload,
         )
-        # Event messages are meant to be short-lived and should not persist.
-        self._control_plane_manager.publish_message(self._events_channel_name, msg, persist=False)
+        self._control_plane_manager.publish_message(self._events_channel_name, msg, persist=True)
 
     def _make_error_message(
         self, error_string: str, original_message: UserspaceMessage

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/version.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 from ._internal.version import strip_version_metadata
 
 # may include build metadata
-__version__ = '0.8.0'
+__version__ = '0.8.1'
 
 version_string = strip_version_metadata(__version__)
 """

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/e2e/test_examples.py

@@ -143,3 +143,10 @@ def test_example_4_service_to_service():
         'Received Response from Service 2: Acknowledging service one text -> Kicking off the example!\n'
         'Received Second Response from Service 2: Acknowledging service one text -> Final Verification\n'
     )
+
+
+def test_example_4_service_to_service_events():
+    assert run_example_test('4_service_to_service_events') == (
+        'From event "internal_service_event", received message "not_feeling_creative" from "example-organization.example-facility.example-system.example-subsystem.internal-service"\n'
+        'From event "internal_service_event", received message "not_feeling_creative" from "example-organization.example-facility.example-system.example-subsystem.internal-service"\n'
+    )

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/fixtures/example_schema.py

@@ -28,16 +28,6 @@ from typing import (
 from uuid import UUID
 
 from annotated_types import Ge, Le
-from intersect_sdk import (
-    HierarchyConfig,
-    IntersectBaseCapabilityImplementation,
-    IntersectDataHandler,
-    IntersectEventDefinition,
-    IntersectMimeType,
-    intersect_event,
-    intersect_message,
-    intersect_status,
-)
 from pydantic import (
     BaseModel,
     Field,
@@ -49,6 +39,17 @@ from pydantic import (
 from pydantic_core import PydanticCustomError, Url
 from typing_extensions import Annotated, TypeAliasType, TypedDict
 
+from intersect_sdk import (
+    HierarchyConfig,
+    IntersectBaseCapabilityImplementation,
+    IntersectDataHandler,
+    IntersectEventDefinition,
+    IntersectMimeType,
+    intersect_event,
+    intersect_message,
+    intersect_status,
+)
+
 FAKE_HIERARCHY_CONFIG = HierarchyConfig(
     organization='test',
     facility='test',
@@ -450,7 +451,7 @@ class DummyCapabilityImplementation(IntersectBaseCapabilityImplementation):
         self.update_status('test_decimal')
         decimal.getcontext().prec = 20
         decimal.getcontext().rounding = decimal.ROUND_HALF_UP
-        return input_value / Decimal(3.14159265358979323846)
+        return input_value / Decimal('3.14159265358979323846')
 
     @intersect_message(
         response_content_type=IntersectMimeType.STRING,

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/integration/test_return_type_mismatch.py

@@ -28,7 +28,6 @@ from intersect_sdk._internal.messages.userspace import (
     create_userspace_message,
     deserialize_and_validate_userspace_message,
 )
-
 from tests.fixtures.example_schema import FAKE_HIERARCHY_CONFIG
 
 # FIXTURE #############################

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/integration/test_service.py

@@ -31,7 +31,6 @@ from intersect_sdk._internal.messages.userspace import (
     create_userspace_message,
     deserialize_and_validate_userspace_message,
 )
-
 from tests.fixtures.example_schema import FAKE_HIERARCHY_CONFIG, DummyCapabilityImplementation
 
 # HELPERS #############################

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/unit/test_annotations.py

@@ -1,4 +1,6 @@
 import pytest
+from pydantic import ValidationError
+
 from intersect_sdk import (
     IntersectBaseCapabilityImplementation,
     IntersectEventDefinition,
@@ -6,7 +8,6 @@ from intersect_sdk import (
     intersect_message,
     intersect_status,
 )
-from pydantic import ValidationError
 
 
 # this should immediately fail when trying to define the class itself
@@ -62,7 +63,7 @@ def test_incorrect_intersect_event_annotations():
     assert len(errors) == 1
     assert {'type': 'missing', 'loc': ('event_type',)} in errors
 
-    # special case: we have a custom vaildator for event_type which fails on some common instantiations
+    # special case: we have a custom validator for event_type which fails on some common instantiations
     with pytest.raises(ValidationError) as ex:
 
         class BadEventArgs4(IntersectBaseCapabilityImplementation):

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/unit/test_base_capability_implementation.py

@@ -4,6 +4,7 @@ from typing import Any
 from uuid import UUID, uuid4
 
 import pytest
+
 from intersect_sdk import (
     INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
     IntersectBaseCapabilityImplementation,

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/unit/test_config.py

@@ -1,4 +1,6 @@
 import pytest
+from pydantic import TypeAdapter, ValidationError
+
 from intersect_sdk import (
     ControlPlaneConfig,
     DataStoreConfig,
@@ -8,7 +10,6 @@ from intersect_sdk import (
     IntersectClientConfig,
     IntersectServiceConfig,
 )
-from pydantic import TypeAdapter, ValidationError
 
 # TESTS #####################
 

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/unit/test_invalid_schema_runtime.py

@@ -6,6 +6,7 @@ check that service configuration is valid.
 """
 
 import pytest
+
 from intersect_sdk import (
     ControlPlaneConfig,
     IntersectBaseCapabilityImplementation,

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/unit/test_lifecycle_message.py

@@ -6,13 +6,14 @@ import datetime
 import uuid
 
 import pytest
+from pydantic import ValidationError
+
 from intersect_sdk import version_string
 from intersect_sdk._internal.messages.lifecycle import (
     LifecycleType,
     create_lifecycle_message,
     deserialize_and_validate_lifecycle_message,
 )
-from pydantic import ValidationError
 
 
 def test_valid_lifecycle_message_deserializes():

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/unit/test_schema_invalids.py

@@ -21,6 +21,9 @@ from typing import Any, Dict, FrozenSet, Generator, List, NamedTuple, Set, Tuple
 
 import pytest
 from annotated_types import Gt
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated, TypeAliasType, TypedDict
+
 from intersect_sdk import (
     HierarchyConfig,
     IntersectBaseCapabilityImplementation,
@@ -32,8 +35,6 @@ from intersect_sdk import (
     intersect_message,
     intersect_status,
 )
-from pydantic import BaseModel, Field
-from typing_extensions import Annotated, TypeAliasType, TypedDict
 
 # HELPERS #########################
 
@@ -132,12 +133,12 @@ def test_disallow_unparsable_annotation(caplog: pytest.LogCaptureFixture):
             three: str
 
         @intersect_message()
-        def cant_parse_annotation(self, unparseable: PydanticUnparsableInner) -> None: ...
+        def cant_parse_annotation(self, unparsable: PydanticUnparsableInner) -> None: ...
 
     with pytest.raises(SystemExit):
         get_schema_helper([PydanticUnparsable])
     assert (
-        "On capability 'PydanticUnparsable', parameter 'unparseable' type annotation" in caplog.text
+        "On capability 'PydanticUnparsable', parameter 'unparsable' type annotation" in caplog.text
     )
     assert "on function 'cant_parse_annotation' is invalid" in caplog.text
 
@@ -158,7 +159,7 @@ def test_disallow_object_typing(caplog: pytest.LogCaptureFixture):
 
 def test_disallow_object_subtyping(caplog: pytest.LogCaptureFixture):
     # should fail because return type has a subtyping object (dynamic typing)
-    # note that 'object' is evalutated exactly like it is as a root type
+    # note that 'object' is evaluated exactly like it is as a root type
     class MockObjectSubtype(IntersectBaseCapabilityImplementation):
         intersect_sdk_capability_name = 'unused'
 
@@ -456,7 +457,7 @@ def test_disallow_empty_dataclass(caplog: pytest.LogCaptureFixture):
 
 
 def test_disallow_ambiguous_typealiastype(caplog: pytest.LogCaptureFixture):
-    # should fail because the TypeVar is ambigous and would resolve to "Any"
+    # should fail because the TypeVar is ambiguous and would resolve to "Any"
     class AmbiguousTypeAliasType(IntersectBaseCapabilityImplementation):
         intersect_sdk_capability_name = 'unused'
         T = TypeVar('T')
@@ -975,4 +976,4 @@ def test_multiple_status_functions_across_capabilities(caplog: pytest.LogCapture
 
     with pytest.raises(SystemExit):
         get_schema_helper([CapabilityName1, CapabilityName2])
-    assert 'Only one capabilitiy may have an @intersect_status function' in caplog.text
+    assert 'Only one capability may have an @intersect_status function' in caplog.text

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/unit/test_schema_valid.py

@@ -10,7 +10,6 @@ from intersect_sdk._internal.constants import (
 )
 from intersect_sdk._internal.schema import get_schema_and_functions_from_capability_implementations
 from intersect_sdk.schema import get_schema_from_capability_implementations
-
 from tests.fixtures.example_schema import (
     FAKE_HIERARCHY_CONFIG,
     DummyCapabilityImplementation,

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/unit/test_userspace_message.py

@@ -6,12 +6,13 @@ import datetime
 import uuid
 
 import pytest
+from pydantic import ValidationError
+
 from intersect_sdk import IntersectDataHandler, IntersectMimeType, version_string
 from intersect_sdk._internal.messages.userspace import (
     create_userspace_message,
     deserialize_and_validate_userspace_message,
 )
-from pydantic import ValidationError
 
 
 def test_valid_userspace_message_deserializes():

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/tests/unit/test_version_resolver.py

@@ -14,6 +14,7 @@ import datetime
 from uuid import uuid4
 
 import pytest
+
 from intersect_sdk import (
     IntersectDataHandler,
     IntersectMimeType,

{intersect_sdk-0.8.0 → intersect_sdk-0.8.1}/src/intersect_sdk/__init__.py

@@ -43,31 +43,31 @@ from .shared_callback_definitions import (
 from .version import __version__, version_info, version_string
 
 __all__ = [
-    'IntersectDataHandler',
-    'IntersectEventDefinition',
-    'IntersectMimeType',
-    'intersect_event',
-    'intersect_message',
-    'intersect_status',
-    'get_schema_from_capability_implementations',
-    'IntersectService',
-    'IntersectClient',
-    'IntersectClientCallback',
-    'IntersectDirectMessageParams',
-    'INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE',
     'INTERSECT_CLIENT_EVENT_CALLBACK_TYPE',
+    'INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE',
     'INTERSECT_JSON_VALUE',
     'INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE',
-    'IntersectBaseCapabilityImplementation',
-    'default_intersect_lifecycle_loop',
-    'IntersectClientConfig',
-    'IntersectServiceConfig',
-    'HierarchyConfig',
     'ControlPlaneConfig',
     'ControlProvider',
     'DataStoreConfig',
     'DataStoreConfigMap',
+    'HierarchyConfig',
+    'IntersectBaseCapabilityImplementation',
+    'IntersectClient',
+    'IntersectClientCallback',
+    'IntersectClientConfig',
+    'IntersectDataHandler',
+    'IntersectDirectMessageParams',
+    'IntersectEventDefinition',
+    'IntersectMimeType',
+    'IntersectService',
+    'IntersectServiceConfig',
     '__version__',
+    'default_intersect_lifecycle_loop',
+    'get_schema_from_capability_implementations',
+    'intersect_event',
+    'intersect_message',
+    'intersect_status',
     'version_info',
     'version_string',
 ]