From 48c98f5e4baa7c8d1d862fed15068820ad23937e Mon Sep 17 00:00:00 2001 From: Jerry Date: Thu, 16 Jul 2026 18:15:52 -0400 Subject: [PATCH] Add setup skill and How to deploy README section Adds .agents/skills/setup/SKILL.md, an end-to-end deploy walkthrough (clone, prereqs, schema config, secrets, Oz environment, first run) that works whether or not the repo is already cloned. Replaces the README Setup section with a How to deploy section leading with a copy-paste prompt that runs the skill, keeping the manual steps as a human-readable reference. Co-Authored-By: Oz --- .agents/skills/setup/SKILL.md | 170 ++++++++++++++++++++++++++++++++++ README.md | 25 ++++- 2 files changed, 190 insertions(+), 5 deletions(-) create mode 100644 .agents/skills/setup/SKILL.md diff --git a/.agents/skills/setup/SKILL.md b/.agents/skills/setup/SKILL.md new file mode 100644 index 0000000..ab01373 --- /dev/null +++ b/.agents/skills/setup/SKILL.md @@ -0,0 +1,170 @@ +--- +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: +```bash +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](https://docs.warp.dev/reference/cli) 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: + ```bash + 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: + ```bash + 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: + +```bash +# 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](https://docs.warp.dev/agent-platform/cloud-agents/environments) +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: + +```bash +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: +```bash +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: +```bash +oz agent run-cloud \ + --environment \ + --prompt "Read instructions.md and run daily fraud detection analysis" +``` + +Or a recurring schedule: +```bash +oz schedule create \ + --name "Daily Fraud Detection" \ + --cron "0 9 * * *" \ + --environment \ + --prompt "Read instructions.md and run daily fraud detection analysis" +``` + +In cloud runs the repo is checked out under `/workspace/`; 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](https://oz.warp.dev/runs) and +`oz schedule list` / `oz schedule get ` 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 diff --git a/README.md b/README.md index 4902a67..52b4c76 100644 --- a/README.md +++ b/README.md @@ -9,16 +9,30 @@ This repo contains instructions and SQL queries that an AI agent uses to: 2. Look for new/emerging fraud clusters 3. Report findings to Slack -## Setup +## How to deploy + +The fastest path is to let an agent do the setup. Paste this prompt into Warp (or any +agent runtime that supports skills): + +> Clone https://github.com/warpdotdev/fraud-detection-agent-oss.git (or use my existing +> clone) and run the setup skill at `.agents/skills/setup/SKILL.md` to deploy fraud-bot. + +The [setup skill](.agents/skills/setup/SKILL.md) handles cloning, schema config, secret +registration, environment creation, and the first run — interactively, asking you only +for the values it can't discover. + +Prefer to do it by hand? The same steps follow as a human-readable reference. + +### Manual setup (reference) > **Prerequisites:** the [Oz CLI](https://docs.warp.dev/reference/cli) (`oz`), authenticated with `oz login` (or `WARP_API_KEY` in CI). You bring your own data sources — a Metabase instance, a BigQuery warehouse matching [`SCHEMA.md`](SCHEMA.md), and Slack (optionally Front/Verisoul) tokens. **This repo ships no credentials.** -### 1. Point the schema config at your warehouse +#### 1. Point the schema config at your warehouse Copy `config/schema.json` to `config/schema.local.json` (git-ignored) and set your project, datasets, tables, and Metabase database IDs. See [`SCHEMA.md`](SCHEMA.md) for the column contract each logical table must satisfy. -### 2. Register secrets +#### 2. Register secrets Store these as team-scoped [Oz agent secrets](https://docs.warp.dev/agent-platform/cloud-agents/secrets) (injected as environment variables at runtime): ```bash @@ -32,7 +46,7 @@ oz secret create --team VERISOUL_API_KEY Running locally instead of on Oz? Export the same names as environment variables — the scripts read them directly (e.g. `export METABASE_API_KEY=...`). -### 3. Create an environment +#### 3. Create an environment Create an [Oz environment](https://docs.warp.dev/agent-platform/cloud-agents/environments) that includes this repo (optionally your own server / data-model repos for extra context), then find its ID: @@ -40,7 +54,7 @@ its ID: oz environment list ``` -### 4. Run +#### 4. Run One-off cloud run: ```bash oz agent run-cloud \ @@ -80,6 +94,7 @@ oz schedule create \ Two complementary skill formats ship with this repo; use whichever your agent runtime supports: - `.agents/skills/` — a granular suite, one directory per capability: + - Deployment: `setup` — end-to-end install/deploy walkthrough (see [How to deploy](#how-to-deploy)) - Detection / investigation: `ip-cluster-analysis`, `prompt-injection-denylist`, `user-graph-traversal`, `user-convo-summary` - Ban-appeal enrichment (optional Front / Slack / Verisoul integrations):