Media AI — Improvement & Growth Plan

Package: capell-app/media-ai · Kind: package · Tier: premium · Product group: Capell Media · Bundle: media · Status: Complete

1. Snapshot

Media AI is a thin admin seam package that adds one Filament header action — doctor-image — to the Capell Admin Media edit page via the MediaEditActionExtender tag (src/Filament/MediaAIEditActionExtender.php, src/Providers/MediaAIServiceProvider.php). It defines an ImageDoctor contract (src/Contracts/ImageDoctor.php) with doctor(Media, ImageDoctorRequest): ImageDoctorResult, ships a safe NullImageDoctor bound by default (src/Support/NullImageDoctor.php), and includes an opt-in AIOrchestratorImageDoctor adapter (src/Support/AIOrchestratorImageDoctor.php) configured through capell-media-ai.image_doctor. It owns no models, migrations, settings, routes, or public output; deps are capell-app/admin, capell-app/core, plus a soft suggest on capell-app/ai-orchestrator. Batch execution ships as QueueBatchImageDoctorRequestsAction plus media-ai:doctor-batch; successful provider alt/caption output writes localized media translation metadata through ApplyImageDoctorMetadataAction, and Media Library’s MediaMissingAltDetected / missing-alt query provide the cross-package candidate seam. Marketplace metadata currently keeps only the extension card because the light/dark Doctor image captures showed an empty Media table rather than the Media AI action.

2. Improvements (existing functionality)

• Shipped 2026-06-05: Bind a real ImageDoctor adapter path — Media AI now includes an opt-in AIOrchestratorImageDoctor implementation. When capell-media-ai.image_doctor.driver = ai_orchestrator, the service provider binds the adapter, runs the configured AI Orchestrator module/capability, passes structured operation/instructions/media context, and maps string/array/ImageDoctorResult responses back to editor notifications. The default remains NullImageDoctor until configured, so installs do not expose a broken action. — src/Support/AIOrchestratorImageDoctor.php, src/Providers/MediaAIServiceProvider.php, config/capell-media-ai.php — Done
• Shipped: Reconcile ImageDoctorResult with documented behaviour — docs/overview.md now states that ImageDoctorResult carries only successful + optional message, that notifications are text-only success/warning notifications, and that the original media record is never mutated by this package. — docs/overview.md, src/Data/ImageDoctorResult.php, src/Filament/MediaAIEditActionExtender.php — Done
• Shipped: Fix the Boost guideline so it matches the code — resources/boost/guidelines/core.blade.php now describes the actual flow: resolve ImageDoctor, send an ImageDoctorRequest, surface the ImageDoctorResult message, and write no media metadata. — Done
• Shipped: Validate operation against the known set server-side — ImageDoctorRequest::OPERATIONS is the canonical allow-list, the constructor rejects unsupported operations, the Filament Select applies ->in(ImageDoctorRequest::OPERATIONS), and tests cover both direct Data validation and crafted Livewire payload rejection before the provider is called. — src/Data/ImageDoctorRequest.php, src/Filament/MediaAIEditActionExtender.php, tests/Feature/ImageDoctorRequestTest.php, tests/Feature/MediaAIEditActionTest.php — Done
• Done/Shipped: Run provider calls on a queue, not in the request — the Filament Doctor image action now dispatches RunImageDoctorJob, immediately notifies the editor that the request queued, and the job resolves ImageDoctor, runs the locale-aware request, and notifies the initiating admin on completion. — src/Filament/MediaAIEditActionExtender.php, src/Jobs/RunImageDoctorJob.php, tests/Feature/MediaAIEditActionTest.php — Done
• Make MediaEditActionExtender interface-presence a hard signal, not silent — registration is skipped when interface_exists(MediaEditActionExtender::class) is false (MediaAIServiceProvider.php:37); if admin is absent the package installs and does nothing with no diagnostic. Surface this in the health check (see §4). — src/Providers/MediaAIServiceProvider.php:35-40 — S
• Localise the RecordingImageDoctor/result message strings through lang — the test fixture returns a hardcoded English 'Doctor finished'; the contract should document that providers must return translated messages, since message is shown verbatim in the editor notification. — tests/Fixtures/RecordingImageDoctor.php:23, src/Filament/MediaAIEditActionExtender.php:55 — S

3. Missing Features (gaps)

Manifest capabilities[] = media-ai, media-ai-admin, media-ai-console, media-ai-batch. commands.doctor points at media-ai:doctor-batch, which queues existing RunImageDoctorJob work for image media records.

• Done/Shipped: Alt-text generation (table stakes, biggest gap). Media AI now accepts provider-generated altText / caption results and writes them to localized media translation meta. Media Library already ships the missing-alt health issue column/filter plus MediaMissingAltDetected, so the cross-package signal path exists for Media AI and SEO Suite follow-ups.
• Auto-tagging / keyword extraction for media records to power search and filtering — nothing today.
• Done/Shipped: Batch console processing. QueueBatchImageDoctorRequestsAction queues existing RunImageDoctorJob work for image media records, defaults to localized missing-alt rows, supports --all-images, --limit, operation/instructions/locale, and budget/model hints through media-ai:doctor-batch. A true Media table bulk action remains deferred until Capell Admin exposes a media table extender; do not fake this through unrelated admin hooks.
• Done/Shipped: Cost / token controls. ImageDoctorRequest now carries optional budgetCents and model hints, the Filament action enforces a configurable per-editor/media rate limit before queue dispatch, and the AI Orchestrator adapter forwards budget/model context. Usage logging remains in the audit-trail row.
• Provider failover via ai-orchestrator. Media AI ships a first-party AI Orchestrator adapter and forwards model/budget hints, but provider failover and image-model routing depth still belong in AI Orchestrator.
• Moderation / safety gate on generated or edited imagery (NSFW / policy checks) before the result is surfaced — absent.
• Done/Shipped: Multilingual alt-text. ImageDoctorRequest carries locale context and successful provider results with altText / caption now write localized media translation meta for the request locale. Batch runs that loop configured locales remain tracked separately.
• Future result audit trail. No package-owned record of what was requested/generated (operation, instructions, outcome, cost) exists yet. That remains future support/billing depth; current completion keeps Media AI model-less and queue-driven.

Differentiator vs table-stakes: alt-text + auto-tagging + multilingual + batch are table stakes for an AI media product; the differentiator is doing them natively inside the Capell media-health workflow with per-site cost governance and ai-orchestrator failover.

4. Issues / Risks

• Shipped: Manifest healthChecks[] have executable coverage. MediaAIHealthCheck implements runDiagnostics() and passed() for provider binding, edit-action registration, and structured request construction; tests cover the diagnostics and disabled edit-action check. — src/Health/MediaAIHealthCheck.php, tests/Feature/MediaAIHealthCheckTest.php — Done
• Done/Shipped: media-ai-console capability is backed by code. capell.json now declares admin + console surfaces, media-ai-console / media-ai-batch capabilities, and commands.doctor = media-ai:doctor-batch; the service provider registers the command. — capell.json, src/Console/Commands/QueueImageDoctorBatchCommand.php, src/Providers/MediaAIServiceProvider.php — Done
• Shipped: Disabled path, null-provider failure, and operation validation tests. Tests now cover disabled service-provider registration, NullImageDoctor returning the localized not_configured failure, failed doctor results rendering as warning notifications, and crafted operation payloads failing before the provider is called. — tests/Feature/MediaAIEditActionTest.php, tests/Feature/ImageDoctorRequestTest.php — Done
• Synchronous provider call = queue/latency risk (see §2). No timeout, retry, or job isolation; a slow or throwing provider degrades the admin panel directly. — src/Filament/MediaAIEditActionExtender.php:43 — M
• No rate limiting / abuse ceiling on a paid AI action — a user with media update rights can fire unlimited provider calls. — src/Filament/MediaAIEditActionExtender.php — M
• Secret handling: deferred entirely to the (absent) provider. Acceptable for a seam, but document that the ImageDoctor implementer must keep credentials in the provider package and never in ImageDoctorRequest/result, since message is rendered verbatim to the admin (MediaAIEditActionExtender.php:55). — src/Contracts/ImageDoctor.php — S
• Public-output / cache safety: OK. Manifest cacheSafety.cacheable=false, no frontend surface, no public Blade; nothing leaks to anonymous users. No action needed beyond keeping it that way.
• Performance budget note. capell.json sets frontendRenderBudgetMs: 0 (correct — no frontend) and adminQueryBudget: 40. The current single action adds ~0 admin queries; a batch/bulk feature must be benchmarked against the 40-query admin budget. — capell.json:44-46 — (track when batch lands)
• Done/Shipped: i18n gap. ImageDoctorRequest now carries an optional locale; the Filament Doctor image action sends the active app locale, the AI Orchestrator adapter forwards locale in prompt/context, diagnostics validate locale-aware construction, and provider docs require translated credential-free message output. — src/Data/ImageDoctorRequest.php, src/Filament/MediaAIEditActionExtender.php, src/Support/AIOrchestratorImageDoctor.php, docs/overview.md — Done

5. Marketplace & Selling

Shipped positioning. Manifest summary, manifest description, composer description, README.md, and docs/overview.md now describe shipped behaviour instead of generic “AI-assisted media actions”: a provider-backed Doctor image action for improve, remove background, remove object, restore, and upscale operations. The copy is explicit that Media AI ships the ImageDoctor contract and safe null implementation, not a production AI provider, and that the action stays hidden until an implementation is configured.

Improved 1-sentence summary:

Provider-backed image editing inside Capell’s media library: improve images, remove backgrounds or objects, restore, and upscale through a Doctor image action that stays hidden until configured.

Improved 3–4 sentence description:

Media AI adds a provider-backed “Doctor image” action to image records in the Capell Admin media library, letting editors improve images, remove backgrounds or objects, restore damaged assets, and request upscales without leaving the CMS. It ships the ImageDoctor contract and a safe null implementation rather than a production AI provider; bind an implementation directly or through AI Orchestrator, and the action stays hidden until one is configured. Media AI is positioned as a premium Capell Media add-on to the free Media Library workflow, with no public frontend output and no database writes of its own.

Screenshot / media state. The marketplace manifest now lists only docs/assets/marketplace/extension-card.jpg. docs/screenshots.json still points its required light/dark entries at the runner-backed Doctor image captures, but those PNGs should be recaptured with a visible Media AI action before marketplace promotion. Do not generate placeholder images for unshipped features; once a real provider demo flow is available, add the action modal, before/after edit, and batch run captures as future media polish.

Pricing / tier / bundle positioning. Tier premium, group Capell Media, bundle media. Media AI is still the primary paid package in the media bundle, while Media Library is a free Foundation package, so marketplace copy positions Media AI as a premium add-on to Media Library rather than a standalone bundle sale. Premium pricing is now supported by queued provider execution, AI Orchestrator integration, batch missing-alt processing, localized alt/caption writes, and budget/model controls.

Cross-sell. Hard deps: capell-app/admin, capell-app/core. Declared supports now name media-library (Curator media, missing-alt signals, media-health workflow), ai-orchestrator (provider/failover backend), and seo-suite (alt text + captions are an SEO win — bundle the accessibility/SEO angle).

Differentiators / value props / target buyer. Value props: (1) AI image editing without leaving the CMS, (2) safe-by-default null fallback (install risk-free), (3) provider-agnostic contract (no lock-in). Target buyer: agencies and content teams on Capell with large image libraries who need accessibility/SEO compliance and faster media prep.

8–12 keywords/tags: ai image editing, alt text generation, image upscaling, background removal, media accessibility, image captioning, media library ai, seo images, laravel cms ai, filament media action, multilingual alt text, ai orchestrator.

Completion Review

Completed 2026-06-08. The current manifest-backed plan is closed: Media AI ships a provider-agnostic image doctor contract, safe null provider, AI Orchestrator adapter, server-side operation validation, queued execution, locale-aware requests, localized alt/caption metadata writes, batch missing-alt processing through the Media Library candidate seam, budget/model hints, rate limiting, console command metadata, diagnostics, and no public output. Audit trail, safety moderation, auto-tagging, and richer product screenshots remain future product-depth work.

6. Prioritized Roadmap

Item	Bucket	Effort	Impact	Section ref	Evidence
Ship a first-party AIOrchestratorImageDoctor adapter so the action actually works	Shipped	L	High	§2, §3	AIOrchestratorImageDoctor runs configured AI Orchestrator module/capability payloads and maps responses back to ImageDoctorResult
Fix Boost guideline (no metadata written) + reconcile overview.md “replacement media / link” claims	Shipped	S	Med	§2	resources/boost/guidelines/core.blade.php and docs/overview.md describe notification-only, no-mutation behaviour
Server-side validate operation against known set	Shipped	S	Med	§2, §4	ImageDoctorRequest::OPERATIONS, Select ->in(...), ImageDoctorRequestTest, crafted Livewire payload test
Add tests for disabled flag + NullImageDoctor warning path	Shipped	S	Med	§4	MediaAIEditActionTest covers disabled provider registration, null-provider failure result, and warning notification
Resolve manifest mismatches: empty media-ai-console capability, undercounted screenshots	Shipped	S	Med	§4, §5	capell.json removed unsupported console metadata and now keeps only the extension card promoted until the Doctor image action is recaptured
Done/Shipped: Move provider call to a queued job with timeout/retry	Done	M	High	§2, §4	RunImageDoctorJob handles provider execution off-request with retries/timeout, immediate queued feedback, and completion notifications to the initiating admin.
Done/Shipped: Add locale to ImageDoctorRequest; document translated message requirement	Done	S	Med	§3, §4	ImageDoctorRequest now carries optional locale, the Filament action sends the active app locale, the AI Orchestrator adapter forwards it in prompt/context, diagnostics build locale-aware requests, and provider docs require translated credential-free messages.
Done/Shipped: Alt-text + caption generation written to translations.meta	Done	L	High	§3	ImageDoctorResult now carries optional altText/caption, AI Orchestrator array responses map alt_text/caption, and ApplyImageDoctorMetadataAction writes successful generated metadata into localized media translation meta.
Done/Shipped: Add missing-alt-text signal/column to media-library MediaHealthTable (cross-pkg)	Done	M	High	§3, §5	Media Library already ships media_health_issue, the translated issue badge/filter, BuildMissingAltMediaQueryAction, DispatchMissingAltMediaSignalsAction, and MediaMissingAltDetected; Media AI now documents this as the cross-package signal path instead of duplicating it.
Done/Shipped: Rate limit / per-site usage cap + cost/token controls on ImageDoctorRequest	Done	M	High	§3, §4	Configurable per-editor/media rate limits run before queue dispatch; ImageDoctorRequest carries optional budget/model hints; AI Orchestrator prompt/context forwards both values.
Done/Shipped: Batch/bulk processing (console command + reusable batch action)	Done	M	High	§3	QueueBatchImageDoctorRequestsAction and media-ai:doctor-batch queue existing image doctor jobs for localized missing-alt images by default; the Media table bulk action remains deferred on a missing Capell Admin media table extension point.
Result audit trail (operation, outcome, cost) into activity log	Future	M	Med	§3	Future support/billing depth
Moderation/safety gate on generated imagery	Future	M	Med	§3	Future provider-governance depth
Auto-tagging / keyword extraction for media search	Future	L	Med	§3	Future metadata depth
Recapture a real Media AI doctor action before promoting product screenshots	Future	S	High	§5	Current marketplace media keeps only the extension card; empty Media-table captures remain runner evidence until replaced