Performance Laravel Package

Product Decisions This Supports

• Roadmap: ship “explain my slow query” and “where should we focus” as product features without building an LLM pipeline. The package now supplies the agents, prompts, feature registration, HTTP endpoints, authorization gate, error taxonomy, and UI panels. The PM decision is whether these two jobs-to-be-done belong in the product now, not whether to staff an AI platform team.
• Build vs. buy for performance advisory tooling. Buying/ adopting gives you EXPLAIN-plan interpretation, index and rewrite suggestions, and ranked optimization focus areas (impact/effort/rationale/actions, quick wins, caveats) behind a stable API contract. Building means owning model choice, prompt quality, schema redaction, retries, and the same three frontend surfaces.
• Feature gating and packaging decisions. performance.ai.use ships permissive (any authenticated user) but is overridable for stricter policies or per-tenant quotas. That makes it a viable paid-tier, seat-limited, or quota-metered feature — but only if you register your own gate; otherwise every authenticated user has access. The 409/412/422/404/403 status contract lets you render “disabled”, “misconfigured”, and “denied” states distinctly instead of a generic failure.
• Use cases this unlocks: an in-admin “why is this query slow?” panel for support/ops, a scheduled or on-demand performance review digest for engineering leads, and an onboarding aid for teams unfamiliar with a inherited schema. The suggestion-only, no-DDL behavior keeps humans in the loop — good for trust and auditability, and it means you are not shipping automated schema mutation.
• Cost and latency planning. Both agents set $cacheable = false (point-in-time diagnostics), so repeat views cost repeat model calls. The optimization agent short-circuits with no model call on empty metrics, and the Livewire panel bounds itself (MAX_WINDOW_DAYS = 90, MAX_METRICS_ROWS = 2000) — both keep worst-case spend predictable. Decide whether to add your own response caching or debounce before exposing to high-traffic users.
• Surface prioritization. All three of Livewire, React, and Vue ship in this package, so the same feature can be delivered on whichever stack the admin surface already uses without waiting on shared UI packages. The Livewire optimization panel reads performance_metrics directly and works out of the box; React/Vue accept a caller-supplied metrics batch, which is more work but keeps data-fetching in your app’s control.
• Security/compliance review trigger. Prompts include slow queries, EXPLAIN plans, and schema hints — potentially sensitive. The decision to ship externally depends on your data-handling posture and whether schema/query redaction is needed before those payloads leave your infrastructure.

When to Consider This Package

Adopt when:

• You already run this performance package (or are choosing it) and want AI-assisted query and optimization guidance as a first-class, supported feature rather than a side project.
• You can accept a hard dependency on artisanpack-ui/ai: ^1.0. This release promotes it from optional to required — the single biggest adoption gate. If you cannot or will not install that package, or you need to run fully offline/no-LLM, this release is not for you (and upgrading is effectively a breaking change to your dependency graph).
• You have a configured model provider and credentials for claude-sonnet-4-6 (or intend to override the default). Missing credentials surface as 412, so a misconfigured deploy degrades visibly rather than silently.
• Your consumers are authenticated. The AI routes default to ['api', 'auth:sanctum'] and are deliberately separate from the anonymous Web Vitals ingest stack — do not assume these endpoints can serve unauthenticated traffic.
• You want advisory-only output. If you need automated index creation or query rewriting applied to production, this is explicitly out of scope by design.
• You are on Livewire and want the fastest path (drop-in panel), or on React/Vue and are willing to supply the metrics batch yourself.

Look elsewhere or defer when:

• You need deterministic, auditable rules-based advice with no external model calls.
• You cannot send query text, EXPLAIN output, or schema to a third-party model provider.
• You need cost guarantees at high volume and are unwilling to add caching/debouncing around non-cacheable agents.
• You need per-tenant quotas out of the box — the shipped gate is permissive; enforcement is your code.
• You are mid-freeze and cannot absorb a new required dependency. Treat the ^1.0 promotion as a planned upgrade with dependency-review sign-off, not a patch bump.
• Multi-database or non-standard driver support matters and you cannot validate the connection driver input path yourself.

How to Pitch It (Stakeholders)

For executives: We can now offer AI-assisted performance guidance — “why is this query slow” and “what should we optimize next” — as a shipped capability instead of a research spike. It arrives with its own UI components for all three of our frontend stacks, a versioned API, and deliberate guardrails: it only suggests indexes and rewrites, never changes a database, and access is controlled by a gate we can tighten for paid tiers or per-tenant quotas. The main cost is a new required internal AI dependency and per-request model spend; the package already bounds the data windows and skips model calls when there is nothing to analyze, which keeps that spend predictable.

For engineering: Two new auto-registered agents (performance.query_insight, performance.optimization_suggestion) on claude-sonnet-4-6, both non-cacheable by design because output is a point-in-time snapshot. Trigger them via POST /api/performance/ai/query-insight and POST /api/performance/ai/optimization-suggestion, or the Livewire/React/Vue panels, or the new PerformanceClient methods. Responses are { data, feature_key }; use PerformanceAiError to branch on 409 disabled / 412 missing credentials / 422 validation / 404 unknown feature / 403 gate denial rather than string-matching. AI routes live on a dedicated ai_middleware stack (api, auth:sanctum) — keep them off the anonymous ingest path. Override the permissive performance.ai.use gate in your AuthServiceProvider (host registration wins) before exposing this beyond a pilot. Note the upgrade makes artisanpack-ui/ai a hard require and adds a JS build step for the React/Vue components — plan both into the release.