microsoft-agents-hosting-core 0.4.0.dev7__py3-none-any.whl → 0.4.0.dev10__py3-none-any.whl

microsoft_agents/hosting/core/storage/__init__.py

@@ -1,5 +1,24 @@
 from .store_item import StoreItem
 from .storage import Storage, AsyncStorageBase
 from .memory_storage import MemoryStorage
+from .transcript_info import TranscriptInfo
+from .transcript_logger import (
+    TranscriptLogger,
+    ConsoleTranscriptLogger,
+    TranscriptLoggerMiddleware,
+    FileTranscriptLogger,
+)
+from .transcript_store import TranscriptStore
 
-__all__ = ["StoreItem", "Storage", "AsyncStorageBase", "MemoryStorage"]
+__all__ = [
+    "StoreItem",
+    "Storage",
+    "AsyncStorageBase",
+    "MemoryStorage",
+    "TranscriptInfo",
+    "TranscriptLogger",
+    "ConsoleTranscriptLogger",
+    "TranscriptLoggerMiddleware",
+    "TranscriptStore",
+    "FileTranscriptLogger",
+]

microsoft_agents/hosting/core/storage/transcript_info.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from datetime import datetime, timezone
+from dataclasses import dataclass
+
+
+@dataclass
+class TranscriptInfo:
+    channel_id: str = ""
+    conversation_id: str = ""
+    created_on: datetime = datetime.min.replace(tzinfo=timezone.utc)

microsoft_agents/hosting/core/storage/transcript_logger.py

@@ -0,0 +1,209 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+import copy
+import random
+import string
+import json
+
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from queue import Queue
+from typing import Awaitable, Callable, List, Optional
+
+from microsoft_agents.activity import Activity, ChannelAccount
+from microsoft_agents.activity.activity import ConversationReference
+from microsoft_agents.activity.activity_types import ActivityTypes
+from microsoft_agents.activity.conversation_reference import ActivityEventNames
+from microsoft_agents.hosting.core.middleware_set import Middleware, TurnContext
+
+
+class TranscriptLogger(ABC):
+    @abstractmethod
+    async def log_activity(self, activity: Activity) -> None:
+        """
+        Asynchronously logs an activity.
+
+        :param activity: The activity to log.
+        """
+        pass
+
+
+class ConsoleTranscriptLogger(TranscriptLogger):
+    """
+    ConsoleTranscriptLogger writes activities to Console output. This is a DEBUG class, intended for testing
+    and log tailing
+    """
+
+    async def log_activity(self, activity: Activity) -> None:
+        """Log an activity to the transcript.
+        :param activity:Activity being logged.
+        """
+        if not activity:
+            raise TypeError("Activity is required")
+
+        json_data = activity.model_dump_json()
+        parsed = json.loads(json_data)
+        print(json.dumps(parsed, indent=4))
+
+
+class FileTranscriptLogger(TranscriptLogger):
+    """
+    A TranscriptLogger implementation that appends each activity as JSON to a file. This class appends
+    each activity to the given file using basic formatting. This is a DEBUG class, intended for testing
+    and log tailing.
+    """
+
+    def __init__(self, file_path: str, encoding: Optional[str] = "utf-8"):
+        """
+        Initializes the FileTranscriptLogger and opens the file for appending.
+
+        :param file_path: Path to the transcript log file.
+        :param encoding: File encoding (default: utf-8).
+        """
+        self.file_path = file_path
+        self.encoding = encoding
+
+        # Open file in append mode to ensure it exists
+        self._file = open(self.file_path, "a", encoding=self.encoding)
+
+    async def log_activity(self, activity: Activity) -> None:
+        """
+        Appends the given activity as a JSON line to the file. This method pretty-prints the JSON for readability, which makes
+        it non-performant. For production scenarios, consider a more efficient logging mechanism.
+
+        :param activity: The Activity object to log.
+        """
+        if not activity:
+            raise TypeError("Activity is required")
+
+        json_data = activity.model_dump_json()
+        parsed = json.loads(json_data)
+
+        self._file.write(json.dumps(parsed, indent=4))
+
+        # As this is a logging / debugging class, we want to ensure the data is written out immediately. This is another
+        # consideration that makes this class non-performant for production scenarios.
+        self._file.flush()
+
+    def __del__(self):
+        if hasattr(self, "_file"):
+            self._file.close()
+
+
+class TranscriptLoggerMiddleware(Middleware):
+    """Logs incoming and outgoing activities to a TranscriptLogger."""
+
+    def __init__(self, logger: TranscriptLogger):
+        if not logger:
+            raise TypeError(
+                "TranscriptLoggerMiddleware requires a TranscriptLogger instance."
+            )
+
+        self.logger = logger
+
+    async def on_turn(
+        self, context: TurnContext, logic: Callable[[TurnContext], Awaitable]
+    ):
+        """Initialization for middleware.
+        :param context: Context for the current turn of conversation with the user.
+        :param logic: Function to call at the end of the middleware chain.
+        """
+        transcript = Queue()
+        activity = context.activity
+        # Log incoming activity at beginning of turn
+        if activity:
+            if not activity.from_property:
+                activity.from_property = ChannelAccount()
+            if not activity.from_property.role:
+                activity.from_property.role = "user"
+
+            # We should not log ContinueConversation events used by skills to initialize the middleware.
+            if not (
+                context.activity.type == ActivityTypes.event
+                and context.activity.name == ActivityEventNames.continue_conversation
+            ):
+                await self._queue_activity(transcript, copy.copy(activity))
+
+        # hook up onSend pipeline
+        # pylint: disable=unused-argument
+        async def send_activities_handler(
+            ctx: TurnContext,
+            activities: List[Activity],
+            next_send: Callable[[], Awaitable[None]],
+        ):
+            # Run full pipeline
+            responses = await next_send()
+            for index, activity in enumerate(activities):
+                cloned_activity = copy.copy(activity)
+                if responses and index < len(responses):
+                    cloned_activity.id = responses[index].id
+
+                # For certain channels, a ResourceResponse with an id is not always sent to the bot.
+                # This fix uses the timestamp on the activity to populate its id for logging the transcript
+                # If there is no outgoing timestamp, the current time for the bot is used for the activity.id
+                if not cloned_activity.id:
+                    alphanumeric = string.ascii_lowercase + string.digits
+                    prefix = "g_" + "".join(
+                        random.choice(alphanumeric) for i in range(5)
+                    )
+                    epoch = datetime.fromtimestamp(0, timezone.utc)
+                    if cloned_activity.timestamp:
+                        reference = cloned_activity.timestamp
+                    else:
+                        reference = datetime.now(timezone.utc)
+                    delta = (reference - epoch).total_seconds() * 1000
+                    cloned_activity.id = f"{prefix}{delta}"
+                await self._queue_activity(transcript, cloned_activity)
+            return responses
+
+        context.on_send_activities(send_activities_handler)
+
+        # hook up update activity pipeline
+        async def update_activity_handler(
+            ctx: TurnContext, activity: Activity, next_update: Callable[[], Awaitable]
+        ):
+            # Run full pipeline
+            response = await next_update()
+            update_activity = copy.copy(activity)
+            update_activity.type = ActivityTypes.message_update
+            await self._queue_activity(transcript, update_activity)
+            return response
+
+        context.on_update_activity(update_activity_handler)
+
+        # hook up delete activity pipeline
+        async def delete_activity_handler(
+            ctx: TurnContext,
+            reference: ConversationReference,
+            next_delete: Callable[[], Awaitable],
+        ):
+            # Run full pipeline
+            await next_delete()
+
+            delete_msg = Activity(
+                type=ActivityTypes.message_delete, id=reference.activity_id
+            )
+            deleted_activity: Activity = TurnContext.apply_conversation_reference(
+                delete_msg, reference, False
+            )
+            await self._queue_activity(transcript, deleted_activity)
+
+        context.on_delete_activity(delete_activity_handler)
+
+        if logic:
+            await logic()
+
+        # Flush transcript at end of turn
+        while not transcript.empty():
+            activity = transcript.get()
+            if activity is None:
+                break
+            await self.logger.log_activity(activity)
+            transcript.task_done()
+
+    async def _queue_activity(self, transcript: Queue, activity: Activity) -> None:
+        """Logs the activity.
+        :param transcript: transcript.
+        :param activity: Activity to log.
+        """
+        transcript.put(activity)

microsoft_agents/hosting/core/storage/transcript_memory_store.py

@@ -0,0 +1,154 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from threading import Lock
+from datetime import datetime, timezone
+from typing import List
+from .transcript_logger import TranscriptLogger
+from .transcript_info import TranscriptInfo
+from microsoft_agents.activity import Activity
+
+
+class TranscriptMemoryStore(TranscriptLogger):
+    """
+    An in-memory implementation of the TranscriptLogger for storing and retrieving activities.
+
+    This class is thread-safe and stores all activities in a list. It supports logging activities,
+    retrieving activities for a specific channel and conversation, and filtering by timestamp.
+    Activities with a None timestamp are treated as the earliest possible datetime.
+
+    Note: This class is intended for testing and prototyping purposes only. It does not persist
+    data and is not suitable for production use. This store will also grow without bound over
+    time, making it especially unsuited for production use.
+    """
+
+    def __init__(self):
+        """
+        Initializes the TranscriptMemoryStore.
+        """
+        self._transcript = []
+        self.lock = Lock()
+
+    async def log_activity(self, activity: Activity) -> None:
+        """
+        Asynchronously logs an activity to the in-memory transcript.
+
+        :param activity: The Activity object to log. Must have a valid conversation and conversation id.
+        :raises ValueError: If activity, activity.conversation, or activity.conversation.id is None.
+        """
+        if not activity:
+            raise ValueError("Activity cannot be None")
+        if not activity.conversation:
+            raise ValueError("Activity.Conversation cannot be None")
+        if not activity.conversation.id:
+            raise ValueError("Activity.Conversation.id cannot be None")
+
+        with self.lock:
+            self._transcript.append(activity)
+
+    async def get_transcript_activities(
+        self,
+        channel_id: str,
+        conversation_id: str,
+        continuation_token: str = None,
+        start_date: datetime = datetime.min.replace(tzinfo=timezone.utc),
+    ) -> tuple[list[Activity], str]:
+        """
+        Retrieves activities for a given channel and conversation, optionally filtered by start_date.
+
+        :param channel_id: The channel ID to filter activities.
+        :param conversation_id: The conversation ID to filter activities.
+        :param continuation_token: (Unused) Token for pagination.
+        :param start_date: Only activities with timestamp >= start_date are returned. None timestamps are treated as datetime.min.
+        :return: A tuple containing the filtered list of Activity objects and a continuation token (always None).
+        :raises ValueError: If channel_id or conversation_id is None.
+        """
+        if not channel_id:
+            raise ValueError("channel_id cannot be None")
+        if not conversation_id:
+            raise ValueError("conversation_id cannot be None")
+
+        with self.lock:
+            # Get the activities that match on channel and conversation id
+            relevant_activities = [
+                a
+                for a in self._transcript
+                if a.channel_id == channel_id
+                and a.conversation
+                and a.conversation.id == conversation_id
+            ]
+            # sort these by timestamp, treating None as datetime.min
+            sorted_relevant_activities = sorted(
+                relevant_activities,
+                key=lambda a: (
+                    a.timestamp
+                    if a.timestamp is not None
+                    else datetime.min.replace(tzinfo=timezone.utc)
+                ),
+            )
+            # grab the ones bigger than the requested start date, treating None as datetime.min
+            filtered_sorted_activities = [
+                a
+                for a in sorted_relevant_activities
+                if (
+                    a.timestamp
+                    if a.timestamp is not None
+                    else datetime.min.replace(tzinfo=timezone.utc)
+                )
+                >= start_date
+            ]
+
+            return filtered_sorted_activities, None
+
+    async def delete_transcript(self, channel_id: str, conversation_id: str) -> None:
+        """
+        Deletes all activities for a given channel and conversation from the in-memory transcript.
+
+        :param channel_id: The channel ID whose transcript should be deleted.
+        :param conversation_id: The conversation ID whose transcript should be deleted.
+        :raises ValueError: If channel_id or conversation_id is None.
+        """
+        if not channel_id:
+            raise ValueError("channel_id cannot be None")
+        if not conversation_id:
+            raise ValueError("conversation_id cannot be None")
+
+        with self.lock:
+            self._transcript = [
+                a
+                for a in self._transcript
+                if not (
+                    a.channel_id == channel_id
+                    and a.conversation
+                    and a.conversation.id == conversation_id
+                )
+            ]
+
+    async def list_transcripts(
+        self, channel_id: str, continuation_token: str = None
+    ) -> tuple[list[TranscriptInfo], str]:
+        """
+        Lists all transcripts (unique conversation IDs) for a given channel.
+
+        :param channel_id: The channel ID to list transcripts for.
+        :param continuation_token: (Unused) Token for pagination.
+        :return: A tuple containing a list of TranscriptInfo objects and a continuation token (always None).
+        :raises ValueError: If channel_id is None.
+        """
+        if not channel_id:
+            raise ValueError("channel_id cannot be None")
+
+        with self.lock:
+            relevant_activities = [
+                a for a in self._transcript if a.channel_id == channel_id
+            ]
+            conversations = set(
+                a.conversation.id
+                for a in relevant_activities
+                if a.conversation and a.conversation.id
+            )
+            transcript_infos = [
+                TranscriptInfo(channel_id=channel_id, conversation_id=conversation_id)
+                for conversation_id in conversations
+            ]
+            return transcript_infos, None

microsoft_agents/hosting/core/storage/transcript_store.py

@@ -0,0 +1,52 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from microsoft_agents.activity import Activity
+from .transcript_info import TranscriptInfo
+from .transcript_logger import TranscriptLogger
+
+
+class TranscriptStore(TranscriptLogger):
+    @abstractmethod
+    async def get_transcript_activities(
+        self,
+        channel_id: str,
+        conversation_id: str,
+        continuation_token: str = None,
+        start_date: datetime = datetime.min.replace(tzinfo=timezone.utc),
+    ) -> tuple[list[Activity], str]:
+        """
+        Asynchronously retrieves activities from a transcript.
+
+        :param channel_id: The channel ID of the conversation.
+        :param conversation_id: The conversation ID.
+        :param continuation_token: (Optional) A token to continue retrieving activities from a specific point.
+        :param start_date: (Optional) The start date to filter activities.
+        :return: A tuple containing a list of activities and a continuation token.
+        """
+        pass
+
+    @abstractmethod
+    async def list_transcripts(
+        self, channel_id: str, continuation_token: str = None
+    ) -> tuple[list[TranscriptInfo, str]]:
+        """
+        Asynchronously lists transcripts for a given channel.
+
+        :param channel_id: The channel ID to list transcripts for.
+        :param continuation_token: (Optional) A token to continue listing transcripts from a specific point.
+        :return: A tuple containing a list of transcripts and a continuation token.
+        """
+        pass
+
+    @abstractmethod
+    async def delete_transcript(self, channel_id: str, conversation_id: str) -> None:
+        """
+        Asynchronously deletes a transcript.
+
+        :param channel_id: The channel ID of the conversation.
+        :param conversation_id: The conversation ID.
+        """
+        pass

{microsoft_agents_hosting_core-0.4.0.dev7.dist-info → microsoft_agents_hosting_core-0.4.0.dev10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-hosting-core
-Version: 0.4.0.dev7
+Version: 0.4.0.dev10
 Summary: Core library for Microsoft Agents
 Author: Microsoft Corporation
 Project-URL: Homepage, https://github.com/microsoft/Agents
@@ -8,7 +8,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
-Requires-Dist: microsoft-agents-activity==0.4.0.dev7
+Requires-Dist: microsoft-agents-activity==0.4.0.dev10
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: isodate>=0.6.1
 Requires-Dist: azure-core>=1.30.0

{microsoft_agents_hosting_core-0.4.0.dev7.dist-info → microsoft_agents_hosting_core-0.4.0.dev10.dist-info}/RECORD

@@ -70,13 +70,17 @@ microsoft_agents/hosting/core/state/__init__.py,sha256=yckKi1wg_86ng-DL9Q3R49QiW
 microsoft_agents/hosting/core/state/agent_state.py,sha256=-6kHxVCl6oUT-XjDXkPOPw0fD227Uy3zNzqMInwFeJc,12891
 microsoft_agents/hosting/core/state/state_property_accessor.py,sha256=kpiNnzkZ6el-oRITRbRkk1Faa_CPFxpJQdvSGxIJP70,1392
 microsoft_agents/hosting/core/state/user_state.py,sha256=zEigX-sroNAyoQAxQjG1OgmJQKjk1zOkdeqylFg7M2E,1484
-microsoft_agents/hosting/core/storage/__init__.py,sha256=wq8zlkoPG6I8PfMvdGPN-tNCdP905W7jylFrmJ-GF6o,196
+microsoft_agents/hosting/core/storage/__init__.py,sha256=X2jWX0qc2YdFNhwOct5Q7VJ9Q5VnOpKB0RqC7HG2_Qs,611
 microsoft_agents/hosting/core/storage/_type_aliases.py,sha256=VCKtjiCBrhEsGSm3zVVSSccdoiY02GYhABvrLjhAcz8,72
 microsoft_agents/hosting/core/storage/error_handling.py,sha256=zH34d7s4pJG_uajpBWhrtTpH2eMy88kSKaqvOqtbgzY,1265
 microsoft_agents/hosting/core/storage/memory_storage.py,sha256=NADem1wQE1MOG1qMriYw4NjILHEBDbIG5HT6wvHfG2M,2353
 microsoft_agents/hosting/core/storage/storage.py,sha256=vft_Kw4pkzo8NnBEyDx7gAn1Ndg2I9ePaxnuxbKVHzs,3227
 microsoft_agents/hosting/core/storage/store_item.py,sha256=4LSkuI0H0lgWig88YoHFn6BP8Bx44YbyuvqBvaBNdEM,276
-microsoft_agents_hosting_core-0.4.0.dev7.dist-info/METADATA,sha256=ZN0PIPhdhiWZnl9MabdpEYhcd9XqRApnnrMB-kPM-lk,584
-microsoft_agents_hosting_core-0.4.0.dev7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-microsoft_agents_hosting_core-0.4.0.dev7.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
-microsoft_agents_hosting_core-0.4.0.dev7.dist-info/RECORD,,
+microsoft_agents/hosting/core/storage/transcript_info.py,sha256=5VN32j99tshChAffvuZ6D3GH3ABCZsQGHC_bYDAwFOk,328
+microsoft_agents/hosting/core/storage/transcript_logger.py,sha256=PxAZTZVFRC2q_i1JABo-JFOPEv9QyXCMe5wZdiiq6_g,8007
+microsoft_agents/hosting/core/storage/transcript_memory_store.py,sha256=xdX4CtyDczN5jCoi-ZtXzBZq52ahsk3IQ_Y6qkmub8U,6323
+microsoft_agents/hosting/core/storage/transcript_store.py,sha256=ka74o0WvI5GhMZcFqSxVdamBhGzZcDZe6VNkG-sMy74,1944
+microsoft_agents_hosting_core-0.4.0.dev10.dist-info/METADATA,sha256=jLXmnVD1NnbBccGs57HhKye8o-c_d2ikm-hYHbjCckg,586
+microsoft_agents_hosting_core-0.4.0.dev10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_agents_hosting_core-0.4.0.dev10.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
+microsoft_agents_hosting_core-0.4.0.dev10.dist-info/RECORD,,