imbi-slackbot 2.8.0__tar.gz

imbi_slackbot-2.8.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

imbi_slackbot-2.8.0/.github/workflows/test.yml

@@ -0,0 +1,49 @@
+name: "Run Tests"
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: "Static Analysis"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Install just
+        uses: extractions/setup-just@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Run lint checks
+        run: just lint
+
+  test:
+    name: "Automated Tests"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Install just
+        uses: extractions/setup-just@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.14"
+      - name: Run tests
+        env:
+          UV_FROZEN: "1"
+        run: just test
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: "build/coverage.xml"
+          flags: unittests

imbi_slackbot-2.8.0/.gitignore

@@ -0,0 +1,8 @@
+.*
+!/.coderabbit.yaml
+!/.github
+!/.gitignore
+!/.pre-commit-config.yaml
+!/.python-version
+/build
+/dist

imbi_slackbot-2.8.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0  # unrelated to the pre-commit utility version
+    hooks:
+      - id: check-executables-have-shebangs
+      - id: check-json
+      - id: check-shebang-scripts-are-executable
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.14
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/tombi-toml/tombi-pre-commit
+    rev: v0.7.27
+    hooks:
+      - id: tombi-format

imbi_slackbot-2.8.0/.python-version

@@ -0,0 +1 @@
+3.14

imbi_slackbot-2.8.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, AWeber
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

imbi_slackbot-2.8.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: imbi-slackbot
+Version: 2.8.0
+Summary: Imbi Slack bot
+Author-email: "Gavin M. Roy" <gavinr@aweber.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: anthropic>=0.84.0
+Requires-Dist: fastapi>=0.135.1
+Requires-Dist: fastmcp>=3.0.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: imbi-common[databases,mcp,server]==2.8.0
+Requires-Dist: pydantic~=2.12
+Requires-Dist: sentry-sdk>=2.48.0
+Requires-Dist: slack-bolt>=1.21
+Description-Content-Type: text/markdown
+
+# imbi-slackbot
+
+A Slack bot for the [Imbi](https://github.com/AWeber-Imbi/imbi) DevOps service
+management platform. It behaves like the
+[Imbi assistant](https://github.com/AWeber-Imbi/imbi-assistant) — giving Claude
+live access to Imbi data and actions through tools — but speaks Slack and acts
+*as the Slack user who asked*, so every answer and action respects that user's
+Imbi permissions.
+
+## How It Works
+
+The bot connects to Slack over [Socket Mode](https://api.slack.com/apis/socket-mode)
+(an outbound websocket, so no public ingress is required). When a user mentions
+the bot or DMs it, the bot:
+
+1. **Resolves the Slack user to an Imbi user.** It looks up the Slack user's
+   email (`users.info`), finds the matching active Imbi `User` in the graph, and
+   mints a short-lived per-user JWT access token signed with the shared
+   `IMBI_AUTH_JWT_SECRET` — exactly the token the Imbi API issues at login. The
+   resolution is cached with a TTL. Users with no matching Imbi account get a
+   friendly explanation instead.
+2. **Reconstructs the thread context** from Slack (`conversations.replies`) so
+   follow-up questions in a thread keep their history. Nothing is persisted
+   server-side; the Slack thread *is* the conversation.
+3. **Runs Claude with the Imbi toolset.** Tools are built at startup from the
+   Imbi API's `openapi.json` via an in-process
+   [FastMCP](https://github.com/jlowin/fastmcp) server, using the shared
+   `imbi_common.mcp` exclusion policy (auth/MFA/status/thumbnail and any
+   `x-imbi-ai-tool: false` operations are filtered out). The user's minted token
+   is forwarded on every tool call, so the API enforces their permissions.
+4. **Replies in-thread** with Claude's answer.
+
+A tiny FastAPI app exposes `/status` (port 8004) for health checks; the Socket
+Mode connection runs as a background task alongside it.
+
+## Configuration
+
+| Environment variable | Purpose |
+|---|---|
+| `SLACK_BOT_TOKEN` | Slack bot token (`xoxb-…`) |
+| `SLACK_APP_TOKEN` | Slack app-level token for Socket Mode (`xapp-…`) |
+| `ANTHROPIC_API_KEY` | Anthropic API key (enables the bot when set) |
+| `IMBI_AUTH_JWT_SECRET` | Shared HS256 secret used to mint per-user tokens |
+| `IMBI_INTERNAL_API_URL` | In-cluster base URL of the Imbi API |
+| `IMBI_UI_URL` | Public base URL of the Imbi UI, used to build deep links |
+| `IMBI_INTERNAL_UI_URL` | In-cluster UI address for fetching `llms.txt` (e.g. the Caddy frontend); falls back to `IMBI_UI_URL` |
+| `POSTGRES_URL` | Imbi graph (Apache AGE) connection URL |
+| `IMBI_SLACKBOT_MODEL` | Claude model (default `claude-sonnet-4-6`) |
+
+See `src/imbi_slackbot/settings.py` for the full set.
+
+## Development
+
+```bash
+just setup    # install deps + pre-commit hooks
+just test     # run the test suite with coverage
+just lint     # ruff + mypy + basedpyright
+just serve    # run the bot against .env
+```

imbi_slackbot-2.8.0/README.md

@@ -0,0 +1,59 @@
+# imbi-slackbot
+
+A Slack bot for the [Imbi](https://github.com/AWeber-Imbi/imbi) DevOps service
+management platform. It behaves like the
+[Imbi assistant](https://github.com/AWeber-Imbi/imbi-assistant) — giving Claude
+live access to Imbi data and actions through tools — but speaks Slack and acts
+*as the Slack user who asked*, so every answer and action respects that user's
+Imbi permissions.
+
+## How It Works
+
+The bot connects to Slack over [Socket Mode](https://api.slack.com/apis/socket-mode)
+(an outbound websocket, so no public ingress is required). When a user mentions
+the bot or DMs it, the bot:
+
+1. **Resolves the Slack user to an Imbi user.** It looks up the Slack user's
+   email (`users.info`), finds the matching active Imbi `User` in the graph, and
+   mints a short-lived per-user JWT access token signed with the shared
+   `IMBI_AUTH_JWT_SECRET` — exactly the token the Imbi API issues at login. The
+   resolution is cached with a TTL. Users with no matching Imbi account get a
+   friendly explanation instead.
+2. **Reconstructs the thread context** from Slack (`conversations.replies`) so
+   follow-up questions in a thread keep their history. Nothing is persisted
+   server-side; the Slack thread *is* the conversation.
+3. **Runs Claude with the Imbi toolset.** Tools are built at startup from the
+   Imbi API's `openapi.json` via an in-process
+   [FastMCP](https://github.com/jlowin/fastmcp) server, using the shared
+   `imbi_common.mcp` exclusion policy (auth/MFA/status/thumbnail and any
+   `x-imbi-ai-tool: false` operations are filtered out). The user's minted token
+   is forwarded on every tool call, so the API enforces their permissions.
+4. **Replies in-thread** with Claude's answer.
+
+A tiny FastAPI app exposes `/status` (port 8004) for health checks; the Socket
+Mode connection runs as a background task alongside it.
+
+## Configuration
+
+| Environment variable | Purpose |
+|---|---|
+| `SLACK_BOT_TOKEN` | Slack bot token (`xoxb-…`) |
+| `SLACK_APP_TOKEN` | Slack app-level token for Socket Mode (`xapp-…`) |
+| `ANTHROPIC_API_KEY` | Anthropic API key (enables the bot when set) |
+| `IMBI_AUTH_JWT_SECRET` | Shared HS256 secret used to mint per-user tokens |
+| `IMBI_INTERNAL_API_URL` | In-cluster base URL of the Imbi API |
+| `IMBI_UI_URL` | Public base URL of the Imbi UI, used to build deep links |
+| `IMBI_INTERNAL_UI_URL` | In-cluster UI address for fetching `llms.txt` (e.g. the Caddy frontend); falls back to `IMBI_UI_URL` |
+| `POSTGRES_URL` | Imbi graph (Apache AGE) connection URL |
+| `IMBI_SLACKBOT_MODEL` | Claude model (default `claude-sonnet-4-6`) |
+
+See `src/imbi_slackbot/settings.py` for the full set.
+
+## Development
+
+```bash
+just setup    # install deps + pre-commit hooks
+just test     # run the test suite with coverage
+just lint     # ruff + mypy + basedpyright
+just serve    # run the bot against .env
+```

imbi_slackbot-2.8.0/docs/slack-app-manifest.md

@@ -0,0 +1,57 @@
+# Slack App Setup
+
+`imbi-slackbot` connects to Slack over **Socket Mode**, so it needs no public
+URL. Create a Slack app from the manifest below (Slack → *Your Apps* →
+*Create New App* → *From an app manifest*), install it to the workspace, then
+provide the two tokens to the service.
+
+## Tokens
+
+| Env var | Where to find it |
+|---|---|
+| `SLACK_BOT_TOKEN` | *OAuth & Permissions* → *Bot User OAuth Token* (`xoxb-…`) after install |
+| `SLACK_APP_TOKEN` | *Basic Information* → *App-Level Tokens* → create one with the `connections:write` scope (`xapp-…`) |
+
+The bot also needs `ANTHROPIC_API_KEY`, the shared `IMBI_AUTH_JWT_SECRET`, and
+`IMBI_INTERNAL_API_URL` / `POSTGRES_URL` (see the README).
+
+## Required scopes & why
+
+- `app_mentions:read` — receive `@imbi` mentions in channels.
+- `chat:write` — post replies.
+- `users:read` + `users:read.email` — **the identity bridge**: resolve the
+  Slack user to their email, which is matched against the Imbi `User` record.
+- `im:history`, `im:read` — read and respond in direct messages.
+- `channels:history`, `groups:history` — read thread context
+  (`conversations.replies`) when mentioned in public/private channels.
+
+## Manifest
+
+```yaml
+display_information:
+  name: Imbi
+  description: Query and manage Imbi from Slack
+features:
+  bot_user:
+    display_name: imbi
+    always_online: true
+oauth_config:
+  scopes:
+    bot:
+      - app_mentions:read
+      - chat:write
+      - users:read
+      - users:read.email
+      - im:history
+      - im:read
+      - channels:history
+      - groups:history
+settings:
+  event_subscriptions:
+    bot_events:
+      - app_mention
+      - message.im
+  socket_mode_enabled: true
+  org_deploy_enabled: false
+  token_rotation_enabled: false
+```

imbi_slackbot-2.8.0/justfile

@@ -0,0 +1,51 @@
+[doc("Bootstrap the environment and run the bot in the foreground")]
+[group("Testing")]
+serve *ARGS: setup
+    uv run --env-file=.env imbi-slackbot serve {{ ARGS }}
+
+[default]
+[private]
+ci: lint test
+
+[doc("Set up your development environment")]
+[group("Environment")]
+setup:
+    uv sync --all-groups --all-extras --frozen
+    uv run pre-commit install --install-hooks --overwrite
+
+[doc("Run tests")]
+[group("Testing")]
+test: setup
+    uv run pytest
+
+[doc("Run linters")]
+[group("Testing")]
+lint: setup
+    uv run pre-commit run --all-files
+    uv run basedpyright
+    uv run mypy
+
+[doc("Reformat code (optionally pass specific files)")]
+[group("Development")]
+format *FILES: setup
+    #!/usr/bin/env sh
+    set -ex
+    if [ "{{FILES}}" = '' ]; then
+        args='--all-files'
+    else
+        args='--files {{FILES}}'
+    fi
+    uv run pre-commit run ruff-format $args
+    uv run pre-commit run tombi-format $args
+
+[doc("Remove runtime artifacts")]
+[group("Environment")]
+clean:
+    rm -f .coverage
+    rm -fR build
+
+[confirm]
+[doc("Remove caches, virtual env, and output files")]
+[group("Environment")]
+real-clean: clean
+    rm -fR .venv .*_cache dist

imbi_slackbot-2.8.0/pyproject.toml

@@ -0,0 +1,189 @@
+[project]
+name = "imbi-slackbot"
+version = "2.8.0"
+description = "Imbi Slack bot"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "BSD-3-Clause"
+authors = [{ name = "Gavin M. Roy", email = "gavinr@aweber.com" }]
+dependencies = [
+  "anthropic>=0.84.0",
+  "fastapi>=0.135.1",
+  "fastmcp>=3.0.0",
+  "httpx>=0.28.1",
+  "imbi-common[databases,mcp,server]==2.8.0",
+  "pydantic~=2.12",
+  "sentry-sdk>=2.48.0",
+  "slack-bolt>=1.21",
+]
+
+[project.scripts]
+imbi-slackbot = "imbi_slackbot.app:cli"
+
+[dependency-groups]
+dev = [
+  "basedpyright>=1.37.1",
+  "coverage[toml]>=7.13.1",
+  "mypy~=1.19.1",
+  "pre-commit>=4.5.1",
+  "pytest>=9.0.2",
+  "pytest-cov>=7.0.0",
+  "python-dotenv>=1.1.0",
+  "ruff~=0.14.6",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+
+[tool.mypy]
+namespace_packages = true
+show_error_codes = true
+strict = true
+packages = ["imbi_slackbot", "tests"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+disallow_untyped_calls = false
+disallow_any_expr = false
+implicit_reexport = true
+warn_return_any = false
+disable_error_code = [
+  "attr-defined",
+  "call-arg",
+  "arg-type",
+  "type-arg",
+  "union-attr",
+  "index",
+  "var-annotated"
+]
+
+[tool.pyright]
+deprecateTypingAliases = true
+reportMissingSuperCall = "hint"
+typeCheckingMode = "strict"
+
+[[tool.pyright.executionEnvironments]]
+root = "src"
+reportUnusedFunction = "warning"
+
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportUnusedFunction = "none"
+reportUnusedVariable = "none"
+reportPrivateUsage = "none"
+reportAttributeAccessIssue = "none"
+reportMissingParameterType = "none"
+reportUnknownLambdaType = "none"
+reportUnknownParameterType = "none"
+reportUnknownVariableType = "none"
+reportMissingTypeArgument = "none"
+reportCallIssue = "none"
+reportOptionalMemberAccess = "none"
+reportOptionalSubscript = "none"
+reportUnknownMemberType = "none"
+reportArgumentType = "none"
+reportUnknownArgumentType = "none"
+extraPaths = ["src", "."]
+
+[tool.pytest.ini_options]
+addopts = [
+  "--cov=src/imbi_slackbot",
+  "--cov-report=xml:build/coverage.xml",
+  "--cov-report=term",
+]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 79
+target-version = "py314"
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+select = [
+  "A",
+  "ANN",
+  "ARG",
+  "ASYNC",
+  "B",
+  "BLE",
+  "C4",
+  "C90",
+  "DTZ",
+  "E",
+  "ERA",
+  "F",
+  "FLY",
+  "FURB",
+  "G",
+  "I",
+  "LOG",
+  "N",
+  "PIE",
+  "PL",
+  "PTH",
+  "Q",
+  "RET",
+  "RSE",
+  "RUF",
+  "S",
+  "SIM",
+  "T10",
+  "T20",
+  "TC",
+  "TRY",
+  "W",
+]
+ignore = [
+  "ANN401",
+  "ARG002",
+  "PLR0913",
+  "PLR2004",
+  "TRY003",
+  "TRY400",
+]
+flake8-quotes = { inline-quotes = "single" }
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = ["pydantic.BaseModel"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.ruff.lint.per-file-ignores]
+"src/imbi_slackbot/client.py" = ["PLW0603"]
+"src/imbi_slackbot/identity.py" = ["PLW0603"]
+"src/imbi_slackbot/links.py" = ["PLW0603"]
+"src/imbi_slackbot/mcp.py" = ["PLW0603"]
+"src/imbi_slackbot/settings.py" = ["PLW0603"]
+"src/imbi_slackbot/slack_handler.py" = ["PLW0603"]
+"src/imbi_slackbot/system_prompt.py" = ["PLW0603"]
+"tests/**/*.py" = [
+  "ANN",
+  "ARG005",
+  "B018",
+  "N802",
+  "PLC0415",
+  "RUF059",
+  "S",
+]
+
+[tool.uv]
+exclude-newer = "7 days"
+exclude-newer-package = { "imbi-common" = false }
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true

imbi_slackbot-2.8.0/src/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