Merge pull request #41 from INTERSECT-SDK/candidate-0.9.0

0.9.0

Author: Lance-Drane

.github/workflows/ci.yml

@@ -4,10 +4,12 @@ on:
   push:
     branches:
       - main
+      - candidate-*
   pull_request:
     types: [opened, synchronize, reopened]
     branches:
       - main
+      - candidate-*
   workflow_dispatch:
 
 permissions:
@@ -22,7 +24,7 @@ jobs:
       - name: Setup PDM
         uses: pdm-project/setup-pdm@v4
         with:
-          python-version: "3.8"
+          python-version: "3.12"
           cache: true
       - name: Install dependencies
         run: |
@@ -38,7 +40,7 @@ jobs:
     name: Windows/MacOS unit tests
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
         os:
           - macos-latest
           - windows-latest
@@ -61,13 +63,13 @@ jobs:
     name: Test with coverage
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
         os:
           - ubuntu-latest
     runs-on: ${{ matrix.os }}
     services:
       rabbitmq:
-        image: "bitnamilegacy/rabbitmq:3.13.3"
+        image: "bitnamilegacy/rabbitmq:4.1"
         env:
           # space-delimited list of plugins
           RABBITMQ_PLUGINS: "rabbitmq_mqtt"

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
     - id: end-of-file-fixer
     - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.4
+    rev: v0.12.7
     hooks:
       - id: ruff
         args: [ --fix ]

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 We follow [Common Changelog](https://common-changelog.org/) formatting for this document.
 
+## Unreleased
+
+### Fixed
+
+- namespace events and statuses to capabilities instead of services ([commit 1](https://github.com/INTERSECT-SDK/python-sdk/commit/e05e27471f05bf50e0bc5a0123f7e0133a3d969e) [commit 2](https://github.com/INTERSECT-SDK/python-sdk/commit/1460e989f70efaf9713eb77bbb4508698db3e655)) (Lance-Drane)
+
+### Changed
+
+- Allow user to specify whatever message Content-Type they would like in messages, and provide handling for non-JSON data types ([commit](https://github.com/INTERSECT-SDK/python-sdk/commit/dcd536ebb03973e8939e2715e51dfc3da0d8bd16)) (Lance Drane)
+- change events API; instead of using `@intersect_event` or `@intersect_message(events=...)`, declare all events in capability variable `intersect_sdk_events` ([commit](https://github.com/INTERSECT-SDK/python-sdk/commit/1460e989f70efaf9713eb77bbb4508698db3e655)) (Lance Drane)
+- move Pika (AMQP) to be a required dependency instead of an optional dependency ([commit](https://github.com/INTERSECT-SDK/python-sdk/commit/5ed5be6a51917b5598043115fb9cb176a6627a2a)) (Lance Drane)
+- bump required Paho MQTT version from v1 to v2 ([commit](https://github.com/INTERSECT-SDK/python-sdk/commit/d0bcb9550aa92c7ef327e313a2ad5b34d914a3b3)) (Lance Drane)
+- change internal message structure representation; metadata is sent through as headers, while the direct payload is always the data. This decreases the number of JSON serializations/deserializations from 2 to at most 1 (if the data is actually JSON). This does NOT modify any APIs already in use, with the exception of core services ([initial commit](https://github.com/INTERSECT-SDK/python-sdk/commit/e09f13f9b244b92b6bcecc814df49c81340dcc02#diff-725ea87422115a87ba1869854601d413f1fcac6bea0c965ce5a14e2fcb0461b1) [commit which adds campaign IDs](https://github.com/INTERSECT-SDK/python-sdk/commit/ef8db5415c97af80df267277f8ddca6347440b5e)) (Lance Drane)
+
+### Added
+
+- Added MQTT 5.0 support ([commit](https://github.com/INTERSECT-SDK/python-sdk/commit/e09f13f9b244b92b6bcecc814df49c81340dcc02)) (Lance Drane)
+- Added a default `intersect_sdk` capability meant to encompass common system querying information ([commit](https://github.com/INTERSECT-SDK/python-sdk/commit/e05e27471f05bf50e0bc5a0123f7e0133a3d969e)) (Lance Drane)
+
+### Removed
+
+- Dropped MQTT 3.1.1 support ([commit](https://github.com/INTERSECT-SDK/python-sdk/commit/e09f13f9b244b92b6bcecc814df49c81340dcc02)) (Lance Drane)
+- Dropped support for Python versions <= 3.9
+
 ## [0.8.4] - 2026-02-05
 
 ### Fixed

README.md

@@ -19,7 +19,8 @@ For a high-level overview, please see [the architecture website.](https://inters
 
 - Event-driven architecture
 - Support core interaction types: request/response, events, commands, statuses
-- Borrows several concepts from [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest), and intends to support multiple different protocols. Currently, we support MQTT 3.1.1 and AMQP 0.9.1, but other protocols will be supported as well.
+- Borrows several concepts from [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest), and intends to support multiple different protocols. Currently, we support MQTT 5.0 and AMQP 0.9.1, but other protocols will be supported as well.
+  - As a general rule, we will not support any protocols which do not support headers, do not allow for asynchronous messaging, or require the microservice itself to "keep alive" multiple connections.
 - Users automatically generate schema from code; schemas are part of the core contract of an INTERSECT microservice, and both external inputs and microservice outputs are required to uphold this contract.
 
 ## Authors

docker-compose.yml

@@ -3,7 +3,7 @@
 
 services:
   broker:
-    image: "bitnamilegacy/rabbitmq:3.13.3"
+    image: "bitnamilegacy/rabbitmq:4.1"
     ports:
       - "1883:1883" # MQTT port
       - "5672:5672" # AMQP port

docs/core_concepts.rst

@@ -38,15 +38,27 @@ Arguments to the ``@intersect_message()`` decorator can be used to specify speci
 CapabilityImplementation - Events
 ---------------------------------
 
-You can emit events globally as part of an ``@intersect_message()`` annotated function by configuring the ``events`` argument to the decorator as a dictionary/mapping of event names (as strings) to IntersectEventDefinitions.
-An IntersectEventDefinition consists of an event_type, which is the typing of the event you'll emit.
+You can emit events globally, with or without input from other INTERSECT messages.
 
-You can also emit events without having to react to an external request by annotating a function with ``@intersect_event()`` and providing the ``events`` argument to the decorator.
+To do this, you must create a mapping of keys to ``IntersectEventDefinition`` as your BaseCapability's ``intersect_sdk_events`` class variable.
+An IntersectEventDefinition consists of an ``event_type``, which is the typing of the event you'll emit.
 
-You can emit an event by calling ``self.intersect_sdk_emit_event(event_name, event)`` . The typing of ``event`` must match the typing in the decorator configuration.
-Calling this function will only be effective if called from either an ``@intersect_message`` or ``@intersect_event`` decorated function, or an inner function called from a decorated function.
+You can emit an event by calling ``self.intersect_sdk_emit_event(event_name, event)`` . The typing of ``event`` must match the typing of ``IntersectEventDefinition(event_type)``.
 
-You can specify the same event name on multiple functions, but it must always contain the same IntersectEventDefinition configuration.
+A simple example of how to configure this:
+
+.. code-block:: python
+
+    class YourCapability(IntersectBaseCapabilityImplementation):
+        # You should configure it on the class itself. Do NOT configure it on the instance.
+        intersect_sdk_events: ClassVar[dict[str, IntersectEventDefinition]] = {
+            'my_integer_event': IntersectEventDefinition(event_type=int),
+            'my_str_event': IntersectEventDefinition(event_type=str),
+            'my_float_event': IntersectEventDefinition(event_type=float),
+        }
+
+
+Now this capability can call ``self.intersect_sdk_emit_event('my_integer_event', value)`` as long as "value" is actually an integer.
 
 Client
 ------

docs/pydantic.rst

@@ -18,7 +18,7 @@ Usage
 External users would benefit most by understanding the `Models <https://docs.pydantic.dev/latest/concepts/models/>`_, `Fields <https://docs.pydantic.dev/latest/concepts/fields/>`_,
 and `Types <https://docs.pydantic.dev/latest/concepts/types/>`_ documentation pages on Pydantic's own documentation website.
 
-INTERSECT-SDK will handle the schema generation logic, but users are able to customize fields themselves. For example, users can combine ``typing_extensions.Annotated``
+INTERSECT-SDK will handle the schema generation logic, but users are able to customize fields themselves. For example, users can combine ``typing.Annotated``
 with ``pydantic.Field`` to specify regular expression patterns for string, minimum lengths for arrays/lists, and many other validation concepts.
 
 For handling complex objects, your class should either extend ``pydantic.BaseModel`` or be a `Python Dataclass <https://docs.python.org/3/library/dataclasses.html>`_.

examples/1_hello_world/hello_client.py

@@ -1,7 +1,7 @@
 import logging
 
 from intersect_sdk import (
-    INTERSECT_JSON_VALUE,
+    INTERSECT_RESPONSE_VALUE,
     IntersectClient,
     IntersectClientCallback,
     IntersectClientConfig,
@@ -13,7 +13,7 @@
 
 
 def simple_client_callback(
-    _source: str, _operation: str, _has_error: bool, payload: INTERSECT_JSON_VALUE
+    _source: str, _operation: str, _has_error: bool, payload: INTERSECT_RESPONSE_VALUE
 ) -> None:
     """This simply prints the response from the service to your console.
 
@@ -48,7 +48,7 @@ def simple_client_callback(
                 'username': 'intersect_username',
                 'password': 'intersect_password',
                 'port': 1883,
-                'protocol': 'mqtt3.1.1',
+                'protocol': 'mqtt5.0',
             },
         ],
     }

examples/1_hello_world/hello_service.py

@@ -21,7 +21,7 @@ class HelloServiceCapabilityImplementation(IntersectBaseCapabilityImplementation
     but we do not use it here.
 
     The operation we are calling is `say_hello_to_name` , so the message being sent will need to have
-    an operationId of `say_hello_to_name`. The operation expects a string sent to it in the payload,
+    an operation_id of `say_hello_to_name`. The operation expects a string sent to it in the payload,
     and will send a string back in its own payload.
     """
 
@@ -50,7 +50,7 @@ def say_hello_to_name(self, name: str) -> str:
                 'username': 'intersect_username',
                 'password': 'intersect_password',
                 'port': 1883,
-                'protocol': 'mqtt3.1.1',
+                'protocol': 'mqtt5.0',
             },
         ],
     }