AI Assistant Technical Notes

This document describes the optional AI Assistant feature, which generates SEO-oriented vehicle descriptions, image alt texts, SEO metadata and equipment highlights from imported listing data.

AI features use the managed Google Gemini configuration in ADP Car Market Hub. **No provider selection, model selection or API key entry is required in the WordPress backend.** Customer-specific AI provisioning is completed by AD Promotion after installation.

When to use this document

Read this document if you need to:

• Decide whether to enable the AI Assistant for your site.
• Understand how the background queue and per-import generation interact with WP-Cron.
• Audit the security model around the managed Gemini configuration and admin triggers.

Overview

The AI Assistant is implemented in AS24CI\Ai_Assistant. When enabled, it can:

• Generate a description automatically as part of the import flow (hooked on as24ci_vehicle_imported).
• Process a queue of pending generations in the background via WP-Cron (as24ci_process_ai_queue).
• Allow editors to generate or regenerate a description manually from the vehicle edit screen, both via an AJAX action and a one-shot admin-post action.

The feature is opt-in: it does nothing until as24ci_ai_assistant_enabled is set to '1' and the managed Gemini configuration is provisioned. The cron callback is registered unconditionally so any pre-scheduled jobs from a previous configuration can still drain.

Managed AI configuration

The plugin uses a single managed AI configuration exposed by AS24CI\Ai_Config. The previously hard-coded Gemini key/model constants on Ai_Config have been removed; the class is now a thin facade over AS24CI\Ai_Credential_Manager:

• Ai_Config::get_effective_model() — returns the fixed runtime Gemini model, always Ai_Credential_Manager::PRIMARY_MODEL (currently gemini-3.5-flash). Any API-supplied model value is metadata only and never controls runtime selection.
• Ai_Config::get_managed_gemini_api_key() — returns the customer Gemini key sourced from the encrypted credential envelope synced server-to-server from the API Platform. Returns an empty string when AI cannot run (no license ai_allowed entitlement or no stored credential). Never exposed in the admin UI, diagnostics, logs or any user-visible surface.
• Ai_Config::is_configured() — returns true only when a usable managed Gemini key is available.

Ai_Assistant's legacy helpers (get_api_key_for_provider(), get_model(), etc.) are retained for backwards compatibility and resolve to the managed Gemini values. There is no provider switch, no per-provider API key field, and no model selector in the WordPress backend.

Available output languages (de, en, fr, it), tones (professional, emotional, technical) and target lengths (short, medium, long) are defined as class constants on Ai_Assistant.

Background queue

• Cron hook: as24ci_process_ai_queue.
• Custom schedule: as24ci_every_5_minutes.
• Batch size per run: up to 3 vehicles.
• Maximum attempts per vehicle: 3.
• Excerpt cap: 160 characters.

The queue lets the plugin spread AI generation across imports without blocking the front-end request that triggered them.

Step by step instructions

To enable and configure the AI Assistant:

1. Open the AI Assistant admin tab.
2. Toggle the Enable AI Assistant setting on (as24ci_ai_assistant_enabled = '1').
3. Pick a language, tone, target length and (optional) custom prompt.
4. Decide whether to enable Auto-generate on import (as24ci_ai_assistant_auto_generate).
5. Save and run an import or trigger a single generation from a vehicle edit screen to verify connectivity.

The managed Gemini configuration is already in place — no provider, model or API key fields are presented in the admin UI.

Manual generation

Two admin paths exist:

• AJAX (as24ci_generate_ai_assistant) — used by the meta box on the vehicle edit screen. Requires the manage_as24_imports capability and the as24ci_ai_generate nonce.
• Admin-post (as24ci_manual_ai_generate) — handles a one-shot manual Generate button. Requires the per-post nonce as24ci_manual_ai_generate_<post_id> and the edit_post capability for the specific vehicle.

Both flows ultimately call the managed Gemini routine and write the result back to the post.

Admin background trigger

The plugin exposes the AJAX action as24ci_trigger_ai_queue_now which processes one batch of the AI queue immediately. It is gated by manage_as24_imports and the as24ci_trigger_ai_queue_now nonce, and returns HTTP 400 if the AI Assistant is disabled.

Configuration reference

For the full list of plugin options, see Options And Settings Storage.

Operational notes

• Third-party data flow: When the AI Assistant is enabled, vehicle data and prompt context leave the WordPress server and are sent to the managed Google Gemini endpoint. Review the applicable data processing and contractual terms for the managed AI setup before enabling AI features in production.
• Cost and quota: AI usage runs against the managed Gemini configuration provisioned by AD Promotion. The plugin does not expose per-call pricing.
• Rate limits: Gemini enforces request and token limits independently of the plugin. Failed generations are retried up to 3 times per vehicle; persistently failing vehicles are abandoned to avoid infinite loops.
• Auto-generation only fires on imports when both the master toggle and the Auto-generate option are enabled. Manual generation always works (regardless of Auto-generate) when the master toggle is on.
• Managed key handling: the managed Gemini key is delivered server-to-server by the API Platform and held encrypted by Ai_Credential_Manager. It is never written to wp_options in plaintext, surfaced in the admin UI, or printed in diagnostics or logs.
• Disabling the feature stops new generations but the registered cron hook remains so already-queued jobs can drain. Verify the queue is empty before relying on the feature being fully off.

Troubleshooting

• No description is generated on import — confirm as24ci_ai_assistant_enabled is '1', Auto-generate is on and Ai_Config::is_configured() returns true (managed key provisioned). Check the plugin log for Gemini error responses.
• Manual Generate button does nothing — check the browser network tab. A 403 indicates a missing capability or nonce, a 400 indicates the AI Assistant is disabled.
• Queue never drains — WP-Cron requires regular site traffic to fire scheduled events. Configure an external cron job or trigger the queue manually via the Trigger AI queue now admin action. See Cron Events And Scheduler.
• Same vehicle never gets a description after multiple attempts — the per-vehicle attempt counter has reached 3. Investigate the underlying Gemini error in the log before resetting.

Related documents

• Cron Events And Scheduler
• AJAX Actions
• Options And Settings Storage
• Security And Capabilities
• Import Engine
• Known Limitations And Open Risks