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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: intersect-sdk
-Version: 0.7.0
+Version: 0.8.0
 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>
@@ -10,6 +10,10 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Project-URL: Homepage, https://github.com/INTERSECT-SDK/python-sdk/
+Project-URL: Changelog, https://github.com/INTERSECT-SDK/python-sdk/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://intersect-python-sdk.readthedocs.io/en/latest/
+Project-URL: Issues, https://github.com/INTERSECT-SDK/python-sdk/issues
 Requires-Python: <4.0,>=3.8.10
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: retrying<2.0.0,>=1.3.4

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

@@ -35,11 +35,17 @@ dependencies = [
     "jsonschema[format-nongpl]>=4.21.1",
     "eval-type-backport>=0.1.3;python_version<'3.10'",
 ]
-version = "0.7.0"
+version = "0.8.0"
 
 [project.license]
 text = "BSD-3-Clause"
 
+[project.urls]
+Homepage = "https://github.com/INTERSECT-SDK/python-sdk/"
+Changelog = "https://github.com/INTERSECT-SDK/python-sdk/blob/main/CHANGELOG.md"
+Documentation = "https://intersect-python-sdk.readthedocs.io/en/latest/"
+Issues = "https://github.com/INTERSECT-SDK/python-sdk/issues"
+
 [project.optional-dependencies]
 amqp = [
     "pika>=1.3.2,<2.0.0",
@@ -52,7 +58,7 @@ docs = [
 [tool.pdm.dev-dependencies]
 lint = [
     "pre-commit>=3.3.1",
-    "ruff>=0.4.2",
+    "ruff==0.5.7",
     "mypy>=1.10.0",
     "types-paho-mqtt>=1.6.0.20240106",
 ]
@@ -214,11 +220,15 @@ addopts = "-ra"
 [tool.coverage.report]
 omit = [
     "*__init__*",
+    "*/discovery_service.py",
 ]
 exclude_also = [
     "pragma: no-cover",
     "if (typing\\\\.)?TYPE_CHECKING:",
     "@(abc\\\\.)?abstractmethod",
+    "class .*\\bProtocol\\):",
+    "raise NotImplementedError",
+    "except.* ImportError",
 ]
 
 [build-system]

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

@@ -19,12 +19,13 @@ from .config.client import IntersectClientConfig
 from .config.service import IntersectServiceConfig
 from .config.shared import (
     ControlPlaneConfig,
+    ControlProvider,
     DataStoreConfig,
     DataStoreConfigMap,
     HierarchyConfig,
 )
 from .core_definitions import IntersectDataHandler, IntersectMimeType
-from .schema import get_schema_from_capability_implementation
+from .schema import get_schema_from_capability_implementations
 from .service import IntersectService
 from .service_callback_definitions import (
     INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
@@ -48,7 +49,7 @@ __all__ = [
     'intersect_event',
     'intersect_message',
     'intersect_status',
-    'get_schema_from_capability_implementation',
+    'get_schema_from_capability_implementations',
     'IntersectService',
     'IntersectClient',
     'IntersectClientCallback',
@@ -63,6 +64,7 @@ __all__ = [
     'IntersectServiceConfig',
     'HierarchyConfig',
     'ControlPlaneConfig',
+    'ControlProvider',
     'DataStoreConfig',
     'DataStoreConfigMap',
     '__version__',

{intersect_sdk-0.7.0 → intersect_sdk-0.8.0}/src/intersect_sdk/_internal/control_plane/control_plane_manager.py

@@ -66,7 +66,7 @@ class ControlPlaneManager:
         """
         if control_configs == 'discovery':
             msg = 'Discovery service not implemented yet'
-            raise ValueError(msg)
+            raise NotImplementedError(msg)
         self._control_providers = [
             create_control_provider(config, self.get_subscription_channels)
             for config in control_configs

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

@@ -36,12 +36,14 @@ class IntersectEventObserver(ABC):
         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.
 
         Params:
           - request: the request we want to send out, encapsulated as an IntersectClientMessageParams 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)
 
         Returns:
           - generated RequestID associated with your request

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import inspect
+import re
 from enum import Enum
 from typing import (
     TYPE_CHECKING,
@@ -55,6 +56,9 @@ For networking types, https://docs.pydantic.dev/latest/api/networks/
 For a complete reference, https://docs.pydantic.dev/latest/concepts/conversion_table
 """
 
+CAPABILITY_NAME_PATTERN = r'[\w-]+'
+"""Regular expression we use to check valid capability names. Since capability namespacing only occurs in services, we can be more lax than for how we name services/systems/etc. """
+
 
 class _FunctionAnalysisResult(NamedTuple):
     """private class generated from static analysis of function."""
@@ -302,7 +306,7 @@ def _add_events(
 
 
 def _introspection_baseline(
-    capability: IntersectBaseCapabilityImplementation,
+    capability: type[IntersectBaseCapabilityImplementation],
     excluded_data_handlers: set[IntersectDataHandler],
 ) -> tuple[
     dict[Any, Any],  # $defs for schemas (common)
@@ -332,8 +336,9 @@ def _introspection_baseline(
     function_map = {}
     event_metadatas: dict[str, EventMetadata] = {}
 
-    cap_name = capability.capability_name
-    status_func, response_funcs, event_funcs = _get_functions(type(capability))
+    # capability_name should have already been checked before calling this function
+    cap_name = capability.intersect_sdk_capability_name
+    status_func, response_funcs, event_funcs = _get_functions(capability)
 
     # parse functions
     for class_name, name, method, min_params in response_funcs:
@@ -439,7 +444,7 @@ def _introspection_baseline(
 
         # final function mapping
         function_map[public_name] = FunctionMetadata(
-            type(capability),
+            capability,
             method,
             function_cache_request_adapter,
             function_cache_response_adapter,
@@ -477,7 +482,7 @@ def _introspection_baseline(
     if status_fn_type_adapter and status_fn and status_fn_name:
         public_status_name = f'{cap_name}.{status_fn_name}'
         function_map[public_status_name] = FunctionMetadata(
-            type(capability),
+            capability,
             status_fn,
             None,
             status_fn_type_adapter,
@@ -494,52 +499,78 @@ def _introspection_baseline(
 
 
 def get_schema_and_functions_from_capability_implementations(
-    capabilities: list[IntersectBaseCapabilityImplementation],
+    capabilities: list[type[IntersectBaseCapabilityImplementation]],
     service_name: HierarchyConfig,
     excluded_data_handlers: set[IntersectDataHandler],
 ) -> tuple[
     dict[str, Any],
     dict[str, FunctionMetadata],
     dict[str, EventMetadata],
-    IntersectBaseCapabilityImplementation | None,
+    type[IntersectBaseCapabilityImplementation] | None,
     str | None,
     TypeAdapter[Any] | None,
 ]:
     """This function generates the core AsyncAPI schema, and the core mappings which are derived from the schema.
 
+    Importantly, this function needs to be able to work with static classes, and not instances. This is because users
+    should be free to define their constructor as they wish, with any arbitrary parameters. Users should also be allowed
+    to execute whatever code they'd like in their constructor, such as establishing remote connections. At the same time,
+    we want to allow users to quickly generate an INTERSECT schema, without having to worry about any dependencies from their constructor code.
+
     In-depth introspection is handled later on.
     """
-    capability_type_docs: str = ''
-    status_function_cap: IntersectBaseCapabilityImplementation | None = None
+    status_function_cap: type[IntersectBaseCapabilityImplementation] | None = None
     status_function_name: str | None = None
     status_function_schema: dict[str, Any] | None = None
     status_function_adapter: TypeAdapter[Any] | None = None
-    schemas: dict[Any, Any] = {}
-    channels: dict[str, dict[str, dict[str, Any]]] = {}  # endpoint schemas
+    shared_schemas: dict[Any, Any] = {}  # "shared" schemas which get put in $defs
+    capability_schemas: dict[str, Any] = {}  # endpoint schemas
     function_map: dict[str, FunctionMetadata] = {}  # endpoint functionality
-    events: dict[str, Any] = {}  # event schemas
+    events: dict[
+        str, Any
+    ] = {}  # event schemas - TODO event names are currently "global" across capabilities, may want to change this?
     event_map: dict[str, EventMetadata] = {}  # event functionality
-    for capability in capabilities:
-        capability_type: type[IntersectBaseCapabilityImplementation] = type(capability)
-        if capability_type.__doc__:
-            capability_type_docs += inspect.cleandoc(capability_type.__doc__) + '\n'
+    for capability_type in capabilities:
+        cap_name = capability_type.intersect_sdk_capability_name
+        if (
+            not cap_name
+            or not isinstance(cap_name, str)
+            or not re.fullmatch(CAPABILITY_NAME_PATTERN, cap_name)
+        ):
+            die(
+                f'Invalid intersect_sdk_capability_name on capability {capability_type.__name__} - must be a non-empty string with only alphanumeric characters and hyphens (you must explicitly set this, and do so on the class and not an instance).'
+            )
+        if cap_name in capability_schemas:
+            die(
+                f'Invalid intersect_sdk_capability_name on capability {capability_type.__name__} - value "{cap_name}" is a duplicate and has already appeared in another capability.'
+            )
+
         (
-            cap_schemas,
+            subschemas,
             (cap_status_fn_name, cap_status_schema, cap_status_type_adapter),
-            cap_channels,
+            cap_functions,
             cap_function_map,
             cap_events,
             cap_event_map,
-        ) = _introspection_baseline(capability, excluded_data_handlers)
+        ) = _introspection_baseline(capability_type, excluded_data_handlers)
 
         if cap_status_fn_name and cap_status_schema and cap_status_type_adapter:
-            status_function_cap = capability
+            if status_function_name is not None:
+                # TODO may want to change this later
+                die('Only one capabilitiy may have an @intersect_status function')
+            status_function_cap = capability_type
             status_function_name = cap_status_fn_name
             status_function_schema = cap_status_schema
             status_function_adapter = cap_status_type_adapter
 
-        schemas.update(cap_schemas)
-        channels.update(cap_channels)
+        shared_schemas.update(subschemas)
+        # NOTE: we will still add the capability to the schema, even if there are no @intersect_message annotations
+        capability_schemas[cap_name] = {
+            'channels': cap_functions,
+        }
+        # add documentation for the capabilities
+        if capability_type.__doc__:
+            capability_schemas[cap_name]['description'] = inspect.cleandoc(capability_type.__doc__)
         function_map.update(cap_function_map)
         events.update(cap_events)
         event_map.update(cap_event_map)
@@ -549,15 +580,17 @@ def get_schema_and_functions_from_capability_implementations(
         'x-intersect-version': version_string,
         'info': {
             'title': service_name.hierarchy_string('.'),
+            'description': 'INTERSECT schema',
             'version': '0.0.0',  # NOTE: this will be modified by INTERSECT CORE, users do not manage their schema versions
         },
         # applies to how an incoming message payload will be parsed.
         # can be changed per channel
         'defaultContentType': 'application/json',
-        'channels': channels,
+        'capabilities': capability_schemas,
         'events': events,
+        'status': status_function_schema if status_function_schema else {'type': 'null'},
         'components': {
-            'schemas': schemas,
+            'schemas': shared_schemas,
             'messageTraits': {
                 # this is where we can define our message headers
                 'commonHeaders': {
@@ -574,21 +607,6 @@ def get_schema_and_functions_from_capability_implementations(
         },
     }
 
-    if capability_type_docs != '':
-        asyncapi_spec['info']['description'] = capability_type_docs  # type: ignore[index]
-
-    if status_function_schema:
-        asyncapi_spec['status'] = status_function_schema
-
-    """
-    TODO - might want to include these fields
-    "securitySchemes": {},
-    "operationTraits": {},
-    "externalDocumentation": {
-        "url": "https://example.com",  # REQUIRED
-    },
-    """
-
     return (
         asyncapi_spec,
         function_map,

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

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import inspect
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, ClassVar
 
 from typing_extensions import final
 
@@ -29,16 +29,23 @@ class IntersectBaseCapabilityImplementation:
     you MUST call `super.__init__()` .
     """
 
+    intersect_sdk_capability_name: ClassVar[str] = ''
+    """The advertised name of your capability, as provided by the extension of this class.
+
+    You MUST override this value per class and set it as a string - it's ideal to do so on the class itself for static analysis purposes,
+    though as long as this variable has been set before the capability is added to the Service,
+    everything should work fine.
+
+    Each capability within a Service MUST have a unique capability name.
+    This value should not be modified once the capability has been added to the Service.
+    This value should ONLY contain alphanumeric characters, hyphens, and underscores.
+    """
+
     def __init__(self) -> None:
         """This constructor just sets up observers.
 
         NOTE: If you write your own constructor, you MUST call `super.__init__()` inside of it. The Service will throw an error if you don't.
         """
-        self._capability_name: str = 'InvalidCapability'
-        """
-        The advertised name for the capability, as opposed to the implementation class name
-        """
-
         self.__intersect_sdk_observers__: list[IntersectEventObserver] = []
         """
         INTERNAL USE ONLY.
@@ -63,15 +70,6 @@ class IntersectBaseCapabilityImplementation:
             msg = f"{cls.__name__}: Attempted to override a reserved INTERSECT-SDK function (don't start your function names with '_intersect_sdk_' or 'intersect_sdk_')"
             raise RuntimeError(msg)
 
-    @property
-    def capability_name(self) -> str:
-        """The advertised name for the capability provided by this implementation."""
-        return self._capability_name
-
-    @capability_name.setter
-    def capability_name(self, cname: str) -> None:
-        self._capability_name = cname
-
     @final
     def _intersect_sdk_register_observer(self, observer: IntersectEventObserver) -> None:
         """INTERNAL USE ONLY."""
@@ -91,7 +89,9 @@ class IntersectBaseCapabilityImplementation:
         register the event on the @intersect_event decorator. The @intersect_event annotation will be IGNORED if you place it
         after an @intersect_message annotation; its intended use is for threaded functions you start from the capability.
 
-        You MAY NOT emit an event from any function called from an @intersect_status decorated function.
+        Do NOT call this function from:
+          - any function called from an @intersect_status decorated function
+          - outside of the capability class (for example: capability_instance.intersect_sdk_emit_event(...) will not work). Create a function in the capability, decorate it with @intersect_event, and call that function.
 
         params:
           event_name: the type of event you are emitting. Note that you must advertise the event in your "entrypoint" function
@@ -133,12 +133,14 @@ class IntersectBaseCapabilityImplementation:
         self,
         request: IntersectDirectMessageParams,
         response_handler: INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None = None,
+        timeout: float = 300.0,
     ) -> list[UUID]:
         """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
           - 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)
 
         Returns:
           - list of generated RequestIDs associated with your request. Note that for almost all use cases,
@@ -148,6 +150,6 @@ class IntersectBaseCapabilityImplementation:
           - pydantic.ValidationError - if the request parameter isn't valid
         """
         return [
-            observer.create_external_request(request, response_handler)
+            observer.create_external_request(request, response_handler, timeout)
             for observer in self.__intersect_sdk_observers__
         ]

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

@@ -35,7 +35,6 @@ from ._internal.messages.userspace import (
     create_userspace_message,
     deserialize_and_validate_userspace_message,
 )
-from ._internal.stoppable_thread import StoppableThread
 from ._internal.utils import die, send_os_signal
 from ._internal.version_resolver import resolve_user_version
 from .client_callback_definitions import (
@@ -121,9 +120,6 @@ class IntersectClient:
             organization=config.organization,
         )
 
-        self._heartbeat_thread: StoppableThread | None = None
-        self._heartbeat = 0.0
-
         self._data_plane_manager = DataPlaneManager(self._hierarchy, config.data_stores)
         self._control_plane_manager = ControlPlaneManager(
             control_configs=config.brokers,
@@ -176,15 +172,6 @@ class IntersectClient:
         # and has nothing to do with the Service at all.
         time.sleep(1.0)
 
-        # start the heartbeat thread
-        if self._heartbeat_thread is None:
-            self._heartbeat = time.time()
-            self._heartbeat_thread = StoppableThread(
-                target=self._heartbeat_ticker,
-                name=f'IntersectClient_{uuid4()!s}_heartbeat_thread',
-            )
-            self._heartbeat_thread.start()
-
         if self._resend_initial_messages or not self._sent_initial_messages:
             for message in self._initial_messages:
                 self._send_userspace_message(message)
@@ -213,13 +200,6 @@ class IntersectClient:
         """
         logger.info(f'Client is shutting down (reason: {reason})')
 
-        # Stop listening to the heartbeat
-        if self._heartbeat_thread is not None:
-            self._heartbeat_thread.stop()
-            self._heartbeat_thread.join()
-            self._heartbeat_thread = None
-            self._heartbeat = 0.0
-
         self._control_plane_manager.disconnect()
 
         logger.info('Client shutdown complete')
@@ -249,7 +229,6 @@ class IntersectClient:
         if self._terminate_after_initial_messages:
             return
 
-        self._heartbeat = time.time()
         try:
             message = deserialize_and_validate_userspace_message(raw)
             logger.debug(f'Received userspace message:\n{message}')
@@ -330,7 +309,6 @@ class IntersectClient:
             # safety check in case we get messages back faster than we can send them
             return
 
-        self._heartbeat = time.time()
         try:
             message = deserialize_and_validate_event_message(raw)
             logger.debug(f'Received userspace message:\n{message}')
@@ -458,26 +436,3 @@ class IntersectClient:
         # but cannot communicate the response to the Client.
         # in experiment controllers or production, you'll want to set persist to True
         self._control_plane_manager.publish_message(channel, msg, persist=False)
-
-    # TODO - consider removing this entire concept
-    def _heartbeat_ticker(self) -> None:
-        """Separate thread which checks to see how long it has been since a broker message was received.
-
-        If a broker has been connected for 5 minutes without sending a message, prepare to terminate the application.
-        """
-        if self._heartbeat_thread:
-            self._heartbeat_thread.wait(300.0)
-            while not self._heartbeat_thread.stopped():
-                elapsed = time.time() - self._heartbeat
-                if elapsed > 300.0:
-                    # NOTE
-                    # This is by design. We explicitly don't want dangling clients
-                    # sucking up bandwidth on brokers. It could even be argued that we should
-                    # just call os.abort() here (this way so the Python application can't catch the SIGABRT),
-                    # but SIGTERM is the soundest to ensure graceful application shutdown.
-                    # However, graceful application shutdown is not as important for clients as it is for services...
-                    logger.warning(
-                        'Client has sat 5 minutes without sending or receiving any messages, exiting'
-                    )
-                    send_os_signal()
-                self._heartbeat_thread.wait(300.0)

{intersect_sdk-0.7.0 → intersect_sdk-0.8.0}/src/intersect_sdk/client_callback_definitions.py

@@ -3,13 +3,13 @@
 See shared_callback_definitions for additional typings which are also shared by service authors.
 """
 
-from typing import Callable, Dict, List, Optional, Union
+from typing import Callable, List, Optional
 
 from pydantic import BaseModel, ConfigDict, Field
-from typing_extensions import Annotated, TypeAlias, final
+from typing_extensions import Annotated, final
 
 from .constants import SYSTEM_OF_SYSTEM_REGEX
-from .shared_callback_definitions import IntersectDirectMessageParams
+from .shared_callback_definitions import INTERSECT_JSON_VALUE, IntersectDirectMessageParams
 
 
 @final
@@ -44,22 +44,6 @@ class IntersectClientCallback(BaseModel):
     model_config = ConfigDict(revalidate_instances='always')
 
 
-INTERSECT_JSON_VALUE: TypeAlias = Union[
-    List['INTERSECT_JSON_VALUE'],
-    Dict[str, 'INTERSECT_JSON_VALUE'],
-    str,
-    bool,
-    int,
-    float,
-    None,
-]
-"""
-This is a simple type representation of JSON as a Python object. INTERSECT will automatically deserialize service payloads into one of these types.
-
-(Pydantic has a similar type, "JsonValue", which should be used if you desire functionality beyond type hinting. This is strictly a type hint.)
-"""
-
-
 INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE = Callable[
     [str, str, bool, INTERSECT_JSON_VALUE],
     Optional[IntersectClientCallback],

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

@@ -24,6 +24,7 @@ The following commit tracks several issues with MINIO: https://code.ornl.gov/int
 """
 
 ControlProvider = Literal['mqtt3.1.1', 'amqp0.9.1']
+"""The type of broker we connect to."""
 
 
 class HierarchyConfig(BaseModel):

intersect_sdk-0.8.0/src/intersect_sdk/schema.py

@@ -0,0 +1,70 @@
+"""This module is responsible for generating the core interface definitions of any Service.
+
+There are two things to generate:
+
+###
+Schema
+###
+
+JSON schema advertises the interfaces to other systems. This is necessary for creating scientific campaigns, and the schema
+is extensible to other clients.
+
+Parts of the schema will be generated from users' own definitions. Functions are represented under "channels",
+while Pydantic models defined by users and used as request or response types in their functions will have their schemas generated here.
+
+There are also several parameters mainly for use by the central INTERSECT microservices, largely encapsulated from users.
+
+###
+Code Interface
+###
+
+When external systems send a message to this system, there are two important things in determining what executes: an operation id string,
+and a payload which can be serialized into an auto-validated object. The operation id string is what can be mapped into various function definitions.
+
+Users are able to define their response and request content-types, as well as their response data platform, for each exposed function (on the annotation).
+
+The SDK needs to be able to dynamically look up functions, validate the request structure and request parameters, and handle responses.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+from ._internal.schema import get_schema_and_functions_from_capability_implementations
+from .capability.base import IntersectBaseCapabilityImplementation
+
+if TYPE_CHECKING:
+    from .config.shared import HierarchyConfig
+
+
+def get_schema_from_capability_implementations(
+    capability_types: list[type[IntersectBaseCapabilityImplementation]],
+    hierarchy: HierarchyConfig,
+) -> dict[str, Any]:
+    """The goal of this function is to be able to generate a complete schema somewhat resembling the AsyncAPI spec 2.6.0 from a BaseModel class.
+
+    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.
+
+    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.
+      - hierarchy - the hierarchy configuration. This is currently only reflected in the title of the global schema.
+    """
+    if not all(issubclass(cap, IntersectBaseCapabilityImplementation) for cap in capability_types):
+        msg = 'get_schema_from_capability_implementations - not all provided values are valid capabilities (class must extend IntersectBaseCapabilityImplementation)'
+        raise RuntimeError(msg)
+
+    schemas, _, _, _, _, _ = get_schema_and_functions_from_capability_implementations(
+        capability_types,
+        hierarchy,
+        set(),  # assume all data handlers are configured if user is just checking their schema
+    )
+    return schemas