PyGuard
Setup guide

Run PyGuard end-to-end in under thirty minutes

Every step below is discrete, ordered, and shows what you should see when it succeeds. If a step fails, follow the italicised note at the bottom of that step.

What you will end up with

A running FastAPI backend, a Slack bot connected over Socket Mode, a local SQLite database already populated with the sample fraud dataset, and (optionally) the Node WhatsApp bridge. You will post one message in Slack and receive a PDF fraud intelligence report in the same thread.

Prerequisites

Before you start, make sure you have all of the following installed and available on your PATH. PyGuard will not start cleanly if any of them are missing.

  • Python 3.11 or newer. Confirm with python3 --version.
  • Node.js 18 or newer (only if you plan to run the optional WhatsApp bridge). Confirm with node --version.
  • Tectonic for LaTeX to PDF compilation. Install with brew install tectonic on macOS, or follow the instructions at tectonic-typesetting.github.io. Confirm with tectonic --version.
  • An OpenAI API key with access to the Responses API and the models referenced in backend/config/agent_config.py.
  • A Composio API key if you want the calendar, email, and Google Docs tools available to the general orchestrator.
  • A Slack workspace you control, so you can create an app, add scopes, and install it.

Tip
Keep all three credentials (OpenAI, Composio, Slack tokens) ready in a password manager before you start. The backend will not boot without the Slack tokens if SLACK_ENABLED=true.

Step 1 — Clone the repository

git clone https://github.com/your-org/pyguard.git
cd pyguard/PyGuard

Expected result. You now see backend/, bridge/, and website/ as sibling directories.

If this fails: double-check that the repository has been pushed to GitHub and that you have read access. See troubleshooting for SSH vs HTTPS tips.

Step 2 — Create the backend virtual environment

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Expected result. Packages including openai-agents, fastapi, slack-sdk, aiohttp, matplotlib, and mermaid-cli install without errors. You see Successfully installed ... near the end.

If this fails: the most common failure is a missing system compiler for matplotlib. On macOS run xcode-select --install. On Linux install build-essential. See troubleshooting.

Step 3 — Configure backend/.env

Copy the example file and fill in the values you collected in Prerequisites.

cp .env.example .env

Open .env and populate every value:

# OpenAI
OPENAI_API_KEY=sk-...
OPENAI_AGENTS_DISABLE_TRACING=1

# Composio (optional but recommended)
COMPOSIO_API_KEY=...

# Slack -- Socket Mode
SLACK_ENABLED=true
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_REPLY_IN_THREAD=true
SLACK_REACT_EMOJI=eyes
SLACK_GROUP_POLICY=mention
SLACK_DM_ENABLED=true
SLACK_DM_POLICY=open

Expected result. No secrets left with ... placeholders. The file is saved and not committed.

If this fails: if you accidentally commit .env, rotate every token immediately. .env is listed in .gitignore but double-check with git status.

Step 4 — Create the Slack app

  1. Go to api.slack.com/apps and click Create New App, choose From scratch.
  2. Name the app (for example PyGuard Local) and pick your workspace.
  3. Under Socket Mode, toggle it on. Generate an App-Level Token with the connections:write scope — this is your SLACK_APP_TOKEN.
  4. Under OAuth & Permissions, add these bot scopes:
    • app_mentions:read
    • channels:history
    • chat:write
    • files:write
    • im:history
    • im:read
    • im:write
    • reactions:write
  5. Install the app to your workspace. Copy the Bot User OAuth Token — this is your SLACK_BOT_TOKEN.
  6. Under Event Subscriptions, enable events and subscribe the bot to app_mention and message.im.

Expected result. The Slack app dashboard shows Socket Mode active, bot scopes installed, and event subscriptions saved. Your .env now contains real values for SLACK_APP_TOKEN and SLACK_BOT_TOKEN.

If this fails: the classic mistake is forgetting to reinstall the app after adding scopes. Every time you change scopes, click Reinstall App in the OAuth page.

Step 5 — Run the backend

From backend/ with your virtualenv still active:

uvicorn main:app --reload --port 8000

Expected result. The following log lines appear in order:

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO [pyguard] Slack service started
INFO [pyguard.slack] Slack bot connected as U...
INFO [pyguard.slack] Starting Slack Socket Mode client...
INFO [slack_sdk.socket_mode.websockets] A new session (s_...) has been established

If this fails:

  • ModuleNotFoundError: No module named 'aiohttp' → your virtualenv is missing aiohttp. Run pip install aiohttp.
  • tectonic: command not found → tectonic is not on PATH. Re-run brew install tectonic and check which tectonic.
  • Slack auth_test failed → double-check SLACK_BOT_TOKEN in .env. Regenerate if necessary.

Step 6 — Send your first message

Invite the bot to a channel (or open a DM with it). Send:

Generate a fraud intelligence report.

Expected result. Within about thirty seconds you see:

  1. A short Slack-friendly summary posted in the channel.
  2. A PDF file (fraud_report_<timestamp>.pdf) uploaded into the thread under the summary.
  3. A new row in the fraud_reports table (pyguard.db) keyed by the thread's thread_ts.

If this fails: look at the live logs from Step 5. If you see Phase 1: Memory Agent but no Phase 2-F: Fraud Orchestrator, the intent classifier misread the message — rephrase with the word "report". See troubleshooting.

Step 7 — Ask a follow-up (Q&A)

Reply inside the same thread where the PDF was uploaded. Click the "Reply in thread" speech-bubble on the PDF message.

Why are money transfer and gift cards showing a 100% flagged rate?

Expected result. The log shows === PHASE 0: REPORT FOLLOWUP (report_id=...) ===. PyGuard posts a narrative answer in the thread. No new PDF is uploaded.

If this fails: the most common cause is replying in the channel root instead of inside the thread — the incoming thread_ts must match the report's thread_ts. See troubleshooting.

Step 8 — Request a LaTeX edit

Still inside the same thread:

Tighten the executive summary to focus on the top three findings for a CEO briefing.

Expected result. PyGuard acknowledges the edit, rewrites report.tex inside the bundle, recompiles with tectonic, bumps the version to v2, and uploads the new PDF into the thread with the message "Here is your updated Fraud Intelligence Report (v2):".

If this fails: if tectonic fails to compile, PyGuard automatically rolls back to the previous version and posts a short error with the tectonic stderr tail. You can safely retry with a smaller edit.

Step 9 — WhatsApp bridge (optional)

Skip this section if you only care about Slack.

cd ../bridge
npm install
npm run build
node dist/index.js

Expected result. A QR code prints in the terminal. Scan it with WhatsApp on your phone (Settings → Linked Devices). The bridge then listens on 127.0.0.1:3001 for WebSocket commands from the backend.

If this fails: make sure port 3001 is free. On macOS run lsof -i :3001 and kill any stale process.

Step 10 — Run the tests

cd ../backend
.venv/bin/python -m unittest discover -s tests -v

Expected result. Ran 26 tests in <1s followed by OK. The 26 tests cover the tex editor primitives and the verification-agent fast-path logic.

If this fails: run a single test file first with -m unittest tests.test_tex_editor -v to narrow down the failure. Report any regression through the contribution flow.

Step 11 — Deploy this website to Vercel

This step is only about the marketing and docs site. It is independent of the backend.

  1. Push the repository to GitHub if you have not already.
  2. On vercel.com, click Add New Project and select your repository.
  3. Set the Root Directory to PyGuard/website. This is the most common deployment mistake — the build will fail with "No Next.js config found" if you skip it.
  4. Leave Framework as auto-detect (Next.js). No custom build command needed.
  5. No environment variables are required for the site itself.
  6. Click Deploy.

Alternatively, from the command line:

cd PyGuard/website
npx vercel --prod

Expected result. Vercel produces a deployment URL within two to three minutes. Every page (home, setup, workflows, architecture, docs, contribute) loads with no 404.

If this fails: re-read step 3 above. If the build log says Couldn't find any pages or next.config not found, the Root Directory is wrong.

Next steps

  • Walk through the workflows page to see the three primary flows visualised.
  • Skim architecture for the full system topology and the rationale behind the beta-state changes.
  • When you are ready to contribute, open the Contribute page. It links directly to the GitHub issue templates.