# 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 |