RFC: AI-powered features across ArtisanPack UI — artisanpack-ui/ai foundation and package-by-package roadmap

[ViewFromTheBox]

Context

With most of the heavy lifting now behind us across the ecosystem, I want to start a serious conversation about how we bring AI capabilities into ArtisanPack UI in a way that's coherent, opt-in, and respects developer autonomy.

This isn't about bolting on AI features for the sake of it. It's about identifying the places where AI genuinely accelerates what our packages already do well — and building a shared foundation so every package can offer those capabilities without each one reinventing the wheel.

I'm opening this as a discussion rather than an issue because I want input on the architecture, the scope, and the prioritization before we start implementing.

Strategic framing

A few principles I want us to anchor on before getting into specifics:

1. AI features are always optional. No package gains a hard dependency on AI. Every AI capability degrades gracefully if AI isn't configured.
2. Bring Your Own Key (BYOK) is the model. Developers and CMS end-users supply their own API credentials. We don't host AI, we don't markup tokens, we don't lock anyone into a provider.
3. Provider-agnostic by default. OpenAI, Anthropic, Gemini, Groq, Ollama (local), and others should all work through the same configuration surface.
4. The Laravel AI SDK is the foundation. It's first-party, supports 14 providers including Ollama, ships with a solid Agent abstraction, structured outputs, streaming, and queue integration. We don't need to invent any of that.
5. Privacy-conscious by design. Some users will never enable AI features. Some will only enable specific ones. Some will require local models. All of these have to be first-class scenarios.

Proposed architecture: artisanpack-ui/ai

I'm proposing we add a new foundational package, artisanpack-ui/ai, that sits alongside core and hooks as a shared layer. Other packages depend on it optionally and check for its presence at boot.

What this package owns:

• Credential resolution. Reads AI configuration from env vars (developer use case) OR from the cms-framework Settings module (CMS end-user use case), with the latter taking precedence when both are present.
• Base Agent class. A thin wrapper around Laravel\Ai\Agent that adds usage logging, caching hooks, and the feature-toggle check. Every AI feature in every package extends this.
• Feature registry. Central catalog of all AI capabilities across the ecosystem. Packages auto-register their features at boot, and the registry is what powers admin UI discovery, per-feature toggles, and usage reporting.
• Admin UI components. Livewire components for the CMS — AI settings page, usage dashboard, per-feature on/off switches. These integrate into the existing cms-framework admin surface.
• Cost/usage tracking. Hooks into Laravel AI's events to capture token counts and estimated costs, grouped by feature.

What it deliberately does NOT own:

• Provider abstraction (laravel/ai handles this)
• Failover, retries, streaming (laravel/ai handles this)
• Conversation persistence, vector stores, embeddings (laravel/ai handles this)
• Spending caps, custom prompt overrides, or anything beyond MVP (deferred until we see real demand)

The package should end up being relatively small — probably 1500–2500 lines. Most of the value is in the integration pattern, not in the code volume.

The Agent pattern

Every AI capability in every package ships as a concrete Agent class extending our base. Here's roughly what it looks like:

<?php

namespace ArtisanPackUI\Seo\Agents;

use ArtisanPackUI\Ai\Agents\ArtisanPackAgent;
use Laravel\Ai\Attributes\Provider;

class MetaDescriptionAgent extends ArtisanPackAgent
{
    public string $featureKey = 'seo.suggest_meta_description';

    public string $package = 'artisanpack-ui/seo';

    public string $defaultModel = 'haiku'; // small/cheap by default

    public function instructions(): string
    {
        return <<<EOT
        You are an SEO specialist. Given page content, generate a meta
        description that is 150-160 characters, naturally includes the
        primary keyword, and entices clicks without being clickbait.
        EOT;
    }

    public function outputSchema(): array
    {
        return [
            'meta_description' => 'string|max:160',
            'character_count'  => 'int',
            'rationale'        => 'string',
        ];
    }
}

Then in user code:

$suggestion = MetaDescriptionAgent::for($post->content)->run();

Why this pattern works for us:

• Each feature is independently testable using Laravel AI's testing layer
• Power users can override any agent in their app by extending and rebinding it in the container
• Structured output handles the JSON parsing — no fragile regex on LLM responses
• The feature registry auto-discovers agents for the admin UI without us maintaining a separate list
• Per-feature model overrides are trivial because each agent declares its preference

BYOK configuration — two modes

Mode 1: Static (env-based) for developers building custom Laravel apps

ARTISANPACK_AI_PROVIDER=anthropic
ARTISANPACK_AI_API_KEY=sk-ant-...
ARTISANPACK_AI_DEFAULT_MODEL=claude-haiku-4-5

# Optional per-feature overrides
ARTISANPACK_AI_SEO_MODEL=claude-haiku-4-5
ARTISANPACK_AI_ANALYTICS_MODEL=claude-opus-4-7

Mode 2: Dynamic (database-based) for CMS end-users

When cms-framework is installed, we expose an "AI Settings" admin page:

• Provider dropdown (populated from laravel/ai's enabled providers, including Ollama for local)
• API key field (encrypted at rest via Laravel's Crypt, never displayed back as plaintext)
• Default model selector
• "Test connection" button
• Per-feature toggles (auto-populated from the feature registry)
• Usage tab showing token counts and estimated costs

Resolution priority: explicit runtime override → database settings → env vars → null (feature disabled).

Per-package AI opportunities

Below is a first pass at what each candidate package gets. This is meant to start the conversation — I expect we'll add and cut features here.

🟢 SEO

The clearest AI fit in the ecosystem. Agents I'd propose:

• MetaTitleSuggestionAgent — generates SEO-optimized title variants for a given page
• MetaDescriptionAgent — example above
• ContentAnalysisAgent — analyzes content for keyword density, readability, semantic completeness, and returns a structured quality score with specific recommendations
• SchemaGenerationAgent — given page content, suggests appropriate JSON-LD schema type and generates a starting structure
• HreflangSuggestionAgent — for multi-language sites, suggests where hreflang relationships are missing or inconsistent

The existing content analysis scoring in the SEO package becomes vastly more useful when paired with AI that can suggest how to fix issues, not just flag them.

🟢 Analytics

The dashboard package gets a lot more interesting with AI summarization:

• InsightSummaryAgent — given a date range of analytics data, generates a plain-language summary of what's working, what's changed, and what's worth investigating
• AnomalyExplanationAgent — when traffic spikes or drops, generates a hypothesis about what might have caused it (correlation with content changes, referrer changes, etc.)
• SegmentInsightAgent — analyzes a specific segment (referrer, page, time period) and surfaces non-obvious patterns
• Weekly/monthly digest emails — agent-generated narrative reports the CMS user can opt into

This is where I think AI delivers the most "I didn't know I needed this" value for non-technical CMS users.

🟢 Visual Editor

Since this is greenfield, we have the opportunity to design AI in from the start rather than retrofitting:

• ContentBlockSuggestionAgent — "What block should come next?" based on what's been written so far
• LayoutSuggestionAgent — given a section's content, suggests appropriate layout patterns from the section library
• AltTextGenerationAgent — when an image is dropped into the editor, auto-suggests alt text (also useful for the Media Library, see below)
• ContentRewriteAgent — "make this shorter," "make this more formal," "rewrite for a 6th-grade reading level" — inline editor commands
• HeadingHierarchyAgent — checks heading structure and suggests fixes (also feeds into Accessibility)

Important constraint: AI suggestions in the visual editor should always be suggestions, never automatic mutations. The user accepts or rejects.

🟢 CMS Framework

The framework itself gains content authoring helpers that downstream packages can opt into:

• PostTitleSuggestionAgent — generate title variants from draft content
• ExcerptGenerationAgent — generate excerpts from full content
• TagSuggestionAgent — suggest tags from existing taxonomy based on content
• CategorySuggestionAgent — same for categories
• SlugSuggestionAgent — generate SEO-friendly slugs from titles

These also become useful API surface for artisanpack-ui/visual-editor and any other content-creating package.

🟢 Forms

A few high-value features here:

• SpamDetectionAgent — analyzes form submissions and flags likely spam without relying solely on honeypots or rate limiting
• SubmissionSummaryAgent — for high-volume forms, generates a periodic summary of what people are submitting and any trends
• ResponseClassificationAgent — auto-categorizes incoming submissions (e.g., "support request," "sales inquiry," "feedback")
• SmartFieldValidationAgent — opt-in semantic validation ("does this address look real?") beyond regex

🟢 Media Library

• AltTextGenerationAgent — generates accessibility-friendly alt text from uploaded images (huge accessibility + SEO win)
• ImageTagSuggestionAgent — suggests tags for uploaded media for organization
• ImageDescriptionAgent — longer-form descriptions for image-heavy sites (galleries, portfolios)

🟢 Accessibility

• ContentAccessibilityAgent — analyzes content for accessibility issues beyond what static rules catch (ambiguous link text, vague headings, etc.)
• AriaSuggestionAgent — suggests appropriate ARIA attributes for custom components
• ColorContrastExplanationAgent — explains why contrast fails and suggests specific fixes

🟢 Security Analytics

• ThreatTriageAgent — given a security event, generates a plain-language explanation of severity and recommended action
• AnomalySummaryAgent — periodic digest of unusual security events
• IncidentResponseAgent — assists with response workflows by suggesting next steps based on event context

🟡 Compliance / Privacy

These need more thought because of the regulatory implications, but candidates:

• PrivacyPolicyDraftAgent — generates starter privacy policy text based on declared data processing activities (always with strong "have a lawyer review" disclaimers)
• DPIAAssistanceAgent — assists with Data Protection Impact Assessment drafting
• ConsentTextSuggestionAgent — suggests clear, plain-language consent text

These are powerful but high-stakes. I'd want explicit human-review checkpoints baked into the UX.

🟡 Performance (in progress)

Once the package matures:

• PerformanceInsightAgent — explains why a query is slow and suggests optimizations
• OptimizationSuggestionAgent — looks at performance metrics and suggests where to focus

Packages that probably DON'T need AI

To keep scope clear, I don't see AI value (right now) in:

• Core, Hooks, Icons — utility/foundational, no content surface
• Code Style, Code Style Pint — deterministic by design
• RBAC, Secure Uploads, Security Auth/Advanced Auth, Security Full — security-critical, deterministic
• Livewire UI Components, React, Vue, Drag and Drop — pure UI libraries
• Starter Kits — scaffolding, not feature surface

Always open to being convinced otherwise.

Open questions for the community

1. Naming. Is artisanpack-ui/ai the right name? Alternatives: intelligence, assist, ai-kit. I lean toward ai for clarity.

2. Agent override pattern. What's the cleanest way for users to override agent prompts and behavior? Service container binding feels right, but should we also support a config-based override path for non-developer CMS users?

3. Streaming UX. For long outputs (content analysis, summaries), should we stream by default in the admin UI, or wait for completion? Streaming is better UX but adds complexity.

4. Caching strategy. SEO suggestions for the same content shouldn't hit the API twice. What's the right cache invalidation — content hash? Time-based? Both?

5. Cost guardrails in v1. I'm leaning toward NOT shipping spending caps in v1.0 to keep scope tight. Counter-arguments?

6. Ollama prioritization. Since laravel/ai ships Ollama support first-party, do we test against local models from launch and advertise local support, or treat it as a v1.1 polish?

7. Per-package vs cross-package agents. Some agents (alt text, content rewrite) could live in ai itself rather than in individual packages, then be consumed everywhere. Where do we draw the line?

8. Backward compatibility. This is the package that touches every other package. I want the v1.0 contract (Agent base class signature, feature registry, credential resolution) frozen hard. What am I likely to want to change in 6 months that I should design for now?

Rough sequencing

If we get alignment on the approach, here's how I'd sequence the work:

1. artisanpack-ui/ai foundation (1–2 weeks) — package skeleton, credential resolution, base Agent class, feature registry, basic admin Livewire components. No package integration yet.

2. SEO end-to-end (1 week) — wire 2–3 agents into the SEO package as the validation case. Highest-value, lowest-risk.

3. Analytics agents (3–4 days) — insight summaries, anomaly explanations.

4. CMS Framework content agents (1 week) — title, excerpt, tag, slug suggestions usable from anywhere.

5. Media Library alt text (2–3 days) — the lowest-effort highest-impact feature in the entire ecosystem.

6. Forms (3–4 days) — spam detection and submission classification.

7. Visual Editor agents (parallel with editor build) — designed into the editor from the start.

8. Accessibility, Security Analytics, Compliance/Privacy — iteratively after the foundation proves out.

Tagging this for visibility

cc anyone interested in shaping AI strategy across the ecosystem.

I'd love feedback on:

• The overall architecture
• Which per-package features feel right or wrong
• Anything I've missed
• Counter-proposals on sequencing

Discussion is wide open. Nothing here is locked in.