# PropertyLab AI — setup guide for white-label deployments

This guide is for the person who runs a white-label PropertyLab deployment. It
explains how to connect your deployment to PropertyLab AI, what changes once it
is connected, and how billing works.

## 1. What PropertyLab AI is

Every AI feature in your deployment (lead analysis, WhatsApp auto-replies, Zoom
and call analysis, the AI chat, transcription, voice calls, and so on) runs on
PropertyLab AI. You do not need accounts or API keys with any AI provider, and
you do not choose models. PropertyLab picks the model behind each feature and
bills you monthly in **credits**.

## 2. What you receive from PropertyLab

- A **PropertyLab AI key**. It looks like `plk_` followed by 40 characters. It is
  shown to PropertyLab once when it is issued, so keep the copy you were given.
- Your **rate per credit** and **currency**. The rate follows the USD exchange
  rate, so it moves a little from month to month; the rate used for each
  statement is printed on it.
- The **PropertyLab AI address**, normally `https://app.propertylab.com.my`.

## 3. Configure your deployment

Add these three lines to your deployment's `.env` file:

```
AI_GATEWAY_MODE=client
PROPERTYLAB_AI_BASE_URL=https://app.propertylab.com.my
PROPERTYLAB_AI_KEY=plk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Then apply the change:

```
php artisan config:clear
php artisan route:clear
```

Restart your queue workers (and the SSR server, if you run one), because they
keep the old configuration in memory until restarted.

If you previously stored AI provider keys in your deployment, they are no longer
used. You can leave them or remove them; they have no effect in this mode.

## 4. Check that it works

1. Log in to your admin portal and open **Setting → PropertyLab API**.
2. The page should show your account name, your rate per credit, and no warning
   banner at the top. A banner means one of the three settings is wrong. Its
   text says which.
3. Use any AI feature, for example the AI chat under AI Employee, or Lead AI
   Sales Coach on a lead.
4. Return to **Setting → PropertyLab API**. The call appears in the request log
   with the credits it cost.

## 5. What changes in your admin portal

- **Setting → AI Requests** is replaced by **Setting → PropertyLab API**.
- **AI Providers** (the API key screen) is gone. There are no keys to manage.
- **Setting → AI Prompts** still lets you edit the wording of every prompt. The
  **Model** choice is gone; PropertyLab manages it.
- Members of your portal can no longer add their own AI provider keys. Their
  free-credit allowance for the AI chat works exactly as before.
- Every AI request shows provider **PropertyLab API** and model
  **PropertyLab AI**.
- **Not available** on white-label deployments: event poster image generation
  and AI Video. Every other AI feature works.

## 6. The PropertyLab API page

**Setting → PropertyLab API** is your usage dashboard.

- **This month**: credits used so far, the estimated amount at your rate, the
  number of requests, and how many failed. Failed requests are never billed.
- **Credits by feature**: which features used the credits.
- **Credits per day**: a bar per day of the month.
- **Statements**: every monthly statement PropertyLab has issued, with a PDF.
- **Requests**: the full log. Click a row to see what was sent and what came
  back.
- **Refresh** re-reads your account details and statements from PropertyLab.

If PropertyLab has set a monthly credit cap for you, the first tile shows how
much of it you have used. The cap is an alert, not a block; AI keeps working.

## 7. How billing works

- Each successful AI request costs credits. A credit is pegged to the US
  dollar, so the credits a request costs depend on the feature (different
  features run on different models) and on how much text is processed. Transcription is charged per minute of audio; voice calls per
  1,000 characters of script. Your rate per credit is the ringgit you pay per
  credit.
- The credits for every request are fixed at the moment it runs. A later price
  change never alters a request already made. The exchange rate is fixed on
  each statement when it is prepared, so an issued statement never changes.
- On the 1st of each month (Malaysia time) PropertyLab prepares a statement for
  the previous month, reviews it, and issues it. The statement lists your usage
  by feature, the credits, and the amount at your rate.
- Issued statements appear on your PropertyLab API page with a PDF, and are
  emailed to the billing address PropertyLab has on file for you.
- The figures on your page during the month are your own deployment's record.
  The issued statement is the bill.

## 8. If AI stops working

Open **Setting → PropertyLab API**. The banner at the top tells you why:

| Banner says | Cause | What to do |
|---|---|---|
| not configured | one of the three `.env` lines is missing | add it, then `php artisan config:clear` |
| API key rejected | the key is wrong, or PropertyLab rotated it | ask PropertyLab for the current key |
| access is suspended | PropertyLab suspended your account | contact PropertyLab |
| could not be reached | your server cannot reach PropertyLab | check your outbound network / firewall |

Your server must be able to reach the PropertyLab AI address over HTTPS. If
PropertyLab restricts access by IP, give them your server's public IP.

## 9. Changing the key

If PropertyLab issues you a new key, the old one stops working immediately.
Update `PROPERTYLAB_AI_KEY`, run `php artisan config:clear`, and restart your
queue workers.