feat: add support for say_stream utility

slack_bolt/__init__.py

@@ -14,6 +14,7 @@
 from .context.fail import Fail
 from .context.respond import Respond
 from .context.say import Say
+from .context.say_stream import SayStream
 from .kwargs_injection import Args
 from .listener import Listener
 from .listener_matcher import CustomListenerMatcher
@@ -42,6 +43,7 @@
     "Fail",
     "Respond",
     "Say",
+    "SayStream",
     "Args",
     "Listener",
     "CustomListenerMatcher",

slack_bolt/async_app.py

@@ -59,13 +59,15 @@ async def command(ack, body, respond):
 from .context.set_suggested_prompts.async_set_suggested_prompts import AsyncSetSuggestedPrompts
 from .context.get_thread_context.async_get_thread_context import AsyncGetThreadContext
 from .context.save_thread_context.async_save_thread_context import AsyncSaveThreadContext
+from .context.say_stream.async_say_stream import AsyncSayStream
 
 __all__ = [
     "AsyncApp",
     "AsyncAck",
     "AsyncBoltContext",
     "AsyncRespond",
     "AsyncSay",
+    "AsyncSayStream",
     "AsyncListener",
     "AsyncCustomListenerMatcher",
     "AsyncBoltRequest",

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/base_context.py

@@ -38,6 +38,7 @@ class BaseContext(dict):
         "set_status",
         "set_title",
         "set_suggested_prompts",
+        "say_stream",
     ]
     # Note that these items are not copyable, so when you add new items to this list,
     # you must modify ThreadListenerRunner/AsyncioListenerRunner's _build_lazy_request method to pass the values.

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,70 @@
+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: Optional[str]
+    recipient_team_id: Optional[str]
+    recipient_user_id: Optional[str]
+    thread_ts: Optional[str]
+
+    def __init__(
+        self,
+        *,
+        client: AsyncWebClient,
+        channel: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+    ):
+        self.client = client
+        self.channel = channel
+        self.recipient_team_id = recipient_team_id
+        self.recipient_user_id = recipient_user_id
+        self.thread_ts = thread_ts
+
+    async def __call__(
+        self,
+        *,
+        buffer_size: Optional[int] = None,
+        channel: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        thread_ts: 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
+        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 is not None:
+            return await self.client.chat_stream(
+                buffer_size=buffer_size,
+                channel=channel,
+                recipient_team_id=recipient_team_id or self.recipient_team_id,
+                recipient_user_id=recipient_user_id or self.recipient_user_id,
+                thread_ts=thread_ts,
+                **kwargs,
+            )
+        return await self.client.chat_stream(
+            channel=channel,
+            recipient_team_id=recipient_team_id or self.recipient_team_id,
+            recipient_user_id=recipient_user_id or self.recipient_user_id,
+            thread_ts=thread_ts,
+            **kwargs,
+        )

slack_bolt/context/say_stream/say_stream.py

@@ -0,0 +1,70 @@
+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: Optional[str]
+    recipient_team_id: Optional[str]
+    recipient_user_id: Optional[str]
+    thread_ts: Optional[str]
+
+    def __init__(
+        self,
+        *,
+        client: WebClient,
+        channel: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+    ):
+        self.client = client
+        self.channel = channel
+        self.recipient_team_id = recipient_team_id
+        self.recipient_user_id = recipient_user_id
+        self.thread_ts = thread_ts
+
+    def __call__(
+        self,
+        *,
+        buffer_size: Optional[int] = None,
+        channel: Optional[str] = None,
+        recipient_team_id: Optional[str] = None,
+        recipient_user_id: Optional[str] = None,
+        thread_ts: 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
+        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 is not None:
+            return self.client.chat_stream(
+                buffer_size=buffer_size,
+                channel=channel,
+                recipient_team_id=recipient_team_id or self.recipient_team_id,
+                recipient_user_id=recipient_user_id or self.recipient_user_id,
+                thread_ts=thread_ts,
+                **kwargs,
+            )
+        return self.client.chat_stream(
+            channel=channel,
+            recipient_team_id=recipient_team_id or self.recipient_team_id,
+            recipient_user_id=recipient_user_id or self.recipient_user_id,
+            thread_ts=thread_ts,
+            **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/kwargs_injection/async_utils.py

@@ -60,6 +60,7 @@ def build_async_required_kwargs(
         "set_suggested_prompts": request.context.set_suggested_prompts,
         "get_thread_context": request.context.get_thread_context,
         "save_thread_context": request.context.save_thread_context,
+        "say_stream": request.context.say_stream,
         # middleware
         "next": next_func,
         "next_": next_func,  # for the middleware using Python's built-in `next()` function

slack_bolt/kwargs_injection/utils.py

@@ -59,6 +59,7 @@ def build_required_kwargs(
         "set_title": request.context.set_title,
         "set_suggested_prompts": request.context.set_suggested_prompts,
         "save_thread_context": request.context.save_thread_context,
+        "say_stream": request.context.say_stream,
         # middleware
         "next": next_func,
         "next_": next_func,  # for the middleware using Python's built-in `next()` function

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=req.context.channel_id,
+                    recipient_team_id=req.context.team_id or req.context.enterprise_id,
+                    recipient_user_id=req.context.user_id,
+                    thread_ts=thread_ts,
+                )
         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=req.context.channel_id,
+                    recipient_team_id=req.context.team_id or req.context.enterprise_id,
+                    recipient_user_id=req.context.user_id,
+                    thread_ts=thread_ts,
+                )
         return next()