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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: intersect-sdk
-Version: 0.6.4
+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.6.4 → 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.6.4"
+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",
 ]
@@ -66,6 +72,7 @@ test = [
 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/"
@@ -162,6 +169,7 @@ max-complexity = 20
 max-args = 10
 max-branches = 20
 max-returns = 10
+max-statements = 75
 
 [tool.ruff.lint.extend-per-file-ignores]
 "__init__.py" = [
@@ -212,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.6.4 → intersect_sdk-0.8.0}/src/intersect_sdk/__init__.py

@@ -13,27 +13,33 @@ from .client import IntersectClient
 from .client_callback_definitions import (
     INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,
     INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE,
-    INTERSECT_JSON_VALUE,
     IntersectClientCallback,
-    IntersectClientMessageParams,
 )
 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,
+)
 from .service_definitions import (
     IntersectEventDefinition,
     intersect_event,
     intersect_message,
     intersect_status,
 )
+from .shared_callback_definitions import (
+    INTERSECT_JSON_VALUE,
+    IntersectDirectMessageParams,
+)
 from .version import __version__, version_info, version_string
 
 __all__ = [
@@ -43,20 +49,22 @@ __all__ = [
     'intersect_event',
     'intersect_message',
     'intersect_status',
-    'get_schema_from_capability_implementation',
+    'get_schema_from_capability_implementations',
     'IntersectService',
     'IntersectClient',
     'IntersectClientCallback',
-    'IntersectClientMessageParams',
+    'IntersectDirectMessageParams',
     'INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE',
     'INTERSECT_CLIENT_EVENT_CALLBACK_TYPE',
     'INTERSECT_JSON_VALUE',
+    'INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE',
     'IntersectBaseCapabilityImplementation',
     'default_intersect_lifecycle_loop',
     'IntersectClientConfig',
     'IntersectServiceConfig',
     'HierarchyConfig',
     'ControlPlaneConfig',
+    'ControlProvider',
     'DataStoreConfig',
     'DataStoreConfigMap',
     '__version__',

{intersect_sdk-0.6.4 → 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.6.4 → intersect_sdk-0.8.0}/src/intersect_sdk/_internal/function_metadata.py

@@ -12,6 +12,10 @@ class FunctionMetadata(NamedTuple):
     NOTE: both this class and all properties in it should remain immutable after creation
     """
 
+    capability: type
+    """
+    The type of the class that implements the target method.
+    """
     method: Callable[[Any], Any]
     """
     The raw method of the function. The function itself is useless and should not be called,

intersect_sdk-0.8.0/src/intersect_sdk/_internal/interfaces.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+    from ..service_callback_definitions import (
+        INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
+    )
+    from ..shared_callback_definitions import (
+        IntersectDirectMessageParams,
+    )
+
+
+class IntersectEventObserver(ABC):
+    """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.
+
+        Args:
+            event_name: The key of the event which is fired.
+            event_value: The value of the event which is fired.
+            operation: The source of the event (generally the function name, not directly invoked by application devs)
+        """
+        ...
+
+    @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.
+
+        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.6.4 → intersect_sdk-0.8.0}/src/intersect_sdk/_internal/messages/userspace.py

@@ -2,6 +2,13 @@
 
 This module is internal-facing and should not be used directly by users.
 
+Services have two associated channels which handle userspace messages: their request channel
+and their response channel. Services always CONSUME messages from these channels, but never PRODUCE messages
+on these channels. (A message is always sent in the receiver's namespace).
+
+The response channel is how the service handles external requests, the request channel is used when this service itself
+needs to make external requests through INTERSECT.
+
 Services should ALWAYS be CONSUMING from their userspace channel.
 They should NEVER be PRODUCING messages on their userspace channel.
 
@@ -9,6 +16,8 @@ Clients should be CONSUMING from their userspace channel, but should only get me
 from services they explicitly messaged.
 """
 
+from __future__ import annotations
+
 import datetime
 import uuid
 from typing import Any, Union
@@ -16,10 +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
-from ...core_definitions import IntersectDataHandler, IntersectMimeType
+from ...constants import SYSTEM_OF_SYSTEM_REGEX  # noqa: TCH001 (this is runtime checked)
+from ...core_definitions import (  # noqa: TCH001 (this is runtime checked)
+    IntersectDataHandler,
+    IntersectMimeType,
+)
 from ...version import version_string
-from ..data_plane.minio_utils import MinioPayload
+from ..data_plane.minio_utils import MinioPayload  # noqa: TCH001 (this is runtime checked)
 
 
 class UserspaceMessageHeader(TypedDict):
@@ -115,7 +127,7 @@ class UserspaceMessage(TypedDict):
     the headers of the message
     """
 
-    payload: Union[bytes, MinioPayload]  # noqa: FA100 (Pydantic uses runtime annotations)
+    payload: Union[bytes, MinioPayload]  # noqa: UP007 (Pydantic uses runtime annotations)
     """
     main payload of the message. Needs to match the schema format, including the content type.
 
@@ -141,11 +153,13 @@ def create_userspace_message(
     content_type: IntersectMimeType,
     data_handler: IntersectDataHandler,
     payload: Any,
+    message_id: uuid.UUID | None = None,
     has_error: bool = False,
 ) -> UserspaceMessage:
     """Payloads depend on the data_handler and has_error."""
+    msg_id = message_id if message_id else uuid.uuid4()
     return UserspaceMessage(
-        messageId=uuid.uuid4(),
+        messageId=msg_id,
         operationId=operation_id,
         contentType=content_type,
         payload=payload,

{intersect_sdk-0.6.4 → 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,11 +56,14 @@ 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."""
 
-    capability_name: str
+    class_name: str
     method_name: str
     method: Callable[[Any], Any]
     """raw method is for inspecting attributes"""
@@ -218,18 +222,18 @@ def _status_fn_schema(
     - The status function's schema
     - The TypeAdapter to use for serializing outgoing responses
     """
-    capability_name, status_fn_name, status_fn, min_params = status_info
+    class_name, status_fn_name, status_fn, min_params = status_info
     status_signature = inspect.signature(status_fn)
     method_params = tuple(status_signature.parameters.values())
     if len(method_params) != min_params or any(
         p.kind not in (p.POSITIONAL_OR_KEYWORD, p.POSITIONAL_ONLY) for p in method_params
     ):
         die(
-            f"On capability '{capability_name}', capability status function '{status_fn_name}' should have no parameters other than 'self' (unless a staticmethod), and should not use keyword or variable length arguments (i.e. '*', *args, **kwargs)."
+            f"On capability '{class_name}', capability status function '{status_fn_name}' should have no parameters other than 'self' (unless a staticmethod), and should not use keyword or variable length arguments (i.e. '*', *args, **kwargs)."
         )
     if status_signature.return_annotation is inspect.Signature.empty:
         die(
-            f"On capability '{capability_name}', capability status function '{status_fn_name}' should have a valid return annotation."
+            f"On capability '{class_name}', capability status function '{status_fn_name}' should have a valid return annotation."
         )
     try:
         status_adapter = TypeAdapter(status_signature.return_annotation)
@@ -246,12 +250,12 @@ def _status_fn_schema(
         )
     except PydanticUserError as e:
         die(
-            f"On capability '{capability_name}', return annotation '{status_signature.return_annotation}' on function '{status_fn_name}' is invalid.\n{e}"
+            f"On capability '{class_name}', return annotation '{status_signature.return_annotation}' on function '{status_fn_name}' is invalid.\n{e}"
         )
 
 
 def _add_events(
-    capability_name: str,
+    class_name: str,
     function_name: str,
     schemas: dict[str, Any],
     event_schemas: dict[str, Any],
@@ -272,13 +276,13 @@ def _add_events(
                     for d in differences_from_cache
                 )
                 die(
-                    f"On capability '{capability_name}', event key '{event_key}' on function '{function_name}' was previously defined differently. \n{diff_str}\n"
+                    f"On capability '{class_name}', event key '{event_key}' on function '{function_name}' was previously defined differently. \n{diff_str}\n"
                 )
             metadata_value.operations.add(function_name)
         else:
             if event_definition.data_handler in excluded_data_handlers:
                 die(
-                    f"On capability '{capability_name}', function '{function_name}' should not set data_handler as {event_definition.data_handler} unless an instance is configured in IntersectConfig.data_stores ."
+                    f"On capability '{class_name}', function '{function_name}' should not set data_handler as {event_definition.data_handler} unless an instance is configured in IntersectConfig.data_stores ."
                 )
             try:
                 event_adapter: TypeAdapter[Any] = TypeAdapter(event_definition.event_type)
@@ -297,7 +301,7 @@ def _add_events(
                 )
             except PydanticUserError as e:
                 die(
-                    f"On capability '{capability_name}', event key '{event_key}' on function '{function_name}' has an invalid value in the events mapping.\n{e}"
+                    f"On capability '{class_name}', event key '{event_key}' on function '{function_name}' has an invalid value in the events mapping.\n{e}"
                 )
 
 
@@ -332,10 +336,14 @@ def _introspection_baseline(
     function_map = {}
     event_metadatas: dict[str, EventMetadata] = {}
 
+    # 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 capability_name, name, method, min_params in response_funcs:
+    for class_name, name, method, min_params in response_funcs:
+        public_name = f'{cap_name}.{name}'
+
         # TODO - I'm placing this here for now because we'll eventually want to capture data plane and broker configs in the schema.
         # (It's possible we may want to separate the backing service schema from the application logic, but it's unlikely.)
         # At the moment, we're just validating that users can support their response_data_handler property.
@@ -343,7 +351,7 @@ def _introspection_baseline(
         data_handler = getattr(method, RESPONSE_DATA)
         if data_handler in excluded_data_handlers:
             die(
-                f"On capability '{capability_name}', function '{name}' should not set response_data_type as {data_handler} unless an instance is configured in IntersectConfig.data_stores ."
+                f"On capability '{class_name}', function '{name}' should not set response_data_type as {data_handler} unless an instance is configured in IntersectConfig.data_stores ."
             )
 
         docstring = inspect.cleandoc(method.__doc__) if method.__doc__ else None
@@ -358,7 +366,7 @@ def _introspection_baseline(
             )
         ):
             die(
-                f"On capability '{capability_name}', function '{name}' should have 'self' (unless a staticmethod) and zero or one additional parameters, and should not use keyword or variable length arguments (i.e. '*', *args, **kwargs)."
+                f"On capability '{class_name}', function '{name}' should have 'self' (unless a staticmethod) and zero or one additional parameters, and should not use keyword or variable length arguments (i.e. '*', *args, **kwargs)."
             )
 
         # The schema format should be hard-coded and determined based on how Pydantic parses the schema.
@@ -390,7 +398,7 @@ def _introspection_baseline(
             # Pydantic BaseModels require annotations even if using a default value, so we'll remain consistent.
             if annotation is inspect.Parameter.empty:
                 die(
-                    f"On capability '{capability_name}', parameter '{parameter.name}' type annotation on function '{name}' missing. {SCHEMA_HELP_MSG}"
+                    f"On capability '{class_name}', parameter '{parameter.name}' type annotation on function '{name}' missing. {SCHEMA_HELP_MSG}"
                 )
             # rationale for disallowing function default values:
             # https://docs.pydantic.dev/latest/concepts/validation_decorator/#using-field-to-describe-function-arguments
@@ -398,7 +406,7 @@ def _introspection_baseline(
             # also makes TypeAdapters considerably easier to construct
             if parameter.default is not inspect.Parameter.empty:
                 die(
-                    f"On capability '{capability_name}', parameter '{parameter.name}' should not use a default value in the function parameter (use 'typing_extensions.Annotated[TYPE, pydantic.Field(default=<DEFAULT>)]' instead - 'default_factory' is an acceptable, mutually exclusive argument to 'Field')."
+                    f"On capability '{class_name}', parameter '{parameter.name}' should not use a default value in the function parameter (use 'typing_extensions.Annotated[TYPE, pydantic.Field(default=<DEFAULT>)]' instead - 'default_factory' is an acceptable, mutually exclusive argument to 'Field')."
                 )
             try:
                 function_cache_request_adapter = TypeAdapter(annotation)
@@ -410,7 +418,7 @@ def _introspection_baseline(
                 )
             except PydanticUserError as e:
                 die(
-                    f"On capability '{capability_name}', parameter '{parameter.name}' type annotation '{annotation}' on function '{name}' is invalid\n{e}"
+                    f"On capability '{class_name}', parameter '{parameter.name}' type annotation '{annotation}' on function '{name}' is invalid\n{e}"
                 )
 
         else:
@@ -419,7 +427,7 @@ def _introspection_baseline(
         # this block handles response parameters
         if return_annotation is inspect.Signature.empty:
             die(
-                f"On capability '{capability_name}', return type annotation on function '{name}' missing. {SCHEMA_HELP_MSG}"
+                f"On capability '{class_name}', return type annotation on function '{name}' missing. {SCHEMA_HELP_MSG}"
             )
         try:
             function_cache_response_adapter = TypeAdapter(return_annotation)
@@ -431,11 +439,12 @@ def _introspection_baseline(
             )
         except PydanticUserError as e:
             die(
-                f"On capability '{capability_name}', return annotation '{return_annotation}' on function '{name}' is invalid.\n{e}"
+                f"On capability '{class_name}', return annotation '{return_annotation}' on function '{name}' is invalid.\n{e}"
             )
 
         # final function mapping
-        function_map[name] = FunctionMetadata(
+        function_map[public_name] = FunctionMetadata(
+            capability,
             method,
             function_cache_request_adapter,
             function_cache_response_adapter,
@@ -444,7 +453,7 @@ def _introspection_baseline(
         # this block handles events associated with intersect_messages (implies command pattern)
         function_events: dict[str, IntersectEventDefinition] = getattr(method, EVENT_ATTR_KEY)
         _add_events(
-            capability_name,
+            class_name,
             name,
             schemas,
             event_schemas,
@@ -455,9 +464,9 @@ def _introspection_baseline(
         channels[name]['events'] = list(function_events.keys())
 
     # parse global schemas
-    for capability_name, name, method, _ in event_funcs:
+    for class_name, name, method, _ in event_funcs:
         _add_events(
-            capability_name,
+            class_name,
             name,
             schemas,
             event_schemas,
@@ -471,7 +480,9 @@ def _introspection_baseline(
     )
     # this conditional allows for the status function to also be called like a message
     if status_fn_type_adapter and status_fn and status_fn_name:
-        function_map[status_fn_name] = FunctionMetadata(
+        public_status_name = f'{cap_name}.{status_fn_name}'
+        function_map[public_status_name] = FunctionMetadata(
+            capability,
             status_fn,
             None,
             status_fn_type_adapter,
@@ -487,44 +498,99 @@ def _introspection_baseline(
     )
 
 
-def get_schema_and_functions_from_capability_implementation(
-    capability_type: type[IntersectBaseCapabilityImplementation],
-    capability_name: HierarchyConfig,
+def get_schema_and_functions_from_capability_implementations(
+    capabilities: list[type[IntersectBaseCapabilityImplementation]],
+    service_name: HierarchyConfig,
     excluded_data_handlers: set[IntersectDataHandler],
 ) -> tuple[
     dict[str, Any],
     dict[str, FunctionMetadata],
     dict[str, EventMetadata],
+    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.
     """
-    (
-        schemas,
-        (status_fn_name, status_schema, status_type_adapter),
-        channels,
-        function_map,
-        events,
-        event_map,
-    ) = _introspection_baseline(capability_type, excluded_data_handlers)
+    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
+    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 - TODO event names are currently "global" across capabilities, may want to change this?
+    event_map: dict[str, EventMetadata] = {}  # event functionality
+    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.'
+            )
+
+        (
+            subschemas,
+            (cap_status_fn_name, cap_status_schema, cap_status_type_adapter),
+            cap_functions,
+            cap_function_map,
+            cap_events,
+            cap_event_map,
+        ) = _introspection_baseline(capability_type, excluded_data_handlers)
+
+        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')
+            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
+
+        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)
 
     asyncapi_spec = {
         'asyncapi': ASYNCAPI_VERSION,
         'x-intersect-version': version_string,
         'info': {
-            'title': capability_name.hierarchy_string('.'),
+            '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': {
@@ -540,19 +606,12 @@ def get_schema_and_functions_from_capability_implementation(
             },
         },
     }
-    if capability_type.__doc__:
-        asyncapi_spec['info']['description'] = inspect.cleandoc(capability_type.__doc__)  # type: ignore[index]
 
-    if status_schema:
-        asyncapi_spec['status'] = status_schema
-
-    """
-    TODO - might want to include these fields
-    "securitySchemes": {},
-    "operationTraits": {},
-    "externalDocumentation": {
-        "url": "https://example.com",  # REQUIRED
-    },
-    """
-
-    return asyncapi_spec, function_map, event_map, status_fn_name, status_type_adapter
+    return (
+        asyncapi_spec,
+        function_map,
+        event_map,
+        status_function_cap,
+        status_function_name,
+        status_function_adapter,
+    )