feat: add support for say_stream utility function

Author: WilliamBergamin

slack_bolt/context/async_context.py

@@ -10,6 +10,7 @@
 from slack_bolt.context.get_thread_context.async_get_thread_context import AsyncGetThreadContext
 from slack_bolt.context.save_thread_context.async_save_thread_context import AsyncSaveThreadContext
 from slack_bolt.context.say.async_say import AsyncSay
+from slack_bolt.context.say_stream.async_say_stream import AsyncSayStream
 from slack_bolt.context.set_status.async_set_status import AsyncSetStatus
 from slack_bolt.context.set_suggested_prompts.async_set_suggested_prompts import AsyncSetSuggestedPrompts
 from slack_bolt.context.set_title.async_set_title import AsyncSetTitle
@@ -203,6 +204,10 @@ def set_suggested_prompts(self) -> Optional[AsyncSetSuggestedPrompts]:
     def get_thread_context(self) -> Optional[AsyncGetThreadContext]:
         return self.get("get_thread_context")
 
+    @property
+    def say_stream(self) -> Optional[AsyncSayStream]:
+        return self.get("say_stream")
+
     @property
     def save_thread_context(self) -> Optional[AsyncSaveThreadContext]:
         return self.get("save_thread_context")

slack_bolt/context/context.py

@@ -10,6 +10,7 @@
 from slack_bolt.context.respond import Respond
 from slack_bolt.context.save_thread_context import SaveThreadContext
 from slack_bolt.context.say import Say
+from slack_bolt.context.say_stream import SayStream
 from slack_bolt.context.set_status import SetStatus
 from slack_bolt.context.set_suggested_prompts import SetSuggestedPrompts
 from slack_bolt.context.set_title import SetTitle
@@ -204,6 +205,10 @@ def set_suggested_prompts(self) -> Optional[SetSuggestedPrompts]:
     def get_thread_context(self) -> Optional[GetThreadContext]:
         return self.get("get_thread_context")
 
+    @property
+    def say_stream(self) -> Optional[SayStream]:
+        return self.get("say_stream")
+
     @property
     def save_thread_context(self) -> Optional[SaveThreadContext]:
         return self.get("save_thread_context")

slack_bolt/context/say_stream/__init__.py

@@ -0,0 +1,6 @@
+# Don't add async module imports here
+from .say_stream import SayStream
+
+__all__ = [
+    "SayStream",
+]

slack_bolt/context/say_stream/async_say_stream.py

@@ -0,0 +1,71 @@
+import warnings
+from typing import Optional
+
+from slack_sdk.web.async_client import AsyncWebClient
+from slack_sdk.web.async_chat_stream import AsyncChatStream
+
+from slack_bolt.warning import ExperimentalWarning
+
+
+class AsyncSayStream:
+    client: AsyncWebClient
+    channel_id: Optional[str]
+    thread_ts: Optional[str]
+    team_id: Optional[str]
+    user_id: Optional[str]
+
+    def __init__(
+        self,
+        *,
+        client: AsyncWebClient,
+        channel_id: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+        team_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ):
+        self.client = client
+        self.channel_id = channel_id
+        self.thread_ts = thread_ts
+        self.team_id = team_id
+        self.user_id = user_id
+
+    async def __call__(
+        self,
+        *,
+        buffer_size: Optional[int] = None,
+        channel: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        **kwargs,
+    ) -> AsyncChatStream:
+        warnings.warn(
+            "say_stream is experimental and may change in future versions.",
+            category=ExperimentalWarning,
+            stacklevel=2,
+        )
+
+        channel = channel or self.channel_id
+        thread_ts = thread_ts or self.thread_ts
+        if channel is None:
+            raise ValueError("say_stream without channel here is unsupported")
+        if thread_ts is None:
+            raise ValueError("say_stream without thread_ts here is unsupported")
+
+        if buffer_size:
+            return await self.client.chat_stream(
+                buffer_size=buffer_size,
+                channel=channel,
+                thread_ts=thread_ts,
+                recipient_team_id=recipient_team_id or self.team_id,
+                recipient_user_id=recipient_user_id or self.user_id,
+                **kwargs,
+            )
+
+        return await self.client.chat_stream(
+            channel=channel,
+            thread_ts=thread_ts,
+            recipient_team_id=recipient_team_id or self.team_id,
+            recipient_user_id=recipient_user_id or self.user_id,
+            **kwargs,
+        )

slack_bolt/context/say_stream/say_stream.py

@@ -0,0 +1,71 @@
+import warnings
+from typing import Optional
+
+from slack_sdk import WebClient
+from slack_sdk.web.chat_stream import ChatStream
+
+from slack_bolt.warning import ExperimentalWarning
+
+
+class SayStream:
+    client: WebClient
+    channel_id: Optional[str]
+    thread_ts: Optional[str]
+    team_id: Optional[str]
+    user_id: Optional[str]
+
+    def __init__(
+        self,
+        *,
+        client: WebClient,
+        channel_id: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+        team_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ):
+        self.client = client
+        self.channel_id = channel_id
+        self.thread_ts = thread_ts
+        self.team_id = team_id
+        self.user_id = user_id
+
+    def __call__(
+        self,
+        *,
+        buffer_size: Optional[int] = None,
+        channel: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        **kwargs,
+    ) -> ChatStream:
+        warnings.warn(
+            "say_stream is experimental and may change in future versions.",
+            category=ExperimentalWarning,
+            stacklevel=2,
+        )
+
+        channel = channel or self.channel_id
+        thread_ts = thread_ts or self.thread_ts
+        if channel is None:
+            raise ValueError("say_stream without channel here is unsupported")
+        if thread_ts is None:
+            raise ValueError("say_stream without thread_ts here is unsupported")
+
+        if buffer_size:
+            return self.client.chat_stream(
+                buffer_size=buffer_size,
+                channel=channel,
+                thread_ts=thread_ts,
+                recipient_team_id=recipient_team_id or self.team_id,
+                recipient_user_id=recipient_user_id or self.user_id,
+                **kwargs,
+            )
+
+        return self.client.chat_stream(
+            channel=channel,
+            thread_ts=thread_ts,
+            recipient_team_id=recipient_team_id or self.team_id,
+            recipient_user_id=recipient_user_id or self.user_id,
+            **kwargs,
+        )

slack_bolt/kwargs_injection/args.py

@@ -11,6 +11,7 @@
 from slack_bolt.agent.agent import BoltAgent
 from slack_bolt.context.save_thread_context import SaveThreadContext
 from slack_bolt.context.say import Say
+from slack_bolt.context.say_stream import SayStream
 from slack_bolt.context.set_status import SetStatus
 from slack_bolt.context.set_suggested_prompts import SetSuggestedPrompts
 from slack_bolt.context.set_title import SetTitle
@@ -105,6 +106,8 @@ def handle_buttons(args):
     """`save_thread_context()` utility function for AI Agents & Assistants"""
     agent: Optional[BoltAgent]
     """`agent` listener argument for AI Agents & Assistants"""
+    say_stream: Optional[SayStream]
+    """`say_stream()` utility function for AI Agents & Assistants"""
     # middleware
     next: Callable[[], None]
     """`next()` utility function, which tells the middleware chain that it can continue with the next one"""
@@ -139,6 +142,7 @@ def __init__(
         get_thread_context: Optional[GetThreadContext] = None,
         save_thread_context: Optional[SaveThreadContext] = None,
         agent: Optional[BoltAgent] = None,
+        say_stream: Optional[SayStream] = None,
         # As this method is not supposed to be invoked by bolt-python users,
         # the naming conflict with the built-in one affects
         # only the internals of this method
@@ -173,6 +177,7 @@ def __init__(
         self.get_thread_context = get_thread_context
         self.save_thread_context = save_thread_context
         self.agent = agent
+        self.say_stream = say_stream
 
         self.next: Callable[[], None] = next
         self.next_: Callable[[], None] = next

slack_bolt/kwargs_injection/async_args.py

@@ -10,6 +10,7 @@
 from slack_bolt.context.get_thread_context.async_get_thread_context import AsyncGetThreadContext
 from slack_bolt.context.save_thread_context.async_save_thread_context import AsyncSaveThreadContext
 from slack_bolt.context.say.async_say import AsyncSay
+from slack_bolt.context.say_stream.async_say_stream import AsyncSayStream
 from slack_bolt.context.set_status.async_set_status import AsyncSetStatus
 from slack_bolt.context.set_suggested_prompts.async_set_suggested_prompts import AsyncSetSuggestedPrompts
 from slack_bolt.context.set_title.async_set_title import AsyncSetTitle
@@ -104,6 +105,8 @@ async def handle_buttons(args):
     """`save_thread_context()` utility function for AI Agents & Assistants"""
     agent: Optional[AsyncBoltAgent]
     """`agent` listener argument for AI Agents & Assistants"""
+    say_stream: Optional[AsyncSayStream]
+    """`say_stream()` utility function for AI Agents & Assistants"""
     # middleware
     next: Callable[[], Awaitable[None]]
     """`next()` utility function, which tells the middleware chain that it can continue with the next one"""
@@ -138,6 +141,7 @@ def __init__(
         get_thread_context: Optional[AsyncGetThreadContext] = None,
         save_thread_context: Optional[AsyncSaveThreadContext] = None,
         agent: Optional[AsyncBoltAgent] = None,
+        say_stream: Optional[AsyncSayStream] = None,
         next: Callable[[], Awaitable[None]],
         **kwargs,  # noqa
     ):
@@ -169,6 +173,7 @@ def __init__(
         self.get_thread_context = get_thread_context
         self.save_thread_context = save_thread_context
         self.agent = agent
+        self.say_stream = say_stream
 
         self.next: Callable[[], Awaitable[None]] = next
         self.next_: Callable[[], Awaitable[None]] = next

slack_bolt/middleware/attaching_agent_kwargs/async_attaching_agent_kwargs.py

@@ -2,6 +2,7 @@
 
 from slack_bolt.context.assistant.async_assistant_utilities import AsyncAssistantUtilities
 from slack_bolt.context.assistant.thread_context_store.async_store import AsyncAssistantThreadContextStore
+from slack_bolt.context.say_stream.async_say_stream import AsyncSayStream
 from slack_bolt.middleware.async_middleware import AsyncMiddleware
 from slack_bolt.request.async_request import AsyncBoltRequest
 from slack_bolt.request.payload_utils import is_assistant_event, to_event
@@ -36,4 +37,15 @@ async def async_process(
                 req.context["set_suggested_prompts"] = assistant.set_suggested_prompts
                 req.context["get_thread_context"] = assistant.get_thread_context
                 req.context["save_thread_context"] = assistant.save_thread_context
+
+            # TODO: in the future we might want to introduce a "proper" extract_ts utility
+            thread_ts = req.context.thread_ts or event.get("ts")
+            if req.context.channel_id and thread_ts:
+                req.context["say_stream"] = AsyncSayStream(
+                    client=req.context.client,
+                    channel_id=req.context.channel_id,
+                    thread_ts=thread_ts,
+                    team_id=req.context.team_id,
+                    user_id=req.context.user_id,
+                )
         return await next()

slack_bolt/middleware/attaching_agent_kwargs/attaching_agent_kwargs.py

@@ -2,6 +2,7 @@
 
 from slack_bolt.context.assistant.assistant_utilities import AssistantUtilities
 from slack_bolt.context.assistant.thread_context_store.store import AssistantThreadContextStore
+from slack_bolt.context.say_stream.say_stream import SayStream
 from slack_bolt.middleware import Middleware
 from slack_bolt.request.payload_utils import is_assistant_event, to_event
 from slack_bolt.request.request import BoltRequest
@@ -30,4 +31,15 @@ def process(self, *, req: BoltRequest, resp: BoltResponse, next: Callable[[], Bo
                 req.context["set_suggested_prompts"] = assistant.set_suggested_prompts
                 req.context["get_thread_context"] = assistant.get_thread_context
                 req.context["save_thread_context"] = assistant.save_thread_context
+
+            # TODO: in the future we might want to introduce a "proper" extract_ts utility
+            thread_ts = req.context.thread_ts or event.get("ts")
+            if req.context.channel_id and thread_ts:
+                req.context["say_stream"] = SayStream(
+                    client=req.context.client,
+                    channel_id=req.context.channel_id,
+                    thread_ts=thread_ts,
+                    team_id=req.context.team_id,
+                    user_id=req.context.user_id,
+                )
         return next()