Fastapi integration package

DevInstructions.md

@@ -32,7 +32,8 @@ Any issues should be filed on the [Agents-for-python](https://github.com/microso
     pip install -e ./libraries/microsoft-agents-hosting-aiohttp/ --config-settings editable_mode=compat
     pip install -e ./libraries/microsoft-agents-hosting-teams/ --config-settings editable_mode=compat
     pip install -e ./libraries/microsoft-agents-storage-blob/ --config-settings editable_mode=compat
-    pip install -e ./libraries/microsoft-agents-storage-cosmos/ --config-settings editable_mode=compat    
+    pip install -e ./libraries/microsoft-agents-storage-cosmos/ --config-settings editable_mode=compat
+    pip install -e ./libraries/microsoft-agents-hosting-fastapi/ --config-settings editable_mode=compat
     ```
 1. Setup the dev dependencies for python. In the terminal, at the project root, run:
     ```

libraries/microsoft-agents-hosting-fastapi/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/__init__.py

@@ -0,0 +1,23 @@
+from ._start_agent_process import start_agent_process
+from .agent_http_adapter import AgentHttpAdapter
+from .channel_service_route_table import channel_service_route_table
+from .cloud_adapter import CloudAdapter
+from .jwt_authorization_middleware import (
+    JwtAuthorizationMiddleware,
+)
+from .app.streaming import (
+    Citation,
+    CitationUtil,
+    StreamingResponse,
+)
+
+__all__ = [
+    "start_agent_process",
+    "AgentHttpAdapter",
+    "CloudAdapter",
+    "JwtAuthorizationMiddleware",
+    "channel_service_route_table",
+    "Citation",
+    "CitationUtil",
+    "StreamingResponse",
+]

libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/_start_agent_process.py

@@ -0,0 +1,26 @@
+from typing import Optional
+from fastapi import Request, Response
+from microsoft_agents.hosting.core.app import AgentApplication
+from .cloud_adapter import CloudAdapter
+
+
+async def start_agent_process(
+    request: Request,
+    agent_application: AgentApplication,
+    adapter: CloudAdapter,
+) -> Optional[Response]:
+    """Starts the agent host with the provided adapter and agent application.
+    Args:
+        adapter (CloudAdapter): The adapter to use for the agent host.
+        agent_application (AgentApplication): The agent application to run.
+    """
+    if not adapter:
+        raise TypeError("start_agent_process: adapter can't be None")
+    if not agent_application:
+        raise TypeError("start_agent_process: agent_application can't be None")
+
+    # Start the agent application with the provided adapter
+    return await adapter.process(
+        request,
+        agent_application,
+    )

libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/agent_http_adapter.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from abc import abstractmethod
+from typing import Optional, Protocol
+
+from fastapi import Request, Response
+
+from microsoft_agents.hosting.core import Agent
+
+
+class AgentHttpAdapter(Protocol):
+    @abstractmethod
+    async def process(self, request: Request, agent: Agent) -> Optional[Response]:
+        raise NotImplementedError()

libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/app/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .streaming import (
+    Citation,
+    CitationUtil,
+    StreamingResponse,
+)
+
+__all__ = [
+    "Citation",
+    "CitationUtil",
+    "StreamingResponse",
+]

libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/app/streaming/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .citation import Citation
+from .citation_util import CitationUtil
+from .streaming_response import StreamingResponse
+
+__all__ = [
+    "Citation",
+    "CitationUtil",
+    "StreamingResponse",
+]

libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/app/streaming/citation.py

@@ -0,0 +1,22 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class Citation:
+    """Citations returned by the model."""
+
+    content: str
+    """The content of the citation."""
+
+    title: Optional[str] = None
+    """The title of the citation."""
+
+    url: Optional[str] = None
+    """The URL of the citation."""
+
+    filepath: Optional[str] = None
+    """The filepath of the document."""

libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/app/streaming/citation_util.py

@@ -0,0 +1,85 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import re
+from typing import List, Optional
+
+from microsoft_agents.activity import ClientCitation
+
+
+class CitationUtil:
+    """Utility functions for manipulating text and citations."""
+
+    @staticmethod
+    def snippet(text: str, max_length: int) -> str:
+        """
+        Clips the text to a maximum length in case it exceeds the limit.
+
+        Args:
+            text: The text to clip.
+            max_length: The maximum length of the text to return, cutting off the last whole word.
+
+        Returns:
+            The modified text
+        """
+        if len(text) <= max_length:
+            return text
+
+        snippet = text[:max_length]
+        snippet = snippet[: min(len(snippet), snippet.rfind(" "))]
+        snippet += "..."
+        return snippet
+
+    @staticmethod
+    def format_citations_response(text: str) -> str:
+        """
+        Convert citation tags `[doc(s)n]` to `[n]` where n is a number.
+
+        Args:
+            text: The text to format.
+
+        Returns:
+            The formatted text.
+        """
+        return re.sub(r"\[docs?(\d+)\]", r"[\1]", text, flags=re.IGNORECASE)
+
+    @staticmethod
+    def get_used_citations(
+        text: str, citations: List[ClientCitation]
+    ) -> Optional[List[ClientCitation]]:
+        """
+        Get the citations used in the text. This will remove any citations that are
+        included in the citations array from the response but not referenced in the text.
+
+        Args:
+            text: The text to search for citation references, i.e. [1], [2], etc.
+            citations: The list of citations to search for.
+
+        Returns:
+            The list of citations used in the text.
+        """
+        regex = re.compile(r"\[(\d+)\]", re.IGNORECASE)
+        matches = regex.findall(text)
+
+        if not matches:
+            return None
+
+        # Remove duplicates
+        filtered_matches = set(matches)
+
+        # Add citations
+        used_citations = []
+        for match in filtered_matches:
+            citation_ref = f"[{match}]"
+            found = next(
+                (
+                    citation
+                    for citation in citations
+                    if f"[{citation.position}]" == citation_ref
+                ),
+                None,
+            )
+            if found:
+                used_citations.append(found)
+
+        return used_citations if used_citations else None