semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/agents/channels/chat_history_channel.py

@@ -0,0 +1,137 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import sys
+from collections import deque
+from collections.abc import AsyncIterable
+
+if sys.version_info >= (3, 12):
+    from typing import override  # pragma: no cover
+else:
+    from typing_extensions import override  # pragma: no cover
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Deque, Protocol, runtime_checkable
+
+from semantic_kernel.agents.channels.agent_channel import AgentChannel
+from semantic_kernel.contents import ChatMessageContent
+from semantic_kernel.contents.chat_history import ChatHistory
+from semantic_kernel.contents.function_call_content import FunctionCallContent
+from semantic_kernel.contents.function_result_content import FunctionResultContent
+from semantic_kernel.exceptions import ServiceInvalidTypeError
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+if TYPE_CHECKING:
+    from semantic_kernel.agents.agent import Agent
+    from semantic_kernel.contents.chat_history import ChatHistory
+    from semantic_kernel.contents.chat_message_content import ChatMessageContent
+    from semantic_kernel.contents.streaming_chat_message_content import StreamingChatMessageContent
+
+
+@experimental_class
+@runtime_checkable
+class ChatHistoryAgentProtocol(Protocol):
+    """Contract for an agent that utilizes a ChatHistoryChannel."""
+
+    @abstractmethod
+    def invoke(self, history: "ChatHistory") -> AsyncIterable["ChatMessageContent"]:
+        """Invoke the chat history agent protocol."""
+        ...
+
+    @abstractmethod
+    def invoke_stream(self, history: "ChatHistory") -> AsyncIterable["StreamingChatMessageContent"]:
+        """Invoke the chat history agent protocol in streaming mode."""
+        ...
+
+
+@experimental_class
+class ChatHistoryChannel(AgentChannel, ChatHistory):
+    """An AgentChannel specialization for that acts upon a ChatHistoryHandler."""
+
+    @override
+    async def invoke(
+        self,
+        agent: "Agent",
+    ) -> AsyncIterable[tuple[bool, ChatMessageContent]]:
+        """Perform a discrete incremental interaction between a single Agent and AgentChat.
+
+        Args:
+            agent: The agent to interact with.
+
+        Returns:
+            An async iterable of ChatMessageContent.
+        """
+        if not isinstance(agent, ChatHistoryAgentProtocol):
+            id = getattr(agent, "id", "")
+            raise ServiceInvalidTypeError(
+                f"Invalid channel binding for agent with id: `{id}` with name: ({type(agent).__name__})"
+            )
+
+        message_count = len(self.messages)
+        mutated_history = set()
+        message_queue: Deque[ChatMessageContent] = deque()
+
+        async for response_message in agent.invoke(self):
+            # Capture all messages that have been included in the mutated history.
+            for message_index in range(message_count, len(self.messages)):
+                mutated_message = self.messages[message_index]
+                mutated_history.add(mutated_message)
+                message_queue.append(mutated_message)
+
+            # Update the message count pointer to reflect the current history.
+            message_count = len(self.messages)
+
+            # Avoid duplicating any message included in the mutated history and also returned by the enumeration result.
+            if response_message not in mutated_history:
+                self.messages.append(response_message)
+                message_queue.append(response_message)
+
+            # Dequeue the next message to yield.
+            yield_message = message_queue.popleft()
+            yield (
+                self._is_message_visible(message=yield_message, message_queue_count=len(message_queue)),
+                yield_message,
+            )
+
+        # Dequeue any remaining messages to yield.
+        while message_queue:
+            yield_message = message_queue.popleft()
+            yield (
+                self._is_message_visible(message=yield_message, message_queue_count=len(message_queue)),
+                yield_message,
+            )
+
+    def _is_message_visible(self, message: ChatMessageContent, message_queue_count: int) -> bool:
+        """Determine if a message is visible to the user."""
+        return (
+            not any(isinstance(item, (FunctionCallContent, FunctionResultContent)) for item in message.items)
+            or message_queue_count == 0
+        )
+
+    @override
+    async def receive(
+        self,
+        history: list[ChatMessageContent],
+    ) -> None:
+        """Receive the conversation messages.
+
+        Args:
+            history: The history of messages in the conversation.
+        """
+        self.messages.extend(history)
+
+    @override
+    async def get_history(  # type: ignore
+        self,
+    ) -> AsyncIterable[ChatMessageContent]:
+        """Retrieve the message history specific to this channel.
+
+        Returns:
+            An async iterable of ChatMessageContent.
+        """
+        for message in reversed(self.messages):
+            yield message
+
+    @override
+    async def reset(self) -> None:
+        """Reset the channel state."""
+        self.messages.clear()

semantic_kernel-1.8.3/semantic_kernel/agents/channels/open_ai_assistant_channel.py

@@ -0,0 +1,97 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import sys
+from collections.abc import AsyncIterable
+from typing import TYPE_CHECKING, Any
+
+from semantic_kernel.contents.function_call_content import FunctionCallContent
+
+if sys.version_info >= (3, 12):
+    from typing import override  # pragma: no cover
+else:
+    from typing_extensions import override  # pragma: no cover
+
+from openai import AsyncOpenAI
+
+from semantic_kernel.agents.channels.agent_channel import AgentChannel
+from semantic_kernel.agents.open_ai.assistant_content_generation import create_chat_message, generate_message_content
+from semantic_kernel.contents.chat_message_content import ChatMessageContent
+from semantic_kernel.exceptions.agent_exceptions import AgentChatException
+
+if TYPE_CHECKING:
+    from semantic_kernel.agents.agent import Agent
+
+
+class OpenAIAssistantChannel(AgentChannel):
+    """OpenAI Assistant Channel."""
+
+    def __init__(self, client: AsyncOpenAI, thread_id: str) -> None:
+        """Initialize the OpenAI Assistant Channel."""
+        self.client = client
+        self.thread_id = thread_id
+
+    @override
+    async def receive(self, history: list["ChatMessageContent"]) -> None:
+        """Receive the conversation messages.
+
+        Args:
+            history: The conversation messages.
+        """
+        for message in history:
+            if any(isinstance(item, FunctionCallContent) for item in message.items):
+                continue
+            await create_chat_message(self.client, self.thread_id, message)
+
+    @override
+    async def invoke(self, agent: "Agent") -> AsyncIterable[tuple[bool, "ChatMessageContent"]]:
+        """Invoke the agent.
+
+        Args:
+            agent: The agent to invoke.
+
+        Yields:
+            tuple[bool, ChatMessageContent]: The conversation messages.
+        """
+        from semantic_kernel.agents.open_ai.open_ai_assistant_base import OpenAIAssistantBase
+
+        if not isinstance(agent, OpenAIAssistantBase):
+            raise AgentChatException(f"Agent is not of the expected type {type(OpenAIAssistantBase)}.")
+
+        if agent._is_deleted:
+            raise AgentChatException("Agent is deleted.")
+
+        async for is_visible, message in agent._invoke_internal(thread_id=self.thread_id):
+            yield is_visible, message
+
+    @override
+    async def get_history(self) -> AsyncIterable["ChatMessageContent"]:
+        """Get the conversation history.
+
+        Yields:
+            ChatMessageContent: The conversation history.
+        """
+        agent_names: dict[str, Any] = {}
+
+        thread_messages = await self.client.beta.threads.messages.list(
+            thread_id=self.thread_id, limit=100, order="desc"
+        )
+        for message in thread_messages.data:
+            assistant_name = None
+            if message.assistant_id and message.assistant_id not in agent_names:
+                agent = await self.client.beta.assistants.retrieve(message.assistant_id)
+                if agent.name:
+                    agent_names[message.assistant_id] = agent.name
+            assistant_name = agent_names.get(message.assistant_id) if message.assistant_id else message.assistant_id
+
+            content: ChatMessageContent = generate_message_content(str(assistant_name), message)
+
+            if len(content.items) > 0:
+                yield content
+
+    @override
+    async def reset(self) -> None:
+        """Reset the agent's thread."""
+        try:
+            await self.client.beta.threads.delete(thread_id=self.thread_id)
+        except Exception as e:
+            raise AgentChatException(f"Failed to delete thread: {e}")

semantic_kernel-1.8.3/semantic_kernel/agents/chat_completion/chat_completion_agent.py

@@ -0,0 +1,197 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from collections.abc import AsyncGenerator, AsyncIterable
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from semantic_kernel.agents import Agent
+from semantic_kernel.agents.channels.agent_channel import AgentChannel
+from semantic_kernel.agents.channels.chat_history_channel import ChatHistoryChannel
+from semantic_kernel.connectors.ai.chat_completion_client_base import ChatCompletionClientBase
+from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+from semantic_kernel.const import DEFAULT_SERVICE_NAME
+from semantic_kernel.contents.chat_history import ChatHistory
+from semantic_kernel.contents.chat_message_content import ChatMessageContent
+from semantic_kernel.contents.streaming_chat_message_content import StreamingChatMessageContent
+from semantic_kernel.contents.utils.author_role import AuthorRole
+from semantic_kernel.exceptions import KernelServiceNotFoundError
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+if TYPE_CHECKING:
+    from semantic_kernel.kernel import Kernel
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+@experimental_class
+class ChatCompletionAgent(Agent):
+    """A KernelAgent specialization based on ChatCompletionClientBase.
+
+    Note: enable `function_choice_behavior` on the PromptExecutionSettings to enable function
+    choice behavior which allows the kernel to utilize plugins and functions registered in
+    the kernel.
+    """
+
+    service_id: str
+    execution_settings: PromptExecutionSettings | None = None
+    channel_type: ClassVar[type[AgentChannel]] = ChatHistoryChannel
+
+    def __init__(
+        self,
+        service_id: str | None = None,
+        kernel: "Kernel | None" = None,
+        name: str | None = None,
+        id: str | None = None,
+        description: str | None = None,
+        instructions: str | None = None,
+        execution_settings: PromptExecutionSettings | None = None,
+    ) -> None:
+        """Initialize a new instance of ChatCompletionAgent.
+
+        Args:
+            service_id: The service id for the chat completion service. (optional) If not provided,
+                the default service name `default` will be used.
+            kernel: The kernel instance. (optional)
+            name: The name of the agent. (optional)
+            id: The unique identifier for the agent. (optional) If not provided,
+                a unique GUID will be generated.
+            description: The description of the agent. (optional)
+            instructions: The instructions for the agent. (optional)
+            execution_settings: The execution settings for the agent. (optional)
+        """
+        if not service_id:
+            service_id = DEFAULT_SERVICE_NAME
+
+        args: dict[str, Any] = {
+            "service_id": service_id,
+            "description": description,
+            "instructions": instructions,
+            "execution_settings": execution_settings,
+        }
+        if name is not None:
+            args["name"] = name
+        if id is not None:
+            args["id"] = id
+        if kernel is not None:
+            args["kernel"] = kernel
+        super().__init__(**args)
+
+    async def invoke(self, history: ChatHistory) -> AsyncIterable[ChatMessageContent]:
+        """Invoke the chat history handler.
+
+        Args:
+            kernel: The kernel instance.
+            history: The chat history.
+
+        Returns:
+            An async iterable of ChatMessageContent.
+        """
+        # Get the chat completion service
+        chat_completion_service = self.kernel.get_service(service_id=self.service_id, type=ChatCompletionClientBase)
+
+        if not chat_completion_service:
+            raise KernelServiceNotFoundError(f"Chat completion service not found with service_id: {self.service_id}")
+
+        assert isinstance(chat_completion_service, ChatCompletionClientBase)  # nosec
+
+        settings = (
+            self.execution_settings
+            or self.kernel.get_prompt_execution_settings_from_service_id(self.service_id)
+            or chat_completion_service.instantiate_prompt_execution_settings(
+                service_id=self.service_id, extension_data={"ai_model_id": chat_completion_service.ai_model_id}
+            )
+        )
+
+        chat = self._setup_agent_chat_history(history)
+
+        message_count = len(chat)
+
+        logger.debug(f"[{type(self).__name__}] Invoking {type(chat_completion_service).__name__}.")
+
+        messages = await chat_completion_service.get_chat_message_contents(
+            chat_history=chat,
+            settings=settings,
+            kernel=self.kernel,
+        )
+
+        logger.info(
+            f"[{type(self).__name__}] Invoked {type(chat_completion_service).__name__} "
+            f"with message count: {message_count}."
+        )
+
+        # Capture mutated messages related function calling / tools
+        for message_index in range(message_count, len(chat)):
+            message = chat[message_index]
+            message.name = self.name
+            history.add_message(message)
+
+        for message in messages:
+            message.name = self.name
+            yield message
+
+    async def invoke_stream(self, history: ChatHistory) -> AsyncIterable[StreamingChatMessageContent]:
+        """Invoke the chat history handler in streaming mode.
+
+        Args:
+            kernel: The kernel instance.
+            history: The chat history.
+
+        Returns:
+            An async generator of StreamingChatMessageContent.
+        """
+        # Get the chat completion service
+        chat_completion_service = self.kernel.get_service(service_id=self.service_id, type=ChatCompletionClientBase)
+
+        if not chat_completion_service:
+            raise KernelServiceNotFoundError(f"Chat completion service not found with service_id: {self.service_id}")
+
+        assert isinstance(chat_completion_service, ChatCompletionClientBase)  # nosec
+
+        settings = (
+            self.execution_settings
+            or self.kernel.get_prompt_execution_settings_from_service_id(self.service_id)
+            or chat_completion_service.instantiate_prompt_execution_settings(
+                service_id=self.service_id, extension_data={"ai_model_id": chat_completion_service.ai_model_id}
+            )
+        )
+
+        chat = self._setup_agent_chat_history(history)
+
+        message_count = len(chat)
+
+        logger.debug(f"[{type(self).__name__}] Invoking {type(chat_completion_service).__name__}.")
+
+        messages: AsyncGenerator[list[StreamingChatMessageContent], Any] = (
+            chat_completion_service.get_streaming_chat_message_contents(
+                chat_history=chat,
+                settings=settings,
+                kernel=self.kernel,
+            )
+        )
+
+        logger.info(
+            f"[{type(self).__name__}] Invoked {type(chat_completion_service).__name__} "
+            f"with message count: {message_count}."
+        )
+
+        async for message_list in messages:
+            for message in message_list:
+                message.name = self.name
+                yield message
+
+        # Capture mutated messages related function calling / tools
+        for message_index in range(message_count, len(chat)):
+            message = chat[message_index]  # type: ignore
+            message.name = self.name
+            history.add_message(message)
+
+    def _setup_agent_chat_history(self, history: ChatHistory) -> ChatHistory:
+        """Setup the agent chat history."""
+        chat = []
+
+        if self.instructions is not None:
+            chat.append(ChatMessageContent(role=AuthorRole.SYSTEM, content=self.instructions, name=self.name))
+
+        chat.extend(history.messages if history.messages else [])
+
+        return ChatHistory(messages=chat)

semantic_kernel-1.8.3/semantic_kernel/agents/group_chat/agent_chat.py

@@ -0,0 +1,180 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import logging
+import threading
+from abc import abstractmethod
+from collections.abc import AsyncGenerator, AsyncIterable
+from typing import Protocol, runtime_checkable
+
+from pydantic import Field, PrivateAttr
+
+from semantic_kernel.agents import Agent
+from semantic_kernel.agents.channels.agent_channel import AgentChannel
+from semantic_kernel.agents.group_chat.agent_chat_utils import KeyEncoder
+from semantic_kernel.agents.group_chat.broadcast_queue import BroadcastQueue, ChannelReference
+from semantic_kernel.contents.chat_history import ChatHistory
+from semantic_kernel.contents.chat_message_content import ChatMessageContent
+from semantic_kernel.contents.utils.author_role import AuthorRole
+from semantic_kernel.exceptions.agent_exceptions import AgentChatException
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+@experimental_class
+@runtime_checkable
+class AgentChatProtocol(Protocol):
+    """A protocol for agent chat."""
+
+    @abstractmethod
+    async def invoke(self, agent: Agent) -> AsyncIterable[ChatMessageContent]:
+        """Invoke an agent asynchronously."""
+        ...
+
+
+@experimental_class
+class AgentChat(KernelBaseModel):
+    """A base class chat interface for agents."""
+
+    broadcast_queue: BroadcastQueue = Field(default_factory=BroadcastQueue)
+    agent_channels: dict[str, AgentChannel] = Field(default_factory=dict)
+    channel_map: dict[Agent, str] = Field(default_factory=dict)
+    history: ChatHistory = Field(default_factory=ChatHistory)
+
+    _lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)
+    _is_active: bool = False
+
+    @property
+    def is_active(self) -> bool:
+        """Indicates whether the agent is currently active."""
+        return self._is_active
+
+    def set_activity_or_throw(self):
+        """Set the activity signal or throw an exception if another agent is active."""
+        with self._lock:
+            if self._is_active:
+                raise Exception("Unable to proceed while another agent is active.")
+            self._is_active = True
+
+    def clear_activity_signal(self):
+        """Clear the activity signal."""
+        with self._lock:
+            self._is_active = False
+
+    def invoke(self, agent: Agent | None = None, is_joining: bool = True) -> AsyncIterable[ChatMessageContent]:
+        """Invoke the agent asynchronously."""
+        raise NotImplementedError("Subclasses should implement this method")
+
+    async def get_messages_in_descending_order(self):
+        """Get messages in descending order asynchronously."""
+        for index in range(len(self.history.messages) - 1, -1, -1):
+            yield self.history.messages[index]
+            await asyncio.sleep(0)  # Yield control to the event loop
+
+    async def get_chat_messages(self, agent: "Agent | None" = None) -> AsyncGenerator[ChatMessageContent, None]:
+        """Get chat messages asynchronously."""
+        self.set_activity_or_throw()
+
+        logger.info("Getting chat messages")
+        try:
+            if agent is None:
+                messages = self.get_messages_in_descending_order()
+            else:
+                channel_key = self._get_agent_hash(agent)
+                channel = await self._synchronize_channel(channel_key)
+                if channel is not None:
+                    messages = channel.get_history()
+            if messages is not None:
+                async for message in messages:
+                    yield message
+        finally:
+            self.clear_activity_signal()
+
+    async def _synchronize_channel(self, channel_key: str) -> AgentChannel | None:
+        """Synchronize a channel."""
+        channel = self.agent_channels.get(channel_key, None)
+        if channel:
+            await self.broadcast_queue.ensure_synchronized(ChannelReference(channel=channel, hash=channel_key))
+        return channel
+
+    def _get_agent_hash(self, agent: Agent):
+        """Get the hash of an agent."""
+        hash_value = self.channel_map.get(agent, None)
+        if hash_value is None:
+            hash_value = KeyEncoder.generate_hash(agent.get_channel_keys())
+            self.channel_map[agent] = hash_value
+
+        return hash_value
+
+    async def add_chat_message(self, message: ChatMessageContent) -> None:
+        """Add a chat message."""
+        await self.add_chat_messages([message])
+
+    async def add_chat_messages(self, messages: list[ChatMessageContent]) -> None:
+        """Add chat messages."""
+        self.set_activity_or_throw()
+
+        for message in messages:
+            if message.role == AuthorRole.SYSTEM:
+                error_message = "System messages cannot be added to the chat history."
+                logger.error(error_message)
+                raise AgentChatException(error_message)
+
+        logger.info(f"Adding `{len(messages)}` agent chat messages")
+
+        try:
+            self.history.messages.extend(messages)
+
+            # Broadcast message to other channels (in parallel)
+            # Note: Able to queue messages without synchronizing channels.
+            channel_refs = [ChannelReference(channel=channel, hash=key) for key, channel in self.agent_channels.items()]
+            await self.broadcast_queue.enqueue(channel_refs, messages)
+        finally:
+            self.clear_activity_signal()
+
+    async def _get_or_create_channel(self, agent: Agent) -> AgentChannel:
+        """Get or create a channel."""
+        channel_key = self._get_agent_hash(agent)
+        channel = await self._synchronize_channel(channel_key)
+        if channel is None:
+            channel = await agent.create_channel()
+            self.agent_channels[channel_key] = channel
+
+            if len(self.history.messages) > 0:
+                await channel.receive(self.history.messages)
+        return channel
+
+    async def invoke_agent(self, agent: Agent) -> AsyncIterable[ChatMessageContent]:
+        """Invoke an agent asynchronously."""
+        self.set_activity_or_throw()
+        logger.info(f"Invoking agent {agent.name}")
+        try:
+            channel: AgentChannel = await self._get_or_create_channel(agent)
+            messages: list[ChatMessageContent] = []
+
+            async for is_visible, message in channel.invoke(agent):
+                messages.append(message)
+                self.history.messages.append(message)
+                if is_visible:
+                    yield message
+
+            # Broadcast message to other channels (in parallel)
+            # Note: Able to queue messages without synchronizing channels.
+            channel_refs = [ChannelReference(channel=channel, hash=key) for key, channel in self.agent_channels.items()]
+            await self.broadcast_queue.enqueue(channel_refs, messages)
+        finally:
+            self.clear_activity_signal()
+
+    async def reset(self) -> None:
+        """Reset the agent chat."""
+        self.set_activity_or_throw()
+
+        try:
+            await asyncio.gather(*(channel.reset() for channel in self.agent_channels.values()))
+            self.agent_channels.clear()
+            self.channel_map.clear()
+            self.history.messages.clear()
+        finally:
+            self.clear_activity_signal()

semantic_kernel-1.8.3/semantic_kernel/agents/group_chat/agent_chat_utils.py

@@ -0,0 +1,33 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import base64
+import hashlib
+from collections.abc import Iterable
+
+from semantic_kernel.exceptions.agent_exceptions import AgentExecutionException
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+
+@experimental_class
+class KeyEncoder:
+    """A class for encoding keys."""
+
+    @staticmethod
+    def generate_hash(keys: Iterable[str]) -> str:
+        """Generate a hash from a list of keys.
+
+        Args:
+            keys: A list of keys to generate the hash from.
+
+        Returns:
+            str: The generated hash.
+
+        Raises:
+            AgentExecutionException: If the keys are empty
+        """
+        if not keys:
+            raise AgentExecutionException("Channel Keys must not be empty. Unable to generate channel hash.")
+        joined_keys = ":".join(keys)
+        buffer = joined_keys.encode("utf-8")
+        sha256_hash = hashlib.sha256(buffer).digest()
+        return base64.b64encode(sha256_hash).decode("utf-8")