PHPackages benbjurstrom/pgvector-scout - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. benbjurstrom/pgvector-scout ActiveLibrary[API Development](/categories/api) benbjurstrom/pgvector-scout =========================== Pgvector driver for Laravel Scout v0.3.3(8mo ago)738.5kβ€”9.7%8[2 issues](https://github.com/benbjurstrom/pgvector-scout/issues)MITPHPPHP ^8.2CI failing Since Nov 16Pushed 8mo ago1 watchersCompare [ Source](https://github.com/benbjurstrom/pgvector-scout)[ Packagist](https://packagist.org/packages/benbjurstrom/pgvector-scout)[ Docs](https://github.com/benbjurstrom/pgvector-scout)[ GitHub Sponsors]()[ RSS](/packages/benbjurstrom-pgvector-scout/feed)WikiDiscussions main Synced yesterday READMEChangelog (9)Dependencies (14)Versions (14)Used By (0) [![Logo](https://private-user-images.githubusercontent.com/12499093/386860511-9c55eb67-f44f-442d-86b9-e0969213862c.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODI2ODc0MzgsIm5iZiI6MTc4MjY4NzEzOCwicGF0aCI6Ii8xMjQ5OTA5My8zODY4NjA1MTEtOWM1NWViNjctZjQ0Zi00NDJkLTg2YjktZTA5NjkyMTM4NjJjLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA2MjglMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNjI4VDIyNTIxOFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTBkMzA1MGRlZDg2YTBhNGRhNjYxYTY4NTgxOWYyYmI4Nzk0ZDQ1ZDdjZGQwM2RmMDlmMzYwZmIxNWFhNjNkZTAmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRnBuZyJ9._5mUNHAgFf7SqZ-9KCgNpABYA4s0wcmugKcDQw5AX4I)](https://private-user-images.githubusercontent.com/12499093/386860511-9c55eb67-f44f-442d-86b9-e0969213862c.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODI2ODc0MzgsIm5iZiI6MTc4MjY4NzEzOCwicGF0aCI6Ii8xMjQ5OTA5My8zODY4NjA1MTEtOWM1NWViNjctZjQ0Zi00NDJkLTg2YjktZTA5NjkyMTM4NjJjLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA2MjglMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNjI4VDIyNTIxOFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTBkMzA1MGRlZDg2YTBhNGRhNjYxYTY4NTgxOWYyYmI4Nzk0ZDQ1ZDdjZGQwM2RmMDlmMzYwZmIxNWFhNjNkZTAmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRnBuZyJ9._5mUNHAgFf7SqZ-9KCgNpABYA4s0wcmugKcDQw5AX4I) [![Latest Version on Packagist](https://camo.githubusercontent.com/dd3fb9ee7a523611d53da789ebe98668e021984349f83fd7cbd96307478493e0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f62656e626a75727374726f6d2f7067766563746f722d73636f75742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/benbjurstrom/pgvector-scout)[![GitHub Tests Action Status](https://camo.githubusercontent.com/a35f503829fe6ebe6e6f74f507aada741d62078a4047afa9e3ab8dae953bdbca/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f62656e626a75727374726f6d2f7067766563746f722d73636f75742f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/benbjurstrom/pgvector-scout/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/ff197ec8900f8832588a0427cdbc425d83c36ab7124894b8d43fc816ae26c86e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f62656e626a75727374726f6d2f7067766563746f722d73636f75742f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/benbjurstrom/pgvector-scout/actions?query=workflow%3A) Pgvector driver for Laravel Scout ================================= [](#pgvector-driver-for-laravel-scout) Use the pgvector extension with Laravel Scout for vector similarity search. To see a full example showing how to use this package check out [benbjurstrom/pgvector-scout-demo](https://github.com/benbjurstrom/pgvector-scout-demo). πŸš€ Quick Start ------------- [](#-quick-start) #### 1. Install the package using composer: [](#1-install-the-package-using-composer) ``` composer require benbjurstrom/pgvector-scout ``` #### 2. Publish the scout config and the package config: [](#2-publish-the-scout-config-and-the-package-config) ``` php artisan vendor:publish --tag="scout-config" php artisan vendor:publish --tag="pgvector-scout-config" ``` This is the contents of the published `pgvector-scout.php` config file. By default it contains 3 different indexes, one for OpenAI, one for Google Gemini, and one for testing. The rest of this guide will use the OpenAI index as an example. ``` return [ /* |-------------------------------------------------------------------------- | Embedding Index Configurations |-------------------------------------------------------------------------- | | Here you can define the configuration for different embedding indexes. | Each index can have its own specific configuration options. | */ 'indexes' => [ 'openai' => [ 'handler' => Handlers\OpenAiHandler::class, 'model' => 'text-embedding-3-small', 'dimensions' => 256, // See Reducing embedding dimensions https://platform.openai.com/docs/guides/embeddings#use-cases 'url' => 'https://api.openai.com/v1', 'api_key' => env('OPENAI_API_KEY'), 'table' => 'openai_embeddings', ], 'gemini' => [ 'handler' => Handlers\GeminiHandler::class, 'model' => 'text-embedding-004', 'dimensions' => 256, 'url' => 'https://generativelanguage.googleapis.com/v1beta', 'api_key' => env('GEMINI_API_KEY'), 'table' => 'gemini_embeddings', 'task' => 'SEMANTIC_SIMILARITY', // https://ai.google.dev/api/embeddings#tasktype ], 'ollama' => [ 'handler' => Handlers\OllamaHandler::class, 'model' => 'nomic-embed-text', 'dimensions' => 768, 'url' => 'http://localhost:11434/api/embeddings', 'api_key' => 'none', 'table' => 'ollama_embeddings', ], 'fake' => [ // Used for testing 'handler' => Handlers\FakeHandler::class, 'model' => 'fake', 'dimensions' => 3, 'url' => 'https://example.com', 'api_key' => '123', 'table' => 'fake_embeddings', ], ], ]; ``` #### 3. Set the scout driver to pgvector in your .env file and add your OpenAI API key: [](#3-set-the-scout-driver-to-pgvector-in-your-env-file-and-add-your-openai-api-key) ``` SCOUT_DRIVER=pgvector OPENAI_API_KEY=your-api-key ``` #### 4. Run the scout index command to create a migration file for your embeddings: [](#4-run-the-scout-index-command-to-create-a-migration-file-for-your-embeddings) ``` php artisan scout:index openai php artisan migrate ``` #### 5. Update the model you wish to make searchable: [](#5-update-the-model-you-wish-to-make-searchable) Add the `HasEmbeddings` and `Searchable` traits to your model. Additionally add a `searchableAs()` method that returns the name of your index. Finally implement `toSearchableArray()` with the content from the model you want converted into an embedding. ``` use BenBjurstrom\PgvectorScout\Models\Concerns\HasEmbeddings; use Laravel\Scout\Searchable; class YourModel extends Model { use HasEmbeddings, Searchable; /** * Get the name of the index associated with the model. */ public function searchableAs(): string { return 'openai'; } /** * Get the indexable content for the model. */ public function toSearchableArray(): array { return [ 'title' => $this->title, 'content' => $this->content, ]; } } ``` πŸ” Usage ------- [](#-usage) ### Create embeddings for your models: [](#create-embeddings-for-your-models) Laravel Scout uses eloquent model observers to automatically keep your search index in sync anytime your Searchable models change. This package uses this functionality automatically generate embeddings for your models when they are saved or updated; or remove them when your models are deleted. If you want to manually generate embeddings for existing models you can use the artisan command below. See the [Scout documentation](https://laravel.com/docs/8.x/scout) for more information. ``` artisan scout:import "App\Models\YourModel" ``` ### Listen for embedding events: [](#listen-for-embedding-events) The package dispatches an `EmbeddingSaved` event whenever an embedding is created or updated. You can listen for this event to monitor embedding operations: ``` use BenBjurstrom\PgvectorScout\Events\EmbeddingSaved; class LogEmbeddingSaved { public function handle(EmbeddingSaved $event): void { $action = $event->wasRecentlyCreated ? 'created' : 'updated'; Log::info("Embedding {$action}", [ 'model' => $event->modelName, 'id' => $event->modelId, 'handler' => $event->handler, ]); } } ``` Register the listener in your `EventServiceProvider`: ``` use BenBjurstrom\PgvectorScout\Events\EmbeddingSaved; protected $listen = [ EmbeddingSaved::class => [ LogEmbeddingSaved::class, ], ]; ``` ### Search using vector similarity: [](#search-using-vector-similarity) You can use the typical Scout syntax to search your models. For example: ``` $results = YourModel::search('your search query')->get(); ``` Note that the text of your query will be converted into a vector embedding using the model index's configured handler. It's important that the same model is used for both indexing and searching. ### Search using existing vectors: [](#search-using-existing-vectors) You can also pass an existing embedding vector as a search parameter. This can be useful to find related models. For example: ``` $vector = $someModel->embedding->vector; $results = YourModel::search($vector)->get(); ``` ### Evaluate search results: [](#evaluate-search-results) All search queries will be ordered by similarity to the given input and include the embedding relationship. The value of the nearest neighbor search can be accessed as follows: ``` $results = YourModel::search('your search query')->get(); $results->first()->embedding->neighbor_distance; // 0.26834 (example value) ``` The larger the distance the less similar the result is to the input. ### Advanced filtering with whereSearchable: [](#advanced-filtering-with-wheresearchable) You can use the `whereSearchable()` macro to apply Eloquent query constraints before the vector similarity search. This improves efficiency by filtering the dataset before computing expensive vector distances. ``` use App\Models\DocumentChunk; $results = DocumentChunk::search('payment terms') ->whereSearchable(fn ($query) => $query->whereHas('document', fn ($doc) => $doc->where('client_id', $clientId) ->where('type', 'contract') ) ) ->get(); ``` πŸ› Using custom handlers ---------------------- [](#using-custom-handlers) By default this package uses OpenAI to generate embeddings. To do this it uses the [OpenAiHandler](https://github.com/benbjurstrom/pgvector-scout/blob/main/src/Handlers/OpenAiHandler.php) class paired with the openai index found in the packages [config file](https://github.com/benbjurstrom/pgvector-scout/blob/main/config/pgvector-scout.php). You can generate embeddings from other providers by adding a custom Handler. A handler is a simple class defined in the [HandlerContract](https://github.com/benbjurstrom/pgvector-scout/blob/main/src/HandlerContract.php) that takes a string, a config object, and returns a `Pgvector\Laravel\Vector` object. Whatever api calls or logic is needed to turn a string into a vector should be defined in the `handle` method of your custom handler. If you need to pass api keys, embedding dimensions, or any other configuration to your handler you can define them in the `config/pgvector-scout.php` file. Installing pgvector when using DBngin ------------------------------------- [](#installing-pgvector-when-using-dbngin) If you're using [DBngin](https://dbngin.com/) for local development you can install the pgvector extention by doing the following: 1. Add PostgreSQL to your path: ``` export PATH=/Users/Shared/DBngin/postgresql/14.3/bin:$PATH ``` 2. Then install pgvector: ``` git clone https://github.com/pgvector/pgvector.git cd pgvector make && make install ``` πŸ‘ Credits --------- [](#-credits) - [Ben Bjurstrom](https://github.com/benbjurstrom) - [All Contributors](../../contributors) πŸ“ License --------- [](#-license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 44 β€” FairBetter than 90% of packages Maintenance60 Regular maintenance activity Popularity39 Limited adoption so far Community14 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 85.7% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~43 days Recently: every ~53 days Total 9 Last Release 246d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/5c6e87e7d26b161a120d9f149fabc989bf2d5bcccee4e9972867b477d336b92b?d=identicon)[benbjurstrom](/maintainers/benbjurstrom) --- Top Contributors [![benbjurstrom](https://avatars.githubusercontent.com/u/12499093?v=4)](https://github.com/benbjurstrom "benbjurstrom (12 commits)")[![roymckenzie](https://avatars.githubusercontent.com/u/1065321?v=4)](https://github.com/roymckenzie "roymckenzie (1 commits)")[![yk-sgr](https://avatars.githubusercontent.com/u/24418343?v=4)](https://github.com/yk-sgr "yk-sgr (1 commits)") --- Tags laravelBen Bjurstrompgvector-scout ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/benbjurstrom-pgvector-scout/health.svg) ``` [![Health](https://phpackages.com/badges/benbjurstrom-pgvector-scout/health.svg)](https://phpackages.com/packages/benbjurstrom-pgvector-scout) ``` ### Alternatives [dedoc/scramble Automatic generation of API documentation for Laravel applications. 2.1k11.2M100](/packages/dedoc-scramble)[spatie/laravel-pdf Create PDFs in Laravel apps 1.0k4.8M47](/packages/spatie-laravel-pdf)[defstudio/telegraph A laravel facade to interact with Telegram Bots 816333.3k3](/packages/defstudio-telegraph)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3914.6k](/packages/rawilk-profile-filament-plugin)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5021.9k](/packages/simplestats-io-laravel-client)[lettermint/lettermint-laravel Official Lettermint driver for Laravel 1190.2k1](/packages/lettermint-lettermint-laravel) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)