Laravel Smartsearch Laravel Package

Getting Started

• Install/upgrade the package, then publish its config and migrations. For v1.2.0, review config/smartsearch.php for the new semantic-search and Ollama options rather than assuming previous defaults.
• Configure the search driver first: start with the existing keyword/database driver if you need a safe fallback, then enable the Ollama embedding driver for semantic search.
• Ensure Ollama is reachable from the Laravel app, the embedding model is pulled, and the host/model/timeouts are set per environment. Do not hard-code localhost for production.
• Run the package migrations and confirm the vector/embedding storage column or table is compatible with your database driver. If upgrading, check whether new migrations or config keys must be published.
• Add the package’s search trait/interface to one small model first, index a handful of records, and run both a keyword query and a semantic query. A good first use case is semantic search over an Article or Product model where exact keyword matching is too brittle.
• Look first at the package README, published config, indexing command/job, and the model trait/interface. Those define the day-to-day workflow: configure driver, index model, query, rebuild index.

Implementation Patterns

• Use model observers or events to enqueue indexing after create/update/delete. Avoid generating embeddings synchronously in web requests unless the dataset and Ollama latency are very small.
• Add a rebuild/reindex command or job to your deploy runbook. Treat embeddings as derived data: when the embedding model, chunking strategy, or indexed fields change, rebuild the index.
• Prefer a hybrid search pattern: run keyword search and semantic search, then merge/rank results. Fall back to keyword search when Ollama is unavailable, slow, or disabled.
• For multi-tenant apps, include tenant/team ID in indexed metadata and scope every search query by tenant. Use a unique index key such as model_type + model_id + tenant_id.
• Queue embedding jobs with retries and backoff. Batch small groups of records where possible, but keep batches small enough to avoid Ollama timeouts.
• Configure environments explicitly: local may use local Ollama; CI/testing should use fake/deterministic embeddings or the keyword driver; production should define fallback behavior.
• For tests, avoid calling a real Ollama instance. Use a fake embedding driver, fixture vectors, or assert that indexing jobs are dispatched rather than asserting exact semantic ranking.
• If exposing search in UI, separate “keyword” and “semantic” modes initially, then add hybrid ranking once relevance is understood.
• Use the package’s extension points for custom embedding providers or drivers if you need OpenAI/other providers later, but keep the same indexing/query contract.

Gotchas and Tips

• Ollama is an external service. Add health checks, timeouts, retries, and clear failure handling; otherwise search can fail or hang when the service is down.
• Changing the embedding model usually invalidates existing vectors. Confirm dimensions and model name match, then reindex everything. Mixed embedding models in one index will produce poor or broken results.
• Upgrading to v1.2.0 may introduce new config keys and driver compatibility expectations. Diff the published config and migrations instead of overwriting custom config blindly.
• Vector storage depends on database/driver support. Verify migrations and column types before deploying; test with your actual database, not only SQLite.
• Long text can exceed model limits. Chunk or truncate content deliberately, and keep chunk metadata so results can point back to the source model.
• Query embeddings can be cached for repeated searches, but be careful with cache keys: include model name, dimensions, and normalized query text.
• Semantic search is not a drop-in replacement for authorization. Always apply authorization/scoping before or alongside vector retrieval.
• Sending data to Ollama may have privacy/compliance implications. Prefer local/self-hosted Ollama where required, and document what content leaves the app.
• Tune similarity thresholds and result limits with real queries. Semantic search can return plausible-but-irrelevant results; monitor misses and add keyword fallback/hybrid ranking.
• Debug by checking: config driver, Ollama connectivity, model name, migration status, indexing job failures, whether records are actually indexed, and whether query and index embeddings use the same model.