Evals Ui Laravel Package

Getting Started

• Install with Composer (composer require vizra-ai/vizra-evals-ui), then follow the README's publish/migrate steps — for a package of this shape expect a config publish, an asset publish, and (if runs are persisted locally) a migration. Verify the exact vendor/package name and publish tags against the README rather than guessing, since this is still a 0.x package.
• Look first at: the README (install + dashboard route), config/ after publishing (route prefix, middleware, storage driver), and the service provider to see what gets registered. The CHANGELOG is short and worth skimming before every bump.
• First use case: boot the dashboard locally, land on the empty state, and use it as the target for your first suite — write a handful of evaluations, run them, and confirm results appear. That round trip is the whole point of the package: turning ad-hoc eval scripts into something you can eyeball and compare.
• New in 0.3.2: the empty dashboard state now carries a single quiet line pointing at vizra.ai/services, and the README footer links there too. It is chrome-level only — no layout shift, no modal, no tracked CTA — and it disappears the moment you have evaluations.

Implementation Patterns

• Dashboard as a read layer, not a runner. Keep evaluation execution in your test suite or CI (Pest/PHPUnit, a console command, or a queued job) and let this package render and compare the results. That separation keeps runs reproducible and the UI disposable.
• CI-first workflow. Run evals on every PR, persist the run, and use the dashboard to diff a regression against the previous green run. This is where day-to-day value actually shows up — catching a prompt or model change that quietly degrades output.
• Local dev loop. Point the dashboard at your dev database, iterate on a suite, and use the empty-state → populated transition as your smoke test that wiring (config, storage, route) is correct.
• Environment gating. Register the dashboard behind auth plus an allowlist or gate in non-local environments; evaluation output frequently contains raw prompts and model responses you don't want public.
• Team visibility. Because it's a UI package rather than a CLI, the natural pattern is to let non-authors (PM, QA) read results without running anything — keep the route on a shared staging host rather than每个人的 laptop.
• Upgrade ritual. With 0.x versioning, pin the minor and re-publish views/assets after each bump so customizations and upstream template changes don't silently diverge.

Gotchas and Tips

• 0.x means minor bumps can break. Treat 0.3.x → 0.4 as potentially breaking and read the CHANGELOG before upgrading; don't rely on semver guarantees that don't exist yet.
• Protect the routes before you demo them. The most common first mistake with dashboard packages is shipping an unguarded route that exposes prompt/response data. Configure middleware at publish time, not after.
• The 0.3.2 upsell is deliberately unobtrusive — note it, don't fight it. The line appears only in the empty state and is styled to match the surrounding chrome (explicitly "nothing solid violet"). No config flag is documented to disable it; if you need it gone, publish and override the relevant view. The README footer link is plain markdown and harmless.
• Watch the trend, not the single instance. One quiet empty-state link is fine; the thing to track across releases is whether vendor promotion starts appearing in populated states or in the run-comparison view, where it would intrude on actual work.
• Empty state is your canary. If you're debugging "the dashboard is blank," first confirm it's a genuine no-data condition and not a failed migration or misconfigured storage — the new services line gives you a quick visual tell that you're on the true empty state and not an error path.
• Debug order when results don't show: published config → php artisan route:list for the registered prefix → storage/migration state → application log. The package is thin enough that most issues are wiring, not internals.
• Views are the extension point. For branding, custom columns, or removing the promo line, publish the views and override rather than patching vendor files — that keeps upgrades survivable.