Filament Natural Language Filter Laravel Package

Getting Started

The package turns a free-text search box into Filament table filters, so users can type things like "active users created last week" instead of clicking through filter dropdowns.

Minimal setup:

1. Install into an existing Filament app:

   composer require hayderhatem/filament-natural-language-filter
   

2. Publish config (almost certainly required for API/model settings):

   php artisan vendor:publish --tag="filament-natural-language-filter-config"
   

3. Configure the LLM provider in config/filament-natural-language-filter.php. Expect fields for provider/model/API key; source the key from env() (e.g. OPENAI_API_KEY) rather than hardcoding.
4. Attach it to a table in a Resource's table() method — typically a ->filters([...]) entry or a header action/search component. Check src/ for the actual Filament component/action class name, since README coverage is thin at 13 stars.

Look here first, in order:

• README.md — install + usage snippet (short).
• config/filament-natural-language-filter.php — reveals provider, model, prompt, and allowed-column config.
• src/ — the Filament filter/action class and the prompt-building logic; this is where you'll debug.

First use case: add it to one low-risk resource (e.g. OrderResource or UserResource) alongside your existing filters. Try a query, inspect storage/logs/laravel.log, and confirm the generated filter array matches what your table expects before rolling it out panel-wide.

Implementation Patterns

Drop-in on a table. The dominant pattern is instantiating the filter inside table():

->filters([
    \HayderHatem\NaturalLanguageFilter\...::make(),
    // existing filters...
])

The exact namespace/class depends on the release — copy from the README or src/.

Coexist with manual filters. Don't replace your SelectFilter/DateFilters. Keep them so users have a deterministic fallback when the LLM misparses. The NL filter is an accelerant, not a replacement.

Scope the vocabulary. Most implementations rely on a schema describing filterable columns and their operators. Review the config's column whitelist and restrict it to columns that actually have filters defined; unconstrained prompts produce filters Filament silently ignores.

Resource-level vs panel-level. Prefer applying per-resource so you can tune allowed columns per model (a TeamResource and InvoiceResource need very different vocab). Avoid a global enable until you've validated a couple of resources.

Prompt/schema customization. If the config exposes the system prompt or a "filter map", treat it as code: version it in config, test representative phrasings ("last 7 days", "bigger than 100", "status is pending"), and iterate.

Chaining with the table query. If the package exposes a generated query array, you can also call it from a custom header action or Livewire method — useful for building "saved NL searches" or dashboards that accept a text query string.

Testing workflow. Write a Pest/PHPUnit test that feeds fixed phrases into the prompt-builder (not the live API) and asserts the resulting filter array. Mock the LLM client so CI doesn't depend on a paid endpoint.

Gotchas and Tips

• Cost and latency per keystroke. Natural language filter UIs often fire on submit/debounce. Ensure it triggers on explicit submit — never on wire:model.live without debounce — or you'll burn API tokens.
• Non-determinism. The same phrase can produce different filters run-to-run. Pin temperature: 0 if configurable, and always show the user which filters were applied (a "chips" or applied-filter display) so surprises are visible.
• API key exposure. The key must live server-side. If any part of this ships to the browser (e.g. an inline Livewire component echoing config), verify it isn't leaking the key.
• Prompt injection. Free-text goes to an LLM that returns structured filters; a malicious user could phrase input to target columns outside your whitelist. Enforce the whitelist server-side after the LLM responds — don't trust the model's output.
• Column name mismatches. Generated filters referencing relationship paths (customer.name) or nonexistent columns are silently dropped by Filament. Log the raw model output during development.
• Rate limits / outages. Wrap the call in try/catch and degrade gracefully: on failure, fall back to the manual filter set and show a toast rather than a hard error.
• Multi-tenancy. Ensure the LLM never sees or produces filters that cross tenant boundaries. Scope the query builder after filters are applied, not before.
• Localization. Phrases like "last week" are locale-sensitive. If the app is non-English, extend the prompt with locale/date context or the parser will misread relative dates.
• Debugging recipe: enable debug logging in the config, echo the prompt and raw LLM response, and diff against Filament's $this->tableFilters after submission. Most "it doesn't work" reports are malformed JSON or wrong filter key names.
• Extension point. If the package allows a custom resolver/parser class, swap in your own implementation — this is the cleanest way to add domain rules (e.g. always AND tenant scope) without forking.
• Maturity check. 13 stars and a June 2025 release means limited community testing; audit src/ before production, pin the version in composer.json, and be prepared to fork if the maintainer goes quiet.