Performance Laravel Package

Getting Started

Install and let the service provider wire everything up:

composer require artisanpack-ui/performance
php artisan vendor:publish --tag=performance-config
php artisan migrate   # performance_metrics

Note that artisanpack-ui/ai: ^1.0 is now a hard dependency — installing or updating this package pulls the AI SDK in whether or not you intend to use the AI features. Configure your provider credentials (the claude-sonnet-4-6 default assumes an Anthropic key) in the artisanpack-ui/ai config before touching the panels, otherwise every AI call returns 412.

Two places to look first:

1. config/performance.php → the ai block (feature enable flags, model overrides) and the new ai_middleware key.
2. AuthServiceProvider → where you'll want to override the performance.ai.use Gate.

First use case: grab a slow query from your slow-query log (query text + EXPLAIN output + a short schema hint) and drop the Livewire panel onto an internal debug page:

<livewire:perf-ai-query-insight-panel
    :query="$sql"
    :explain="$explainJson"
    :schema="$createTableStatements"
    driver="mysql"
    :duration-ms="1840"
/>

That single component exercises the whole stack — agent registration, feature flag, gate, and response shaping — so it's the fastest way to validate credentials and config before wiring anything into a real workflow.

Implementation Patterns

Livewire-first for internal tooling. perf-ai-query-insight-panel and perf-ai-optimization-suggestion-panel are the lowest-effort integration: no JS build changes, no client wiring, just Blade. The optimization panel reads performance_metrics itself, so it works with zero props on a dashboard page. That's the right default for admin/staging surfaces.

React/Vue when you already own the frontend. Both components ship inside the performance package rather than in @artisanpack-ui/react / @artisanpack-ui/vue. Import them from the performance package's dist, not the shared UI kit — and don't expect them to appear in the shared kit's docs. Unlike the Livewire optimization panel, the React/Vue variants do not query the database; you pass a metrics batch in. That's a deliberate separation: server-side data, client-side rendering.

Vanilla JS / custom clients via PerformanceClient. The most flexible path, and the one to use when you want the AI call driven by something other than a component lifecycle:

import { PerformanceClient, PerformanceAiError } from '@artisanpack-ui/performance';

try {
    const { data, feature_key } = await client.suggestQueryInsight({ query, explain, schema, driver, duration_ms });
} catch (e) {
    if (e instanceof PerformanceAiError) {
        // e.status, e.featureKey — branch on these, not on message text
    }
}

Always branch on status / featureKey. 409 means the feature is disabled in config (a deploy/flag problem), 412 means credentials are missing (an ops problem), 403 means the gate denied (a policy problem). Those three deserve different UI states, and PerformanceAiError exists precisely so you don't regex the message.

Server-side dispatch via the API. POST /api/performance/ai/query-insight and .../optimization-suggestion return { data, feature_key }. Useful when you want the AI call to happen in a queued job or an artisan command rather than in a request from the browser — hit the endpoint with an authenticated token, or dispatch the agent through the artisanpack-ui/ai runner the same way AiAgentApiController does. The feature_key in the response is handy for logging/attribution across both entry points.

Gate overrides for quotas. The default performance.ai.use Gate is permissive — any authenticated user. In a multi-tenant app, override it in AuthServiceProvider (the package guards its own registration so yours wins) and enforce per-tenant rate limits or plan tiers there. Doing it at the Gate keeps the policy in one place instead of scattering checks across controllers and components.

Cost-aware workflows. Both agents are $cacheable = false by design (point-in-time diagnostics), so every invocation is a real model call. Patterns that hold up:

• Trigger query insight from a slow-query event or an explicit "Analyze" button, not on every page render.
• For optimization suggestions, run on a schedule (daily/weekly) and store the ranked output; render the stored result rather than re-asking.
• Pass only what the model needs: the query, a truncated EXPLAIN (drop the noise columns), and relevant CREATE TABLE statements — not your whole schema dump.

Gotchas and Tips

The hard dependency is the headline risk. Promoting artisanpack-ui/ai from optional to required means composer update on an existing install will now pull the AI SDK and its transitive deps. Run it in CI first; if you're on a locked-down network or have a conflicting SDK version, this is where it bites.

MAX_WINDOW_DAYS = 90 and MAX_METRICS_ROWS = 2000 are silent truncation. The Livewire optimization panel bounds its own query so it "works out of the box" — which means on a busy app you're feeding the model a sample, not the full window. The returned focus areas are only as good as the sample. If your metrics volume exceeds that, bypass the Livewire panel and pass an explicitly aggregated batch through the React/Vue component or the API, and say in your UI that it's sampled.

Non-cacheable + Livewire re-renders = surprise bills. Livewire will re-render on any public property change. If the panel is inside a form or a polling component, you'll re-invoke the agent repeatedly. Isolate it, use wire:ignore, or gate the call behind an explicit action.

ai_middleware is separate for a reason. The default ['api', 'auth:sanctum'] deliberately does not share the anonymous stack used by Web Vitals ingest. If your app authenticates via Passport, session, or a custom guard, override ai_middleware — otherwise you'll get 401s that look like credential failures but aren't. Related: 412 (missing AI credentials) and 401 (auth) are easy to conflate in logs.

422 is an agent validation error, not a request validation error. It means the model's structured output failed the agent's schema. Don't surface it as "check your input." Log the raw response and treat it as a model/config issue — usually resolved by a tighter prompt or a model swap.

404 unknown feature almost always means registration, not routing. Either the feature key is misspelled or the provider's aiFeatures() didn't run (cached config, provider not discovered). php artisan config:clear before debugging deeper.

Schema hints accept JSON or plain text. Plain CREATE TABLE output is usually cheaper and just as effective as JSON for the model; use it unless you need structured field metadata.

The agents never emit DDL — keep it that way. Both are advisory by contract. Resist the temptation to parse suggested indexes out of the response and auto-apply them; the value is the rationale, and a human should read it before anything touches your schema.

Extension points worth knowing: override the Livewire component aliases to swap in your own view, publish the React/Vue sources from the performance package if you need to restyle, and set per-feature model overrides in the AI config if claude-sonnet-4-6 is overkill for your volume (the optimization agent's ranked-output task tolerates a cheaper model better than the query diagnosis one).