setup

name

setup

description

Set up and deploy the fraud-bot agent end to end: clone the repo (or reuse an existing clone), configure the schema mapping for the adopter's warehouse, register secrets, create an Oz environment, and launch a first run or daily schedule. Use whenever someone asks to "set up fraud-bot", "run the setup skill", "deploy the fraud detection agent", "install this agent", or is getting started with this repo for the first time. Part of the fraud-bot skill suite.

Fraud Bot Setup

Take a fresh adopter from zero to a working fraud-bot deployment. Work through the steps in order, but check the current state first — every step is skippable if it's already done. Ask the user for values you can't discover yourself (project names, API keys, channel IDs); never invent them.

Security note: you will handle API keys in this flow. Never echo, log, or write secret values to disk. Let oz secret create prompt for values interactively, or have the user export environment variables themselves.

Step 0: Get the repo

Check whether you're already inside a clone (look for config/schema.json, instructions.md, and queries/ in the current directory or a nearby parent).

If not cloned yet:

git clone https://github.com/warpdotdev/fraud-detection-agent-oss.git
cd fraud-detection-agent-oss

Run all subsequent steps from the repo root.

Step 1: Check prerequisites

• Oz CLI: oz --version. If missing, direct the user to the Oz CLI docs to install it.
• Authentication: run a harmless authenticated command like oz environment list. If it fails with an auth error, ask the user to run oz login (or set WARP_API_KEY in CI) and re-check.
• Python 3: python3 --version. The helper scripts are standard-library only — no pip install needed at runtime.

This repo ships no credentials and no data sources. The user brings their own Metabase instance, a BigQuery warehouse satisfying the contract in SCHEMA.md, and Slack (optionally Front / Verisoul) tokens. Confirm early which of these they have — Metabase + the warehouse are required for detection; Slack is required for reporting; Front / Verisoul are only needed for the ban-appeal enrichment skills.

Step 2: Point the schema config at their warehouse

The queries use logical table names resolved from a config file (see SCHEMA.md for the full contract).

1. Copy the template to the git-ignored local override:

   cp config/schema.json config/schema.local.json
   

2. Ask the user for, and fill in:
   • project — their GCP project ID
   • metabase_databases.warehouse and .ugc — their Metabase database IDs
   • each entry in tables — the physical dataset / name for every logical table they plan to use (they can leave defaults for tables they don't have yet, but warn them which skills/queries depend on which tables per SCHEMA.md)
3. If their columns don't match the contract in SCHEMA.md, recommend creating views that alias columns to the expected names rather than editing the SQL.
4. Verify the config resolves:

   python3 scripts/schema.py show
   python3 scripts/schema.py render queries/known_patterns.sql
   

   The rendered SQL should show their real dataset/table names and Metabase database ids. Note the GCP project only appears for {{ fq.* }} placeholders, which the stock queries don't use — don't let its absence suggest the config isn't applied.

Step 3: Register secrets

Create team-scoped Oz secrets (injected as environment variables into cloud agent runs). Each command prompts interactively for the value — do not pass values on the command line:

# Required
oz secret create --team METABASE_API_KEY
oz secret create --team SLACK_BOT_TOKEN      # needs chat:write and files:write scopes

# Optional — only for the appeals / verification skills
oz secret create --team BOT_FRONT_API_KEY
oz secret create --team SLACK_COMMUNITY_BOT_TOKEN
oz secret create --team VERISOUL_API_KEY

Skip any secret that already exists (oz secret list). Only create the optional ones if the user wants the corresponding skills (front-appeals-inbox, slack-community-check, verisoul-lookup).

If the user plans to run locally instead of on Oz, have them export the same names as environment variables in their shell; the scripts read them directly.

Step 4: Create an Oz environment

The agent needs an Oz environment that includes this repo (and optionally the user's own server / data-model repos for extra context).

1. Check whether a suitable environment already exists: oz environment list.
2. If not, help the user create one that clones this repo (their fork, if they made local schema/config changes they want cloud runs to see — remind them that config/schema.local.json is git-ignored, so cloud runs on the upstream repo fall back to the placeholder config/schema.json unless they commit a config to a fork or set the FRAUD_BOT_SCHEMA env var to the path of a config file — it takes precedence over both config files, per scripts/schema.py).
3. Record the environment ID for the next step.

Step 5: Verify (optional but recommended)

If the user exported METABASE_API_KEY locally, smoke-test the pipeline before the first cloud run:

python3 scripts/api_client.py query -d warehouse \
  -s "SELECT user_id FROM {{ tables.core_user_facts }} WHERE signup_date >= CURRENT_DATE() - 1 LIMIT 5"

A JSON result means schema config + Metabase auth both work. If they exported SLACK_BOT_TOKEN, they can also test posting:

python3 scripts/api_client.py slack -m "fraud-bot setup test"

Step 6: Run

Ask which cadence the user wants and pick the matching instructions file:

• instructions.md — daily fraud report (24h window → CSV + Slack summary)
• instructions_v2.md — in-depth investigation workflow (~8h cadence)
• instructions_signup_spike.md — lightweight signup-spike monitor (every 30 min)

One-off cloud run:

oz agent run-cloud \
  --environment <ENV_ID> \
  --prompt "Read instructions.md and run daily fraud detection analysis"

Or a recurring schedule:

oz schedule create \
  --name "Daily Fraud Detection" \
  --cron "0 9 * * *" \
  --environment <ENV_ID> \
  --prompt "Read instructions.md and run daily fraud detection analysis"

In cloud runs the repo is checked out under /workspace/<repo-name>; if the agent has trouble finding the file, use the full path in the prompt (e.g. Read /workspace/fraud-detection-agent-oss/instructions.md ...).

Point the user at the Oz web app and oz schedule list / oz schedule get <SCHEDULE_ID> for monitoring.

Wrap-up checklist

Confirm with the user before declaring setup done:

• Repo cloned, oz authenticated
• config/schema.local.json (or fork/FRAUD_BOT_SCHEMA) resolves to their warehouse
• Required secrets registered (METABASE_API_KEY, SLACK_BOT_TOKEN)
• Environment created and its ID known
• First run launched or schedule created