docs: improve readability with docstrings (#21)

Co-authored-by: Eden Zimbelman <eden.zimbelman@salesforce.com>

Author: srtaalej

ai/llm_caller.py

@@ -1,11 +1,10 @@
 import os
-from typing import List, Dict
+from typing import Dict, List
 
 import openai
 from openai import Stream
 from openai.types.responses import ResponseStreamEvent
 
-
 DEFAULT_SYSTEM_CONTENT = """
 You're an assistant in a Slack workspace.
 Users in the workspace will ask you to help them write something or to think better about a specific topic.

app.py

@@ -1,5 +1,5 @@
-import os
 import logging
+import os
 
 from dotenv import load_dotenv
 

app_oauth.py

@@ -1,9 +1,9 @@
 import logging
 import os
+
 from slack_bolt import App, BoltResponse
-from slack_bolt.oauth.callback_options import CallbackOptions, SuccessArgs, FailureArgs
+from slack_bolt.oauth.callback_options import CallbackOptions, FailureArgs, SuccessArgs
 from slack_bolt.oauth.oauth_settings import OAuthSettings
-
 from slack_sdk.oauth.installation_store import FileInstallationStore
 from slack_sdk.oauth.state_store import FileOAuthStateStore
 

listeners/__init__.py

@@ -1,9 +1,9 @@
-from listeners import actions
-from listeners import assistant
-from listeners import events
+from slack_bolt import App
 
+from listeners import actions, assistant, events
 
-def register_listeners(app):
+
+def register_listeners(app: App):
     actions.register(app)
     assistant.register(app)
     events.register(app)

listeners/actions/__init__.py

@@ -1,4 +1,5 @@
 from slack_bolt import App
+
 from .actions import handle_feedback
 
 

listeners/actions/actions.py

@@ -1,8 +1,19 @@
-import logging
+from logging import Logger
 
+from slack_bolt import Ack
+from slack_sdk import WebClient
 
-# Handle feedback buttons (thumbs up/down)
-def handle_feedback(ack, body, client, logger: logging.Logger):
+
+def handle_feedback(ack: Ack, body: dict, client: WebClient, logger: Logger):
+    """
+    Handles user feedback on AI-generated responses via thumbs up/down buttons.
+
+    Args:
+        ack: Function to acknowledge the action request
+        body: Action payload containing feedback details (message, channel, user, action value)
+        client: Slack WebClient for making API calls
+        logger: Logger instance for debugging and error tracking
+    """
     try:
         ack()
         message_ts = body["message"]["ts"]

listeners/assistant/__init__.py

@@ -1,4 +1,5 @@
 from slack_bolt import App
+
 from .assistant import assistant
 
 

listeners/assistant/assistant.py

@@ -1,27 +1,35 @@
-import logging
+from logging import Logger
 from typing import Dict, List
 
 from slack_bolt import Assistant, BoltContext, Say, SetStatus, SetSuggestedPrompts
 from slack_bolt.context.get_thread_context import GetThreadContext
 from slack_sdk import WebClient
 from slack_sdk.errors import SlackApiError
 
-from ..views.feedback_block import create_feedback_block
 from ai.llm_caller import call_llm
 
+from ..views.feedback_block import create_feedback_block
 
 # Refer to https://tools.slack.dev/bolt-python/concepts/assistant/ for more details
 assistant = Assistant()
 
 
-# This listener is invoked when a human user opened an assistant thread
 @assistant.thread_started
 def start_assistant_thread(
     say: Say,
     get_thread_context: GetThreadContext,
     set_suggested_prompts: SetSuggestedPrompts,
-    logger: logging.Logger,
+    logger: Logger,
 ):
+    """
+    Handle the assistant thread start event by greeting the user and setting suggested prompts.
+
+    Args:
+        say: Function to send messages to the thread from the app
+        get_thread_context: Function to retrieve thread context information
+        set_suggested_prompts: Function to configure suggested prompt options
+        logger: Logger instance for error tracking
+    """
     try:
         say("How can I help you?")
 
@@ -60,11 +68,23 @@ def respond_in_assistant_thread(
     client: WebClient,
     context: BoltContext,
     get_thread_context: GetThreadContext,
-    logger: logging.Logger,
+    logger: Logger,
     payload: dict,
     say: Say,
     set_status: SetStatus,
 ):
+    """
+    Handles when users send messages or select a prompt in an assistant thread and generate AI responses:
+
+    Args:
+        client: Slack WebClient for making API calls
+        context: Bolt context containing channel and thread information
+        get_thread_context: Function to retrieve thread context (e.g., referred channel)
+        logger: Logger instance for error tracking
+        payload: Event payload with message details (channel, user, text, etc.)
+        say: Function to send messages to the thread
+        set_status: Function to update the assistant's status
+    """
     try:
         channel_id = payload["channel"]
         team_id = context.team_id
@@ -84,8 +104,6 @@ def respond_in_assistant_thread(
         )
 
         if user_message == "Can you generate a brief summary of the referred channel?":
-            # the logic here requires the additional bot scopes:
-            # channels:join, channels:history, groups:history
             thread_context = get_thread_context()
             referred_channel_id = thread_context.get("channel_id")
             try:

listeners/events/__init__.py

@@ -1,4 +1,5 @@
 from slack_bolt import App
+
 from .app_mentioned import app_mentioned_callback
 
 

listeners/events/app_mentioned.py

@@ -1,17 +1,23 @@
 from logging import Logger
-from slack_sdk import WebClient
+
 from slack_bolt import Say
+from slack_sdk import WebClient
 
 from ai.llm_caller import call_llm
 from ..views.feedback_block import create_feedback_block
 
-"""
-Handles the event when the app is mentioned in a Slack conversation
-and generates an AI response.
-"""
-
 
 def app_mentioned_callback(client: WebClient, event: dict, logger: Logger, say: Say):
+    """
+    Handles the event when the app is mentioned in a Slack conversation
+    and generates an AI response.
+
+    Args:
+        client: Slack WebClient for making API calls
+        event: Event payload containing mention details (channel, user, text, etc.)
+        logger: Logger instance for error tracking
+        say: Function to send messages to the thread from the app
+    """
     try:
         channel_id = event.get("channel")
         team_id = event.get("team")