arcade-slack 0.1.6__py3-none-any.whl → 0.5.0__py3-none-any.whl

arcade_slack/constants.py

@@ -0,0 +1,18 @@
+import os
+
+from arcade_slack.custom_types import PositiveNonZeroInt
+
+MAX_PAGINATION_SIZE_LIMIT = 200
+
+MAX_PAGINATION_TIMEOUT_SECONDS = PositiveNonZeroInt(
+    os.environ.get(
+        "MAX_PAGINATION_TIMEOUT_SECONDS",
+        os.environ.get("MAX_SLACK_PAGINATION_TIMEOUT_SECONDS", 30),
+    ),
+    name="MAX_PAGINATION_TIMEOUT_SECONDS or MAX_SLACK_PAGINATION_TIMEOUT_SECONDS",
+)
+
+MAX_CONCURRENT_REQUESTS = PositiveNonZeroInt(
+    os.environ.get("SLACK_MAX_CONCURRENT_REQUESTS", 3),
+    name="SLACK_MAX_CONCURRENT_REQUESTS",
+)

arcade_slack/conversation_retrieval.py

@@ -0,0 +1,74 @@
+import json
+from typing import cast
+
+from arcade_tdk.errors import RetryableToolError, ToolExecutionError
+from slack_sdk.errors import SlackApiError
+from slack_sdk.web.async_client import AsyncWebClient
+
+from arcade_slack.models import (
+    ConversationType,
+    FindChannelByNameSentinel,
+)
+from arcade_slack.utils import (
+    async_paginate,
+    extract_conversation_metadata,
+)
+
+
+async def get_conversation_by_id(
+    auth_token: str,
+    conversation_id: str,
+) -> dict:
+    """Get metadata of a conversation in Slack by the conversation_id."""
+    try:
+        slack_client = AsyncWebClient(token=auth_token)
+        response = await slack_client.conversations_info(
+            channel=conversation_id,
+            include_locale=True,
+            include_num_members=True,
+        )
+        return dict(**extract_conversation_metadata(response["channel"]))
+
+    except SlackApiError as e:
+        slack_error = cast(str, e.response.get("error", ""))
+        if "not_found" in slack_error.lower():
+            message = f"Conversation with ID '{conversation_id}' not found."
+            raise ToolExecutionError(message=message, developer_message=message)
+        raise
+
+
+async def get_channel_by_name(
+    auth_token: str,
+    channel_name: str,
+) -> dict:
+    channel_name_casefolded = channel_name.lstrip("#").casefold()
+
+    slack_client = AsyncWebClient(token=auth_token)
+
+    results, _ = await async_paginate(
+        func=slack_client.conversations_list,
+        response_key="channels",
+        types=",".join([
+            ConversationType.PUBLIC_CHANNEL.value,
+            ConversationType.PRIVATE_CHANNEL.value,
+        ]),
+        exclude_archived=True,
+        sentinel=FindChannelByNameSentinel(channel_name_casefolded),
+    )
+
+    available_channels = []
+
+    for channel in results:
+        if channel["name"].casefold() == channel_name_casefolded:
+            return dict(**extract_conversation_metadata(channel))
+        else:
+            available_channels.append({"id": channel["id"], "name": channel["name"]})
+
+    error_message = f"Channel with name '{channel_name}' not found."
+
+    raise RetryableToolError(
+        message=error_message,
+        developer_message=error_message,
+        additional_prompt_content=f"Available channels: {json.dumps(available_channels)}",
+        retry_after_ms=500,
+    )

arcade_slack/critics.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+from arcade_evals import BinaryCritic
+
+
+class RelativeTimeBinaryCritic(BinaryCritic):
+    def evaluate(self, expected: Any, actual: Any) -> dict[str, float | bool]:
+        """
+        Evaluates whether the expected and actual relative time strings are equivalent after
+        casting.
+
+        Args:
+            expected: The expected value.
+            actual: The actual value to compare, cast to the type of expected.
+
+        Returns:
+            dict: A dictionary containing the match status and score.
+        """
+        try:
+            actual_casted = self.cast_actual(expected, actual)
+        except TypeError:
+            actual_casted = actual
+
+        expected_parts = tuple(map(int, expected.split(":")))
+        actual_parts = tuple(map(int, actual_casted.split(":")))
+
+        if len(expected_parts) != 3 or len(actual_parts) != 3:
+            return {"match": False, "score": 0.0}
+
+        exp_days, exp_hours, exp_minutes = expected_parts
+        act_days, act_hours, act_minutes = actual_parts
+
+        match = exp_days == act_days and exp_hours == act_hours and exp_minutes == act_minutes
+        return {"match": match, "score": self.weight if match else 0.0}

arcade_slack/custom_types.py

@@ -0,0 +1,26 @@
+from typing import NewType
+
+
+class PositiveNonZeroInt(int):
+    def __new__(cls, value: str | int, name: str = "value") -> "PositiveNonZeroInt":
+        def validate(val: int) -> int:
+            if val < 1:
+                raise ValueError(f"{name} must be a positive non-zero integer, got {val}")
+            return val
+
+        try:
+            value = int(value)
+        except ValueError:
+            raise ValueError(f"{name} must be a valid integer, got {value!r}")
+
+        validated_value = validate(value)
+        instance = super().__new__(cls, validated_value)
+        return instance
+
+
+SlackOffsetSecondsFromUTC = NewType("SlackOffsetSecondsFromUTC", int)  # observe it can be negative
+SlackPaginationNextCursor = str | None
+SlackUserFieldId = NewType("SlackUserFieldId", str)
+SlackUserId = NewType("SlackUserId", str)
+SlackTeamId = NewType("SlackTeamId", str)
+SlackTimestampStr = NewType("SlackTimestampStr", str)

arcade_slack/exceptions.py

@@ -0,0 +1,10 @@
+class SlackToolkitError(Exception):
+    """Base class for all Slack toolkit errors."""
+
+
+class PaginationTimeoutError(SlackToolkitError):
+    """Raised when a timeout occurs during pagination."""
+
+    def __init__(self, timeout_seconds: int):
+        self.timeout_seconds = timeout_seconds
+        super().__init__(f"The pagination process timed out after {timeout_seconds} seconds.")

arcade_slack/message_retrieval.py

@@ -0,0 +1,76 @@
+from datetime import datetime, timezone
+from typing import Any
+
+from arcade_tdk.errors import ToolExecutionError
+from slack_sdk.web.async_client import AsyncWebClient
+
+from arcade_slack.utils import (
+    async_paginate,
+    convert_datetime_to_unix_timestamp,
+    convert_relative_datetime_to_unix_timestamp,
+    enrich_message_datetime,
+)
+
+
+async def retrieve_messages_in_conversation(
+    conversation_id: str,
+    auth_token: str | None = None,
+    oldest_relative: str | None = None,
+    latest_relative: str | None = None,
+    oldest_datetime: str | None = None,
+    latest_datetime: str | None = None,
+    limit: int | None = None,
+    next_cursor: str | None = None,
+) -> dict:
+    error_message = None
+    if oldest_datetime and oldest_relative:
+        error_message = "Cannot specify both 'oldest_datetime' and 'oldest_relative'."
+
+    if latest_datetime and latest_relative:
+        error_message = "Cannot specify both 'latest_datetime' and 'latest_relative'."
+
+    if error_message:
+        raise ToolExecutionError(error_message, developer_message=error_message)
+
+    current_unix_timestamp = int(datetime.now(timezone.utc).timestamp())
+
+    if latest_relative:
+        latest_timestamp = convert_relative_datetime_to_unix_timestamp(
+            latest_relative, current_unix_timestamp
+        )
+    elif latest_datetime:
+        latest_timestamp = convert_datetime_to_unix_timestamp(latest_datetime)
+    else:
+        latest_timestamp = None
+
+    if oldest_relative:
+        oldest_timestamp = convert_relative_datetime_to_unix_timestamp(
+            oldest_relative, current_unix_timestamp
+        )
+    elif oldest_datetime:
+        oldest_timestamp = convert_datetime_to_unix_timestamp(oldest_datetime)
+    else:
+        oldest_timestamp = None
+
+    datetime_args: dict[str, Any] = {}
+    if oldest_timestamp:
+        datetime_args["oldest"] = oldest_timestamp
+    if latest_timestamp:
+        datetime_args["latest"] = latest_timestamp
+
+    slackClient = AsyncWebClient(token=auth_token)
+
+    response, next_cursor = await async_paginate(
+        slackClient.conversations_history,
+        "messages",
+        limit=limit,
+        next_cursor=next_cursor,
+        channel=conversation_id,
+        include_all_metadata=True,
+        inclusive=True,  # Include messages at the start and end of the time range
+        **datetime_args,
+    )
+
+    messages = [enrich_message_datetime(message) for message in response]
+
+    return {"messages": messages, "next_cursor": next_cursor}

arcade_slack/models.py

@@ -0,0 +1,370 @@
+import asyncio
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from enum import Enum
+from typing import Any, Literal, TypedDict
+
+from arcade_tdk.errors import ToolExecutionError
+from slack_sdk.errors import SlackApiError
+
+from arcade_slack.custom_types import (
+    SlackOffsetSecondsFromUTC,
+    SlackPaginationNextCursor,
+    SlackTeamId,
+    SlackTimestampStr,
+    SlackUserFieldId,
+    SlackUserId,
+)
+
+
+class ConversationTypeSlackName(str, Enum):
+    PUBLIC_CHANNEL = "public_channel"  # Public channels are visible to all users in the workspace
+    PRIVATE_CHANNEL = "private_channel"  # Private channels are visible to only specific users
+    MPIM = "mpim"  # Multi-person direct message conversation
+    IM = "im"  # Two person direct message conversation
+
+
+class ConversationType(str, Enum):
+    PUBLIC_CHANNEL = "public_channel"
+    PRIVATE_CHANNEL = "private_channel"
+    MULTI_PERSON_DIRECT_MESSAGE = "multi_person_direct_message"
+    DIRECT_MESSAGE = "direct_message"
+
+    def to_slack_name_str(self) -> str:
+        mapping = {
+            ConversationType.PUBLIC_CHANNEL: ConversationTypeSlackName.PUBLIC_CHANNEL.value,
+            ConversationType.PRIVATE_CHANNEL: ConversationTypeSlackName.PRIVATE_CHANNEL.value,
+            ConversationType.MULTI_PERSON_DIRECT_MESSAGE: ConversationTypeSlackName.MPIM.value,
+            ConversationType.DIRECT_MESSAGE: ConversationTypeSlackName.IM.value,
+        }
+
+        return mapping[self]
+
+
+"""
+About Slack dictionaries: Slack does not guarantee the presence of all fields for a given
+object. It will vary from endpoint to endpoint and even if the field is present, they say it may
+contain a None value or an empty string instead of the actual expected value.
+
+See, for example, the 'Common Fields' section of the user type definition at:
+https://api.slack.com/types/user#fields (https://archive.is/RUZdL)
+
+Because of that, our TypedDicts ended up having to be mostly total=False and most of the fields'
+type hints are Optional. Use Slack dictionary fields with caution. It's advisable to validate the
+value before using it and raise errors that are clear to understand, when appropriate.
+"""
+
+
+class SlackUserFieldData(TypedDict, total=False):
+    """Type definition for Slack user field data dictionary.
+
+    Slack type definition: https://api.slack.com/methods/users.profile.set#custom-profile
+    """
+
+    value: str | None
+    alt: bool | None
+
+
+class SlackStatusEmojiDisplayInfo(TypedDict, total=False):
+    """Type definition for Slack status emoji display info dictionary."""
+
+    emoji_name: str | None
+    display_url: str | None
+
+
+class SlackUserProfile(TypedDict, total=False):
+    """Type definition for Slack user profile dictionary.
+
+    Slack type definition: https://api.slack.com/types/user#profile (https://archive.is/RUZdL)
+    """
+
+    title: str | None
+    phone: str | None
+    skype: str | None
+    email: str | None
+    real_name: str | None
+    real_name_normalized: str | None
+    display_name: str | None
+    display_name_normalized: str | None
+    first_name: str | None
+    last_name: str | None
+    fields: list[dict[SlackUserFieldId, SlackUserFieldData]] | None
+    image_original: str | None
+    is_custom_image: bool | None
+    image_24: str | None
+    image_32: str | None
+    image_48: str | None
+    image_72: str | None
+    image_192: str | None
+    image_512: str | None
+    image_1024: str | None
+    status_emoji: str | None
+    status_emoji_display_info: list[SlackStatusEmojiDisplayInfo] | None
+    status_text: str | None
+    status_text_canonical: str | None
+    status_expiration: int | None
+    avatar_hash: str | None
+    start_date: str | None
+    pronouns: str | None
+    huddle_state: str | None
+    huddle_state_expiration: int | None
+    team: SlackTeamId | None
+
+
+class SlackUser(TypedDict, total=False):
+    """Type definition for Slack user dictionary.
+
+    Slack type definition: https://api.slack.com/types/user (https://archive.is/RUZdL)
+    """
+
+    id: SlackUserId
+    team_id: SlackTeamId
+    name: str | None
+    deleted: bool | None
+    color: str | None
+    real_name: str | None
+    tz: str | None
+    tz_label: str | None
+    tz_offset: SlackOffsetSecondsFromUTC | None
+    profile: SlackUserProfile | None
+    is_admin: bool | None
+    is_owner: bool | None
+    is_primary_owner: bool | None
+    is_restricted: bool | None
+    is_ultra_restricted: bool | None
+    is_bot: bool | None
+    is_app_user: bool | None
+    is_email_confirmed: bool | None
+    who_can_share_contact_card: str | None
+
+
+class SlackUserList(TypedDict, total=False):
+    """Type definition for the returned user list dictionary."""
+
+    members: list[SlackUser]
+
+
+class SlackConversationPurpose(TypedDict, total=False):
+    """Type definition for the Slack conversation purpose dictionary."""
+
+    value: str | None
+
+
+class SlackConversation(TypedDict, total=False):
+    """Type definition for the Slack conversation dictionary."""
+
+    id: str | None
+    name: str | None
+    is_private: bool | None
+    is_archived: bool | None
+    is_member: bool | None
+    is_channel: bool | None
+    is_group: bool | None
+    is_im: bool | None
+    is_mpim: bool | None
+    purpose: SlackConversationPurpose | None
+    num_members: int | None
+    user: SlackUser | None
+    is_user_deleted: bool | None
+
+
+class SlackMessage(TypedDict, total=True):
+    """Type definition for the Slack message dictionary."""
+
+    type: Literal["message"]
+    user: SlackUser
+    text: str
+    ts: SlackTimestampStr  # Slack timestamp as a string (e.g. "1234567890.123456")
+
+
+class Message(SlackMessage, total=False):
+    """Type definition for the message dictionary.
+
+    Having a human-readable datetime string is useful for LLMs when they need to display the
+    date/time for the user. If not, they'll try to convert the unix timestamp to a human-readable
+    date/time,which they don't usually do accurately.
+    """
+
+    datetime_timestamp: str  # Human-readable datetime string (e.g. "2025-01-22 12:00:00")
+
+
+class ConversationMetadata(TypedDict, total=False):
+    """Type definition for the conversation metadata dictionary."""
+
+    id: str | None
+    name: str | None
+    conversation_type: str | None
+    is_private: bool | None
+    is_archived: bool | None
+    is_member: bool | None
+    purpose: str | None
+    num_members: int | None
+    user: SlackUser | None
+    is_user_deleted: bool | None
+
+
+class BasicUserInfo(TypedDict, total=False):
+    """Type definition for the returned basic user info dictionary."""
+
+    id: str | None
+    name: str | None
+    is_bot: bool | None
+    email: str | None
+    display_name: str | None
+    real_name: str | None
+    timezone: str | None
+
+
+class SlackConversationsToolResponse(TypedDict, total=True):
+    """Type definition for the Slack conversations tool response dictionary."""
+
+    conversations: list[ConversationMetadata]
+    next_cursor: SlackPaginationNextCursor | None
+
+
+class PaginationSentinel(ABC):
+    """Base class for pagination sentinel classes."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        self.kwargs = kwargs
+
+    @abstractmethod
+    def __call__(self, last_result: Any) -> bool:
+        """Determine if the pagination should stop."""
+        raise NotImplementedError
+
+
+class FindUserByUsernameSentinel(PaginationSentinel):
+    """Sentinel class for finding a user by username."""
+
+    def __call__(self, last_result: Any) -> bool:
+        for user in last_result:
+            if not isinstance(user.get("name"), str):
+                continue
+            if user.get("name").casefold() == self.kwargs["username"].casefold():
+                return True
+        return False
+
+
+class FindMultipleUsersByUsernameSentinel(PaginationSentinel):
+    """Sentinel class for finding multiple users by username."""
+
+    def __init__(self, usernames: list[str]) -> None:
+        if not usernames:
+            raise ValueError("usernames must be a non-empty list of strings")
+        super().__init__(usernames=usernames)
+        self.usernames_pending = {username.casefold() for username in usernames}
+
+    def _flag_username_found(self, username: str) -> None:
+        with suppress(KeyError):
+            self.usernames_pending.remove(username.casefold())
+
+    def _all_usernames_found(self) -> bool:
+        return not self.usernames_pending
+
+    def __call__(self, last_result: Any) -> bool:
+        if not self.usernames_pending:
+            return True
+        for user in last_result:
+            username = user.get("name")
+            if not isinstance(username, str):
+                continue
+            if username.casefold() in self.usernames_pending:
+                self._flag_username_found(username)
+                if self._all_usernames_found():
+                    return True
+        return False
+
+
+class FindMultipleUsersByIdSentinel(PaginationSentinel):
+    """Sentinel class for finding multiple users by ID."""
+
+    def __init__(self, user_ids: list[str]) -> None:
+        if not user_ids:
+            raise ValueError("user_ids must be a non-empty list of strings")
+        super().__init__(user_ids=user_ids)
+        self.user_ids_pending = set(user_ids)
+
+    def _flag_user_id_found(self, user_id: str) -> None:
+        with suppress(KeyError):
+            self.user_ids_pending.remove(user_id.casefold())
+
+    def _all_user_ids_found(self) -> bool:
+        return not self.user_ids_pending
+
+    def __call__(self, last_result: Any) -> bool:
+        if not self.user_ids_pending:
+            return True
+        for user in last_result:
+            user_id = user.get("id")
+            if user_id in self.user_ids_pending:
+                self._flag_user_id_found(user_id)
+                if self._all_user_ids_found():
+                    return True
+        return False
+
+
+class FindChannelByNameSentinel(PaginationSentinel):
+    """Sentinel class for finding a channel by name."""
+
+    def __init__(self, channel_name: str) -> None:
+        super().__init__(channel_name=channel_name)
+        self.channel_name_casefold = channel_name.casefold()
+
+    def __call__(self, last_result: Any) -> bool:
+        for channel in last_result:
+            channel_name = channel.get("name")
+            if not isinstance(channel_name, str):
+                continue
+            if channel_name.casefold() == self.channel_name_casefold:
+                return True
+        return False
+
+
+class AbstractConcurrencySafeCoroutineCaller(ABC):
+    """Abstract base class for concurrency-safe coroutine callers."""
+
+    def __init__(self, func: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> None:
+        self.func = func
+        self.args = args
+        self.kwargs = kwargs
+
+    @abstractmethod
+    async def __call__(self, semaphore: asyncio.Semaphore) -> Any:
+        """Call a coroutine with a semaphore."""
+        raise NotImplementedError
+
+
+class ConcurrencySafeCoroutineCaller(AbstractConcurrencySafeCoroutineCaller):
+    """Calls a coroutine with an asyncio semaphore."""
+
+    async def __call__(self, semaphore: asyncio.Semaphore) -> Any:
+        async with semaphore:
+            return await self.func(*self.args, **self.kwargs)
+
+
+class GetUserByEmailCaller(AbstractConcurrencySafeCoroutineCaller):
+    """Call Slack's lookupByEmail method with an asyncio semaphore while handling API errors."""
+
+    def __init__(
+        self,
+        func: Callable[..., Awaitable[Any]],
+        email: str,
+    ) -> None:
+        super().__init__(func)
+        self.email = email
+
+    async def __call__(self, semaphore: asyncio.Semaphore) -> dict[str, Any]:
+        async with semaphore:
+            try:
+                user = await self.func(email=self.email)
+                return {"user": user["user"], "email": self.email}
+            except SlackApiError as e:
+                if e.response.get("error") in ["user_not_found", "users_not_found"]:
+                    return {"user": None, "email": self.email}
+                else:
+                    raise ToolExecutionError(
+                        message="Error getting user by email",
+                        developer_message=f"Error getting user by email: {e.response.get('error')}",
+                    )