Turn Traditional PHP Forms into Conversational AI with AIForm

Introducing AIForm for Neuron AI

When building an open‑source framework, community feedback often reveals the next most useful feature. Users repeatedly asked how to collect information via conversation instead of traditional forms, across scenarios such as registration, support tickets, and appointment scheduling. Implementing this manually required extensive glue code.

AIForm is released to address this exact need. It is a dedicated Neuron AI component that abstracts conversational form handling.

AIForm Features

The design is straightforward: use the familiar #[SchemaProperty] attribute to define the data structure you want to collect, just like Neuron AI’s structured output system, and optionally add validation rules.

Then extend the AIForm class, configure a provider, and the component automatically manages multi‑turn dialogs, field tracking, validation retries, and invokes your callback once all data is ready.

class RegistrationData
{
    #[SchemaProperty(description: 'User full name', required: true)]
    #[NotBlank]
    public string $name;

    #[SchemaProperty(description: 'Email address', required: true)]
    #[Email]
    public string $email;

    #[SchemaProperty(description: 'Phone number')]
    public ?string $phone = null;
}

class RegistrationForm extends AIForm
{
    protected string $formDataClass = RegistrationData::class;

    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: env('ANTHROPIC_API_KEY'),
            model: env('ANTHROPIC_MODEL'),
        );
    }

    protected function callback(): mixed
    {
        return function (RegistrationData $data) {
            $this->userService->register($data);
        };
    }
}

In a controller you simply feed each user message to the form instance, receive a state object containing status, completion percentage, missing fields, etc., and return that to the front‑end.

$form = RegistrationForm::make()
    ->setChatHistory(new FileChatHistory("/tmp/chats/{$sessionId}"));

$handler = $form->process(new UserMessage($request->input('message')));
$state = $handler->run();

return response()->json([
    'status'       => $state->getStatus()->value,
    'message'      => $handler->getLastResponse(),
    'completion'   => $state->getCompletionPercentage(),
    'missing_fields'=> $state->getMissingFields(),
    'is_complete'  => $form->isComplete(),
]);

Confirmation Step

When all required fields are collected, a real workflow often needs the user to review the information before the callback runs. AIForm provides requireConfirmation(), which throws a FormInterruptRequest instead of immediately submitting.

You can serialize this interrupt, present an AI‑generated summary to the user, and resume the workflow based on the user’s response.

$form = RegistrationForm::make()->requireConfirmation();

$handler = $form->process(new UserMessage($request->input('message')));
$state = $handler->run();

if ($handler->getInterrupt() instanceof FormInterruptRequest) {
    $_SESSION['form_interrupt'] = serialize($handler->getInterrupt());
    // Return AI‑generated summary to the user
}

// On the next request, restore the flow:
$interrupt = unserialize($_SESSION['form_interrupt']);
$handler = $form->process(new UserMessage($request->input('message')), $interrupt);

This mechanism builds on the human‑in‑the‑loop interrupt feature introduced in Neuron AI v2 workflows.

Why It Matters

AIForm is more than a chatbot wrapper for a form. It gracefully handles users who skip optional fields, mistype emails, answer out of order, or abandon a rigid UI. The conversational flow asks follow‑up questions, explains validation errors in plain language, and maintains state across turns without any extra developer effort.

It also shines on mobile and voice interfaces where long static forms are cumbersome. If your PHP application already exposes an API, adding AIForm gives you a conversational endpoint that any front‑end—keyboard, touch, or voice—can consume.

Building on Existing Stack

Because AIForm is a Neuron AI workflow at its core, it inherits all workflow capabilities, including native Inspector integration. Setting the INSPECTOR_INGESTION_KEY environment variable streams every form conversation to the Inspector dashboard, providing a complete execution timeline useful for debugging stalled dialogs or validation loops.

The component is open‑source on GitHub (repository neuron-core/ai-form). Install it via Composer:

composer require neuron-ai/ai-form

For detailed documentation of the structured output system and workflow components, visit docs.neuron-ai.dev.