Frosh AI

Experimental
This plugin is under active development. APIs, admin UI, config keys, and provider behaviour may change without a stable semver guarantee until a non-experimental release. Use in production only if you accept that risk and pin to a specific commit or pre-release version. Feedback and contributions are welcome.

Provider-agnostic AI toolkit for Shopware 6.7 / 6.8. Merchants configure providers in the administration; other plugins call a single PHP facade (AiClient) instead of vendor SDKs or hard-coded API keys.

---

Features

Area	Description
Providers	OpenAI (API key + ChatGPT device / Codex), Google Gemini, OpenAI-compatible endpoints (Ollama, LM Studio, OpenRouter, Azure, …)
Capabilities	Text generation, image generation, image editing (source image + instruction)
Catalog AI	Product title, description (HTML), SEO (meta title/description, keywords, Open Graph) via one admin modal
Playground	Text, image generate, image edit — same path as extension code
Feature flags	Master switch + per-ability toggles
Usage log	Success/failure, tokens, duration; CSV export, filters, retention cleanup — no prompts stored
Extensibility	Symfony-tagged providers, events, models.dev catalog

---

Requirements

• Shopware ~6.7.0 or ~6.8.0
• PHP 8.2+
• At least one configured provider (API key and/or ChatGPT device login)
• Message queue / scheduled tasks for usage log retention cleanup

---

Installation

# Plugin in custom/plugins/FroshAI (or via Composer when published)
bin/console plugin:refresh
bin/console plugin:install --activate FroshAI
bin/console database:migrate --all FroshAI   # if required by your setup
bin/console scheduled-task:register
bin/console cache:clear

Rebuild administration after UI changes:

bin/build-administration.sh

Open Settings → Extensions / Plugins → Frosh AI (or Settings → Frosh AI depending on menu registration).

1. Enable AI features (master switch)
2. Configure a provider (e.g. OpenAI or Gemini)
3. Optionally set Default models for text and image
4. Use Playground or catalog product forms

---

Architecture

Admin / other plugin / CLI
        │
        ▼
   AiClient  (frosh_ai.client)
        │
        ├─ FeatureFlags
        ├─ ModelResolver  (prefer() → shop defaults → first configured)
        ├─ Events (chat / image before · after · failed)
        └─ ProviderRegistry  (tag: frosh_ai.provider)
                 │
                 ├─ OpenAI (Completions / Codex + Images)
                 ├─ Gemini (generateContent + image / edit)
                 └─ OpenAI-compatible custom endpoints

Concept	Role
AiClient	Only public entry point for consumers
Capability	What a model/provider can do (text_generation, image_generation, …)
FeatureId	Merchant toggles (product_description, image_edit, …)
frosh_ai.provider	Tag to register another backend

Extension authors should not depend on HTTP clients, config keys, or admin routes. See docs/INTEGRATION.md.

---

Quick start (PHP)

use Frosh\AI\Client\AiClient;
use Frosh\AI\Request\ImageInput;

final class Example
{
    public function __construct(private readonly AiClient $ai) {}

    public function title(string $description): string
    {
        return $this->ai->prompt($description)
            ->system('Suggest a concise product title. Return only the title.')
            ->prefer('openai', 'gpt-4o')
            ->prefer('gemini', 'gemini-2.5-flash')
            ->withMetadata(['extension' => 'AcmeSeo', 'feature' => 'product-title'])
            ->generateText();
    }

    public function editProductPhoto(string $pngBase64): \Frosh\AI\Response\ImageResponse
    {
        return $this->ai->prompt('Remove background, pure white studio, keep product sharp')
            ->prefer('gemini', 'gemini-2.5-flash-image')
            ->withSourceImage($pngBase64, 'image/png')
            ->editImage();
    }
}

DI: Frosh\AI\Client\AiClient or alias frosh_ai.client.

---

Providers

OpenAI

• API key — Chat Completions + Images (generate + edit)
• ChatGPT device login — Codex Responses backend (text); images still need an API key
• Optional base URL for Azure / proxies

Device auth follows the public Codex device flow. Tokens are encrypted with APP_SECRET. Intended for the shop operator’s ChatGPT account, not storefront end-customer login.

Google Gemini

• AI Studio API key
• Chat via generateContent
• Image generate / edit via native image models (e.g. gemini-2.5-flash-image)
• Imagen models supported for generation (:predict); edit uses native Gemini image models

OpenAI-compatible

Merchant-defined endpoints (Ollama, LM Studio, OpenRouter, …): base URL, optional key, default model. Text-only unless the host implements compatible image routes.

---

Built-in merchant features

Feature	Flag	Where
Product description	product_description	Catalog → Product
Product title	product_title	Catalog → Product
Product SEO	product_seo	Catalog → Product → SEO
Image generation	image_generation	Playground + generateImage()
Image editing	image_edit	Playground + withSourceImage() / editImage()

All catalog tools share tone presets, content language (product language switcher), and a single Generate with AI modal (fill empty only, overwrite confirm, remembered prefs).

---

Usage tracking

Every chat and image call is logged to frosh_ai_usage_log (provider, model, duration, tokens, feature, status). Prompts and image bytes are not stored.

• Admin: Settings → Frosh AI → Usage (filters, expand errors, CSV, purge, retention)
• Config: usageRetentionDays (default 90; 0 = keep forever)
• Scheduled task: frosh_ai.cleanup_usage_logs

---

Admin module

Tab	Purpose
General	Master switch, feature flags, default text/image models
Providers	List + detail panels (frosh-ai-provider-{id})
Product	Tone presets for catalog AI
Usage	Stats, filters, export, retention
Playground	Text / image generate / image edit

ACL: frosh_ai_settings.viewer / frosh_ai_settings.editor.

---

Configuration

Prefer the admin UI. Plugin config (config.xml) remains available for headless installs, including API keys, Gemini/OpenAI defaults, feature flags, and usage retention.

---

Extending

Custom provider

<service id="Acme\AI\MyProvider">
    <tag name="frosh_ai.provider"/>
</service>

Implement Frosh\AI\Contract\AiProviderInterface and return an LlmClientInterface. Optional admin panel: register Vue component frosh-ai-provider-{id}.

Events

• Chat: AiChatBeforeEvent, AiChatAfterEvent, AiChatFailedEvent
• Image: AiImageBeforeEvent, AiImageAfterEvent, AiImageFailedEvent

---

Development

# Unit tests (from plugin root)
../../../vendor/bin/phpunit -c phpunit.xml

# PHP CS / types (from shopware root, as applicable)
composer cs
composer phpstan

Integration contract for other plugins: docs/INTEGRATION.md.

---

Security notes

• API keys and device tokens live in system config / encrypted storage — protect admin ACL and APP_SECRET.
• Usage logs deliberately omit prompts and image payloads.
• Third-party AI providers receive product data you send; ensure GDPR / contractual basis with your processor.

---

Licence

MIT — FriendsOfShopware.

---

Support

• Issues: FriendsOfShopware/FroshAI (when published)
• Experimental status: expect breaking changes; discuss design before building large plugins on unreleased APIs.