# Lusha Docs Slack Agent

A Slack bot that listens for mentions from an authorized user, reads the thread, identifies which `user-guide/` docs need updating, and opens a GitHub PR with the proposed changes.

## Architecture


```
Slack mention
    │
    ▼
API Gateway (POST /slack/events)
    │
    ▼
Lambda A: receive.py          ← responds to Slack in <3s, ACKs immediately
    │  (async invoke)
    ▼
Lambda B: process.py          ← reads thread → asks Claude → edits docs → opens PR
    │
    ├── Slack API (read thread, post reply)
    ├── GitHub API (read files, create branch, commit, open PR)
    └── Anthropic API (Claude — identify gaps, generate updated content)
```

## Setup

### Step 1 — Create a Slack App

1. Go to https://api.slack.com/apps → **Create New App** → **From scratch**
2. Name: `Lusha Docs Agent`, pick your workspace
3. Under **OAuth & Permissions → Bot Token Scopes**, add:
  - `app_mentions:read`
  - `channels:history`
  - `groups:history`
  - `chat:write`
  - `users:read`
  - `users:read.email`
4. Under **Event Subscriptions**, toggle on, then (after deploying) paste the API Gateway URL
5. Subscribe to the **bot event**: `app_mention`
6. **Install App** to your workspace — copy the **Bot User OAuth Token** (`xoxb-...`)
7. Copy the **Signing Secret** from **Basic Information → App Credentials**


### Step 2 — Create GitHub credentials

Create a **fine-grained personal access token** (or classic token) with:

- `Contents: Read & Write` (to commit files)
- `Pull requests: Read & Write` (to open PRs)
- Scoped to the `danielturg22/lusha-api-hub` repository


### Step 3 — Get an Anthropic API key

https://console.anthropic.com → API Keys → Create key

### Step 4 — Deploy to AWS


```bash
cd slack-agent/
chmod +x deploy.sh
AWS_REGION=us-east-1 ./deploy.sh
```

After deployment, update the Lambda environment variables with real secrets:

**`lusha-slack-agent-receive`**

| Variable | Value |
|  --- | --- |
| `SLACK_SIGNING_SECRET` | From Slack app Basic Information |
| `PROCESSOR_LAMBDA_NAME` | `lusha-slack-agent-process` |


**`lusha-slack-agent-process`**

| Variable | Value |
|  --- | --- |
| `SLACK_BOT_TOKEN` | `xoxb-...` from Slack |
| `ANTHROPIC_API_KEY` | From Anthropic console |
| `GITHUB_TOKEN` | Your GitHub PAT |
| `AUTHORIZED_USER_EMAIL` | `hila.rabinovich@lusha.com` |
| `GITHUB_REPO` | `danielturg22/lusha-api-hub` |
| `GITHUB_BASE_BRANCH` | `main` |


Update them via AWS Console (Lambda → Configuration → Environment variables) or CLI:


```bash
aws lambda update-function-configuration \
  --function-name lusha-slack-agent-receive \
  --environment "Variables={SLACK_SIGNING_SECRET=<secret>,PROCESSOR_LAMBDA_NAME=lusha-slack-agent-process}"

aws lambda update-function-configuration \
  --function-name lusha-slack-agent-process \
  --environment "Variables={SLACK_BOT_TOKEN=xoxb-...,ANTHROPIC_API_KEY=sk-ant-...,GITHUB_TOKEN=ghp_...,AUTHORIZED_USER_EMAIL=hila.rabinovich@lusha.com,GITHUB_REPO=danielturg22/lusha-api-hub,GITHUB_BASE_BRANCH=main}"
```

### Step 5 — Wire up Slack Event Subscriptions

1. Copy the API Gateway endpoint printed by `deploy.sh`
2. Paste it into **Slack App → Event Subscriptions → Request URL**
3. Slack will hit the URL with a challenge — the Lambda handles it automatically
4. Subscribe to bot event `app_mention` → Save Changes
5. Reinstall the app to your workspace


### Step 6 — Invite the bot to a channel


```
/invite @Lusha Docs Agent
```

## Usage

Tag the bot in any thread:


```
@Lusha Docs Agent please update the docs based on this discussion
```

The bot will:

1. Ignore mentions from anyone other than `hila.rabinovich@lusha.com`
2. Read the full thread
3. Identify which `user-guide/` files need updating
4. Open a GitHub PR with the proposed changes
5. Reply in the thread with the PR link


## Local testing

To test the processor logic locally without deploying:


```bash
pip install -r requirements.txt

SLACK_BOT_TOKEN=xoxb-... \
ANTHROPIC_API_KEY=sk-ant-... \
GITHUB_TOKEN=ghp_... \
AUTHORIZED_USER_EMAIL=hila.rabinovich@lusha.com \
GITHUB_REPO=danielturg22/lusha-api-hub \
GITHUB_BASE_BRANCH=main \
python - <<'EOF'
from process import handler
handler({
    "slack_event": {
        "type": "app_mention",
        "user": "<your-slack-user-id>",
        "channel": "<channel-id>",
        "ts": "<message-ts>",
        "thread_ts": "<thread-ts>",
        "text": "<@bot> please update docs"
    }
}, None)
EOF
```