# Overview.Admin

## What it does

Media AI adds a queued **Doctor image** action to image records. It can improve, remove a background or named object, restore, or upscale an image. A provider may also return localised alt text and a caption. Generated image output is attached as a new media item, while the original file is preserved.

## Setup requirements

The package ships with a null provider and does not make AI requests by default. **Doctor image** stays hidden until a real `ImageDoctor` provider is bound. To use the built-in integration, set the image-doctor driver to `ai_orchestrator` and configure AI Orchestrator's `media-ai` / `doctor-image` capability and image provider. There is no Media AI settings screen; enablement, rate limit, model hints, output limit, and batch size come from `capell-media-ai` configuration.

Keep a queue worker running. Every admin and batch request dispatches an encrypted, unique job; the image is not processed in the browser request. The default job timeout is 120 seconds with two attempts.

## Run Doctor image

Open an image in the Media Library and select **Doctor image**. The action appears only for image media when you can update that media record and a provider is configured. Choose an operation, give precise instructions, and submit it. The default limit is ten submissions per account and media item per hour; the warning tells you when that window becomes available again.

The completion notification means the provider job finished and its accepted output was applied. Review all generated content:

- Returned alt text and captions are written directly to the media translation for the request locale, falling back to an available language when necessary.
- Returned image bytes create a separate item in the same collection and on the same disk. The new item records its source media ID, operation, locale, and generation time; the original image file is not replaced.
- Image output is ignored unless its declared and detected type agree, it is JPEG, PNG, WebP, or GIF, and it is within the configured size limit (10 MB by default). Valid metadata can still be applied when image output is rejected.

## Batch workflow

`media-ai:doctor-batch` is an operator command for queued bulk work. By default it selects the oldest image records missing alt text in the requested locale and queues at most 50. Set a lower `--limit` for the first run and inspect results before expanding it. `--all-images` also includes images that already have alt text and may overwrite that localised metadata, so use it only for a deliberate regeneration pass. A queue worker is still required after the command reports how many jobs it queued.

For example, an operator can queue up to 25 English images missing alt text, using user 42's current media permissions and asking for accurate alt text plus a concise catalogue caption.

The operational outcomes are `queued` while background work is pending, `reviewable` when a separate generated image is ready to inspect, `applied` when metadata was written, `refused` when no safe output could be applied, and `failed` when the provider could not complete the request and the queue retry policy applies.

## Privacy and provider boundaries

The configured provider receives the operation, instructions, locale, model hint, and media context including its name, type, size, owning model identifiers, and a URL from which it can read the image. Public media uses its normal URL. Private media uses a temporary URL valid for five minutes; if the disk cannot issue one, no permanent URL is substituted. Raw storage disk names, paths, and file names are not sent in the provider context.

Do not submit confidential imagery unless the configured AI provider's storage and training terms are acceptable. Financial authorization belongs to the consuming application and is not performed by Media AI.

## Failures and recovery

Identical jobs for the same account, image, and request parameters are deduplicated for one hour. If a provider fails, the queued job throws and can run once more before entering the application's failed-job handling. Media AI has no separate run-history screen and does not send a package-specific failure notification. Inspect the queue and application log, correct provider availability, credentials, or image access, then retry the failed job or submit a changed request. If an image was deleted before its job runs, the job exits without creating output.