microsoft-agents-a365-notifications 0.1.0__py3-none-any.whl

microsoft_agents_a365/notifications/__init__.py

@@ -0,0 +1,39 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Microsoft Agent 365 Notifications
+
+Notification and messaging extensions for AI agent applications.
+This module provides utilities for handling agent notifications and routing.
+"""
+
+# Main notification handler class
+from .agent_notification import (
+    AgentNotification,
+    AgentHandler,
+)
+
+# Import all models from the models subpackage
+from .models import (
+    AgentNotificationActivity,
+    EmailReference,
+    WpxComment,
+    EmailResponse,
+    NotificationTypes,
+    AgentSubChannel,
+    AgentLifecycleEvent,
+)
+
+__all__ = [
+    # Main notification handler
+    "AgentNotification",
+    "AgentHandler",
+    # Models and data classes
+    "AgentNotificationActivity",
+    "EmailReference",
+    "WpxComment",
+    "EmailResponse",
+    "NotificationTypes",
+    "AgentSubChannel",
+    "AgentLifecycleEvent",
+]

microsoft_agents_a365/notifications/agent_notification.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable
+from typing import Any, TypeVar
+
+from microsoft_agents.activity import ChannelId
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.hosting.core.app.state import TurnState
+from .models.agent_notification_activity import AgentNotificationActivity, NotificationTypes
+from .models.agent_subchannel import AgentSubChannel
+from .models.agent_lifecycle_event import AgentLifecycleEvent
+
+TContext = TypeVar("TContext", bound=TurnContext)
+TState = TypeVar("TState", bound=TurnState)
+
+AgentHandler = Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]
+
+
+class AgentNotification:
+    def __init__(
+        self,
+        app: Any,
+        known_subchannels: Iterable[str | AgentSubChannel] | None = None,
+        known_lifecycle_events: Iterable[str | AgentLifecycleEvent] | None = None,
+    ):
+        self._app = app
+        if known_subchannels is None:
+            source_subchannels: Iterable[str | AgentSubChannel] = AgentSubChannel
+        else:
+            source_subchannels = known_subchannels
+
+        self._known_subchannels = {
+            normalized
+            for normalized in (
+                self._normalize_subchannel(sub_channel) for sub_channel in source_subchannels
+            )
+            if normalized
+        }
+
+        if known_lifecycle_events is None:
+            source_lifecycle_events: Iterable[str | AgentLifecycleEvent] = AgentLifecycleEvent
+        else:
+            source_lifecycle_events = known_lifecycle_events
+
+        self._known_lifecycle_events = {
+            normalized
+            for normalized in (
+                self._normalize_lifecycleevent(lifecycle_event)
+                for lifecycle_event in source_lifecycle_events
+            )
+            if normalized
+        }
+
+    def on_agent_notification(
+        self,
+        channel_id: ChannelId,
+        **kwargs: Any,
+    ):
+        registered_channel = channel_id.channel.lower()
+        registered_subchannel = (channel_id.sub_channel or "*").lower()
+
+        def route_selector(context: TurnContext) -> bool:
+            ch = context.activity.channel_id
+            received_channel = (ch.channel if ch else "").lower()
+            received_subchannel = (ch.sub_channel if ch and ch.sub_channel else "").lower()
+            if received_channel != registered_channel:
+                return False
+            if registered_subchannel == "*":
+                return True
+            if registered_subchannel not in self._known_subchannels:
+                return False
+            return received_subchannel == registered_subchannel
+
+        def create_handler(handler: AgentHandler):
+            async def route_handler(context: TurnContext, state: TurnState):
+                ana = AgentNotificationActivity(context.activity)
+                await handler(context, state, ana)
+
+            return route_handler
+
+        def decorator(handler: AgentHandler):
+            route_handler = create_handler(handler)
+            self._app.add_route(route_selector, route_handler, **kwargs)
+            return route_handler
+
+        return decorator
+
+    def on_agent_lifecycle_notification(
+        self,
+        lifecycle_event: str,
+        **kwargs: Any,
+    ):
+        def route_selector(context: TurnContext) -> bool:
+            ch = context.activity.channel_id
+            received_channel = ch.channel if ch else ""
+            received_channel = received_channel.lower()
+            if received_channel != "agents":
+                return False
+            if context.activity.name != NotificationTypes.AGENT_LIFECYCLE:
+                return False
+            if lifecycle_event == "*":
+                return True
+            if context.activity.value_type not in self._known_lifecycle_events:
+                return False
+            return True
+
+        def create_handler(handler: AgentHandler):
+            async def route_handler(context: TurnContext, state: TurnState):
+                ana = AgentNotificationActivity(context.activity)
+                await handler(context, state, ana)
+
+            return route_handler
+
+        def decorator(handler: AgentHandler):
+            route_handler = create_handler(handler)
+            self._app.add_route(route_selector, route_handler, **kwargs)
+            return route_handler
+
+        return decorator
+
+    def on_email(
+        self, **kwargs: Any
+    ) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
+        return self.on_agent_notification(
+            ChannelId(channel="agents", sub_channel=AgentSubChannel.EMAIL), **kwargs
+        )
+
+    def on_word(
+        self, **kwargs: Any
+    ) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
+        return self.on_agent_notification(
+            ChannelId(channel="agents", sub_channel=AgentSubChannel.WORD), **kwargs
+        )
+
+    def on_excel(
+        self, **kwargs: Any
+    ) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
+        return self.on_agent_notification(
+            ChannelId(channel="agents", sub_channel=AgentSubChannel.EXCEL), **kwargs
+        )
+
+    def on_powerpoint(
+        self, **kwargs: Any
+    ) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
+        return self.on_agent_notification(
+            ChannelId(channel="agents", sub_channel=AgentSubChannel.POWERPOINT), **kwargs
+        )
+
+    def on_lifecycle(
+        self, **kwargs: Any
+    ) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
+        return self.on_lifecycle_notification("*", **kwargs)
+
+    def on_user_created(
+        self, **kwargs: Any
+    ) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
+        return self.on_lifecycle_notification(AgentLifecycleEvent.USERCREATED, **kwargs)
+
+    def on_user_workload_onboarding(
+        self, **kwargs: Any
+    ) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
+        return self.on_lifecycle_notification(
+            AgentLifecycleEvent.USERWORKLOADONBOARDINGUPDATED, **kwargs
+        )
+
+    def on_user_deleted(
+        self, **kwargs: Any
+    ) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
+        return self.on_lifecycle_notification(AgentLifecycleEvent.USERDELETED, **kwargs)
+
+    @staticmethod
+    def _normalize_subchannel(value: str | AgentSubChannel | None) -> str:
+        if value is None:
+            return ""
+        resolved = value.value if isinstance(value, AgentSubChannel) else str(value)
+        return resolved.lower().strip()
+
+    @staticmethod
+    def _normalize_lifecycleevent(value: str | AgentLifecycleEvent | None) -> str:
+        if value is None:
+            return ""
+        resolved = value.value if isinstance(value, AgentLifecycleEvent) else str(value)
+        return resolved.lower().strip()

microsoft_agents_a365/notifications/models/__init__.py

@@ -0,0 +1,17 @@
+from .agent_notification_activity import AgentNotificationActivity
+from .email_reference import EmailReference
+from .wpx_comment import WpxComment
+from .email_response import EmailResponse
+from .notification_types import NotificationTypes
+from .agent_subchannel import AgentSubChannel
+from .agent_lifecycle_event import AgentLifecycleEvent
+
+__all__ = [
+    "AgentNotificationActivity",
+    "EmailReference",
+    "WpxComment",
+    "EmailResponse",
+    "NotificationTypes",
+    "AgentSubChannel",
+    "AgentLifecycleEvent",
+]

microsoft_agents_a365/notifications/models/agent_lifecycle_event.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class AgentLifecycleEvent(str, Enum):
+    USERCREATED = "agenticuseridentitycreated"
+    USERWORKLOADONBOARDINGUPDATED = "agenticuserworkloadonboardingupdated"
+    USERDELETED = "agenticuseridentitydeleted"

microsoft_agents_a365/notifications/models/agent_notification_activity.py

@@ -0,0 +1,85 @@
+from typing import Any, Optional, Type, TypeVar
+from microsoft_agents.activity import Activity
+from .notification_types import NotificationTypes
+from .email_reference import EmailReference
+from .wpx_comment import WpxComment
+
+TModel = TypeVar("TModel")
+
+
+class AgentNotificationActivity:
+    """Light wrapper around an Activity object with typed entities parsed at create time."""
+
+    def __init__(self, activity: Activity):
+        if not activity:
+            raise ValueError("activity parameter is required and cannot be None")
+        self.activity = activity
+        self._email: Optional[EmailReference] = None
+        self._wpx_comment: Optional[WpxComment] = None
+        self._notification_type: Optional[NotificationTypes] = None
+
+        entities = self.activity.entities or []
+        for ent in entities:
+            etype = ent.type.lower()
+            payload = getattr(ent, "additional_properties", ent)
+
+            if etype == NotificationTypes.EMAIL_NOTIFICATION.lower() and self._email is None:
+                try:
+                    self._email = EmailReference.model_validate(payload)
+                    self._notification_type = NotificationTypes.EMAIL_NOTIFICATION
+                except Exception:
+                    self._email = None
+
+            if etype == NotificationTypes.WPX_COMMENT.lower() and self._wpx_comment is None:
+                try:
+                    self._wpx_comment = WpxComment.model_validate(payload)
+                    self._notification_type = NotificationTypes.WPX_COMMENT
+                except Exception:
+                    self._wpx_comment = None
+
+        # Set notification type from activity name if not already set
+        if self._notification_type is None:
+            self._notification_type = (
+                NotificationTypes.AGENT_LIFECYCLE
+                if NotificationTypes(self.activity.name) is NotificationTypes.AGENT_LIFECYCLE
+                else None
+            )
+
+    # ---- passthroughs ----
+    @property
+    def channel(self) -> Optional[str]:
+        ch = self.activity.channel_id
+        return ch.channel if ch else None
+
+    @property
+    def sub_channel(self) -> Optional[str]:
+        ch = self.activity.channel_id
+        return ch.sub_channel if ch else None
+
+    @property
+    def value(self) -> Any:
+        return self.activity.value
+
+    @property
+    def type(self) -> Optional[str]:
+        return self.activity.type
+
+    # --- typed entities available directly on the activity ---
+    @property
+    def email(self) -> Optional[EmailReference]:
+        return self._email
+
+    @property
+    def wpx_comment(self) -> Optional[WpxComment]:
+        return self._wpx_comment
+
+    @property
+    def notification_type(self) -> Optional[NotificationTypes]:
+        return self._notification_type
+
+    # Generic escape hatch
+    def as_model(self, model: Type[TModel]) -> Optional[TModel]:
+        try:
+            return model.model_validate(self.value or {})
+        except Exception:
+            return None

microsoft_agents_a365/notifications/models/agent_subchannel.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class AgentSubChannel(str, Enum):
+    EMAIL = "email"
+    EXCEL = "excel"
+    WORD = "word"
+    POWERPOINT = "powerpoint"
+    FEDERATED_KNOWLEDGE_SERVICE = "federatedknowledgeservice"

microsoft_agents_a365/notifications/models/email_reference.py

@@ -0,0 +1,10 @@
+from typing import Optional, Literal
+from microsoft_agents.activity.entity import Entity
+from .notification_types import NotificationTypes
+
+
+class EmailReference(Entity):
+    type: Literal["emailNotification"] = NotificationTypes.EMAIL_NOTIFICATION
+    id: Optional[str] = None
+    conversation_id: Optional[str] = None
+    html_body: Optional[str] = None

microsoft_agents_a365/notifications/models/email_response.py

@@ -0,0 +1,25 @@
+from typing import Literal
+from microsoft_agents.activity.activity import Activity
+from microsoft_agents.activity.entity import Entity
+
+
+class EmailResponse(Entity):
+    type: Literal["emailResponse"] = "emailResponse"
+    html_body: str = ""
+
+    @staticmethod
+    def create_email_response_activity(email_response_html_body: str) -> Activity:
+        """Create a new Activity with an EmailResponse entity.
+
+        Args:
+            email_response_html_body: The HTML content for the email response.
+
+        Returns:
+            A new Activity instance with type='message' and the EmailResponse entity attached.
+        """
+        working_activity = Activity(type="message")
+        email_response = EmailResponse(html_body=email_response_html_body)
+        if working_activity.entities is None:
+            working_activity.entities = []
+        working_activity.entities.append(email_response)
+        return working_activity

microsoft_agents_a365/notifications/models/notification_types.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class NotificationTypes(str, Enum):
+    EMAIL_NOTIFICATION = "emailNotification"
+    WPX_COMMENT = "wpxComment"
+    AGENT_LIFECYCLE = "agentLifecycle"

microsoft_agents_a365/notifications/models/wpx_comment.py

@@ -0,0 +1,12 @@
+from typing import Optional, Literal
+from microsoft_agents.activity.entity import Entity
+from .notification_types import NotificationTypes
+
+
+class WpxComment(Entity):
+    type: Literal["wpxComment"] = NotificationTypes.WPX_COMMENT
+
+    odata_id: Optional[str] = None
+    document_id: Optional[str] = None
+    parent_comment_id: Optional[str] = None
+    comment_id: Optional[str] = None

microsoft_agents_a365_notifications-0.1.0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-a365-notifications
+Version: 0.1.0
+Summary: Notification and messaging extensions for AI agent applications
+Author-email: Microsoft <support@microsoft.com>
+License: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agent365-python
+Project-URL: Repository, https://github.com/microsoft/Agent365-python
+Project-URL: Issues, https://github.com/microsoft/Agent365-python/issues
+Project-URL: Documentation, https://github.com/microsoft/Agent365-python/tree/main/libraries/microsoft-agents-a365-notifications
+Keywords: notifications,messaging,agents,ai,routing,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Communications
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: microsoft-agents-activity>=0.4.0
+Requires-Dist: microsoft-agents-hosting-core>=0.4.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+
+# microsoft-agents-a365-notifications
+
+[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-notifications?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-notifications)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-notifications?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-notifications)
+
+Notification and messaging extensions for AI agent applications. This package provides utilities for handling agent notifications, lifecycle events, and routing across different channels and subchannels in Microsoft 365 applications.
+
+## Installation
+
+```bash
+pip install microsoft-agents-a365-notifications
+```
+
+## Usage
+
+For usage examples and detailed documentation, see the [Notification documentation](https://learn.microsoft.com/microsoft-agent-365/developer/notification?tabs=python) on Microsoft Learn.
+
+## Support
+
+For issues, questions, or feedback:
+
+- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section
+- See the [main documentation](../../../README.md) for more information
+
+## Trademarks
+
+*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.*
+
+## License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details.

microsoft_agents_a365_notifications-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+microsoft_agents_a365/notifications/__init__.py,sha256=ppyGNL9uLOzwaMy9v83UDYT-f2HNrA9H_yxf8rEwfQU,864
+microsoft_agents_a365/notifications/agent_notification.py,sha256=_3Ice9EjzgHWD-_4XlIfP9PiH28eZuZe4YZV90N-obw,6995
+microsoft_agents_a365/notifications/models/__init__.py,sha256=tVhQU7QuOtLk_Ihz5UaHhcHfDXAjR81iRV1v4aMI_fw,524
+microsoft_agents_a365/notifications/models/agent_lifecycle_event.py,sha256=0UZ39c_HnwJgDZmNaLRGkjabCC1kNiiwC_eT8OnOazU,231
+microsoft_agents_a365/notifications/models/agent_notification_activity.py,sha256=oRo-M_NYk7mf5039oW2JtV_pnYdDfUGc612jMV9YLDE,3008
+microsoft_agents_a365/notifications/models/agent_subchannel.py,sha256=Ra-nZdJgFExb6_ArVXJ-4lbW_XjuzRaLdleHifyMw6w,208
+microsoft_agents_a365/notifications/models/email_reference.py,sha256=DWuzqT-DDns3YsE20JgRFb7xS8mvUgJZ0FAfqpNMVNA,356
+microsoft_agents_a365/notifications/models/email_response.py,sha256=470zqPN6ElhZJf-mGWfa9z6BWbSEvWxxNYJRI_oOsAY,932
+microsoft_agents_a365/notifications/models/notification_types.py,sha256=-xgwGVzuqnzLdxnM25x6WDJeUKwIXwmzcrzs8nRwdSA,175
+microsoft_agents_a365/notifications/models/wpx_comment.py,sha256=KKg9o4Y7di7D1cGojDlV7k_FRntN8W-BGkJVUhpRm6w,386
+microsoft_agents_a365_notifications-0.1.0.dist-info/METADATA,sha256=chcCj_8asPZEzKuYjHEbULZiceq60KqbL1TQ3G2Vq1o,3459
+microsoft_agents_a365_notifications-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_agents_a365_notifications-0.1.0.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
+microsoft_agents_a365_notifications-0.1.0.dist-info/RECORD,,

microsoft_agents_a365_notifications-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

microsoft_agents_a365_notifications-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+microsoft_agents_a365