Media AI

Media AI

Provider-backed image editing actions for Capell media records.

At A Glance

• Package: capell-app/media-ai
• Namespace: Capell\MediaAI\
• Service providers: packages/media-ai/src/Providers/MediaAIServiceProvider.php
• Capell dependencies: capell-app/admin, capell-app/core
• Third-party dependencies: filament/filament, laravel/framework, spatie/laravel-package-tools

Why It Helps Your Capell Workflow

• Adds a provider-backed Doctor image action without forcing the media library to depend on an AI provider.
• Helps editors request background removal, object removal, image restoration, improvement, and upscaling from the admin media workflow.
• Fits sites that want premium AI support for media workflows but still need predictable fallbacks when AI is disabled or unconfigured.

Best Used With

• Media Library
• AI Orchestrator
• Foundation Theme

What It Adds

Provider-backed image editing actions for Capell media records.

• Optional image edit action for improve, remove-background, remove-object, restore, and upscale operations.
• ImageDoctor contract with a safe null implementation.
• Opt-in AI Orchestrator image doctor adapter configured through capell-media-ai.image_doctor.
• Filament media action extender for admin workflows.
• No public frontend output and no required AI provider binding.

Why It Matters

For developers: Keeps Media AI package responsibilities isolated behind providers, actions, data objects, and package-owned resources where the package needs them.

For teams: Makes the Capell Media capability easier to explain, install, and verify during package selection.

Built With

This package makes its Composer dependencies visible because they are part of the value proposition, not just plumbing. When an upstream package has a public repository, its linked preview card points readers back to the maintainers so their work gets proper credit.

Capell packages used here

• Capell Admin
• Capell Core

Open-source packages used here

• Spatie Laravel Package Tools - Laravel package bootstrapping for config, migrations, commands, translations, and service provider setup.

Linked package previews

Screens And Workflow

Screenshots are generated from docs/screenshots.json during package deployment.

Code Map

Data And Persistence

• Config: packages/media-ai/config/capell-media-ai.php.
• Data objects live in src/Data/; use them for payloads, form state, and view models.

Extension Points

• Contracts: ImageDoctor.
• Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

Install And Setup

• Install with composer require capell-app/media-ai in the host Capell application.
• In this repository, verify package changes with vendor/bin/pest; do not use php artisan.

Docs

• docs index
• credits-and-acknowledgements.md
• overview.md

Testing

Run package tests from the repository root:

vendor/bin/pest packages/media-ai/tests --configuration=phpunit.xml

Maintenance Notes

• Use package Data classes at boundaries instead of passing anonymous arrays between layers.

Media AI

The Media AI package adds provider-backed image actions to Capell's existing media resource. It does not replace the media backend, crop system, or localized metadata model.

Status: Optional · Tier: Premium · Bundle: media · Surface: Admin · Depends on: capell-app/admin, capell-app/core

What It Adds

• A Doctor image action on image records in the Media resource.
• A small form for the editor to choose the image operation and add instructions.
• A Capell\MediaAI\Contracts\ImageDoctor contract that a provider package can bind to the real image-editing implementation, directly or through AI Orchestrator.
• An opt-in AIOrchestratorImageDoctor adapter that runs a configured AI Orchestrator module/capability and maps its response back to ImageDoctorResult.
• A safe default NullImageDoctor, so installing the package never exposes a broken action before an AI provider is configured.

Marketplace Positioning

Media AI is a premium Capell Media add-on to the free Media Library workflow. Today it should be sold as the admin-safe provider seam for image operations - improve, remove background, remove object, restore, and upscale - rather than as a full AI media suite. Pair Media AI with Media Library for the editing surface and AI Orchestrator for provider governance; the bundled adapter connects to a registered AI Orchestrator image capability, but the actual image model/provider remains outside this package.

Editor Flow

1. Upload or open an image in Admin > Media.
2. Select Doctor image.
3. Choose the operation, such as background removal or cleanup.
4. Add short instructions.
5. Submit the action.

When the action runs, the editor sees a Filament notification carrying the ImageDoctorResult message — a success notification when the request succeeds, or a warning when it does not. The result object carries successful, an optional message, and optional generated altText / caption fields. Successful results with generated alt text or captions are written to the media record's localized translation meta for the request locale.

Integration Contract

By default the package binds NullImageDoctor. To use the first-party AI Orchestrator adapter, configure the driver and capability keys:

return [
    'image_doctor' => [
        'driver' => 'ai_orchestrator',
        'ai_orchestrator' => [
            'module' => 'media-ai',
            'capability' => 'doctor-image',
        ],
    ],
];

Custom providers can still bind Capell\MediaAI\Contracts\ImageDoctor directly. Every implementation receives the current media record and an ImageDoctorRequest (a validated operation, free-text instructions, and optional locale). It returns an ImageDoctorResult reporting successful, an optional human-readable message, and optional localized altText / caption values. The message is rendered verbatim in the editor notification, so providers must return a translated, credential-free string for the request locale.

Doctor image requests are rate-limited per editor/media pair through capell-media-ai.image_doctor.rate_limit. Optional budget_cents and model config values are forwarded on ImageDoctorRequest and through the AI Orchestrator prompt/context so provider packages can enforce spend and model selection consistently.

Boundaries

• Cropping remains owned by Curator when capell.media.backend is curator.
• Spatie installs use Capell's fallback focal-point and crop-preset UI.
• Localized alt text, captions, credits, and decorative flags are stored in the shared translations.meta JSON column.