# AI Field Mapping

## Overview

Form Connector includes an AI-powered field mapping feature that automatically suggests how your form fields should map to CareHQ contact fields. This saves time when configuring new forms and reduces mapping errors.

## How It Works

1. **Enable AI** in Settings → AI Mapping
2. **Open a form** on the Mappings tab
3. **Click "✨ Auto-map with AI"** to request suggestions
4. **Review** the suggestions — each shows the suggested target field, a confidence score, and a brief reason
5. **Accept** suggestions individually or in bulk, then save

## Architecture

AI requests are routed through the FormConnector backend server (`app.formconnector.co.uk`):

```
WordPress Plugin  →  FormConnector Server  →  AI Provider
   (your site)        (approval/rate-limit)     (inference)
```

Your license key authenticates the request. The backend server handles:
- Request approval and rate limiting
- AI provider selection and inference
- Response validation

## Privacy

**Only field metadata is sent** — field IDs, labels, types, and option labels. No form submission data, no personal information, and no user content is ever transmitted to the AI service.

The data sent looks like:
```json
{
  "form_fields": [
    { "id": "field_1", "label": "Your Name", "type": "text" },
    { "id": "field_2", "label": "Email Address", "type": "email" },
    { "id": "field_3", "label": "Message", "type": "textarea" }
  ],
  "carehq_fields": {
    "first_name": "First Name",
    "last_name": "Last Name",
    "email": "Email Address",
    "phone": "Phone Number",
    "care_requirements": "Message / Enquiry Details"
  }
}
```

## Caching

Suggestions are cached for 24 hours per unique combination of form fields and CareHQ fields. Clicking the AI button again within that window returns the cached result without making a new request.

## Requirements

- Active Form Connector license
- AI Mapping enabled in Settings
