# Fraud Alert Verification

Instantly reach cardholders when suspicious activity is detected, confirm whether transactions are legitimate, and lock or unlock accounts — all in real time.

### Why this matters

PCI-compliant, fully auditable voice automation for loans, collections, onboarding, and fraud prevention. This example shows you how to automate fraud alert verification calls end-to-end with Guava's SDK — no telephony plumbing, no prompt engineering, just Python.

## Installation

Install from Guava's private PyPI index. A public package is coming soon — the install command will simplify to `pip install guava`.

```bash
# Step 1: Install Guava
pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com

# Public PyPI package coming soon — the install command will simplify to:
# pip install guava

# Step 2: Set your credentials
export GUAVA_API_KEY="..."
export GUAVA_AGENT_NUMBER="..."
```

## How it's built

Every Guava agent is a Python class. Walk through the key sections below, then grab the complete file at the end.

### Imports

Import the Guava SDK and any helpers you need. `guava.CallController` is the base class for every voice agent.

```python
# Install: pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com
import guava
import os
```

### Agent setup

`set_persona()` defines how the agent presents itself. `set_task()` gives it its mission in plain English. The checklist drives the conversation — Guava works through it top-to-bottom, collecting `Field` values and speaking `Say` items as it goes.

```python
class FraudVerificationBot(guava.CallController):
    def __init__(self, cardholder: str, last_four: str, flagged_transactions: list[dict]):
        super().__init__()
        self.cardholder = cardholder
        self.last_four = last_four
        self.flagged = flagged_transactions
        self.set_persona(
            organization_name="First National Bank Fraud Prevention",
            agent_name="Morgan",
        )
        self.set_task(
            objective=f"Verify flagged transactions on card ending {last_four} with {cardholder}",
            checklist=[
                f"Greet {cardholder} and explain this is a fraud verification call — do NOT ask for full card number.",
                guava.Field(
                    key="verified_identity",
                    field_type="bool",
                    description="Verify identity with last 4 of SSN and ZIP code",
                ),
                *[
                    guava.Field(
                        key=f"txn_{i}_legitimate",
                        field_type="bool",
                        description=f"Did you authorize: {t['merchant']} for ${t['amount']} on {t['date']}?",
                    )
                    for i, t in enumerate(flagged_transactions)
                ],
                guava.Field(
                    key="freeze_card",
                    field_type="bool",
                    description="Does the cardholder want to freeze their card?",
                ),
                "Confirm resolution and provide case reference number.",
            ],
            on_complete=self.resolve_fraud,
        )

def resolve_fraud(self, fields):
        fraudulent = [i for i, t in enumerate(self.flagged) if not fields.get(f"txn_{i}_legitimate")]
        if fraudulent or fields.get("freeze_card"):
            print(f"Freezing card for {self.cardholder}, flagging {len(fraudulent)} transactions")

guava.dial(
    controller=FraudVerificationBot,
    controller_args={
        "cardholder": "Patricia Lane",
        "last_four": "4821",
        "flagged_transactions": [
            {"merchant": "Amazon Marketplace", "amount": "847.99", "date": "today at 2:14pm"},
            {"merchant": "Steam Games", "amount": "129.00", "date": "today at 2:17pm"},
        ],
    },
    to=os.environ["CARDHOLDER_PHONE"],
    agent_number=os.environ["GUAVA_AGENT_NUMBER"],
    api_key=os.environ["GUAVA_API_KEY"],
)
```

## Full example

The complete file — copy it, save it as `example.py`, and run it.

```python
# Install: pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com
import guava
import os

class FraudVerificationBot(guava.CallController):
    def __init__(self, cardholder: str, last_four: str, flagged_transactions: list[dict]):
        super().__init__()
        self.cardholder = cardholder
        self.last_four = last_four
        self.flagged = flagged_transactions
        self.set_persona(
            organization_name="First National Bank Fraud Prevention",
            agent_name="Morgan",
        )
        self.set_task(
            objective=f"Verify flagged transactions on card ending {last_four} with {cardholder}",
            checklist=[
                f"Greet {cardholder} and explain this is a fraud verification call — do NOT ask for full card number.",
                guava.Field(
                    key="verified_identity",
                    field_type="bool",
                    description="Verify identity with last 4 of SSN and ZIP code",
                ),
                *[
                    guava.Field(
                        key=f"txn_{i}_legitimate",
                        field_type="bool",
                        description=f"Did you authorize: {t['merchant']} for ${t['amount']} on {t['date']}?",
                    )
                    for i, t in enumerate(flagged_transactions)
                ],
                guava.Field(
                    key="freeze_card",
                    field_type="bool",
                    description="Does the cardholder want to freeze their card?",
                ),
                "Confirm resolution and provide case reference number.",
            ],
            on_complete=self.resolve_fraud,
        )

## Run it

Start the agent. It will connect to Guava's infrastructure and begin accepting calls on your assigned number.

```bash
python example.py
```