microsoft-agents-hosting-slack 1.1.0.dev7__tar.gz

microsoft_agents_hosting_slack-1.1.0.dev7/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    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

microsoft_agents_hosting_slack-1.1.0.dev7/MANIFEST.in

@@ -0,0 +1 @@
+include VERSION.txt

microsoft_agents_hosting_slack-1.1.0.dev7/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-hosting-slack
+Version: 1.1.0.dev7
+Summary: Integration library for Microsoft Agents with Slack
+Author: Microsoft Corporation
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: microsoft-agents-hosting-core==1.1.0.dev7
+Requires-Dist: aiohttp>=3.11.11
+Dynamic: license-file
+Dynamic: requires-dist
+
+# Microsoft Agents Hosting - Slack
+
+[![PyPI version](https://img.shields.io/pypi/v/microsoft-agents-hosting-slack)](https://pypi.org/project/microsoft-agents-hosting-slack/)
+
+Integration library for building Slack agents using the Microsoft 365 Agents SDK. Provides direct-to-Slack responses (the full Slack Web API surface, beyond what Azure Bot Service exposes), a typed `SlackChannelData` envelope with dot-notation property access, and a `SlackStream` helper for `chat.startStream` / `chat.appendStream` / `chat.stopStream`.
+
+## Installation
+
+```bash
+pip install microsoft-agents-hosting-slack
+```
+
+## Usage
+
+```python
+from microsoft_agents.hosting.core.app import AgentApplication
+from microsoft_agents.hosting.slack import SlackAgentExtension
+from microsoft_agents.hosting.slack.api import SlackChannelData
+
+app = AgentApplication(options)
+slack = SlackAgentExtension(app)
+
+@slack.on_message()
+async def on_slack_message(context, state):
+    channel_data = SlackChannelData.from_activity(context.activity)
+    await slack.call(
+        context,
+        "chat.postMessage",
+        {
+            "channel": channel_data.get("event.channel"),
+            "text": f"You said: {context.activity.text}",
+        },
+        token=channel_data.api_token,
+    )
+```
+
+## Key Classes
+
+- **`SlackAgentExtension`** — registers Slack-channel-scoped message/event handlers; exposes `call(...)` and `create_stream(...)`.
+- **`SlackChannelData`** — typed wrapper around Bot Service's Slack channel-data payload with `get(path)` / `try_get(path)` accessors.
+- **`SlackApi`** — async HTTP client for the Slack Web API.
+- **`SlackStream`** — wraps Slack's streaming methods for incremental message updates.
+- **`SlackHelpers`** — encode/decode and conversation-id parsing utilities.
+
+# Quick Links
+
+- 📦 [All SDK Packages on PyPI](https://pypi.org/search/?q=microsoft-agents)
+- 📖 [Complete Documentation](https://aka.ms/agents)
+- 🐛 [Report Issues](https://github.com/microsoft/Agents-for-python/issues)

microsoft_agents_hosting_slack-1.1.0.dev7/VERSION.txt

@@ -0,0 +1 @@
+1.1.0.dev7

microsoft_agents_hosting_slack-1.1.0.dev7/microsoft_agents/hosting/slack/__init__.py

@@ -0,0 +1,26 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from .slack_agent_extension import SlackAgentExtension
+from .slack_helpers import (
+    create_conversation_id,
+    slack_bot_id_from_conversation_id,
+    slack_channel_id_from_conversation_id,
+    slack_decode,
+    slack_encode,
+    slack_team_id_from_conversation_id,
+    slack_thread_ts_from_conversation_id,
+)
+
+__all__ = [
+    "SlackAgentExtension",
+    "create_conversation_id",
+    "slack_bot_id_from_conversation_id",
+    "slack_channel_id_from_conversation_id",
+    "slack_decode",
+    "slack_encode",
+    "slack_team_id_from_conversation_id",
+    "slack_thread_ts_from_conversation_id",
+]

microsoft_agents_hosting_slack-1.1.0.dev7/microsoft_agents/hosting/slack/_path_navigator.py

@@ -0,0 +1,108 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple
+
+
+def _parse_path(path: str) -> Optional[list[int | str]]:
+    """Tokenize a dot/bracket path into a list of segments.
+
+    Supports ``a.b.c``, ``a[0].b``, ``a[1][2]``. Integer brackets become ``int``
+    segments; everything else becomes a string segment. Returns ``None`` for
+    malformed bracket nesting.
+    """
+    if not path:
+        return []
+
+    segments: list[Any] = []
+    i = 0
+    start = 0
+
+    def emit() -> None:
+        nonlocal start
+        if start < i:
+            segments.append(path[start:i])
+        start = i + 1
+
+    while i < len(path):
+        ch = path[i]
+        if ch == ".":
+            emit()
+        elif ch == "[":
+            emit()
+            nesting = 1
+            i += 1
+            inner_start = i
+            while i < len(path):
+                c = path[i]
+                if c == "[":
+                    nesting += 1
+                elif c == "]":
+                    nesting -= 1
+                    if nesting == 0:
+                        break
+                i += 1
+            if nesting != 0:
+                return None
+            inner = path[inner_start:i]
+            if inner.isdigit() or (inner.startswith("-") and inner[1:].isdigit()):
+                segments.append(int(inner))
+            else:
+                segments.append(inner)
+            start = i + 1
+        i += 1
+
+    emit()
+    return segments
+
+
+def _resolve_segment(current: Any, segment: Any) -> Tuple[bool, Any]:
+    """Resolve one path segment against the current node.
+
+    Returns ``(found, value)``. ``found`` is False when the segment cannot be
+    resolved (missing key, out-of-range index, primitive node).
+    """
+    if current is None:
+        return False, None
+
+    if isinstance(segment, int):
+        if isinstance(current, (list, tuple)):
+            if -len(current) <= segment < len(current):
+                return True, current[segment]
+            return False, None
+        return False, None
+
+    # string segment → dict key (case-sensitive fast path, case-insensitive fallback)
+    if isinstance(current, dict):
+        if segment in current:
+            return True, current[segment]
+        lower = segment.lower()
+        for key, value in current.items():
+            if isinstance(key, str) and key.lower() == lower:
+                return True, value
+        return False, None
+
+    return False, None
+
+
+def try_get_path_value(data: Any, path: str) -> Tuple[bool, Any]:
+    """Walk ``path`` against ``data``. Returns ``(found, value)``."""
+    if data is None:
+        return False, None
+    if not path:
+        return True, data
+
+    segments = _parse_path(path)
+    if segments is None:
+        return False, None
+
+    current: Any = data
+    for segment in segments:
+        found, current = _resolve_segment(current, segment)
+        if not found:
+            return False, None
+    return True, current

microsoft_agents_hosting_slack-1.1.0.dev7/microsoft_agents/hosting/slack/api/__init__.py

@@ -0,0 +1,42 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from .action_payload import ActionPayload
+from .chunks import (
+    BlocksChunk,
+    Chunk,
+    MarkdownTextChunk,
+    SlackTaskStatus,
+    Source,
+    TaskDisplayMode,
+    TaskUpdateChunk,
+)
+from .event_content import EventContent
+from .event_envelope import EventEnvelope
+from .slack_api import SLACK_API_BASE, SlackApi
+from .slack_channel_data import SlackChannelData
+from .slack_model import SlackModel
+from .slack_response import SlackResponse, SlackResponseException
+from .slack_stream import SlackStream
+
+__all__ = [
+    "ActionPayload",
+    "BlocksChunk",
+    "Chunk",
+    "EventContent",
+    "EventEnvelope",
+    "MarkdownTextChunk",
+    "SLACK_API_BASE",
+    "SlackApi",
+    "SlackChannelData",
+    "SlackModel",
+    "SlackResponse",
+    "SlackResponseException",
+    "SlackStream",
+    "SlackTaskStatus",
+    "Source",
+    "TaskDisplayMode",
+    "TaskUpdateChunk",
+]

microsoft_agents_hosting_slack-1.1.0.dev7/microsoft_agents/hosting/slack/api/action_payload.py

@@ -0,0 +1,26 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import ConfigDict
+
+from .slack_model import SlackModel
+
+
+class ActionPayload(SlackModel):
+    """
+    Interactive Message / Block Kit action payload from Slack. Sent when a user
+    clicks a button or interacts with a block element.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: Optional[str] = None
+    channel: Optional[Any] = None
+    message: Optional[Any] = None
+    actions: Optional[Any] = None

microsoft_agents_hosting_slack-1.1.0.dev7/microsoft_agents/hosting/slack/api/chunks.py

@@ -0,0 +1,77 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+
+Streaming chunk shapes for Slack ``chat.appendStream`` / ``chat.stopStream``.
+See https://docs.slack.dev/reference/methods/chat.appendStream
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SlackTaskStatus:
+    """Status values accepted by :class:`TaskUpdateChunk`."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETE = "complete"
+    ERROR = "error"
+
+
+class TaskDisplayMode:
+    """Values accepted by ``chat.startStream``'s ``task_display_mode``."""
+
+    PLAN = "plan"
+    TIMELINE = "timeline"
+
+
+class Source(BaseModel):
+    """Citation/source attached to a :class:`TaskUpdateChunk`."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: str = "url"
+    url: str = ""
+    text: str = ""
+
+
+class MarkdownTextChunk(BaseModel):
+    """Append a chunk of markdown-formatted text to a Slack stream."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: str = Field(default="markdown_text", frozen=True)
+    text: str = ""
+
+
+class BlocksChunk(BaseModel):
+    """Append a chunk of Block Kit blocks to a Slack stream."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: str = Field(default="blocks", frozen=True)
+    blocks: list[Any] = Field(default_factory=list)
+
+
+class TaskUpdateChunk(BaseModel):
+    """Append a task-status update chunk to a Slack stream."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: str = Field(default="task_update", frozen=True)
+    id: str
+    title: str
+    status: str = SlackTaskStatus.IN_PROGRESS
+    details: Optional[str] = None
+    output: Optional[str] = None
+    sources: Optional[list[Source]] = None
+
+
+# Type alias for any chunk variant.
+Chunk = (
+    BaseModel  # all chunk classes are BaseModel subclasses with a `type` discriminator
+)

microsoft_agents_hosting_slack-1.1.0.dev7/microsoft_agents/hosting/slack/api/event_content.py

@@ -0,0 +1,45 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import ConfigDict
+
+from .slack_model import SlackModel
+
+
+class EventContent(SlackModel):
+    """
+    The inner ``event`` object from a Slack Events API callback payload.
+
+    Slack calls this the "event content". Because event payloads vary so widely
+    by ``type``, every unmodelled field is preserved via Pydantic's
+    ``extra="allow"`` and is reachable through :meth:`SlackModel.get` using the
+    same snake_case names shown in the Slack docs.
+
+    See https://docs.slack.dev/reference/events
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    # ── Common event fields (https://docs.slack.dev/apis/events-api/#event-type-structure)
+    type: Optional[str] = None
+    event_ts: Optional[str] = None
+    user: Optional[str] = None
+    ts: Optional[str] = None
+    subtype: Optional[str] = None
+    channel: Optional[str] = None
+    channel_type: Optional[str] = None
+    team: Optional[str] = None
+
+    # ── message event fields ──
+    text: Optional[str] = None
+    client_msg_id: Optional[str] = None
+
+    # ── reaction_added / reaction_removed event fields ──
+    reaction: Optional[str] = None
+    item_user: Optional[str] = None

microsoft_agents_hosting_slack-1.1.0.dev7/microsoft_agents/hosting/slack/api/event_envelope.py

@@ -0,0 +1,56 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import ConfigDict, Field
+
+from .event_content import EventContent
+from .slack_model import SlackModel
+
+
+class EventEnvelope(SlackModel):
+    """
+    Outer envelope for a Slack Events API callback. Contains workspace, application,
+    and authorization context, plus the inner event payload (``event_content``).
+
+    See https://docs.slack.dev/apis/events-api/#callback-field.
+
+    Path navigation supports both the Slack JSON prefix ``event.`` and the Python
+    property prefix ``event_content.`` interchangeably::
+
+        envelope = SlackChannelData.from_activity(turn_context.activity).envelope
+        workspace_id = envelope.get("team_id")
+        channel      = envelope.get("event.channel")
+        block_type   = envelope.get("event.blocks[0].type")
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    token: Optional[str] = None
+    team_id: Optional[str] = None
+    context_team_id: Optional[str] = None
+    context_enterprise_id: Optional[str] = None
+    api_app_id: Optional[str] = None
+
+    # Python name `event_content` ↔ JSON field `event`
+    event_content: Optional[EventContent] = Field(default=None, alias="event")
+
+    type: Optional[str] = None
+    event_id: Optional[str] = None
+    event_time: Optional[int] = None
+    authorizations: Optional[Any] = None
+    is_ext_shared_channel: Optional[bool] = None
+    event_context: Optional[str] = None
+
+    def _normalize_path(self, path: str) -> str:
+        """Map the C# property alias ``event_content`` to JSON field ``event``."""
+        if path.lower() == "event_content":
+            return "event"
+        if path.lower().startswith("event_content."):
+            return "event" + path[len("event_content") :]
+        return path

microsoft_agents_hosting_slack-1.1.0.dev7/microsoft_agents/hosting/slack/api/slack_api.py

@@ -0,0 +1,120 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from aiohttp import ClientSession, ClientTimeout
+from pydantic import BaseModel
+
+from .slack_response import SlackResponse, SlackResponseException
+
+SLACK_API_BASE = "https://slack.com/api"
+
+
+def _serialize_options(options: Any) -> str:
+    """Serialize the ``options`` argument to a JSON string suitable for Slack.
+
+    - ``None`` becomes ``"{}"``.
+    - A pre-built JSON string is returned as-is.
+    - A Pydantic model is dumped with ``exclude_none=True`` to match Slack's
+      tolerance of omitted fields and the C# implementation's null-stripping.
+    - Anything else is passed through :func:`json.dumps`, after recursively
+      removing ``None`` values from dicts/lists.
+    """
+    if options is None:
+        return "{}"
+    if isinstance(options, str):
+        return options
+    if isinstance(options, BaseModel):
+        return options.model_dump_json(by_alias=True, exclude_none=True)
+    return json.dumps(_strip_nones(options), ensure_ascii=False)
+
+
+def _strip_nones(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {k: _strip_nones(v) for k, v in value.items() if v is not None}
+    if isinstance(value, list):
+        return [_strip_nones(v) for v in value if v is not None]
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json", by_alias=True, exclude_none=True)
+    return value
+
+
+class SlackApi:
+    """
+    Async HTTP client for the Slack Web API.
+
+    Mirrors the C# ``SlackApi``: every call is a ``POST`` to
+    ``https://slack.com/api/{method}`` with a JSON body and an optional bearer
+    token. The response body is parsed into a :class:`SlackResponse`; a
+    :class:`SlackResponseException` is raised on a non-2xx HTTP status or when
+    Slack returns ``ok=false``.
+    """
+
+    def __init__(
+        self,
+        session: Optional[ClientSession] = None,
+        *,
+        base_url: str = SLACK_API_BASE,
+        request_timeout: float = 30.0,
+    ) -> None:
+        self._session = session
+        self._owns_session = session is None
+        self._base_url = base_url
+        self._timeout = ClientTimeout(total=request_timeout)
+
+    async def call(
+        self,
+        method: str,
+        options: Any = None,
+        token: str = "",
+    ) -> SlackResponse:
+        """Invoke a Slack Web API method.
+
+        :param method: The API method name (e.g. ``"chat.postMessage"``).
+        :param options: Request payload. May be ``None``, a JSON string, a
+            ``dict`` / ``list``, or a Pydantic model.
+        :param token: Bearer token. Sent as ``Authorization: Bearer {token}``
+            when non-empty.
+        :returns: The parsed :class:`SlackResponse`.
+        :raises ValueError: if ``method`` is empty or whitespace.
+        :raises SlackResponseException: on HTTP error or ``ok=false``.
+        """
+        if not method or not method.strip():
+            raise ValueError("method must be a non-empty string")
+
+        body = _serialize_options(options)
+        url = f"{self._base_url}/{method}"
+        headers = {"Content-Type": "application/json"}
+        if token and token.strip():
+            headers["Authorization"] = f"Bearer {token}"
+
+        session = self._session or ClientSession()
+        try:
+            async with session.post(
+                url, data=body, headers=headers, timeout=self._timeout
+            ) as response:
+                text = await response.text()
+                try:
+                    payload = json.loads(text) if text else {}
+                    data = SlackResponse.model_validate(payload)
+                except Exception as exc:
+                    raise SlackResponseException(
+                        f"Slack API error on {method} (HTTP {response.status}):\n{text}"
+                    ) from exc
+
+                if not response.ok or not data.ok:
+                    raise SlackResponseException(
+                        f"Slack API error on {method} (HTTP {response.status}):\n{text}",
+                        data,
+                    )
+
+                return data
+        finally:
+            if self._owns_session:
+                await session.close()

microsoft_agents_hosting_slack-1.1.0.dev7/microsoft_agents/hosting/slack/api/slack_channel_data.py

@@ -0,0 +1,67 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .action_payload import ActionPayload
+from .event_envelope import EventEnvelope
+
+
+class SlackChannelData(BaseModel):
+    """
+    Data associated with a Slack channel activity, as delivered by Azure Bot
+    Service in :attr:`Activity.channel_data`.
+
+    Bot Service historically named the envelope property ``SlackMessage`` and
+    the API token ``ApiToken``; this model accepts both the PascalCase JSON
+    names (via aliases) and snake_case Python names.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    envelope: Optional[EventEnvelope] = Field(default=None, alias="SlackMessage")
+    payload: Optional[ActionPayload] = Field(default=None, alias="Payload")
+    api_token: Optional[str] = Field(default=None, alias="ApiToken")
+
+    @property
+    def channel(self) -> Optional[str]:
+        """Slack channel id, sourced from the envelope or action payload."""
+        if self.envelope is not None:
+            return self.envelope.get("event.channel")
+        if self.payload is not None:
+            return self.payload.get("channel")
+        return None
+
+    @property
+    def thread_ts(self) -> Optional[str]:
+        """Thread timestamp, sourced from the envelope event or payload message."""
+        if self.envelope is not None:
+            return self.envelope.get("event.thread_ts") or self.envelope.get("event.ts")
+        if self.payload is not None:
+            return self.payload.get("message.thread_ts") or self.payload.get(
+                "message.ts"
+            )
+        return None
+
+    @classmethod
+    def from_activity(cls, activity: Any) -> "SlackChannelData":
+        """Build a :class:`SlackChannelData` from an Activity's ``channel_data``.
+
+        Accepts ``Activity.channel_data`` that is either a ``dict`` (typical for
+        deserialized incoming requests) or already a :class:`SlackChannelData`.
+        Returns an empty instance when ``channel_data`` is missing.
+        """
+        data = getattr(activity, "channel_data", None) if activity is not None else None
+        if data is None:
+            return cls()
+        if isinstance(data, cls):
+            return data
+        if isinstance(data, BaseModel):
+            data = data.model_dump(mode="json", by_alias=True)
+        return cls.model_validate(data)