Download the PHP package pdro-lucas/filament-ai-writer without Composer

filament-ai-writer

https://github.com/user-attachments/assets/05b8f24e-e01e-4acc-836a-32acda143b42

A reusable Filament Action that adds AI-powered text generation to any form field. Supports Anthropic Claude, OpenAI, and Google Gemini out of the box.

Status: Beta — This package is in active development. APIs may change and issues can occur.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• Filament 4.x

Installation

The service provider is auto-discovered by Laravel. No manual registration needed.

Configuration

Add your API key to .env depending on which provider you want to use:

To switch providers or customize the model, add the following variables:

If you need to customize the full configuration, publish the config file:

This creates config/filament-ai-writer.php in your project where you can set per-provider models, API keys, and token limits. Publishing is optional — the package works with just the .env variables.

Usage

Import the action and attach it to any Filament form field using hintAction or suffixAction.

The action works in two modes: interactive and silent. Interactive mode opens a modal where the user describes what they want. Silent mode reads other fields from the current form as context and generates immediately, with no modal.

Interactive mode

The user clicks the sparkles button, a modal opens with a free-text area, and the AI generates content based on the user input and the configured prompt. The result is injected into the target field.

Silent mode

The user clicks the button and the AI generates immediately, reading the specified context fields from the current form. No modal is shown. A success notification is displayed when generation completes.

If any of the context fields are empty when the button is clicked, the action shows a warning notification listing the missing fields and does not generate.

Silent mode with a select field

Use ->valueMap() when the target field is a select or radio. Pass the same id => name map used in ->options(). The AI receives the available options as context and returns the key of the chosen option.

Silent mode with tags or multi-select

Use ->allowedValues() when the target field is a tags input or multi-select. The AI receives the list of allowed values and must return a JSON array containing only values from that list. Values not present in the list are filtered out before injection.

When no ->allowedValues() is provided but the target field still expects an array, use ->expectArray():

API reference

AiWriterAction::make(?string $name = null): static

Creates a new action instance. Defaults to 'ai_writer'. If you attach more than one action to the same form, give each a unique name.

->targetField(string $field): static

The name of the form field where the generated text will be injected.

->prompt(string $prompt): static

The system prompt sent to the AI provider. Use this to define tone, format, length constraints, and domain-specific instructions. The more specific the prompt, the better the output.

->contextFields(array $fields): static

An array of field names to read from the current form and pass to the AI as context. Used in silent mode.

->silent(bool $condition = true): static

Enables silent mode. The action generates immediately on click with no modal, using contextFields as input.

->valueMap(array $map): static

An id => name map for select or radio fields. The AI receives the options as context and returns a single key. Use this instead of ->allowedValues() when the field expects a scalar value.

->allowedValues(array $values): static

A flat array of allowed values for tags inputs or multi-selects. The AI must return a JSON array containing only values from this list. Values not present in the list are filtered out before injection.

->expectArray(bool $condition = true): static

Tells the action to parse the AI response as an array even when no ->allowedValues() is defined. Useful for free-form tags where any value is acceptable.

->normalizeArrayCase(bool $condition = true): static

Converts all values in the generated array to lowercase before injection. Useful for tags to ensure consistent casing regardless of what the AI returns.

->beforeGenerate(callable $callback): static

Register a callback that runs before AI generation on this action instance. Return false to cancel generation. Useful for credit checks, permissions, or rate limiting.

AiWriterAction::globalBeforeGenerate(callable $callback): void

Register a global callback that runs before every AI generation across all action instances. Typically called in AppServiceProvider::boot(). The instance-level ->beforeGenerate() runs after this global hook.

AiTextGenerated event

Dispatched after every successful AI generation. The payload contains:

Listen to this event to debit credits, log usage, or send notifications:

Supported providers

Package structure

Extending with a custom provider

Implement the AiProvider contract and rebind it in your AppServiceProvider:

Local development

To use this package in a local project, add a path repository to your project's composer.json:

Then run:

Composer will symlink the local package directory, so any changes you make to the package are reflected immediately in the project.

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

Before contributing, please ensure your changes follow the existing code style and include any necessary updates to documentation.

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes using conventional commits
4. Push to your fork and open a pull request

License

This project is open-sourced under the MIT license.