arcade-slack 0.4.6__tar.gz

arcade_slack-0.4.6/.gitignore

@@ -0,0 +1,175 @@
+.DS_Store
+credentials.yaml
+docker/credentials.yaml
+
+*.lock
+
+# example data
+examples/data
+scratch
+
+
+docs/source
+
+# From https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

arcade_slack-0.4.6/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+files: ^.*/slack/.*
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v4.4.0"
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

arcade_slack-0.4.6/.ruff.toml

@@ -0,0 +1,47 @@
+target-version = "py310"
+line-length = 100
+fix = true
+
+[lint]
+select = [
+    # flake8-2020
+    "YTT",
+    # flake8-bandit
+    "S",
+    # flake8-bugbear
+    "B",
+    # flake8-builtins
+    "A",
+    # flake8-comprehensions
+    "C4",
+    # flake8-debugger
+    "T10",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+    # mccabe
+    "C90",
+    # pycodestyle
+    "E", "W",
+    # pyflakes
+    "F",
+    # pygrep-hooks
+    "PGH",
+    # pyupgrade
+    "UP",
+    # ruff
+    "RUF",
+    # tryceratops
+    "TRY",
+]
+
+[lint.per-file-ignores]
+"*" = ["TRY003", "B904"]
+"**/tests/*" = ["S101", "E501"]
+"**/evals/*" = ["S101", "E501"]
+
+
+[format]
+preview = true
+skip-magic-trailing-comma = false

arcade_slack-0.4.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025, Arcade AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arcade_slack-0.4.6/Makefile

@@ -0,0 +1,55 @@
+.PHONY: help
+
+help:
+	@echo "🛠️ github Commands:\n"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: install
+install: ## Install the uv environment and install all packages with dependencies
+	@echo "🚀 Creating virtual environment and installing all packages using uv"
+	@uv sync --active --all-extras --no-sources
+	@if [ -f .pre-commit-config.yaml ]; then uv run --no-sources pre-commit install; fi
+	@echo "✅ All packages and dependencies installed via uv"
+
+.PHONY: install-local
+install-local: ## Install the uv environment and install all packages with dependencies with local Arcade sources
+	@echo "🚀 Creating virtual environment and installing all packages using uv"
+	@uv sync --active --all-extras
+	@if [ -f .pre-commit-config.yaml ]; then uv run pre-commit install; fi
+	@echo "✅ All packages and dependencies installed via uv"
+
+.PHONY: build
+build: clean-build ## Build wheel file using poetry
+	@echo "🚀 Creating wheel file"
+	uv build
+
+.PHONY: clean-build
+clean-build: ## clean build artifacts
+	@echo "🗑️ Cleaning dist directory"
+	rm -rf dist
+
+.PHONY: test
+test: ## Test the code with pytest
+	@echo "🚀 Testing code: Running pytest"
+	@uv run --no-sources pytest -W ignore -v --cov --cov-config=pyproject.toml --cov-report=xml
+
+.PHONY: coverage
+coverage: ## Generate coverage report
+	@echo "coverage report"
+	@uv run --no-sources coverage report
+	@echo "Generating coverage report"
+	@uv run --no-sources coverage html
+
+.PHONY: bump-version
+bump-version: ## Bump the version in the pyproject.toml file by a patch version
+	@echo "🚀 Bumping version in pyproject.toml"
+	uv version --no-sources --bump patch
+
+.PHONY: check
+check: ## Run code quality tools.
+	@if [ -f .pre-commit-config.yaml ]; then\
+		echo "🚀 Linting code: Running pre-commit";\
+		uv run --no-sources pre-commit run -a;\
+	fi
+	@echo "🚀 Static type checking: Running mypy"
+	@uv run --no-sources mypy --config-file=pyproject.toml

arcade_slack-0.4.6/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: arcade_slack
+Version: 0.4.6
+Summary: Arcade.dev LLM tools for Slack
+Author-email: Arcade <dev@arcade.dev>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aiodns<2.0.0,>=1.0
+Requires-Dist: aiohttp<4.0.0,>=3.7.3
+Requires-Dist: arcade-tdk<3.0.0,>=2.0.0
+Requires-Dist: slack-sdk<4.0.0,>=3.31.0
+Requires-Dist: typing; python_version < '3.7'
+Provides-Extra: dev
+Requires-Dist: arcade-ai[evals]<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: arcade-serve<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: mypy<1.6.0,>=1.5.1; extra == 'dev'
+Requires-Dist: pre-commit<3.5.0,>=3.4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<0.25.0,>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov<4.1.0,>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock<3.12.0,>=3.11.1; extra == 'dev'
+Requires-Dist: pytest<8.4.0,>=8.3.0; extra == 'dev'
+Requires-Dist: ruff<0.8.0,>=0.7.4; extra == 'dev'
+Requires-Dist: tox<4.12.0,>=4.11.1; extra == 'dev'

arcade_slack-0.4.6/arcade_slack/constants.py

@@ -0,0 +1,13 @@
+import os
+
+from arcade_slack.custom_types import PositiveInt
+
+MAX_PAGINATION_SIZE_LIMIT = 200
+
+MAX_PAGINATION_TIMEOUT_SECONDS = PositiveInt(
+    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",
+)

arcade_slack-0.4.6/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-0.4.6/arcade_slack/custom_types.py

@@ -0,0 +1,26 @@
+from typing import NewType
+
+
+class PositiveInt(int):
+    def __new__(cls, value: str | int, name: str = "value") -> "PositiveInt":
+        def validate(val: int) -> int:
+            if val <= 0:
+                raise ValueError(f"{name} must be positive, 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-0.4.6/arcade_slack/exceptions.py

@@ -0,0 +1,30 @@
+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.")
+
+
+class ItemNotFoundError(SlackToolkitError):
+    """Raised when an item is not found."""
+
+
+class UsernameNotFoundError(SlackToolkitError):
+    """Raised when a user is not found by the username searched"""
+
+    def __init__(self, usernames_found: list[str], username_not_found: str) -> None:
+        self.usernames_found = usernames_found
+        self.username_not_found = username_not_found
+
+
+class ConversationNotFoundError(SlackToolkitError):
+    """Raised when a conversation is not found"""
+
+
+class DirectMessageConversationNotFoundError(ConversationNotFoundError):
+    """Raised when a direct message conversation searched is not found"""

arcade_slack-0.4.6/arcade_slack/models.py

@@ -0,0 +1,206 @@
+from enum import Enum
+from typing import Literal, TypedDict
+
+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"
+
+
+"""
+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