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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: intersect-sdk
-Version: 0.6.3
+Version: 0.7.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>
@@ -16,12 +16,11 @@ Requires-Dist: retrying<2.0.0,>=1.3.4
 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"
 Requires-Dist: pika<2.0.0,>=1.3.2; extra == "amqp"
-Requires-Dist: eval-type-backport>=0.1.3; extra == "py38"
 Requires-Dist: sphinx>=5.3.0; extra == "docs"
 Requires-Dist: furo>=2023.3.27; extra == "docs"
 Provides-Extra: amqp
-Provides-Extra: py38
 Provides-Extra: docs
 Description-Content-Type: text/markdown
 

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

@@ -33,8 +33,9 @@ dependencies = [
     "paho-mqtt>=1.6.1,<2.0.0",
     "minio>=7.2.3",
     "jsonschema[format-nongpl]>=4.21.1",
+    "eval-type-backport>=0.1.3;python_version<'3.10'",
 ]
-version = "0.6.3"
+version = "0.7.0"
 
 [project.license]
 text = "BSD-3-Clause"
@@ -43,9 +44,6 @@ text = "BSD-3-Clause"
 amqp = [
     "pika>=1.3.2,<2.0.0",
 ]
-py38 = [
-    "eval-type-backport>=0.1.3",
-]
 docs = [
     "sphinx>=5.3.0",
     "furo>=2023.3.27",
@@ -68,6 +66,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/"
@@ -164,6 +163,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" = [

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

@@ -13,9 +13,7 @@ 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
@@ -28,12 +26,19 @@ from .config.shared import (
 from .core_definitions import IntersectDataHandler, IntersectMimeType
 from .schema import get_schema_from_capability_implementation
 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__ = [
@@ -47,10 +52,11 @@ __all__ = [
     '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',

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

@@ -13,7 +13,7 @@ if TYPE_CHECKING:
     from ...config.shared import ControlPlaneConfig
     from .brokers.broker_client import BrokerClient
 
-GENERIC_MESSAGE_SERIALIZER = TypeAdapter(Any)
+GENERIC_MESSAGE_SERIALIZER: TypeAdapter[Any] = TypeAdapter(Any)
 
 
 def serialize_message(message: Any) -> bytes:

{intersect_sdk-0.6.3 → intersect_sdk-0.7.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.7.0/src/intersect_sdk/_internal/interfaces.py

@@ -0,0 +1,49 @@
+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,
+    ) -> 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.
+
+        Returns:
+          - generated RequestID associated with your request
+        """
+        ...

{intersect_sdk-0.6.3 → intersect_sdk-0.7.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.3 → intersect_sdk-0.7.0}/src/intersect_sdk/_internal/schema.py

@@ -59,7 +59,7 @@ For a complete reference, https://docs.pydantic.dev/latest/concepts/conversion_t
 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 +218,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 +246,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 +272,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,12 +297,12 @@ 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}"
                 )
 
 
 def _introspection_baseline(
-    capability: type[IntersectBaseCapabilityImplementation],
+    capability: IntersectBaseCapabilityImplementation,
     excluded_data_handlers: set[IntersectDataHandler],
 ) -> tuple[
     dict[Any, Any],  # $defs for schemas (common)
@@ -332,10 +332,13 @@ def _introspection_baseline(
     function_map = {}
     event_metadatas: dict[str, EventMetadata] = {}
 
-    status_func, response_funcs, event_funcs = _get_functions(capability)
+    cap_name = capability.capability_name
+    status_func, response_funcs, event_funcs = _get_functions(type(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 +346,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 +361,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 +393,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 +401,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 +413,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 +422,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 +434,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(
+            type(capability),
             method,
             function_cache_request_adapter,
             function_cache_response_adapter,
@@ -444,7 +448,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 +459,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 +475,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(
+            type(capability),
             status_fn,
             None,
             status_fn_type_adapter,
@@ -487,14 +493,15 @@ 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[IntersectBaseCapabilityImplementation],
+    service_name: HierarchyConfig,
     excluded_data_handlers: set[IntersectDataHandler],
 ) -> tuple[
     dict[str, Any],
     dict[str, FunctionMetadata],
     dict[str, EventMetadata],
+    IntersectBaseCapabilityImplementation | None,
     str | None,
     TypeAdapter[Any] | None,
 ]:
@@ -502,20 +509,46 @@ def get_schema_and_functions_from_capability_implementation(
 
     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)
+    capability_type_docs: str = ''
+    status_function_cap: 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
+    function_map: dict[str, FunctionMetadata] = {}  # endpoint functionality
+    events: dict[str, Any] = {}  # event schemas
+    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'
+        (
+            cap_schemas,
+            (cap_status_fn_name, cap_status_schema, cap_status_type_adapter),
+            cap_channels,
+            cap_function_map,
+            cap_events,
+            cap_event_map,
+        ) = _introspection_baseline(capability, excluded_data_handlers)
+
+        if cap_status_fn_name and cap_status_schema and cap_status_type_adapter:
+            status_function_cap = capability
+            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)
+        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('.'),
             '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.
@@ -540,11 +573,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
+    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
@@ -555,4 +589,11 @@ def get_schema_and_functions_from_capability_implementation(
     },
     """
 
-    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,
+    )

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

@@ -11,21 +11,34 @@ from .._internal.constants import BASE_EVENT_ATTR, BASE_RESPONSE_ATTR, BASE_STAT
 from .._internal.logger import logger
 
 if TYPE_CHECKING:
+    from uuid import UUID
+
     from .._internal.interfaces import IntersectEventObserver
+    from ..service_callback_definitions import (
+        INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
+    )
+    from ..shared_callback_definitions import (
+        IntersectDirectMessageParams,
+    )
 
 
 class IntersectBaseCapabilityImplementation:
     """Base class for all capabilities.
 
     EVERY capability implementation will need to extend this class. Additionally, if you redefine the constructor,
-    you MUST call super.__init__() .
+    you MUST call `super.__init__()` .
     """
 
     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.
+        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.
@@ -34,16 +47,31 @@ class IntersectBaseCapabilityImplementation:
         """
 
     def __init_subclass__(cls) -> None:
-        """This prevents users from overriding a few key functions."""
+        """This prevents users from overriding a few key functions.
+
+        General rule of thumb is that any function which starts with `intersect_sdk_` is a protected namespace for defining
+        the INTERSECT-SDK public API between a capability and its observers.
+        """
         if (
             cls._intersect_sdk_register_observer
             is not IntersectBaseCapabilityImplementation._intersect_sdk_register_observer
             or cls.intersect_sdk_emit_event
             is not IntersectBaseCapabilityImplementation.intersect_sdk_emit_event
+            or cls.intersect_sdk_call_service
+            is not IntersectBaseCapabilityImplementation.intersect_sdk_call_service
         ):
-            msg = f"{cls.__name__}: Cannot override functions '_intersect_sdk_register_observer' or 'intersect_sdk_emit_event'"
+            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."""
@@ -99,3 +127,27 @@ class IntersectBaseCapabilityImplementation:
             return
         for observer in self.__intersect_sdk_observers__:
             observer._on_observe_event(event_name, event_value, annotated_operation)  # noqa: SLF001 (private for application devs, NOT for base implementation)
+
+    @final
+    def intersect_sdk_call_service(
+        self,
+        request: IntersectDirectMessageParams,
+        response_handler: INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None = None,
+    ) -> 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.
+
+        Returns:
+          - list of generated RequestIDs associated with your request. Note that for almost all use cases,
+            this list will have only one associated RequestID.
+
+        Raises:
+          - pydantic.ValidationError - if the request parameter isn't valid
+        """
+        return [
+            observer.create_external_request(request, response_handler)
+            for observer in self.__intersect_sdk_observers__
+        ]