# Utility Shutoff Warning

Notify residents of impending utility shutoff due to non-payment, offer payment plan options, and connect them with assistance programs before service is interrupted.

### Why this matters

Reach constituents at scale for benefits enrollment, permit follow-ups, public health outreach, and emergency notifications. This example shows you how to automate utility shutoff warning 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`.

```
# 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.

```
# 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 UtilityShutoffBot(guava.CallController):
    def __init__(self, account_holder: str, utility_type: str, account_number: str,
                 amount_due: float, shutoff_date: str):
        super().__init__()
        self.set_persona(
            organization_name="Metro Water & Power",
            agent_name="Devon",
        )
        self.set_task(
            objective=f"Warn {account_holder} of {utility_type} shutoff on {shutoff_date} for ${amount_due:.2f} due",
            checklist=[
                f"Reach {account_holder} urgently about their {utility_type} account {account_number}.",
                guava.Say(f"Service will be disconnected on {shutoff_date} unless ${amount_due:.2f} is paid."),
                guava.Field(
                    key="payment_intent",
                    field_type="choice",
                    description="How does the customer want to resolve the balance?",
                    choices=["pay in full now by phone", "pay online today",
                             "set up payment arrangement", "apply for assistance program",
                             "dispute the bill"],
                ),
                guava.Field(
                    key="medical_necessity",
                    field_type="bool",
                    description="Is there a medical necessity that requires uninterrupted service?",
                ),
                guava.Field(
                    key="assistance_program_interest",
                    field_type="bool",
                    description="Are they interested in the LIHEAP energy assistance program?",
                ),
                "Transfer to payment line or assistance program enrollment as appropriate.",
            ],
            on_complete=lambda fields: print(f"Shutoff warning call done: {account_holder} — {fields.get('payment_intent')}"),
        )

guava.dial(
    controller=UtilityShutoffBot,
    controller_args={"account_holder": "David Osei", "utility_type": "electric",
                     "account_number": "MWP-447821", "amount_due": 387.44,
                     "shutoff_date": "this Friday"},
    to=os.environ["ACCOUNT_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.

```
import guava
import os

class UtilityShutoffBot(guava.CallController):
    def __init__(self, account_holder: str, utility_type: str, account_number: str,
                 amount_due: float, shutoff_date: str):
        super().__init__()
        self.set_persona(
            organization_name="Metro Water & Power",
            agent_name="Devon",
        )
        self.set_task(
            objective=f"Warn {account_holder} of {utility_type} shutoff on {shutoff_date} for ${amount_due:.2f} due",
            checklist=[
                f"Reach {account_holder} urgently about their {utility_type} account {account_number}.",
                guava.Say(f"Service will be disconnected on {shutoff_date} unless ${amount_due:.2f} is paid."),
                guava.Field(
                    key="payment_intent",
                    field_type="choice",
                    description="How does the customer want to resolve the balance?",
                    choices=["pay in full now by phone", "pay online today",
                             "set up payment arrangement", "apply for assistance program",
                             "dispute the bill"],
                ),
                guava.Field(
                    key="medical_necessity",
                    field_type="bool",
                    description="Is there a medical necessity that requires uninterrupted service?",
                ),
                guava.Field(
                    key="assistance_program_interest",
                    field_type="bool",
                    description="Are they interested in the LIHEAP energy assistance program?",
                ),
                "Transfer to payment line or assistance program enrollment as appropriate.",
            ],
            on_complete=lambda fields: print(f"Shutoff warning call done: {account_holder} — {fields.get('payment_intent')}"),
        )

# Make the call

## Run it

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

```
python example.py
```