README

Filament v5 admin plugin for eloquage/laravel-vector-search with CRUD resources and a semantic search dashboard.

Requirements

Requirement	Version / notes
PHP	8.4+
Filament	5.x
Core package	`eloquage/laravel-vector-search`
Queue worker	Required for document indexing (`ProcessVectorDocument`, `EmbedVectorChunks`)
Database	PostgreSQL with pgvector, or Meilisearch, depending on driver

Architecture

VectorIndex → VectorDocument → VectorChunk → embedding provider → vector driver

The plugin surfaces this pipeline in Filament:

Artifact	Class	Purpose
Dashboard	`VectorSearchDashboard`	Semantic search playground + pipeline widgets
Index resource	`VectorIndexResource`	CRUD for vector indexes
Document resource	`VectorDocumentResource`	CRUD for documents + index action
Playground	`SearchPlayground`	Livewire semantic search UI
Widgets	`VectorEngineStatsWidget`, `IndexingPipelineWidget`	Counts and pipeline status

Installation

1. Install the core package first

composer require eloquage/laravel-vector-search

Publish and migrate:

php artisan vendor:publish --tag=vector-search-migrations
php artisan migrate

Optionally publish config:

php artisan vendor:publish --provider="Eloquage\LaravelVectorSearch\LaravelVectorSearchServiceProvider"

Configure .env for your driver and embedding provider. Examples:

pgvector + OpenAI

VECTOR_SEARCH_DRIVER=postgres_vector
VECTOR_SEARCH_EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

pgvector + Ollama (local)

VECTOR_SEARCH_DRIVER=postgres_vector
VECTOR_SEARCH_EMBEDDING_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

Meilisearch

VECTOR_SEARCH_DRIVER=meilisearch
MEILISEARCH_HOST=http://localhost:7700
MEILISEARCH_KEY=masterKey

Start a queue worker — indexing is asynchronous:

php artisan queue:work

ProcessVectorDocument runs on the queue with a 300-second timeout, uniqueness per document, and backoff of 10, 60, and 300 seconds.

For pgvector, optionally publish and run the HNSW index migration stub from the core package.

2. Install the Filament plugin

composer require eloquage/filament-vector-search

Publish config (optional):

php artisan vendor:publish --tag=filament-vector-search-config

use Eloquage\FilamentVectorSearch\VectorSearchPlugin;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            VectorSearchPlugin::make()
                ->navigationGroup('Knowledge Base')
        );
}

The service provider registers the filament-vector-search.search-playground Livewire alias automatically.

Quick start

Create a Vector Index in the admin (driver, embedding provider, chunking strategy).
Create a Vector Document with title and content.
Click Index document on draft records (queues chunking + embedding).
Ensure a queue worker is running.
Open Vector Search (/admin/vector-search) and run a semantic query.

Plugin registration

VectorSearchPlugin registers:

Page: VectorSearchDashboard at slug vector-search (nav label: "Vector Search")
Resources: VectorIndexResource, VectorDocumentResource
Widgets: VectorEngineStatsWidget, IndexingPipelineWidget

Default navigation group: Vector Search.

Fluent customization

VectorSearchPlugin::make()
    ->navigationGroup('Knowledge Base')
    ->dashboardPage(CustomVectorSearchDashboard::class)
    ->indexResource(AppVectorIndexResource::class)
    ->documentResource(AppVectorDocumentResource::class)
    ->widgets([
        VectorEngineStatsWidget::class,
        IndexingPipelineWidget::class,
    ]);

Method	Purpose
`navigationGroup()`	Sets nav group for all plugin pages/resources
`dashboardPage()`	Replace the dashboard page class
`indexResource()`	Replace the index resource class
`documentResource()`	Replace the document resource class
`widgets()`	Replace dashboard header widgets

Configuration

Key	Env	Purpose
`default_playground_index`	`FILAMENT_VECTOR_SEARCH_DEFAULT_INDEX`	Preferred index name for the search playground
`archive.enabled`	`FILAMENT_VECTOR_SEARCH_ARCHIVE_INTEGRATION`	Enable document-archive metadata columns and actions (default `true`)
`widgets.polling_interval`	`FILAMENT_VECTOR_SEARCH_WIDGET_POLLING`	Dashboard widget polling interval (default `30s`)

When archive integration is enabled and eloquage/laravel-document-archive is installed, the plugin reads document-archive.vector_index for the default playground index.

Bulk actions

On the documents table:

Index selected — dispatches ProcessVectorDocument for selected draft rows (requires update policy).
Re-index failed — clears error_log and re-queues failed documents.

Header action Re-index all failed appears when any failed documents exist.

Document archive integration (optional)

When eloquage/laravel-document-archive and/or eloquage/laravel-document-archive-ai are installed:

Feature	When visible
Metadata columns (`collection`, `canonical_basename`, archive `status`)	`archive.enabled=true` and `ManifestService` is bound
View manifest row action	Document has `metadata.collection` + `metadata.canonical_basename`
Correlate row/header actions	`CorrelationAgent` class is available
Collection filter	Archive integration active

Index naming aligns with document-archive.vector_index (default document-archive), matching eloquage/laravel-document-archive-vector.

Disable integration without uninstalling archive packages:

FILAMENT_VECTOR_SEARCH_ARCHIVE_INTEGRATION=false

Third-party recipes

See docs/third-party-evaluation.md for guidance on:

spatie/laravel-permission — implement canManage() in concrete policies (document-only; no package dependency)
spatie/laravel-activitylog — log changes on core VectorDocument / VectorIndex models in the host app
filament/spatie-laravel-media-library-plugin — skipped; vector documents use text content, not media uploads

Dashboard and semantic search playground

VectorSearchDashboard shows:

Header widgets: index/document/chunk counts and queue size (database driver), plus indexing pipeline status counts
SearchPlayground embedded via Filament\Schemas\Components\Livewire
Recent failures: latest three failed documents with truncated error logs

SearchPlayground behavior:

Select a vector index and type a semantic query
Debounced live search (wire:model.live.debounce.500ms) after 3+ characters
Configurable result limit (default 5, max 20 in UI)
Uses LaravelVectorSearch::forIndex($index)->search($query, $limit)

Resources

VectorIndexResource

Fields: name, driver, embedding provider, embedding model, dimensions (pgvector only), chunking strategy, chunk size, chunk overlap (recursive strategy only).

Includes a documents relation manager.

VectorDocumentResource

Fields: index, title, content (textarea).

Table action Index document appears for draft records and dispatches ProcessVectorDocument.

Includes a chunks relation manager (paginated 10/25/50).

Customization

Navigation icons

Subclass a page or resource and override $navigationIcon using the Filament 5 union type (string|BackedEnum|null):

use Filament\Support\Icons\Heroicon;

class CustomVectorSearchDashboard extends VectorSearchDashboard
{
    protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedSparkles;

    public static function getNavigationGroup(): string|\UnitEnum|null
    {
        return 'Knowledge Base';
    }
}

Policies

The plugin ships abstract base policies you can extend in your app:

use Eloquage\FilamentVectorSearch\Policies\VectorDocumentPolicy as BaseVectorDocumentPolicy;
use Eloquage\FilamentVectorSearch\Policies\VectorIndexPolicy as BaseVectorIndexPolicy;
use Illuminate\Contracts\Auth\Authenticatable;

class VectorIndexPolicy extends BaseVectorIndexPolicy
{
    protected function canManage(Authenticatable $user): bool
    {
        return $user->hasRole('admin');
    }
}

use Eloquage\LaravelVectorSearch\Models\VectorDocument;
use Eloquage\LaravelVectorSearch\Models\VectorIndex;

Gate::policy(VectorIndex::class, VectorIndexPolicy::class);
Gate::policy(VectorDocument::class, VectorDocumentPolicy::class);

Filament respects viewAny, view, create, update, and delete automatically.

The shared Index document table action already checks auth()->user()->can('update', $record) before showing for draft records.

See workbench/app/Policies/ for example policies used in package tests.

Extending resources

class AppVectorDocumentResource extends VectorDocumentResource
{
    public static function form(Schema $schema): Schema
    {
        return parent::form($schema);
    }
}

To auto-index on create, extend CreateVectorDocument and dispatch ProcessVectorDocument in afterCreate().

Custom playground

Extend SearchPlayground, override search() or swap the view, then embed your component in a custom dashboard page registered via ->dashboardPage().

Troubleshooting

See docs/troubleshooting.md for Filament 5 namespace pitfalls, Livewire wire:model issues, and large-document performance guidance.

Testing

composer test
composer analyse
composer format

Related packages

eloquage/laravel-vector-search — core (required)
eloquage/laravel-vector-search-ai — Laravel AI SDK + MCP (optional)

Changelog

See CHANGELOG.

License

MIT. See LICENSE.md.

eloquage / filament-vector-search

Package info

Security

Fund package maintenance!

Statistics