microsoft-agents-activity 0.3.2__tar.gz → 0.4.0__tar.gz

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-activity
-Version: 0.3.2
+Version: 0.4.0
 Summary: A protocol library for Microsoft Agents
 Author: Microsoft Corporation
 Project-URL: Homepage, https://github.com/microsoft/Agents

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/__init__.py

@@ -24,32 +24,32 @@ from .conversation_reference import ConversationReference
 from .conversation_resource_response import ConversationResourceResponse
 from .conversations_result import ConversationsResult
 from .expected_replies import ExpectedReplies
-from .entity import Entity
-from .ai_entity import (
+from .entity import (
+    Entity,
     AIEntity,
     ClientCitation,
     ClientCitationAppearance,
     ClientCitationImage,
     ClientCitationIconName,
+    Mention,
     SensitivityUsageInfo,
     SensitivityPattern,
-    add_ai_to_activity,
+    GeoCoordinates,
+    Place,
+    Thing,
 )
 from .error import Error
 from .error_response import ErrorResponse
 from .fact import Fact
-from .geo_coordinates import GeoCoordinates
 from .hero_card import HeroCard
 from .inner_http_error import InnerHttpError
 from .invoke_response import InvokeResponse
 from .media_card import MediaCard
 from .media_event_value import MediaEventValue
 from .media_url import MediaUrl
-from .mention import Mention
 from .message_reaction import MessageReaction
 from .oauth_card import OAuthCard
 from .paged_members_result import PagedMembersResult
-from .place import Place
 from .receipt_card import ReceiptCard
 from .receipt_item import ReceiptItem
 from .resource_response import ResourceResponse
@@ -57,7 +57,6 @@ from .semantic_action import SemanticAction
 from .signin_card import SigninCard
 from .suggested_actions import SuggestedActions
 from .text_highlight import TextHighlight
-from .thing import Thing
 from .thumbnail_card import ThumbnailCard
 from .thumbnail_url import ThumbnailUrl
 from .token_exchange_invoke_request import TokenExchangeInvokeRequest
@@ -92,7 +91,6 @@ from .caller_id_constants import CallerIdConstants
 from .conversation_update_types import ConversationUpdateTypes
 from .message_update_types import MessageUpdateTypes
 
-
 from .channel_adapter_protocol import ChannelAdapterProtocol
 from .turn_context_protocol import TurnContextProtocol
 from ._load_configuration import load_configuration_from_env
@@ -131,7 +129,6 @@ __all__ = [
     "ClientCitationIconName",
     "SensitivityUsageInfo",
     "SensitivityPattern",
-    "add_ai_to_activity",
     "Error",
     "ErrorResponse",
     "Fact",

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/_load_configuration.py

@@ -1,7 +1,7 @@
-from typing import Any, Dict
+from typing import Any
 
 
-def load_configuration_from_env(env_vars: Dict[str, Any]) -> dict:
+def load_configuration_from_env(env_vars: dict[str, Any]) -> dict:
     """
     Parses environment variables and returns a dictionary with the relevant configuration.
     """
@@ -18,6 +18,11 @@ def load_configuration_from_env(env_vars: Dict[str, Any]) -> dict:
             current_level = current_level[next_level]
         last_level[levels[-1]] = value
 
+    if result.get("CONNECTIONSMAP") and isinstance(result["CONNECTIONSMAP"], dict):
+        result["CONNECTIONSMAP"] = [
+            conn for conn in result.get("CONNECTIONSMAP", {}).values()
+        ]
+
     return {
         "AGENTAPPLICATION": result.get("AGENTAPPLICATION", {}),
         "CONNECTIONS": result.get("CONNECTIONS", {}),

microsoft_agents_activity-0.4.0/microsoft_agents/activity/_model_utils.py

@@ -0,0 +1,61 @@
+from abc import ABC
+from typing import Any, Callable
+
+from .agents_model import AgentsModel
+
+
+class ModelFieldHelper(ABC):
+    """Base class for model field processing prior to initialization of an AgentsModel"""
+
+    def process(self, key: str) -> dict[str, Any]:
+        """Takes the key in the destination object and returns a dictionary of new fields to add"""
+        raise NotImplementedError()
+
+
+class SkipIf(ModelFieldHelper):
+    """Skip if the value meets the given condition."""
+
+    def __init__(self, value, skip_condition: Callable[[Any], bool]):
+        self.value = value
+        self._skip_condition = skip_condition
+
+    def process(self, key: str) -> dict[str, Any]:
+        if self._skip_condition(self.value):
+            return {}
+        return {key: self.value}
+
+
+class SkipNone(SkipIf):
+    """Skip if the value is None."""
+
+    def __init__(self, value):
+        super().__init__(value, lambda v: v is None)
+
+
+def pick_model_dict(**kwargs):
+    """Processes a list of keyword arguments, using ModelFieldHelper subclasses to determine which fields to include in the final model.
+
+    This function is useful for dynamically constructing models based on varying input data.
+
+    Usage:
+        activity_dict = pick_model_dict(type="message", id="123", text=SkipNone(text_variable))
+        activity = Activity.model_validate(activity_dict)
+    """
+
+    model_dict = {}
+    for key, value in kwargs.items():
+        if not isinstance(value, ModelFieldHelper):
+            model_dict[key] = value
+        else:
+            model_dict.update(value.process(key))
+
+    return model_dict
+
+
+def pick_model(model_class: type[AgentsModel], **kwargs) -> AgentsModel:
+    """Picks model fields from the given keyword arguments.
+
+    Usage:
+        activity = pick_model(Activity, type="message", id="123", text=SkipNone(text_variable))
+    """
+    return model_class(**pick_model_dict(**kwargs))

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/_type_aliases.py

@@ -1,5 +1,4 @@
 from typing import Annotated
 from pydantic import StringConstraints
 
-
 NonEmptyString = Annotated[str, StringConstraints(min_length=1)]

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/activity.py

@@ -5,16 +5,23 @@ from pydantic import Field, SerializeAsAny
 from .activity_types import ActivityTypes
 from .channel_account import ChannelAccount
 from .conversation_account import ConversationAccount
-from .mention import Mention
 from .message_reaction import MessageReaction
 from .resource_response import ResourceResponse
 from .suggested_actions import SuggestedActions
 from .attachment import Attachment
-from .entity import Entity
+from .entity import (
+    Entity,
+    Mention,
+    AIEntity,
+    ClientCitation,
+    SensitivityUsageInfo,
+)
 from .conversation_reference import ConversationReference
 from .text_highlight import TextHighlight
 from .semantic_action import SemanticAction
 from .agents_model import AgentsModel
+from .role_types import RoleTypes
+from ._model_utils import pick_model, SkipNone
 from ._type_aliases import NonEmptyString
 
 
@@ -390,32 +397,31 @@ class Activity(AgentsModel):
         .. remarks::
             The new activity sets up routing information based on this activity.
         """
-        return Activity(
+        return pick_model(
+            Activity,
             type=ActivityTypes.message,
             timestamp=datetime.now(timezone.utc),
-            from_property=ChannelAccount(
-                id=self.recipient.id if self.recipient else None,
-                name=self.recipient.name if self.recipient else None,
+            from_property=SkipNone(
+                ChannelAccount.pick_properties(self.recipient, ["id", "name"])
             ),
-            recipient=ChannelAccount(
-                id=self.from_property.id if self.from_property else None,
-                name=self.from_property.name if self.from_property else None,
+            recipient=SkipNone(
+                ChannelAccount.pick_properties(self.from_property, ["id", "name"])
             ),
             reply_to_id=(
-                self.id
+                SkipNone(self.id)
                 if type != ActivityTypes.conversation_update
                 or self.channel_id not in ["directline", "webchat"]
                 else None
             ),
             service_url=self.service_url,
             channel_id=self.channel_id,
-            conversation=ConversationAccount(
-                is_group=self.conversation.is_group,
-                id=self.conversation.id,
-                name=self.conversation.name,
+            conversation=SkipNone(
+                ConversationAccount.pick_properties(
+                    self.conversation, ["is_group", "id", "name"]
+                )
             ),
             text=text if text else "",
-            locale=locale if locale else self.locale,
+            locale=locale if locale else SkipNone(self.locale),
             attachments=[],
             entities=[],
         )
@@ -434,36 +440,35 @@ class Activity(AgentsModel):
         :returns: The new trace activity.
         """
         if not value_type and value:
-            value_type = type(value)
+            value_type = type(value).__name__
 
-        return Activity(
+        return pick_model(
+            Activity,
             type=ActivityTypes.trace,
             timestamp=datetime.now(timezone.utc),
-            from_property=ChannelAccount(
-                id=self.recipient.id if self.recipient else None,
-                name=self.recipient.name if self.recipient else None,
+            from_property=SkipNone(
+                ChannelAccount.pick_properties(self.recipient, ["id", "name"])
             ),
-            recipient=ChannelAccount(
-                id=self.from_property.id if self.from_property else None,
-                name=self.from_property.name if self.from_property else None,
+            recipient=SkipNone(
+                ChannelAccount.pick_properties(self.from_property, ["id", "name"])
             ),
             reply_to_id=(
-                self.id
+                SkipNone(self.id)  # preserve unset
                 if type != ActivityTypes.conversation_update
                 or self.channel_id not in ["directline", "webchat"]
                 else None
             ),
             service_url=self.service_url,
             channel_id=self.channel_id,
-            conversation=ConversationAccount(
-                is_group=self.conversation.is_group,
-                id=self.conversation.id,
-                name=self.conversation.name,
+            conversation=SkipNone(
+                ConversationAccount.pick_properties(
+                    self.conversation, ["is_group", "id", "name"]
+                )
             ),
-            name=name,
-            label=label,
-            value_type=value_type,
-            value=value,
+            name=SkipNone(name),
+            label=SkipNone(label),
+            value_type=SkipNone(value_type),
+            value=SkipNone(value),
         ).as_trace_activity()
 
     @staticmethod
@@ -481,14 +486,15 @@ class Activity(AgentsModel):
         :returns: The new trace activity.
         """
         if not value_type and value:
-            value_type = type(value)
+            value_type = type(value).__name__
 
-        return Activity(
+        return pick_model(
+            Activity,
             type=ActivityTypes.trace,
             name=name,
-            label=label,
-            value_type=value_type,
-            value=value,
+            label=SkipNone(label),
+            value_type=SkipNone(value_type),
+            value=SkipNone(value),
         )
 
     @staticmethod
@@ -506,10 +512,10 @@ class Activity(AgentsModel):
 
         :returns: A conversation reference for the conversation that contains this activity.
         """
-
-        return ConversationReference(
+        return pick_model(
+            ConversationReference,
             activity_id=(
-                self.id
+                SkipNone(self.id)
                 if self.type != ActivityTypes.conversation_update
                 or self.channel_id not in ["directline", "webchat"]
                 else None
@@ -532,8 +538,9 @@ class Activity(AgentsModel):
             This method is defined on the :class:`Activity` class, but is only intended for use with a message activity,
             where the activity Activity.Type is set to ActivityTypes.Message.
         """
-        _list = self.entities
-        return [x for x in _list if str(x.type).lower() == "mention"]
+        if not self.entities:
+            return []
+        return [x for x in self.entities if x.type.lower() == "mention"]
 
     def get_reply_conversation_reference(
         self, reply: ResourceResponse
@@ -596,7 +603,7 @@ class Activity(AgentsModel):
         if self.type is None:
             return False
 
-        type_attribute = str(self.type).lower()
+        type_attribute = f"ActivityTypes.{str(self.type)}".lower()
         activity_type = str(activity_type).lower()
 
         result = type_attribute.startswith(activity_type)
@@ -611,3 +618,50 @@ class Activity(AgentsModel):
                 )
 
         return result
+
+    def add_ai_metadata(
+        self,
+        citations: Optional[list[ClientCitation]] = None,
+        usage_info: Optional[SensitivityUsageInfo] = None,
+    ) -> None:
+        """
+        Adds AI entity to an activity to indicate AI-generated content.
+
+        Args:
+            activity: The activity to modify
+            citations: Optional list of citations
+            usage_info: Optional sensitivity usage information
+        """
+        if citations:
+            ai_entity = AIEntity(
+                type="https://schema.org/Message",
+                schema_type="Message",
+                context="https://schema.org",
+                id="",
+                additional_type=["AIGeneratedContent"],
+                citation=citations,
+                usage_info=usage_info,
+            )
+
+            if self.entities is None:
+                self.entities = []
+
+            self.entities.append(ai_entity)
+
+    def is_agentic_request(self) -> bool:
+        return self.recipient and self.recipient.role in [
+            RoleTypes.agentic_identity,
+            RoleTypes.agentic_user,
+        ]
+
+    def get_agentic_instance_id(self) -> Optional[str]:
+        """Gets the agent instance ID from the context if it's an agentic request."""
+        if not self.is_agentic_request() or not self.recipient:
+            return None
+        return self.recipient.agentic_app_id
+
+    def get_agentic_user(self) -> Optional[str]:
+        """Gets the agentic user (UPN) from the context if it's an agentic request."""
+        if not self.is_agentic_request() or not self.recipient:
+            return None
+        return self.recipient.id

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/adaptive_card_invoke_value.py

@@ -10,9 +10,9 @@ class AdaptiveCardInvokeValue(AgentsModel):
     Defines the structure that arrives in the Activity.Value for Invoke activity with Name of 'adaptiveCard/action'.
 
     :param action: The action of this adaptive card invoke action value.
-    :type action: :class:`microsoft_agents.activity.models.AdaptiveCardInvokeAction`
+    :type action: :class:`microsoft_agents.activity.adaptive_card_invoke_action.AdaptiveCardInvokeAction`
     :param authentication: The TokenExchangeInvokeRequest for this adaptive card invoke action value.
-    :type authentication: :class:`microsoft_agents.activity.models.TokenExchangeInvokeRequest`
+    :type authentication: :class:`microsoft_agents.activity.token_exchange_invoke_request.TokenExchangeInvokeRequest`
     :param state: The 'state' or magic code for an OAuth flow.
     :type state: str
     """

microsoft_agents_activity-0.4.0/microsoft_agents/activity/agents_model.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+class AgentsModel(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    """
+    @model_serializer
+    def _serialize(self):
+        omit_if_empty = {
+            k
+            for k, v in self
+            if isinstance(v, list) and not v
+        }
+
+        return {k: v for k, v in self if k not in omit_if_empty and v is not None}
+    """
+
+    @classmethod
+    def pick_properties(cls, original: AgentsModel, fields_to_copy=None, **kwargs):
+        """Picks properties from the original model and returns a new instance (of a possibly different AgentsModel) with those properties.
+
+        This method preserves unset values.
+
+        args:
+            original: The original model instance to copy properties from. If None, returns None.
+            fields_to_copy: The specific fields to copy. If None, all fields are copied.
+            **kwargs: Additional fields to include in the new instance.
+        """
+        if not original:
+            return None
+
+        if fields_to_copy is None:
+            fields_to_copy = original.model_fields_set
+        else:
+            fields_to_copy = original.model_fields_set & set(fields_to_copy)
+
+        dest = {}
+        for field in fields_to_copy:
+            dest[field] = getattr(original, field)
+
+        dest.update(kwargs)
+        return cls.model_validate(dest)

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/animation_card.py

@@ -42,7 +42,7 @@ class AnimationCard(AgentsModel):
 
     title: NonEmptyString = None
     subtitle: NonEmptyString = None
-    text: NonEmptyString = None
+    text: str = None
     image: ThumbnailUrl = None
     media: list[MediaUrl] = None
     buttons: list[CardAction] = None

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/audio_card.py

@@ -42,7 +42,7 @@ class AudioCard(AgentsModel):
 
     title: NonEmptyString = None
     subtitle: NonEmptyString = None
-    text: NonEmptyString = None
+    text: str = None
     image: ThumbnailUrl = None
     media: list[MediaUrl] = None
     buttons: list[CardAction] = None

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/basic_card.py

@@ -24,7 +24,7 @@ class BasicCard(AgentsModel):
 
     title: NonEmptyString = None
     subtitle: NonEmptyString = None
-    text: NonEmptyString = None
+    text: str = None
     images: list[CardImage] = None
     buttons: list[CardAction] = None
     tap: CardAction = None

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/channel_account.py

@@ -26,6 +26,9 @@ class ChannelAccount(AgentsModel):
     name: str = None
     aad_object_id: NonEmptyString = None
     role: NonEmptyString = None
+    agentic_user_id: NonEmptyString = None
+    agentic_app_id: NonEmptyString = None
+    tenant_id: NonEmptyString = None
 
     @property
     def properties(self) -> dict[str, Any]:

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/channels.py

@@ -10,6 +10,9 @@ class Channels(str, Enum):
     Ids of channels supported by ABS.
     """
 
+    """Agents channel."""
+    agents = "agents"
+
     console = "console"
     """Console channel."""
 

microsoft_agents_activity-0.4.0/microsoft_agents/activity/entity/__init__.py

@@ -0,0 +1,29 @@
+from .mention import Mention
+from .entity import Entity
+from .ai_entity import (
+    ClientCitation,
+    ClientCitationAppearance,
+    ClientCitationImage,
+    ClientCitationIconName,
+    AIEntity,
+    SensitivityPattern,
+    SensitivityUsageInfo,
+)
+from .geo_coordinates import GeoCoordinates
+from .place import Place
+from .thing import Thing
+
+__all__ = [
+    "Entity",
+    "AIEntity",
+    "ClientCitation",
+    "ClientCitationAppearance",
+    "ClientCitationImage",
+    "ClientCitationIconName",
+    "Mention",
+    "SensitivityUsageInfo",
+    "SensitivityPattern",
+    "GeoCoordinates",
+    "Place",
+    "Thing",
+]

{microsoft_agents_activity-0.3.2/microsoft_agents/activity → microsoft_agents_activity-0.4.0/microsoft_agents/activity/entity}/ai_entity.py

@@ -5,8 +5,7 @@ from enum import Enum
 from typing import List, Optional, Union, Literal
 from dataclasses import dataclass
 
-from .agents_model import AgentsModel
-from .activity import Activity
+from ..agents_model import AgentsModel
 from .entity import Entity
 
 
@@ -110,33 +109,3 @@ class AIEntity(Entity):
     def __post_init__(self):
         if self.additional_type is None:
             self.additional_type = ["AIGeneratedContent"]
-
-
-def add_ai_to_activity(
-    activity: Activity,
-    citations: Optional[List[ClientCitation]] = None,
-    usage_info: Optional[SensitivityUsageInfo] = None,
-) -> None:
-    """
-    Adds AI entity to an activity to indicate AI-generated content.
-
-    Args:
-        activity: The activity to modify
-        citations: Optional list of citations
-        usage_info: Optional sensitivity usage information
-    """
-    if citations:
-        ai_entity = AIEntity(
-            type="https://schema.org/Message",
-            schema_type="Message",
-            context="https://schema.org",
-            id="",
-            additional_type=["AIGeneratedContent"],
-            citation=citations,
-            usage_info=usage_info,
-        )
-
-        if activity.entities is None:
-            activity.entities = []
-
-        activity.entities.append(ai_entity)

{microsoft_agents_activity-0.3.2/microsoft_agents/activity → microsoft_agents_activity-0.4.0/microsoft_agents/activity/entity}/entity.py

@@ -1,9 +1,11 @@
 from typing import Any, Optional
+from enum import Enum
 
 from pydantic import model_serializer, model_validator
-from .agents_model import AgentsModel, ConfigDict
 from pydantic.alias_generators import to_camel, to_snake
-from ._type_aliases import NonEmptyString
+
+from ..agents_model import AgentsModel, ConfigDict
+from .._type_aliases import NonEmptyString
 
 
 class Entity(AgentsModel):
@@ -15,7 +17,7 @@ class Entity(AgentsModel):
 
     model_config = ConfigDict(extra="allow")
 
-    type: NonEmptyString
+    type: str
 
     @property
     def additional_properties(self) -> dict[str, Any]:

{microsoft_agents_activity-0.3.2/microsoft_agents/activity → microsoft_agents_activity-0.4.0/microsoft_agents/activity/entity}/geo_coordinates.py

@@ -1,5 +1,5 @@
-from .agents_model import AgentsModel
-from ._type_aliases import NonEmptyString
+from ..agents_model import AgentsModel
+from .._type_aliases import NonEmptyString
 
 
 class GeoCoordinates(AgentsModel):

{microsoft_agents_activity-0.3.2/microsoft_agents/activity → microsoft_agents_activity-0.4.0/microsoft_agents/activity/entity}/mention.py

@@ -1,6 +1,8 @@
-from .channel_account import ChannelAccount
+from typing import Literal
+
+from ..channel_account import ChannelAccount
 from .entity import Entity
-from ._type_aliases import NonEmptyString
+from .._type_aliases import NonEmptyString
 
 
 class Mention(Entity):
@@ -15,5 +17,5 @@ class Mention(Entity):
     """
 
     mentioned: ChannelAccount = None
-    text: NonEmptyString = None
-    type: NonEmptyString = None
+    text: str = None
+    type: Literal["mention"] = "mention"

{microsoft_agents_activity-0.3.2/microsoft_agents/activity → microsoft_agents_activity-0.4.0/microsoft_agents/activity/entity}/place.py

@@ -1,5 +1,5 @@
-from .agents_model import AgentsModel
-from ._type_aliases import NonEmptyString
+from ..agents_model import AgentsModel
+from .._type_aliases import NonEmptyString
 
 
 class Place(AgentsModel):

{microsoft_agents_activity-0.3.2/microsoft_agents/activity → microsoft_agents_activity-0.4.0/microsoft_agents/activity/entity}/thing.py

@@ -1,5 +1,5 @@
-from .agents_model import AgentsModel
-from ._type_aliases import NonEmptyString
+from ..agents_model import AgentsModel
+from .._type_aliases import NonEmptyString
 
 
 class Thing(AgentsModel):

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/hero_card.py

@@ -24,7 +24,7 @@ class HeroCard(AgentsModel):
 
     title: NonEmptyString = None
     subtitle: NonEmptyString = None
-    text: NonEmptyString = None
+    text: str = None
     images: list[CardImage] = None
     buttons: list[CardAction] = None
     tap: CardAction = None

{microsoft_agents_activity-0.3.2 → microsoft_agents_activity-0.4.0}/microsoft_agents/activity/media_card.py

@@ -42,7 +42,7 @@ class MediaCard(AgentsModel):
 
     title: NonEmptyString = None
     subtitle: NonEmptyString = None
-    text: NonEmptyString = None
+    text: str = None
     image: ThumbnailUrl = None
     media: list[MediaUrl] = None
     buttons: list[CardAction] = None