ed89af4b4d
# Backwards-compatible refactoring of the Slack toolkit Several performance improvements, streamlined tool set, and easier to understand tool interfaces. All "old" tools were kept for backwards compatibility, with the same interfaces and response structure (but using the new and more performant tools under the hood). Full revision of unit-tests and evals. ## Streamlined tool set Multiple groups of tools were streamlined into a single one: * "get conversation metadata" from 5 tools to one; * "send message" from 2 tools to one; * "get users in conversation" from 3 tools to one; * "get messages" from 4 tools to one ## New capabilities * Messages retrieved are now populated with the users' names, apart from ID: makes it easier for LLMs to reference who sent a message, were mentioned, or reacted to a message * Retrieve users by username, email, and/or ID (before we only supported ID) * Retrieve multiple users in a single tool call ## Concurrency controls All operations issuing multiple requests concurrently now have a `Semaphore` to limit the concurrency level. The limit can be controlled through the `SLACK_MAX_CONCURRENT_REQUESTS` env var (defaults to 3). ## Networking performance improvement Various operations that used to make multiple API calls are now executed more efficiently: ### Find users by username * Before: a full scan of `users_list` was required (potentially multiple pages for large workspaces); * Now it stops as soon as we have all users needed (yes, it was dumb before) ### Get multiple users by their IDs * Before: for each user ID, we made one API call to the `users_info` endpoint * Now: we call `list_users` and scan the results to match the user IDs (an estimate of 99.5% of Slack workspaces have < 200 users; for large workspaces, we may need to paginate `list_users`) ### Get a conversation by its users * Before: * Call to `list_conversations` (potentially paginating) * For each conversation, one call to `conversations_members` (potentially paginating) * Then loop and find which conversation matches the users' IDs * Now: * A single call to `conversations_open`
99 lines
4.1 KiB
Python
99 lines
4.1 KiB
Python
from typing import Annotated, Any, cast
|
|
|
|
from arcade_tdk import ToolContext, tool
|
|
from arcade_tdk.auth import Slack
|
|
from slack_sdk.web.async_client import AsyncWebClient
|
|
|
|
from arcade_slack.constants import MAX_PAGINATION_TIMEOUT_SECONDS
|
|
from arcade_slack.models import (
|
|
SlackPaginationNextCursor,
|
|
)
|
|
from arcade_slack.user_retrieval import get_users_by_id_username_or_email
|
|
from arcade_slack.utils import (
|
|
async_paginate,
|
|
extract_basic_user_info,
|
|
is_user_a_bot,
|
|
is_user_deleted,
|
|
)
|
|
|
|
|
|
@tool(requires_auth=Slack(scopes=["users:read", "users:read.email"]))
|
|
async def get_users_info(
|
|
context: ToolContext,
|
|
user_ids: Annotated[list[str] | None, "The IDs of the users to get"] = None,
|
|
usernames: Annotated[
|
|
list[str] | None,
|
|
"The usernames of the users to get. Prefer retrieving by user_ids and/or emails, "
|
|
"when available, since the performance is better.",
|
|
] = None,
|
|
emails: Annotated[list[str] | None, "The emails of the users to get"] = None,
|
|
) -> Annotated[dict[str, Any], "The users' information"]:
|
|
"""Get the information of one or more users in Slack by ID, username, and/or email.
|
|
|
|
Provide any combination of user_ids, usernames, and/or emails. If you need to retrieve
|
|
data about multiple users, DO NOT CALL THE TOOL MULTIPLE TIMES. Instead, call it once
|
|
with all the user_ids, usernames, and/or emails. IF YOU CALL THIS TOOL MULTIPLE TIMES
|
|
UNNECESSARILY, YOU WILL RELEASE MORE CO2 IN THE ATMOSPHERE AND CONTRIBUTE TO GLOBAL WARMING.
|
|
|
|
If you need to get metadata or messages of a conversation, use the
|
|
`Slack.GetConversationMetadata` or `Slack.GetMessages` tool instead. These
|
|
tools accept user_ids, usernames, and/or emails. Do not retrieve users' info first,
|
|
as it is inefficient, releases more CO2 in the atmosphere, and contributes to climate change.
|
|
"""
|
|
users = await get_users_by_id_username_or_email(context, user_ids, usernames, emails)
|
|
return {"users": users}
|
|
|
|
|
|
@tool(requires_auth=Slack(scopes=["users:read", "users:read.email"]))
|
|
async def list_users(
|
|
context: ToolContext,
|
|
exclude_bots: Annotated[
|
|
bool | None, "Whether to exclude bots from the results. Defaults to True."
|
|
] = True,
|
|
limit: Annotated[
|
|
int,
|
|
# The user object is relatively small, so we allow a higher limit than the default of 200.
|
|
"The maximum number of users to return. Defaults to 200. Maximum is 500.",
|
|
] = 200,
|
|
next_cursor: Annotated[str | None, "The next cursor token to use for pagination."] = None,
|
|
) -> Annotated[dict, "The users' info"]:
|
|
"""List all users in the authenticated user's Slack team.
|
|
|
|
If you need to get metadata or messages of a conversation, use the
|
|
`Slack.GetConversationMetadata` tool or `Slack.GetMessages` tool instead. These
|
|
tools accept a user_id, username, and/or email. Do not use this tool to first retrieve user(s),
|
|
as it is inefficient and releases more CO2 in the atmosphere, contributing to climate change.
|
|
"""
|
|
limit = max(1, min(limit, 500))
|
|
slack_client = AsyncWebClient(token=context.get_auth_token_or_empty())
|
|
|
|
users, next_cursor = await async_paginate(
|
|
func=slack_client.users_list,
|
|
response_key="members",
|
|
limit=limit,
|
|
next_cursor=cast(SlackPaginationNextCursor, next_cursor),
|
|
max_pagination_timeout_seconds=MAX_PAGINATION_TIMEOUT_SECONDS,
|
|
)
|
|
|
|
users = [
|
|
extract_basic_user_info(user)
|
|
for user in users
|
|
if not is_user_deleted(user) and (not exclude_bots or not is_user_a_bot(user))
|
|
]
|
|
|
|
return {"users": users, "next_cursor": next_cursor}
|
|
|
|
|
|
# NOTE: This tool is kept here for backwards compatibility.
|
|
# Use the `Slack.GetUsersInfo` tool instead.
|
|
@tool(requires_auth=Slack(scopes=["users:read", "users:read.email"]))
|
|
async def get_user_info_by_id(
|
|
context: ToolContext,
|
|
user_id: Annotated[str, "The ID of the user to get"],
|
|
) -> Annotated[dict[str, Any], "The user's information"]:
|
|
"""Get the information of a user in Slack.
|
|
|
|
This tool is deprecated. Use the `Slack.GetUsersInfo` tool instead.
|
|
"""
|
|
users = await get_users_info(context, user_ids=[user_id])
|
|
return cast(dict[str, Any], users["users"][0])
|