imbi-slackbot 2.8.0__py3-none-any.whl

imbi_slackbot/__init__.py

@@ -0,0 +1,18 @@
+import re as _re
+from importlib import metadata as _metadata
+
+try:
+    version = _metadata.version('imbi-slackbot')
+except _metadata.PackageNotFoundError:
+    version = '0.0.0'
+
+version_info: list[int | str] = []
+for _part in version.split('.'):
+    _match = _re.fullmatch(r'(\d+)(.*)', _part)
+    if _match is None:
+        version_info.append(_part)
+    else:
+        version_info.append(int(_match.group(1)))
+        if _match.group(2):
+            version_info.append(_match.group(2))
+del _metadata, _re

imbi_slackbot/agent.py

@@ -0,0 +1,148 @@
+"""Non-streaming Claude tool loop for the Slack bot.
+
+Given a reconstructed conversation, run Claude with the Imbi toolset,
+executing any tool calls in a loop (up to ``max_rounds``) until Claude
+stops requesting tools, and return the final assistant text.
+
+"""
+
+from __future__ import annotations
+
+import logging
+import typing
+
+import anthropic
+
+from imbi_slackbot import client, mcp
+
+LOGGER = logging.getLogger(__name__)
+
+
+def _collect(
+    content: list[typing.Any],
+) -> tuple[str, list[dict[str, typing.Any]], list[dict[str, typing.Any]]]:
+    """Split a response's content into text, assistant blocks, tool uses.
+
+    Returns:
+        ``(text, assistant_blocks, tool_uses)`` where ``assistant_blocks``
+        is the content to echo back as the assistant turn and ``tool_uses``
+        are the ``tool_use`` blocks to execute.
+
+    """
+    text_parts: list[str] = []
+    assistant_blocks: list[dict[str, typing.Any]] = []
+    tool_uses: list[dict[str, typing.Any]] = []
+    for block in content:
+        if block.type == 'text':
+            text_parts.append(block.text)
+            assistant_blocks.append({'type': 'text', 'text': block.text})
+        elif block.type == 'tool_use':
+            tool_block = {
+                'type': 'tool_use',
+                'id': block.id,
+                'name': block.name,
+                'input': block.input,
+            }
+            assistant_blocks.append(tool_block)
+            tool_uses.append(tool_block)
+    return '\n'.join(text_parts), assistant_blocks, tool_uses
+
+
+def _tool_result_block(
+    tool_use_id: str,
+    content: str,
+    *,
+    is_error: bool,
+) -> dict[str, typing.Any]:
+    """Build an Anthropic ``tool_result`` block, flagged on failure."""
+    block: dict[str, typing.Any] = {
+        'type': 'tool_result',
+        'tool_use_id': tool_use_id,
+        'content': content,
+    }
+    if is_error:
+        block['is_error'] = True
+    return block
+
+
+async def run_turn(
+    *,
+    messages: list[dict[str, typing.Any]],
+    system: str,
+    tools: list[dict[str, typing.Any]] | None,
+    auth_token: str,
+    model: str,
+    max_tokens: int,
+    max_rounds: int,
+) -> str:
+    """Run one user turn through Claude and the tool loop.
+
+    Args:
+        messages: Conversation history in Anthropic message format. The
+            final message must be the user's latest input.
+        system: The system prompt.
+        tools: Anthropic tool definitions, or ``None`` for no tools.
+        auth_token: Per-user bearer token forwarded on every tool call.
+        model: Claude model id.
+        max_tokens: Max output tokens per response.
+        max_rounds: Max tool-use rounds before giving up.
+
+    Returns:
+        The assistant's final text (concatenated across rounds).
+
+    """
+    api_client = client.get_client()
+    manager = mcp.get_manager()
+    accumulated: list[str] = []
+    # Work on a copy so appending assistant/tool-result turns does not
+    # mutate the caller-supplied list.
+    messages = list(messages)
+
+    for _round in range(max_rounds):
+        kwargs: dict[str, typing.Any] = {
+            'model': model,
+            'max_tokens': max_tokens,
+            'system': system,
+            'messages': messages,
+        }
+        if tools:
+            kwargs['tools'] = tools
+
+        try:
+            response = typing.cast(
+                'anthropic.types.Message',
+                await api_client.messages.create(**kwargs),
+            )
+        except anthropic.APIError:
+            LOGGER.exception('Anthropic API error')
+            return (
+                'Sorry — I hit an error talking to the model. '
+                'Please try again.'
+            )
+
+        text, assistant_blocks, tool_uses = _collect(response.content)
+        if text:
+            accumulated.append(text)
+
+        if response.stop_reason != 'tool_use' or not tool_uses:
+            break
+
+        messages.append({'role': 'assistant', 'content': assistant_blocks})
+
+        tool_results: list[dict[str, typing.Any]] = []
+        for tool_use in tool_uses:
+            result_text, is_error = await manager.execute_tool(
+                tool_use['name'],
+                tool_use['input'],
+                auth_token,
+            )
+            tool_results.append(
+                _tool_result_block(
+                    tool_use['id'], result_text, is_error=is_error
+                )
+            )
+        messages.append({'role': 'user', 'content': tool_results})
+    else:
+        accumulated.append('_(Reached the tool-call limit before finishing.)_')
+
+    return '\n\n'.join(part for part in accumulated if part).strip()

imbi_slackbot/app.py

@@ -0,0 +1,91 @@
+import contextlib
+import datetime
+from typing import TYPE_CHECKING
+
+import fastapi
+import typer
+from imbi_common import graph, lifespan, sentry, server
+
+import imbi_slackbot
+from imbi_slackbot import (
+    app_status,
+    client,
+    identity,
+    links,
+    mcp,
+    slack_handler,
+)
+
+if TYPE_CHECKING:
+    from collections import abc
+
+
+@contextlib.asynccontextmanager
+async def _anthropic_lifespan() -> abc.AsyncGenerator[None, None]:
+    await client.initialize()
+    try:
+        yield
+    finally:
+        await client.aclose()
+
+
+@contextlib.asynccontextmanager
+async def _mcp_lifespan() -> abc.AsyncGenerator[None, None]:
+    await mcp.initialize()
+    try:
+        yield
+    finally:
+        await mcp.aclose()
+
+
+@contextlib.asynccontextmanager
+async def _links_lifespan() -> abc.AsyncGenerator[None, None]:
+    await links.initialize()
+    yield
+
+
+@contextlib.asynccontextmanager
+async def _slack_lifespan() -> abc.AsyncGenerator[None, None]:
+    # Runs last so the graph, Anthropic client, and MCP tools are ready
+    # before the bot starts accepting Slack events.
+    await slack_handler.initialize()
+    try:
+        yield
+    finally:
+        await slack_handler.aclose()
+
+
+def create_app() -> fastapi.FastAPI:
+    # Capture the shared graph connection for identity resolution once
+    # ``graph_lifespan`` opens it.
+    graph.set_on_startup(identity.on_graph_ready)
+
+    app = fastapi.FastAPI(
+        title='Imbi Slack Bot',
+        version=imbi_slackbot.version,
+        started_at=datetime.datetime.now(datetime.UTC),
+        lifespan=lifespan.Lifespan(
+            sentry.sentry_lifespan,
+            graph.graph_lifespan,
+            _anthropic_lifespan,
+            _mcp_lifespan,
+            _links_lifespan,
+            _slack_lifespan,
+        ),
+    )
+    app.include_router(app_status.router)
+    return app
+
+
+cli = typer.Typer(no_args_is_help=True)
+cli.command('serve')(
+    server.bind_entrypoint(
+        'imbi_slackbot.app:create_app',
+        default_port=8004,
+    )
+)
+
+
+@cli.callback()
+def _callback() -> None:  # pyright: ignore[reportUnusedFunction]
+    """Imbi Slack Bot CLI"""

imbi_slackbot/app_status.py

@@ -0,0 +1,41 @@
+import datetime
+import os
+import typing as t
+
+import fastapi
+import pydantic
+
+router = fastapi.APIRouter()
+
+
+class Status(pydantic.BaseModel):
+    environment: t.Annotated[
+        str,
+        pydantic.Field(
+            description='Operating environment',
+            examples=['production'],
+        ),
+    ]
+    service: t.Annotated[
+        str, pydantic.Field(description='Service instance name')
+    ] = 'imbi-slackbot'
+    status: t.Literal['ok', 'failing']
+    version: t.Annotated[
+        str,
+        pydantic.Field(description='Application version', examples=['0.0.0']),
+    ]
+    started_at: datetime.datetime
+
+
+@router.get(
+    '/status',
+    summary='Operational status',
+    operation_id='getStatus',
+)
+def status_endpoint(*, request: fastapi.Request) -> Status:
+    return Status(
+        environment=os.environ.get('ENVIRONMENT', 'development'),
+        status='ok',
+        version=request.app.version,
+        started_at=request.app.extra['started_at'],
+    )

imbi_slackbot/client.py

@@ -0,0 +1,73 @@
+"""AsyncAnthropic client singleton for the Slack bot."""
+
+import logging
+
+import anthropic
+
+from imbi_slackbot import settings
+
+LOGGER = logging.getLogger(__name__)
+
+_client: anthropic.AsyncAnthropic | None = None
+
+
+async def initialize() -> None:
+    """Initialize the AsyncAnthropic client.
+
+    Non-fatal if the bot is disabled or no API key is configured.
+
+    """
+    global _client
+
+    await aclose()
+
+    slackbot_settings = settings.get_slackbot_settings()
+
+    if not slackbot_settings.enabled:
+        LOGGER.info('Slack bot is disabled')
+        return
+
+    if not slackbot_settings.api_key:
+        LOGGER.warning(
+            'Slack bot enabled but no API key configured '
+            '(set ANTHROPIC_API_KEY)'
+        )
+        return
+
+    _client = anthropic.AsyncAnthropic(
+        api_key=slackbot_settings.api_key,
+    )
+    LOGGER.info('Slack bot Anthropic client initialized')
+
+
+async def aclose() -> None:
+    """Close the AsyncAnthropic client."""
+    global _client
+    if _client is not None:
+        await _client.close()
+        _client = None
+        LOGGER.debug('Slack bot Anthropic client closed')
+
+
+def get_client() -> anthropic.AsyncAnthropic:
+    """Get the AsyncAnthropic client singleton.
+
+    Returns:
+        The initialized AsyncAnthropic client.
+
+    Raises:
+        RuntimeError: If the client has not been initialized.
+
+    """
+    if _client is None:
+        raise RuntimeError(
+            'Slack bot Anthropic client not initialized. '
+            'Check that ANTHROPIC_API_KEY, SLACK_BOT_TOKEN, and '
+            'SLACK_APP_TOKEN are set.'
+        )
+    return _client
+
+
+def is_available() -> bool:
+    """Check if the Anthropic client is available."""
+    return _client is not None

imbi_slackbot/identity.py

@@ -0,0 +1,155 @@
+"""Map Slack users to Imbi users and mint per-user API tokens.
+
+A Slack user is resolved to an Imbi user by email: the Slack profile
+email (``users.info``) is matched against an active ``User`` node in the
+graph. A short-lived per-user JWT access token is then minted with the
+shared ``IMBI_AUTH_JWT_SECRET`` — identical to the token the Imbi API
+issues at login — so every tool call the bot makes on the user's behalf
+is authorized as, and limited to, that user.
+
+Resolutions (including "no matching Imbi user") are cached with a TTL to
+avoid hitting Slack and the graph on every message.
+
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime
+import logging
+import typing
+
+from imbi_common import graph
+from imbi_common.auth import core
+
+from imbi_slackbot import settings
+
+# slack_sdk's AsyncWebClient is only loosely typed (its responses are
+# AsyncSlackResponse with Unknown generics), so treat it as Any rather
+# than propagate Unknown through every call site.
+SlackClient = typing.Any
+
+LOGGER = logging.getLogger(__name__)
+
+_USER_QUERY = """
+MATCH (u:User {{email: {email}}})
+RETURN u
+"""
+
+
+@dataclasses.dataclass(frozen=True)
+class ImbiUser:
+    """An Imbi user resolved from a Slack identity."""
+
+    email: str
+    display_name: str
+    is_admin: bool = False
+
+
+@dataclasses.dataclass
+class _CacheEntry:
+    """A cached resolution; ``user`` is ``None`` for a known non-user."""
+
+    user: ImbiUser | None
+    expires_at: datetime.datetime
+
+
+# Shared graph instance captured at startup via ``graph.set_on_startup``.
+_graph: graph.Graph | None = None
+_cache: dict[str, _CacheEntry] = {}
+
+
+def set_graph(db: graph.Graph) -> None:
+    """Capture the shared graph connection opened by ``graph_lifespan``."""
+    global _graph
+    _graph = db
+
+
+async def on_graph_ready(db: graph.Graph) -> None:
+    """``graph.set_on_startup`` callback that captures the connection."""
+    set_graph(db)
+
+
+def clear_cache() -> None:
+    """Drop all cached resolutions (used by tests and on shutdown)."""
+    _cache.clear()
+
+
+async def _slack_email(
+    slack_client: SlackClient,
+    slack_user_id: str,
+) -> str | None:
+    """Return the Slack user's profile email, if any."""
+    response: typing.Any = await slack_client.users_info(user=slack_user_id)
+    user: typing.Any = response['user'] or {}
+    profile: typing.Any = user.get('profile') or {}
+    email: typing.Any = profile.get('email')
+    return str(email) if email else None
+
+
+async def _load_imbi_user(email: str) -> ImbiUser | None:
+    """Look up an active Imbi ``User`` node by email."""
+    if _graph is None:
+        raise RuntimeError('Graph connection not initialized')
+    records = await _graph.execute(_USER_QUERY, {'email': email}, ['u'])
+    if not records:
+        return None
+    raw = graph.parse_agtype(records[0]['u'])
+    if not isinstance(raw, dict):
+        return None
+    data = typing.cast('dict[str, typing.Any]', raw)
+    if not data.get('is_active', True):
+        return None
+    return ImbiUser(
+        email=email,
+        display_name=str(data.get('display_name') or email),
+        is_admin=bool(data.get('is_admin', False)),
+    )
+
+
+async def resolve(
+    slack_client: SlackClient,
+    slack_user_id: str,
+    *,
+    now: datetime.datetime | None = None,
+) -> ImbiUser | None:
+    """Resolve a Slack user id to an Imbi user, using the TTL cache.
+
+    Args:
+        slack_client: The Slack web client (for ``users.info``).
+        slack_user_id: The Slack user id (e.g. ``U012ABCDEF``).
+        now: Override the current time (for testing).
+
+    Returns:
+        The matching :class:`ImbiUser`, or ``None`` if the Slack user has
+        no email or no active Imbi account.
+
+    """
+    now = now or datetime.datetime.now(datetime.UTC)
+    entry = _cache.get(slack_user_id)
+    if entry is not None and entry.expires_at > now:
+        return entry.user
+
+    email = await _slack_email(slack_client, slack_user_id)
+    user = await _load_imbi_user(email) if email else None
+
+    ttl = settings.get_slackbot_settings().identity_cache_ttl
+    _cache[slack_user_id] = _CacheEntry(
+        user=user,
+        expires_at=now + datetime.timedelta(seconds=ttl),
+    )
+    if user is None:
+        LOGGER.info('No Imbi user for Slack user %s', slack_user_id)
+    return user
+
+
+def mint_token(user: ImbiUser) -> str:
+    """Mint a per-user Imbi API access token.
+
+    The token is signed with the shared ``IMBI_AUTH_JWT_SECRET`` and
+    carries the user's email as its subject, exactly as the Imbi API
+    does at login. The API loads the user's permissions fresh from the
+    graph on each request keyed by this subject.
+
+    """
+    return core.create_access_token(user.email)

imbi_slackbot/links.py

@@ -0,0 +1,89 @@
+"""Fetch and cache the Imbi UI URL patterns (``llms.txt``).
+
+The Imbi UI publishes an ``llms.txt`` at its root documenting the route
+patterns for building deep links. This module fetches it once at startup
+from the in-cluster ``IMBI_INTERNAL_UI_URL`` (falling back to the public
+``IMBI_UI_URL``) and caches it; if the UI is unreachable or neither is set
+a built-in fallback is used so the system prompt always has URL guidance.
+
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from imbi_slackbot import settings
+
+LOGGER = logging.getLogger(__name__)
+
+# httpx.InvalidURL is a separate hierarchy from httpx.HTTPError, so a
+# malformed IMBI_UI_URL must be caught explicitly to keep startup fail-soft.
+_FETCH_ERRORS = (httpx.HTTPError, httpx.InvalidURL)
+
+# Used when the UI's llms.txt cannot be fetched. Keep this roughly in sync
+# with imbi-ui's public/llms.txt, which is the canonical source.
+FALLBACK_URL_PATTERNS = """\
+- `/dashboard`: the user's dashboard.
+- `/projects`: the project inventory list.
+- `/projects/{project_id}`: a project's detail page.
+- `/projects/{project_id}/{tab}`: a project tab (overview, dependencies,
+  relationships, documents, configuration, logs, operations-log).
+- `/operations-log`: the operations log.
+- `/reports` and `/reports/{report_id}`: reports.
+- `/settings` and `/settings/{tab}`: the current user's settings.
+- `/users/{email}`: a user's profile page.
+- `/admin/{section}`: an admin list view (sections: project-types,
+  environments, teams, organizations, blueprints, roles, users,
+  service-accounts).
+- `/admin/{section}/new`: the create form.
+- `/admin/{section}/{slug}`: an admin item's detail view.
+- `/admin/{section}/{slug}/edit`: an admin item's edit form."""
+
+_url_patterns: str | None = None
+
+
+async def initialize() -> None:
+    """Fetch the UI's ``llms.txt`` and cache its contents."""
+    global _url_patterns
+    slackbot_settings = settings.get_slackbot_settings()
+    base_url = slackbot_settings.llms_base_url
+    if not base_url:
+        LOGGER.info(
+            'No IMBI_INTERNAL_UI_URL or IMBI_UI_URL configured; '
+            'using built-in URL patterns'
+        )
+        _url_patterns = FALLBACK_URL_PATTERNS
+        return
+
+    llms_url = f'{base_url.rstrip("/")}/llms.txt'
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            response = await client.get(llms_url)
+            response.raise_for_status()
+        text = response.text.strip()
+    except _FETCH_ERRORS:
+        LOGGER.warning(
+            'Failed to load %s; using built-in URL patterns', llms_url
+        )
+        _url_patterns = FALLBACK_URL_PATTERNS
+        return
+
+    # An empty body or an HTML page (e.g. an SPA 404 fallback) is not
+    # usable URL guidance.
+    if not text or text.startswith('<'):
+        LOGGER.warning(
+            '%s did not return markdown; using built-in URL patterns',
+            llms_url,
+        )
+        _url_patterns = FALLBACK_URL_PATTERNS
+        return
+
+    _url_patterns = text
+    LOGGER.info('Loaded UI URL patterns from %s', llms_url)
+
+
+def get_url_patterns() -> str:
+    """Return the cached UI URL patterns (or the built-in fallback)."""
+    return _url_patterns or FALLBACK_URL_PATTERNS