Merge branch 'main' into docs-haley-order-confirmation-tutorial

Author: haleychaas

docs/english/building-an-app.md

@@ -475,8 +475,8 @@ Now that you have a basic app up and running, you can start exploring how to mak
 
 * Read through the concepts pages to learn about the different methods and features your Bolt app has access to.
 
-* Explore the different events your bot can listen to with the [`app.event()`](/tools/bolt-python/concepts/event-listening) method. All of the events are listed [on the API docs site](/reference/events).
+* Explore the different events your bot can listen to with the [`app.event()`](/tools/bolt-python/concepts/event-listening) method. View the full events reference docs [here](/reference/events).
 
-* Bolt allows you to [call Web API methods](/tools/bolt-python/concepts/web-api) with the client attached to your app. There are [over 200 methods](/reference/methods) on our API site.
+* Bolt allows you to [call Web API methods](/tools/bolt-python/concepts/web-api) with the client attached to your app. There are over 200 methods; view them [here](/reference/methods).
 
-* Learn more about the different token types [on the API docs site](/authentication/tokens). Your app may need different tokens depending on the actions you want it to perform.
+* Learn more about the different token types in the [tokens guide](/authentication/tokens). Your app may need different tokens depending on the actions you want it to perform.

docs/english/getting-started.md

@@ -279,6 +279,41 @@ This will open the following page:
 
 On these pages you're free to make changes such as updating your app icon, configuring app features, and perhaps even distributing your app!
 
+## Adding AI features {#ai-features}
+
+Now that you're familiar with a basic app setup, try it out again, this time using the AI agent template!
+
+<Tabs groupId="cli-or-terminal">
+<TabItem value="cli" label="Slack CLI">
+
+Get started with the agent template:
+
+```sh
+$ slack create ai-app --template slack-samples/bolt-python-assistant-template
+$ cd ai-app
+```
+
+</TabItem>
+<TabItem value="terminal" label="Terminal">
+
+Get started with the agent template:
+
+```sh
+$ git clone https://github.com/slack-samples/bolt-python-assistant-template ai-app
+$ cd ai-app
+```
+
+Using this method, be sure to set the app and bot tokens as we did in the [Running the app](#running-the-app) section above.
+
+</TabItem>
+</Tabs>
+
+Once the project is created, update the `.env.sample` file by setting the `OPENAI_API_KEY` with the value of your key and removing the `.sample` from the file name.
+
+In the `ai` folder of this app, you'll find default instructions for the LLM and an OpenAI client setup. 
+
+The `listeners` include utilities intended for messaging with an LLM. Those are outlined in detail in the guide to [Using AI in apps](/tools/bolt-python/concepts/ai-apps) and [Sending messages](/tools/bolt-python/concepts/message-sending).
+
 ## Next steps {#next-steps}
 
 Congrats once more on getting up and running with this quick start.

slack_bolt/context/complete/async_complete.py

@@ -7,6 +7,7 @@
 class AsyncComplete:
     client: AsyncWebClient
     function_execution_id: Optional[str]
+    _called: bool
 
     def __init__(
         self,
@@ -15,6 +16,7 @@ def __init__(
     ):
         self.client = client
         self.function_execution_id = function_execution_id
+        self._called = False
 
     async def __call__(self, outputs: Optional[Dict[str, Any]] = None) -> AsyncSlackResponse:
         """Signal the successful completion of the custom function.
@@ -31,6 +33,15 @@ async def __call__(self, outputs: Optional[Dict[str, Any]] = None) -> AsyncSlack
         if self.function_execution_id is None:
             raise ValueError("complete is unsupported here as there is no function_execution_id")
 
+        self._called = True
         return await self.client.functions_completeSuccess(
             function_execution_id=self.function_execution_id, outputs=outputs or {}
         )
+
+    def has_been_called(self) -> bool:
+        """Check if this complete function has been called.
+
+        Returns:
+            bool: True if the complete function has been called, False otherwise.
+        """
+        return self._called

slack_bolt/context/complete/complete.py

@@ -7,6 +7,7 @@
 class Complete:
     client: WebClient
     function_execution_id: Optional[str]
+    _called: bool
 
     def __init__(
         self,
@@ -15,6 +16,7 @@ def __init__(
     ):
         self.client = client
         self.function_execution_id = function_execution_id
+        self._called = False
 
     def __call__(self, outputs: Optional[Dict[str, Any]] = None) -> SlackResponse:
         """Signal the successful completion of the custom function.
@@ -31,4 +33,13 @@ def __call__(self, outputs: Optional[Dict[str, Any]] = None) -> SlackResponse:
         if self.function_execution_id is None:
             raise ValueError("complete is unsupported here as there is no function_execution_id")
 
+        self._called = True
         return self.client.functions_completeSuccess(function_execution_id=self.function_execution_id, outputs=outputs or {})
+
+    def has_been_called(self) -> bool:
+        """Check if this complete function has been called.
+
+        Returns:
+            bool: True if the complete function has been called, False otherwise.
+        """
+        return self._called

slack_bolt/context/fail/async_fail.py

@@ -7,6 +7,7 @@
 class AsyncFail:
     client: AsyncWebClient
     function_execution_id: Optional[str]
+    _called: bool
 
     def __init__(
         self,
@@ -15,6 +16,7 @@ def __init__(
     ):
         self.client = client
         self.function_execution_id = function_execution_id
+        self._called = False
 
     async def __call__(self, error: str) -> AsyncSlackResponse:
         """Signal that the custom function failed to complete.
@@ -31,4 +33,13 @@ async def __call__(self, error: str) -> AsyncSlackResponse:
         if self.function_execution_id is None:
             raise ValueError("fail is unsupported here as there is no function_execution_id")
 
+        self._called = True
         return await self.client.functions_completeError(function_execution_id=self.function_execution_id, error=error)
+
+    def has_been_called(self) -> bool:
+        """Check if this fail function has been called.
+
+        Returns:
+            bool: True if the fail function has been called, False otherwise.
+        """
+        return self._called

slack_bolt/context/fail/fail.py

@@ -7,6 +7,7 @@
 class Fail:
     client: WebClient
     function_execution_id: Optional[str]
+    _called: bool
 
     def __init__(
         self,
@@ -15,6 +16,7 @@ def __init__(
     ):
         self.client = client
         self.function_execution_id = function_execution_id
+        self._called = False
 
     def __call__(self, error: str) -> SlackResponse:
         """Signal that the custom function failed to complete.
@@ -31,4 +33,13 @@ def __call__(self, error: str) -> SlackResponse:
         if self.function_execution_id is None:
             raise ValueError("fail is unsupported here as there is no function_execution_id")
 
+        self._called = True
         return self.client.functions_completeError(function_execution_id=self.function_execution_id, error=error)
+
+    def has_been_called(self) -> bool:
+        """Check if this fail function has been called.
+
+        Returns:
+            bool: True if the fail function has been called, False otherwise.
+        """
+        return self._called

tests/scenario_tests/test_function.py

@@ -300,16 +300,20 @@ def reverse(body, event, context, client, complete, inputs):
     assert context.client.token == "xwfp-valid"
     assert client.token == "xwfp-valid"
     assert complete.client.token == "xwfp-valid"
+    assert complete.has_been_called() is False
     complete(
         outputs={"reverseString": "olleh"},
     )
+    assert complete.has_been_called() is True
 
 
 def reverse_error(body, event, fail):
     assert body == function_body
     assert event == function_body["event"]
     assert fail.function_execution_id == "Fx111"
+    assert fail.has_been_called() is False
     fail(error="there was an error")
+    assert fail.has_been_called() is True
 
 
 def complete_it(body, event, complete):

tests/scenario_tests_async/test_function.py

@@ -312,18 +312,22 @@ async def reverse(body, event, client, context, complete, inputs):
     assert context.client.token == "xwfp-valid"
     assert client.token == "xwfp-valid"
     assert complete.client.token == "xwfp-valid"
+    assert complete.has_been_called() is False
     await complete(
         outputs={"reverseString": "olleh"},
     )
+    assert complete.has_been_called() is True
 
 
 async def reverse_error(body, event, fail):
     assert body == function_body
     assert event == function_body["event"]
     assert fail.function_execution_id == "Fx111"
+    assert fail.has_been_called() is False
     await fail(
         error="there was an error",
     )
+    assert fail.has_been_called() is True
 
 
 async def complete_it(body, event, complete):

tests/slack_bolt/context/test_complete.py

@@ -30,3 +30,12 @@ def test_complete_no_function_execution_id(self):
 
         with pytest.raises(ValueError):
             complete(outputs={"key": "value"})
+
+    def test_has_been_called_false_initially(self):
+        complete = Complete(client=self.web_client, function_execution_id="fn1111")
+        assert complete.has_been_called() is False
+
+    def test_has_been_called_true_after_complete(self):
+        complete = Complete(client=self.web_client, function_execution_id="fn1111")
+        complete(outputs={"key": "value"})
+        assert complete.has_been_called() is True

tests/slack_bolt/context/test_fail.py

@@ -30,3 +30,12 @@ def test_fail_no_function_execution_id(self):
 
         with pytest.raises(ValueError):
             fail(error="there was an error")
+
+    def test_has_been_called_false_initially(self):
+        fail = Fail(client=self.web_client, function_execution_id="fn1111")
+        assert fail.has_been_called() is False
+
+    def test_has_been_called_true_after_fail(self):
+        fail = Fail(client=self.web_client, function_execution_id="fn1111")
+        fail(error="there was an error")
+        assert fail.has_been_called() is True