Brim Internals

Prerequisites

# PostgreSQL with pgvector extension
CREATE EXTENSION vector;

# Ollama (for local embeddings)
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text

Package Installation

composer require brimleylabs/brim

php artisan vendor:publish --provider="Brim\BrimServiceProvider"
php artisan migrate

Configuration (config/brim.php)

return [
    // Default embedding driver: 'ollama' or 'openai'
    'driver' => env('BRIM_DRIVER', 'ollama'),

    // Auto-generate embeddings on model save
    'auto_sync' => env('BRIM_AUTO_SYNC', true),

    // Queue embedding generation (recommended for production)
    'queue' => env('BRIM_QUEUE_EMBEDDINGS', false),

    'drivers' => [
        'ollama' => [
            'host' => env('BRIM_OLLAMA_HOST', 'http://localhost:11434'),
            'model' => env('BRIM_OLLAMA_MODEL', 'nomic-embed-text'),
        ],
        'openai' => [
            'api_key' => env('BRIM_OPENAI_KEY'),
            'model' => env('BRIM_OPENAI_MODEL', 'text-embedding-3-small'),
        ],
    ],

    'chunking' => [
        'enabled' => true,
        'max_tokens' => 8192,      // Model context window
        'chunk_size' => 1000,      // Tokens per chunk
        'chunk_overlap' => 200,   // Overlap between chunks
    ],
];

1. Prepare Your Model

<?php

namespace App\Models;

use Brim\Contracts\Embeddable;
use Brim\Traits\HasEmbeddings;
use Illuminate\Database\Eloquent\Model;

class Article extends Model implements Embeddable
{
    use HasEmbeddings;

    /**
     * Define the text content for embedding generation.
     * This is the ONLY required method to implement.
     */
    public function toEmbeddableText(): string
    {
        return <<title}

        {$this->content}

        Tags: {$this->tags->pluck('name')->implode(', ')}
        TEXT;
    }

    /**
     * Optional: Namespace embeddings for multi-tenant apps
     */
    public function getEmbeddingNamespace(): ?string
    {
        return "tenant:{$this->tenant_id}";
    }
}

2. Automatic Embedding Generation

// With auto_sync enabled, embeddings generate on save
$article = Article::create([
    'title' => 'Understanding Vector Databases',
    'content' => 'Vector databases store high-dimensional...',
]);
// Embedding automatically generated!

// Check if embedding exists
$article->hasEmbedding();  // true

// Manual generation (if auto_sync disabled)
$article->generateEmbedding();

// Delete embedding
$article->deleteEmbedding();

3. Semantic Search

// Basic semantic search
$results = Article::semanticSearch('machine learning tutorials')->get();

// With limit
$results = Article::semanticSearch('database optimization')
    ->take(5)
    ->get();

// Access similarity scores
foreach ($results as $article) {
    echo "{$article->title}: {$article->similarity_score}";
}

// Combine with Eloquent scopes
$results = Article::semanticSearch('API design patterns')
    ->where('published', true)
    ->where('created_at', '>', now()->subMonth())
    ->with(['author', 'tags'])
    ->get();

4. Find Similar Models

// Find articles similar to a specific article
$article = Article::find(1);
$similar = $article->findSimilar(5);

foreach ($similar as $related) {
    echo "{$related->title} - {$related->similarity}% match";
}

// "Related Articles" widget
public function show(Article $article)
{
    return view('articles.show', [
        'article' => $article,
        'related' => $article->findSimilar(3),
    ]);
}

Queued Embedding Generation

For production workloads, queue embedding generation to avoid blocking requests.

// config/brim.php
'queue' => true,

// The GenerateEmbedding job handles retries and batching
// Jobs are dispatched automatically on model save

// Manual queue dispatch
use Brim\Jobs\GenerateEmbedding;

GenerateEmbedding::dispatch($article)
    ->onQueue('embeddings')
    ->delay(now()->addSeconds(10));

Multi-Tenant Namespacing

Isolate embeddings per tenant without separate tables.

class Document extends Model implements Embeddable
{
    use HasEmbeddings;

    public function getEmbeddingNamespace(): ?string
    {
        return "org:{$this->organization_id}";
    }

    public function toEmbeddableText(): string
    {
        return $this->content;
    }
}

// Search within a specific namespace
$results = Document::inNamespace("org:{$orgId}")
    ->semanticSearch($query)
    ->get();

Hybrid Search (Semantic + Filters)

Combine vector similarity with traditional SQL filtering.

class ProductController
{
    public function search(Request $request)
    {
        $query = Product::semanticSearch($request->q);

        // Apply traditional filters
        if ($request->category) {
            $query->where('category_id', $request->category);
        }

        if ($request->min_price) {
            $query->where('price', '>=', $request->min_price);
        }

        if ($request->in_stock) {
            $query->where('stock', '>', 0);
        }

        return $query
            ->with(['category', 'images'])
            ->paginate(20);
    }
}

Batch Operations

use Brim\Facades\Brim;

// Batch generate embeddings for existing records
Article::whereDoesntHave('embeddings')
    ->chunk(100, function ($articles) {
        foreach ($articles as $article) {
            $article->generateEmbedding();
        }
    });

// Using the Artisan command
// php artisan brim:embed App\\Models\\Article --batch=50

// Prune orphaned embeddings (models deleted but embeddings remain)
Brim::store()->deleteOrphaned();

Custom Embedding Logic

class Recipe extends Model implements Embeddable
{
    use HasEmbeddings;

    /**
     * Rich embeddable content from multiple sources
     */
    public function toEmbeddableText(): string
    {
        $ingredients = $this->ingredients
            ->pluck('name')
            ->implode(', ');

        $techniques = $this->steps
            ->pluck('technique')
            ->unique()
            ->implode(', ');

        return <<title}
        Cuisine: {$this->cuisine->name}
        Difficulty: {$this->difficulty}
        Cooking Time: {$this->cook_time} minutes

        Description: {$this->description}

        Ingredients: {$ingredients}

        Techniques used: {$techniques}

        Dietary: {$this->dietary_tags}
        TEXT;
    }

    /**
     * Disable auto-sync for bulk imports
     */
    public bool $brimAutoSync = false;
}

Optimization Tips

// 1. Use queues for embedding generation in production
'queue' => true,

// 2. Tune HNSW index parameters for your dataset size
-- For datasets > 100K, adjust m and ef_construction
CREATE INDEX ON brim_embeddings
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

// 3. Use connection pooling (PgBouncer) for high concurrency

// 4. Consider dedicated database connection for embeddings
'vector_store' => [
    'connection' => 'pgsql_vectors',  // Separate connection
],

// 5. Cache frequent searches
$results = Cache::remember(
    "search:{$query}",
    3600,
    fn() => Article::semanticSearch($query)->take(10)->get()
);