# AgentForms — Form Infrastructure for AI Agents

## Positioning

AgentForms is form infrastructure for AI agents. Agents are the primary builders — they create, configure, and manage forms, documents, and workflows programmatically. Humans can interact when needed: inspecting forms, monitoring submissions, overriding config, or building manually for quick one-offs.

**What agents do:**
- "Create an intake form for a client onboarding"
- "Generate a quote document for this prospect"
- "Build a survey for our users"
- "Set up automated follow-up emails after form submission"

**What humans do when needed:**
- Inspect agent-built forms and submissions
- Override field config or action settings
- Build forms manually via the web UI for quick one-offs
- Monitor analytics and campaign performance

The entire form lifecycle is API-first. Every form is a JSON schema. Every action is a webhook hook. Every workflow is an LLM-generated pipeline. The human UI shares the same backend — no separate data paths.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│  AI Agent (Claude, Codex, Hermes, Custom)               │
│                                                         │
│  "Create a client intake form with fields:              │
│   name, email, company, budget, timeline"               │
└──────────────────────┬──────────────────────────────────┘
                       │  /api/agent/build
                       ▼
┌─────────────────────────────────────────────────────────┐
│  AgentForms Relay (Flask + Gunicorn)                    │
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌────────────────┐  │
│  │ Workflow     │  │ Action      │  │ Form Logic     │  │
│  │ Builder (P2) │  │ Pipeline    │  │ Engine (P3)    │  │
│  │             │  │ (P1)        │  │                │  │
│  └──────┬──────┘  └──────┬──────┘  └────────┬───────┘  │
│         │                │                   │          │
│  ┌──────┴──────┐  ┌──────┴──────┐  ┌────────┴───────┐  │
│  │ LLM Client  │  │ Webhook     │  │ Validation     │  │
│  │ (Qwen 4B)   │  │ Dispatch    │  │ Conditions     │  │
│  └─────────────┘  │ Calculations│  │ Multi-step     │  │
│                   └─────────────┘  └────────────────┘  │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  AgentForms Worker (Celery + Redis)                     │
│                                                         │
│  Async action execution: email delivery,                │
│  webhook dispatch, document generation                  │
└─────────────────────────────────────────────────────────┘
```

## Agent API Surface

### Phase 1 — Action Pipeline

Post-submission automation. When a form is submitted, configured actions execute:

| Action Type | Description |
|---|---|
| `webhook` | POST to any URL with submission data |
| `email` | Send formatted email via configured provider |
| `log` | Store in internal audit log |
| `redirect` | Redirect user to specified URL |
| `document` | Generate document (PDF, DOCX) from template |

Actions are ordered by `execution_order`, triggered by `trigger_event` (default: `submission`).

### Phase 2 — Workflow Builder

Agent tells the LLM what it needs. LLM returns a complete form schema:

```
POST /api/agent/build
{
  "prompt": "Create a contractor NDA with fields: party names, effective date, scope of work, confidentiality period, governing state",
  "form_type": "contract",
  "theme": { "primary": "#2563eb" }
}
```

Returns: complete `field_config` JSON + action suggestions.

### Phase 3 — Form Logic Engine

Server-side evaluation of form logic:

- **Validation** — email, phone, pattern, min/max, required
- **Conditional fields** — show/hide based on other field values (11 operators)
- **Calculated fields** — `{{price}} * {{quantity}}` formula engine
- **Multi-step forms** — step grouping with navigation

All logic is evaluable by headless agents — no client-side dependency.

### Phase 4 — Event Stream + SDK

- **SSE Event Stream** — real-time submission events for agent consumption
- **JS SDK** — client-side embed for human-facing forms

## API Reference

### Agent Build Endpoint

```
POST /api/agent/build
Authorization: Bearer <token>
```

**Request:**
```json
{
  "prompt": "string (required)",
  "form_type": "string (optional, default: 'form')",
  "theme": {
    "primary": "string (hex color)"
  }
}
```

**Response:**
```json
{
  "success": true,
  "site_id": 1,
  "fields": [...],
  "actions_suggested": [...],
  "embed_url": "https://agentforms.io/embed/abc123",
  "token": "abc123"
}
```

### Site CRUD

```
POST /api/sites              — Create site
GET  /api/sites              — List sites
GET  /api/sites/:id          — Get site
PUT  /api/sites/:id          — Update site
DELETE /api/sites/:id        — Delete site

POST /api/sites/:id/actions  — Create action
GET  /api/sites/:id/actions  — List actions
PUT  /api/actions/:id        — Update action
DELETE /api/actions/:id      — Delete action
```

### Form Submission

```
POST /api/submit?token=<token>
Content-Type: application/x-www-form-urlencoded
```

Returns `200 OK` on success, `422` with validation errors.

## Data Model

```
users
  └── sites
        ├── field_config (JSON)
        ├── actions
        │     ├── type
        │     ├── config (JSON)
        │     ├── trigger_event
        │     └── execution_order
        └── submissions
              └── data (JSON)
```

## Authentication

- **API Key** — `X-API-Key` header or `Bearer` token
- **Session** — SameSite+Secure cookies for human UI
- **CSRF** — Exempted for JSON API endpoints; required for HTML forms

## Deployment

- **Relay** — Flask + Gunicorn on `0.0.0.0:5060`
- **Worker** — Celery + Redis for async actions
- **Database** — SQLite (`relay.db`), Postgres migration planned
- **LLM** — Qwen3.5-4B via llama.cpp on port 8086 (configurable via `BUILDER_LLM_HOST`)
- **Docker** — `docker compose up -d`

## Phase Roadmap

| Phase | Status | Description |
|---|---|---|
| P1: Action Pipeline | ✅ Done | Webhook/email/log/redirect/document actions |
| P2: Workflow Builder | ✅ Done | LLM-generated forms from prompts |
| P3: Form Logic Engine | ✅ Done | Validation, conditions, calculations, multi-step |
| P4: SSE + JS SDK | ✅ Done | Real-time streaming build, EventSource SDK |
| P5: Document Generation | 🔜 Planned | PDF/DOCX from templates |
| P6: Postgres Migration | 🔜 Planned | Production-scale database |

## Testing

```bash
cd /home/vincent/projects/agentforms
python -m pytest tests/ -v
```