resync libraries

Author: ryukofc

libraries/microsoft-agents-a365-notifications/README.md

@@ -1,36 +1,140 @@
 # Microsoft Agent 365 Notifications
+[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-notifications.svg)](https://badge.fury.io/py/microsoft-agents-a365-notifications)
 
-This package provides notification and messaging extensions for AI agent applications.
+Notification and messaging extensions for AI agent applications built with the Microsoft Agent 365 SDK. Enable your agents to handle rich notifications from Microsoft 365 applications like Word, Excel, PowerPoint, and Email.
 
-## Features
+## What is this?
 
-- **Agent SDK Extensions**: Enhanced notification capabilities for AI agents
-- **Channel Management**: Support for different communication channels
-- **Activity Handling**: Interfaces for managing agent activities and recipients
-- **Role-based Messaging**: Support for role-based communication patterns
+This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The notifications package specifically handles incoming notifications from Microsoft 365 applications, allowing your agents to respond to events like document updates, email mentions, and collaborative activities.
 
-## Quick Start
-
-### Import the notification extensions
-```python
-from microsoft_kairo.notification import agents_sdk_extensions
-```
+## Key Features
 
-### Basic Usage
-
-The package provides interfaces and utilities for:
-- Managing communication channels (`ChannelId`)
-- Defining recipients with roles (`IRecipient`)
-- Handling agent activities (`IActivity`)
-- Assertion helpers for validation
+✅ **Microsoft 365 Integration** - Handle notifications from Word, Excel, PowerPoint, and Outlook  
+✅ **Channel Routing** - Intelligent routing based on source application and context  
+✅ **Type Safety** - Built with Pydantic for automatic validation and type checking  
+✅ **Flexible Handlers** - Support for wildcard and specific channel notification handlers  
+✅ **Enterprise Ready** - Built for production Microsoft 365 environments  
+✅ **Async Support** - Full async/await support for high-performance applications  
 
 ## Installation
 
 ```bash
 pip install microsoft-agents-a365-notifications
 ```
 
+## Quick Start
+
+### Basic Concepts
+
+The Microsoft Agent 365 Notifications package enables your agents to receive and respond to notifications from Microsoft 365 applications. Key concepts include:
+
+- **Notification Handlers**: Functions that process incoming notifications
+- **Channel Routing**: Route notifications based on the source application
+- **Sub-Channel Filtering**: Handle specific types of notifications (email, documents, etc.)
+- **Context Integration**: Access rich context about the notification source
+
+### Getting Started
+
+1. Install the package: `pip install microsoft-agents-a365-notifications`
+2. Configure your agent application with notification support
+3. Register handlers for specific Microsoft 365 applications
+4. Process incoming notifications with full context
+
+## Supported Microsoft 365 Applications
+
+| Application | Sub-Channel ID | Description |
+|-------------|----------------|-------------|
+| **Email** | `email` | Handle mentions and email-based interactions |
+| **Word** | `word` | Respond to document collaboration events |
+| **Excel** | `excel` | Process spreadsheet updates and analysis requests |
+| **PowerPoint** | `powerpoint` | Handle presentation collaboration notifications |
+| **Federated Knowledge** | `federatedknowledgeservice` | Enterprise knowledge base interactions |
+
+## Advanced Usage
+
+### Notification Processing Features
+
+- **Custom Route Priorities**: Configure handler execution order for different notification types
+- **Authentication Integration**: Seamless integration with Microsoft 365 authentication flows  
+- **Rich Context Access**: Access detailed metadata about notification sources and content
+- **Flexible Filtering**: Support for wildcard matching and specific application targeting
+
+### Notification Types
+
+The package supports various notification scenarios:
+- Document collaboration events (Word, Excel, PowerPoint)
+- Email mentions and interactions  
+- Enterprise knowledge base updates
+- Custom application notifications
+
+## Architecture
+
+The notifications package follows a clean architecture pattern:
+
+- **Route Selectors**: Determine which notifications match specific handlers
+- **Activity Wrappers**: Strongly-typed wrappers around raw notification data  
+- **Handler Registry**: Manages registration and execution of notification handlers
+- **Channel Filtering**: Intelligent filtering based on Microsoft 365 application context
+
+## Integration with Microsoft Agent 365 SDK
+
+This package works seamlessly with other Microsoft Agent 365 SDK components:
+
+| Package | Integration |
+|---------|-------------|
+| `microsoft-agents-activity` | Core activity types and protocols |
+| `microsoft-agents-hosting-core` | Agent lifecycle and middleware |
+| `microsoft-agents-authentication-msal` | Microsoft 365 authentication |
+| `microsoft-agents-hosting-teams` | Teams-specific hosting |
+
+## Sample Applications
+
+Check out these working examples:
+
+| Sample | Description | Location |
+|--------|-------------|----------|
+| **Word Assistant** | Agent that helps with document writing | `samples/word-assistant/` |
+| **Excel Analyzer** | Data analysis agent for spreadsheets | `samples/excel-analyzer/` |
+| **Email Summarizer** | Automatic email summary agent | `samples/email-summarizer/` |
+| **Multi-App Agent** | Handles notifications from all M365 apps | `samples/multi-app-agent/` |
+
 ## Requirements
 
-- Python 3.9+
-- Compatible with AI agent frameworks
+- **Python**: 3.11+
+- **Dependencies**: 
+  - `typing-extensions >= 4.0.0`
+  - `microsoft-agents-activity >= 0.4.0`
+  - `microsoft-agents-hosting-core >= 0.4.0`
+  - `pydantic >= 2.0.0`
+
+## Common Use Cases
+
+### Document Collaboration
+- Respond to document updates and changes
+- Provide writing assistance and suggestions
+- Generate document summaries and reviews
+- Handle collaborative editing scenarios
+
+### Data Analysis Assistant  
+- Process spreadsheet updates and changes
+- Generate insights from data modifications
+- Create visualizations and reports
+- Assist with data analysis workflows
+
+### Email Productivity
+- Handle email mentions and notifications
+- Draft responses and follow-ups
+- Extract action items from conversations
+- Manage email-based workflows
+
+## Quick Links
+
+📦 [All SDK Packages on PyPI](TODO: Update when packages are published)  
+📖 [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python)  
+💡 [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples)  
+🐛 [Report Issues](https://github.com/microsoft/Agent365/issues)  
+🔧 [Microsoft 365 Developer Center](https://developer.microsoft.com/microsoft-365/)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/__init__.py

@@ -7,30 +7,33 @@
 This module provides utilities for handling agent notifications and routing.
 """
 
-from .agents_sdk_extensions import (
-    AddRoute,
-    AgentApplication,
-    AgentNotificationExtensions,
-    AgentsSdkExtension,
-    ChannelId,
-    IActivity,
-    IRecipient,
-    ITurnContext,
-    OnAgentNotification,
-    RouteHandler,
-    RouteSelector,
+# 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__ = [
-    "AddRoute",
-    "AgentApplication",
-    "AgentNotificationExtensions",
-    "AgentsSdkExtension",
-    "ChannelId",
-    "IActivity",
-    "IRecipient",
-    "ITurnContext",
-    "OnAgentNotification",
-    "RouteHandler",
-    "RouteSelector",
+    # Main notification handler
+    "AgentNotification",
+    "AgentHandler",
+    # Models and data classes
+    "AgentNotificationActivity",
+    "EmailReference",
+    "WpxComment",
+    "EmailResponse",
+    "NotificationTypes",
+    "AgentSubChannel",
+    "AgentLifecycleEvent",
 ]

libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py

@@ -1,33 +1,27 @@
 from __future__ import annotations
 
 from collections.abc import Awaitable, Callable, Iterable
-from enum import Enum
 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
+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 AgentSubChannel(str, Enum):
-    EMAIL = "email"
-    EXCEL = "excel"
-    WORD = "word"
-    POWERPOINT = "powerpoint"
-    FEDERATED_KNOWLEDGE_SERVICE = "federatedknowledgeservice"
-
-
 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:
@@ -43,6 +37,20 @@ def __init__(
             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,
@@ -79,6 +87,39 @@ def decorator(handler: AgentHandler):
 
         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]]]:
@@ -107,9 +148,38 @@ def on_powerpoint(
             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()

libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/__init__.py

@@ -2,10 +2,16 @@
 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",
 ]

libraries/microsoft-agents-a365-notifications/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"