python-slack-agents 0.5.0__py3-none-any.whl

slack_agents/access/allow_list.py

@@ -0,0 +1,19 @@
+"""Access provider that checks user against an allow list of user IDs."""
+
+from slack_agents import UserConversationContext
+from slack_agents.access.base import (
+    AccessDenied,
+    AccessGranted,
+    BaseAccessProvider,
+)
+
+
+class Provider(BaseAccessProvider):
+    def __init__(self, *, userid_list: list[str], deny_message: str) -> None:
+        self._userid_list = set(userid_list)
+        self._deny_message = deny_message
+
+    async def check_access(self, *, context: UserConversationContext) -> AccessGranted:
+        if context["user_id"] in self._userid_list:
+            return AccessGranted()
+        raise AccessDenied(self._deny_message)

slack_agents/access/base.py

@@ -0,0 +1,20 @@
+"""Abstract access-control provider interface."""
+
+from abc import ABC, abstractmethod
+from typing import TypedDict
+
+from slack_agents import UserConversationContext
+
+
+class AccessGranted(TypedDict):
+    pass
+
+
+class AccessDenied(Exception):
+    pass
+
+
+class BaseAccessProvider(ABC):
+    @abstractmethod
+    async def check_access(self, *, context: UserConversationContext) -> AccessGranted:
+        """Check access. Returns AccessGranted on success, raises AccessDenied on denial."""

slack_agents/agent_loop.py

@@ -0,0 +1,208 @@
+"""Core agent loop: LLM -> tools -> LLM -> ... until done."""
+
+import asyncio
+import json
+import logging
+from typing import AsyncIterator
+
+from slack_agents import UserConversationContext
+from slack_agents.llm import CHARS_PER_TOKEN
+from slack_agents.llm.base import BaseLLMProvider, LLMResponse, Message, StreamEvent
+from slack_agents.observability import observe
+from slack_agents.storage.base import BaseStorageProvider
+from slack_agents.tools.base import BaseToolProvider, ToolResult
+
+logger = logging.getLogger(__name__)
+
+MAX_ITERATIONS = 15
+
+
+def _estimate_input_tokens(
+    messages: list[Message],
+    system_prompt: str,
+    tools: list[dict] | None,
+) -> int:
+    """Estimate total input tokens from character count."""
+    chars = len(system_prompt)
+    chars += len(json.dumps(tools)) if tools else 0
+    for msg in messages:
+        if isinstance(msg.content, str):
+            chars += len(msg.content)
+        else:
+            chars += len(json.dumps(msg.content))
+    return chars // CHARS_PER_TOKEN
+
+
+@observe(name="agent_loop_streaming")
+async def run_agent_loop_streaming(
+    llm: BaseLLMProvider,
+    messages: list[Message],
+    system_prompt: str = "",
+    tool_providers: list[BaseToolProvider] | None = None,
+    user_conversation_context: UserConversationContext | None = None,
+    storage: BaseStorageProvider | None = None,
+) -> AsyncIterator[StreamEvent | dict]:
+    """Run the agent loop with streaming.
+
+    Yields StreamEvents for text and status dicts for tool calls.
+    """
+    providers = tool_providers or []
+    tools = [t for p in providers for t in p.tools] or None
+    provider_map = {t["name"]: p for p in providers for t in p.tools}
+    total_input_tokens = 0
+    total_output_tokens = 0
+    total_cache_creation_input_tokens = 0
+    total_cache_read_input_tokens = 0
+    peak_single_call_input_tokens = 0
+
+    for iteration in range(MAX_ITERATIONS):
+        logger.info("Agent loop streaming iteration %d", iteration + 1)
+
+        estimated = _estimate_input_tokens(messages, system_prompt, tools)
+        if estimated > llm.max_input_tokens:
+            logger.warning(
+                "Estimated input ~%d tokens exceeds limit of %d",
+                estimated,
+                llm.max_input_tokens,
+            )
+            yield StreamEvent(
+                type="text_delta",
+                text="\n\n_This conversation has grown too long. Please start a new thread._",
+            )
+            yield StreamEvent(
+                type="message_end",
+                stop_reason="max_input_tokens",
+                input_tokens=total_input_tokens,
+                output_tokens=total_output_tokens,
+                cache_creation_input_tokens=total_cache_creation_input_tokens,
+                cache_read_input_tokens=total_cache_read_input_tokens,
+                peak_single_call_input_tokens=peak_single_call_input_tokens,
+            )
+            return
+
+        collected_text = ""
+        collected_tool_calls = []
+        current_tool_inputs: dict[str, list[str]] = {}
+        stop_reason = ""
+
+        async for event in llm.stream(
+            messages=messages,
+            system_prompt=system_prompt,
+            tools=tools or None,
+        ):
+            if event.type == "text_delta":
+                collected_text += event.text
+                yield event
+
+            elif event.type == "tool_use_start":
+                if event.tool_call:
+                    current_tool_inputs[event.tool_call.id] = []
+
+            elif event.type == "tool_use_delta":
+                for tid in current_tool_inputs:
+                    current_tool_inputs[tid].append(event.tool_input_delta)
+
+            elif event.type == "tool_use_end":
+                if event.tool_call:
+                    collected_tool_calls.append(event.tool_call)
+
+            elif event.type == "message_end":
+                stop_reason = event.stop_reason
+                total_input_tokens += event.input_tokens
+                total_output_tokens += event.output_tokens
+                total_cache_creation_input_tokens += event.cache_creation_input_tokens
+                total_cache_read_input_tokens += event.cache_read_input_tokens
+                call_input = (
+                    event.input_tokens
+                    + event.cache_creation_input_tokens
+                    + event.cache_read_input_tokens
+                )
+                peak_single_call_input_tokens = max(peak_single_call_input_tokens, call_input)
+
+        if not collected_tool_calls:
+            yield StreamEvent(
+                type="message_end",
+                stop_reason=stop_reason,
+                input_tokens=total_input_tokens,
+                output_tokens=total_output_tokens,
+                cache_creation_input_tokens=total_cache_creation_input_tokens,
+                cache_read_input_tokens=total_cache_read_input_tokens,
+                peak_single_call_input_tokens=peak_single_call_input_tokens,
+            )
+            return
+
+        response = LLMResponse(
+            text=collected_text,
+            tool_calls=collected_tool_calls,
+            stop_reason=stop_reason,
+        )
+        assistant_content = _build_assistant_content(response)
+        messages.append(Message(role="assistant", content=assistant_content))
+
+        for tc in collected_tool_calls:
+            yield {
+                "type": "tool_status",
+                "tool_id": tc.id,
+                "tool_name": tc.name,
+                "status": "calling",
+                "tool_input": tc.input,
+            }
+
+        async def _call(tc) -> ToolResult:
+            provider = provider_map.get(tc.name)
+            if provider:
+                return await provider.call_tool(
+                    tc.name, tc.input, user_conversation_context, storage
+                )
+            return {"content": f"Unknown tool: {tc.name}", "is_error": True, "files": []}
+
+        results = await asyncio.gather(*[_call(tc) for tc in collected_tool_calls])
+
+        tool_results = []
+        for tc, result in zip(collected_tool_calls, results):
+            yield {
+                "type": "tool_status",
+                "tool_id": tc.id,
+                "tool_name": tc.name,
+                "status": "done",
+                "tool_input": tc.input,
+                "tool_result": result,
+            }
+            tool_results.append(
+                {
+                    "type": "tool_result",
+                    "tool_use_id": tc.id,
+                    "content": result["content"],
+                    **({"is_error": True} if result["is_error"] else {}),
+                }
+            )
+
+        messages.append(Message(role="user", content=tool_results))
+
+    yield StreamEvent(type="text_delta", text="\n\n_Reached maximum tool-calling steps._")
+    yield StreamEvent(
+        type="message_end",
+        stop_reason="max_iterations",
+        input_tokens=total_input_tokens,
+        output_tokens=total_output_tokens,
+        cache_creation_input_tokens=total_cache_creation_input_tokens,
+        cache_read_input_tokens=total_cache_read_input_tokens,
+        peak_single_call_input_tokens=peak_single_call_input_tokens,
+    )
+
+
+def _build_assistant_content(response: LLMResponse) -> list[dict]:
+    """Build Anthropic-style assistant content blocks from an LLMResponse."""
+    blocks: list[dict] = []
+    if response.text:
+        blocks.append({"type": "text", "text": response.text})
+    for tc in response.tool_calls:
+        blocks.append(
+            {
+                "type": "tool_use",
+                "id": tc.id,
+                "name": tc.name,
+                "input": tc.input,
+            }
+        )
+    return blocks

slack_agents/cli/__init__.py

@@ -0,0 +1,48 @@
+"""Unified CLI for slack-agents."""
+
+import argparse
+from datetime import datetime
+
+from slack_agents.cli import (
+    build_docker,
+    export_conversations,
+    export_usage,
+    healthcheck,
+    run,
+)
+
+
+def _parse_tz_aware(value: str) -> datetime:
+    """Parse an ISO datetime string, rejecting naive (tz-unaware) values."""
+    dt = datetime.fromisoformat(value)
+    if dt.tzinfo is None:
+        raise argparse.ArgumentTypeError(
+            f"datetime must include a timezone offset (e.g. +00:00), got: {value}"
+        )
+    return dt
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="slack-agents",
+        description="CLI for running and managing slack-agents.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run.register(subparsers)
+    healthcheck.register(subparsers)
+    export_conversations.register(subparsers, _parse_tz_aware)
+    export_usage.register(subparsers, _parse_tz_aware)
+    build_docker.register(subparsers)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.handler(args)
+
+
+if __name__ == "__main__":
+    main()

slack_agents/cli/build_docker.py

@@ -0,0 +1,94 @@
+"""CLI subcommand: build-docker."""
+
+
+def register(subparsers):
+    p = subparsers.add_parser("build-docker", help="Build a Docker image for an agent")
+    p.add_argument(
+        "agent_dir",
+        help="Path to agent directory containing config.yaml and system_prompt.txt",
+    )
+    p.add_argument(
+        "--push",
+        metavar="REGISTRY",
+        help="Push image to registry after building (e.g. registry.example.com)",
+    )
+    p.add_argument(
+        "--image-name",
+        metavar="NAME",
+        help="Custom image name (default: slack-agents-<agent-dir-name>)",
+    )
+    p.add_argument(
+        "--platform",
+        default="linux/amd64",
+        help="Target platform (default: linux/amd64)",
+    )
+    p.set_defaults(handler=execute)
+
+
+def _is_valid_docker_name(name: str) -> bool:
+    """Check if a string is a valid Docker image name component."""
+    import re
+
+    return bool(re.fullmatch(r"[a-z0-9]+(?:[._-][a-z0-9]+)*", name))
+
+
+def execute(args):
+    import subprocess
+    import sys
+    from pathlib import Path
+
+    from slack_agents.config import load_agent_config
+    from slack_agents.main import setup_environment
+
+    setup_environment()
+
+    agent_dir = Path(args.agent_dir)
+    if not agent_dir.is_dir():
+        print(f"Error: agent directory not found: {agent_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    config, _system_prompt, agent_name = load_agent_config(agent_dir)
+    version = config.version
+    dockerfile = Path(__file__).resolve().parent.parent / "Dockerfile"
+    image_name = args.image_name or f"slack-agents-{agent_name}"
+
+    if not _is_valid_docker_name(image_name):
+        print(
+            f"Error: '{image_name}' is not a valid Docker image name. "
+            "Names must be lowercase alphanumeric, optionally separated by "
+            "'.', '-', or '_'. Use --image-name to provide a valid name.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if args.push:
+        image_tag = f"{args.push}/{image_name}:{version}"
+    else:
+        image_tag = f"{image_name}:{version}"
+
+    print(f"Building {image_tag} ...")
+    result = subprocess.run(
+        [
+            "docker",
+            "build",
+            "--platform",
+            args.platform,
+            "--build-arg",
+            f"AGENT_PATH={agent_dir}",
+            "-f",
+            str(dockerfile),
+            "-t",
+            image_tag,
+            ".",
+        ]
+    )
+    if result.returncode != 0:
+        sys.exit(result.returncode)
+
+    if args.push:
+        print(f"Pushing {image_tag} ...")
+        result = subprocess.run(["docker", "push", image_tag])
+        if result.returncode != 0:
+            sys.exit(result.returncode)
+
+    print(f"Done: {image_tag}")

slack_agents/cli/export_conversations.py

@@ -0,0 +1,84 @@
+"""CLI subcommand: export-conversations."""
+
+
+def register(subparsers, parse_tz_aware):
+    p = subparsers.add_parser("export-conversations", help="Export conversations from an agent")
+    p.add_argument("agent_dir", help="Path to agent directory (e.g. agents/hello-world)")
+    p.add_argument(
+        "--format",
+        required=True,
+        choices=["html"],
+        help="Export format (currently: html)",
+    )
+    p.add_argument("--handle", help="Filter by Slack user handle")
+    p.add_argument(
+        "--date-from",
+        type=parse_tz_aware,
+        help="Filter start datetime (ISO format with tz, e.g. 2026-01-01T00:00:00+00:00)",
+    )
+    p.add_argument(
+        "--date-to",
+        type=parse_tz_aware,
+        help="Filter end datetime (ISO format with tz)",
+    )
+    p.add_argument("--output", required=True, help="Output directory")
+    p.set_defaults(handler=execute)
+
+
+def execute(args):
+    import asyncio
+    import sys
+    from pathlib import Path
+
+    from slack_agents.config import load_agent_config, load_plugin
+    from slack_agents.conversations import ConversationManager
+    from slack_agents.main import setup_environment
+
+    setup_environment()
+
+    agent_dir = Path(args.agent_dir).resolve()
+    if not agent_dir.exists():
+        print(f"Error: agent directory not found: {agent_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    config, _system_prompt, agent_name = load_agent_config(agent_dir)
+
+    storage_config = dict(config.storage)
+    type_path = storage_config.pop("type")
+
+    async def run() -> None:
+        storage = load_plugin(type_path, **storage_config)
+        await storage.initialize()
+        try:
+            conversations = ConversationManager(storage)
+
+            if not conversations.supports_export:
+                print(
+                    "Error: export-conversations requires persistent storage"
+                    " (file-based SQLite or PostgreSQL).\n"
+                    "The current storage backend does not support conversation export.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+
+            output_dir = args.output
+
+            if args.format == "html":
+                from slack_agents.cli.export_conversations_html import export_conversations_html
+
+                count = await export_conversations_html(
+                    conversations,
+                    agent_name,
+                    output_dir,
+                    handle=args.handle,
+                    date_from=args.date_from.isoformat() if args.date_from else None,
+                    date_to=args.date_to.isoformat() if args.date_to else None,
+                )
+                if count == 0:
+                    print("No conversations found matching the filters.")
+                else:
+                    print(f"Exported {count} conversation(s) to {output_dir}/")
+        finally:
+            await storage.close()
+
+    asyncio.run(run())