setup

# 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 <ENV_ID> \ --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 <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](https://oz.warp.dev/runs) 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