Filament Laravel Package

Technical Evaluation

Architecture fit. Vibefilter is a Filament table filter that scores rows against a natural-language statement using an LLM, caches those scores, and then filters on a score threshold. That is a good fit for admin and back-office surfaces already built on Filament (support queues, CRM lists, moderation queues, catalogue triage) where users currently express intent through stacked where-clauses. It is a poor fit for customer-facing high-QPS paths, for anything requiring deterministic/auditable filtering, or for tables where row content cannot leave the application boundary. The v0.3.0 additions tighten the architecture in three useful places: the threshold tuner makes the score semantics inspectable in-product, vibefilter:prune acknowledges that the cache is a durable, growing store rather than a request-scoped artifact, and the OpenRouter attribution config makes the outbound provider relationship explicit rather than implicit.

Integration feasibility. Low-to-moderate. Installation is Composer plus a Filament plugin registration, a published config, and now a migration. v0.3.0's migration (last_used_at) is additive and explicitly non-blocking for existing filtering behaviour — only vibefilter:prune depends on it — which is the right failure ordering. The two upgrade friction points are config drift (previously published configs do not receive the new attribution block, so attribution silently stays off) and the pruning semantics for pre-migration rows, where last_used_at will be NULL unless backfilled.

Technical risk.

• Data egress. Row content is sent to a model provider. This is the dominant risk and needs a DPIA-style review, column-level scoping, and a decision on which tables are eligible before any rollout.
• Cache growth and pruning safety. Scores are persisted per statement; pruning is the only lifecycle control. First-run pruning against rows with NULL last_used_at could remove statements users still rely on. --dry-run must be mandatory in the runbook.
• Score drift. Thresholds (0.6–0.9) are only meaningful relative to a specific model and prompt. A silent provider-side model update or a driver switch invalidates tuned thresholds and cached scores, with no versioning signal described.
• Pre-1.0 API instability. At v0.3.0 the public surface (config keys, artisan signatures, filter API) can still move. Pin the version.
• Attribution headers. HTTP-Referer and X-OpenRouter-Title are now sent by default; if left pointing at the package, usage and any embedded referer detail are credited externally. Trivial to fix, easy to forget.
• Opaque relevance. Users will read the threshold as a quality guarantee. It is a tunable cut-off, not a correctness metric.

Key questions.

1. Which Filament major versions are supported, and is that pinned in composer.json?
2. What exactly leaves the app per scored row — full record, selected columns, or a configured projection? Are there redaction hooks?
3. Are statements per-user, per-table, or global, and are they tenant-isolated?
4. What invalidates a cached score when the underlying row changes?
5. Does vibefilter:prune treat NULL last_used_at as "old"? Is there a backfill or a safeguard?
6. Which drivers exist beyond OpenRouter (OpenAI, Anthropic, self-hosted/embeddings), and is the interface driver-agnostic?
7. Are scores comparable across queries and models, or is the scale model-specific?
8. What is the degradation behaviour on provider timeout, rate limit, or 5xx — empty result set, unfiltered table, or error?
9. Licensing, support SLA, and release cadence for the 0.x line.
10. Expected token cost per row and per statement — is there instrumentation, or must we measure it ourselves?

Integration Approach

Stack fit. Native for Laravel + Filament shops; no separate infrastructure beyond a queue/HTTP client and the provider API key. The cache is a normal database table, so it inherits existing backup, retention, and access-control policy — a real advantage over an external vector store. Teams without Filament get little value; teams with it get a contained, single-table-scoped feature.

Migration path. Upgrade is two commands (vendor:publish --tag="vibefilter-migrations", migrate), and filtering continues to work if the migration is delayed, which makes this a safe, reversible-by-omission step. The one required manual action is merging the new attribution block into any previously published config; treat this as a tracked checklist item, not a note in release text. Before deploying, confirm whether existing cache rows need a last_used_at backfill so the first prune run is not destructive.

Compatibility. Additive schema change, no breaking API changes called out. Verify PHP/Laravel/Filament version constraints against our application matrix, and pin the package version in composer.json for the duration of the pilot. Config-file divergence is the main compatibility hazard across future releases; consider tracking the package config in version control with a diff review step on each upgrade.

Sequencing.

1. Compliance and data-egress review; define the eligible-table allowlist and column scope.
2. Staging spike against an anonymised subset of a real table; measure tokens, latency, and cache row growth per statement.
3. Publish config and migration; merge attribution; run vibefilter:prune --dry-run and inspect output before enabling the schedule.
4. Enable ->thresholdTuner() in staging only, use it to choose per-table default thresholds, then disable it for production surfaces.
5. Pilot on one internal Filament table with a small named user group; instrument cost per query and empty-result rate.
6. Set attribution to our own app name/referer (or disable deliberately), then roll out table by table.
7. Only after the pilot: schedule vibefilter:prune --days=90 daily and add alerting on cache table size.

Operational Impact

Maintenance. Modest but non-zero: a daily prune job, a pinned version with a review step per upgrade, config diffing on each release, and periodic re-tuning of thresholds whenever the model, driver, or prompt changes. The last_used_at column adds write traffic on every filter use — negligible at admin-scale, worth checking if statements are shared broadly.

Support. Expect two classes of tickets: "the AI filter returns nothing" (usually threshold too high, provider error, or unscored rows) and "the filter forgot my saved query" (pruning, or a statement that aged out). The threshold tuner is the primary deflection tool — it lets a support engineer or power user see row counts per threshold without a model call, which converts a vague complaint into a self-service fix. Publish an internal one-pager on what the threshold means and that it is not a relevance guarantee.

Scaling. Scales well on read (cached scores are a plain indexed query); scaling pressure is concentrated in (a) initial scoring of large tables, which is token-bound and should be queued/batched, (b) cache table growth proportional to statements × rows, and (c) provider rate limits under concurrent use. Budget the provider spend explicitly and attribute it to the feature owner. OpenRouter attribution headers are irrelevant to scaling but relevant to cost visibility — point them at our app so usage is traceable in provider dashboards.

Failure modes.

• Provider outage or rate limit → filter unusable or degraded; confirm the actual fallback and document it.
• Migration skipped → vibefilter:prune fails; harmless to filtering but silent if the schedule swallows output.
• First prune run without backfill → loss of active statements and their scores; mitigated only by --dry-run.
• Stale cache after row edits → wrong rows filtered in; no invalidation signal described.
• Model/prompt change → thresholds silently miscalibrated; requires re-tuning.
• Config not updated on upgrade → attribution headers stay defaulted to the package.
• Misread thresholds by users → perceived unreliability despite correct behaviour.
• PII in row payloads → compliance incident; the only real mitigation is pre-deployment scoping.

Ramp-up. A Laravel developer can complete the staging spike in one to three days. TPM-side effort is roughly a week of elapsed time: egress review, pilot scoping, cost/latency measurement, and a decision memo on eligible tables and default thresholds. Because the package is pre-1.0, position this as a bounded pilot on internal tooling with an explicit exit criterion (cost per query and empty-result rate within agreed bounds) before expanding to any user-facing or regulated data surface.