Merge branch 'ai-apps' into ale-ai-apps-rename

mwbrooks · mwbrooks · commit 40b540092fd5 · 2025-10-06T15:07:42.000-07:00
diff --git a/.env.sample b/.env.sample
@@ -0,0 +1,5 @@
+SLACK_APP_TOKEN=YOUR_SLACK_APP_TOKEN
+SLACK_BOT_TOKEN=YOUR_SLACK_BOT_TOKEN
+# SLACK_API_URL=YOUR_SLACK_API_URL
+# This template uses OpenAI, but you can use any other provider!
+OPENAI_API_KEY=YOUR_OPENAI_API_KEY
diff --git a/.gitignore b/.gitignore
@@ -16,6 +16,7 @@ env*/
 venv/
 .venv*
 .env*
+!.env.sample
 
 # codecov / coverage
 .coverage
diff --git a/README.md b/README.md
@@ -17,20 +17,25 @@ Join the [Slack Developer Program](https://api.slack.com/developer-program) for
 4. Review the configuration and click *Create*
 5. Click *Install to Workspace* and *Allow* on the screen that follows. You'll then be redirected to the App Configuration dashboard.
 
-#### Environment Variables
+### Environment Variables
+
 Before you can run the app, you'll need to store some environment variables.
 
-1. Open your app configuration page from this list, click **OAuth & Permissions** in the left hand menu, then copy the Bot User OAuth Token. You will store this in your environment as `SLACK_BOT_TOKEN`.
-2. Click **Basic Information** from the left hand menu and follow the steps in the App-Level Tokens section to create an app-level token with the `connections:write` scope. Copy this token. You will store this in your environment as `SLACK_APP_TOKEN`.
 
+1. Rename `.env.sample` to `.env`.
+2. Open your apps setting page from [this list](https://api.slack.com/apps), click _OAuth & Permissions_ in the left hand menu, then copy the _Bot User OAuth Token_ into your `.env` file under `SLACK_BOT_TOKEN`.
+```zsh
+SLACK_BOT_TOKEN=YOUR_SLACK_BOT_TOKEN
+```
+3. Click _Basic Information_ from the left hand menu and follow the steps in the _App-Level Tokens_ section to create an app-level token with the `connections:write` scope. Copy that token into your `.env` as `SLACK_APP_TOKEN`.
 ```zsh
-# Replace with your app token and bot token
-# For Windows OS, env:SLACK_BOT_TOKEN = <your-bot-token> works
-export SLACK_BOT_TOKEN=<your-bot-token>
-export SLACK_APP_TOKEN=<your-app-token>
-# This sample uses OpenAI's API by default, but you can switch to any other solution!
-export OPENAI_API_KEY=<your-openai-api-key>
+SLACK_APP_TOKEN=YOUR_SLACK_APP_TOKEN
 ```
+4. Save your OpenAI key into `.env` under `OPENAI_API_KEY`.
+```zsh
+OPENAI_API_KEY=YOUR_OPEN_API_KEY
+```
+
 
 ### Setup Your Local Project
 ```zsh
@@ -84,7 +89,7 @@ Configures the new Slack Assistant features, providing a dedicated side panel UI
 *  The `@assistant.thread_started` listener receives an event when users start new app thread.
 *  The `@assistant.user_message` listener processes user messages in app threads or from the app **Chat** and **History** tab.
 
-`llm_caller.py`, which handles OpenAI API integration and message formatting. It includes the `call_llm()` function that sends conversation threads to OpenAI's models.
+`ai/llm_caller.py`, which handles OpenAI API integration and message formatting. It includes the `call_llm()` function that sends conversation threads to OpenAI's models.
 
 ## App Distribution / OAuth
 
diff --git a/ai/llm_caller.py b/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.
diff --git a/app.py b/app.py
@@ -1,12 +1,17 @@
-import os
 import logging
+import os
+
+from dotenv import load_dotenv
 
 from slack_bolt import App
 from slack_bolt.adapter.socket_mode import SocketModeHandler
 from slack_sdk import WebClient
 
 from listeners import register_listeners
 
+# Load environment variables
+load_dotenv(dotenv_path=".env", override=False)
+
 # Initialization
 logging.basicConfig(level=logging.DEBUG)
 
diff --git a/app_oauth.py b/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
 
diff --git a/listeners/__init__.py b/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)
diff --git a/listeners/actions/__init__.py b/listeners/actions/__init__.py
@@ -1,4 +1,5 @@
 from slack_bolt import App
+
 from .actions import handle_feedback
 
 
diff --git a/listeners/actions/actions.py b/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"]
diff --git a/listeners/assistant/__init__.py b/listeners/assistant/__init__.py
@@ -1,4 +1,5 @@
 from slack_bolt import App
+
 from .assistant import assistant
 
 
diff --git a/listeners/assistant/assistant.py b/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 ..llm_caller import call_llm
+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,16 +68,28 @@ 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 = payload["team"]
+        team_id = context.team_id
         thread_ts = payload["thread_ts"]
-        user_id = payload["user"]
+        user_id = context.user_id
         user_message = payload["text"]
 
         set_status(
@@ -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:
diff --git a/listeners/events/__init__.py b/listeners/events/__init__.py
@@ -1,4 +1,5 @@
 from slack_bolt import App
+
 from .app_mentioned import app_mentioned_callback
 
 
diff --git a/listeners/events/app_mentioned.py b/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 ..llm_caller import call_llm
+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")
diff --git a/listeners/views/feedback_block.py b/listeners/views/feedback_block.py
@@ -1,5 +1,6 @@
 from typing import List
-from slack_sdk.models.blocks import Block, ContextActionsBlock, FeedbackButtonsElement, FeedbackButtonObject
+
+from slack_sdk.models.blocks import Block, ContextActionsBlock, FeedbackButtonObject, FeedbackButtonsElement
 
 
 def create_feedback_block() -> List[Block]:
diff --git a/requirements.txt b/requirements.txt
@@ -7,3 +7,4 @@ openai
 pytest
 flake8
 black
+python-dotenv==1.1.1

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`from slack_bolt import App`
	`2`	`+`
`2`	`3`	`from .actions import handle_feedback`
`3`	`4`
`4`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`from slack_bolt import App`
	`2`	`+`
`2`	`3`	`from .assistant import assistant`
`3`	`4`
`4`	`5`