<!-- status: plan -->
<!-- started: 2026-03-01 -->
<!-- component: gateway -->

# Web Image Search -- WEB_SEARCH_MEDIA Operation Type

## Beschreibung und Kontext

PowerOn unterstützt Web-Suche über den Tavily-Connector (`WEB_SEARCH_DATA`). Es fehlt eine dedizierte Bildersuche. Ziel ist ein neuer OperationType `WEB_SEARCH_MEDIA` mit Google Custom Search Connector, damit der AI Agent Bilder suchen und als ActionDocuments zurückgeben kann.

**Business-Treiber:** Mandanten benötigen Bildmaterial (z.B. für Immobilien-Exposés, Marketing-Content) direkt im AI Workspace.

**Risiko bei Nicht-Umsetzung:** Manuelle Bildersuche ausserhalb der Plattform, kein automatisierter Image-Workflow.

## Fokus und kritische Details

- Google Custom Search API erfordert API Key + Search Engine ID mit aktivierter Image Search
- Model-Selection muss `WEB_SEARCH_MEDIA` korrekt zum Google-Connector routen
- Rückgabeformat: JSON-Array mit Image-URLs, konsistent mit Tavily-Format
- Rate Limiting der Google API (100 queries/Tag im Free Tier)

## Ziel und Nicht-Ziele

- **Ziel:** `WEB_SEARCH_MEDIA` OperationType in `OperationTypeEnum`
- **Ziel:** Google Custom Search Connector (`aicorePluginGoogle.py`)
- **Ziel:** `AiCallPromptWebSearchMedia` Pydantic Model
- **Ziel:** `ai.searchImages` Action in `methodAi`
- **Explizit NICHT:** Video-Suche, Tavily-Erweiterung, SharePoint-Integration

## Betroffene Module

- Gateway: `modules/datamodels/datamodelAi.py`, `modules/aicore/aicorePluginGoogle.py` (NEU), `modules/services/serviceAi/mainServiceAi.py`, `modules/workflows/methods/methodAi/`
- Frontend: keine (Agent nutzt Action intern)
- DB-Migration: nein
- Andere: Google Cloud Console Setup (API Key)

## Entscheidungen

| Datum | Entscheidung | Begründung |
|-------|-------------|------------|
| 2026-03-01 | Google Custom Search statt Tavily | Tavily unterstützt keine Bildersuche |
| 2026-03-01 | Eigener Connector statt Tavily-Erweiterung | Saubere Trennung, unabhängige Skalierung |

## Umsetzungs-Checkliste

- [ ] `WEB_SEARCH_MEDIA` in `OperationTypeEnum` hinzufügen
- [ ] `AiCallPromptWebSearchMedia` Model erstellen
- [ ] `aicorePluginGoogle.py` Connector implementieren
- [ ] Connector in Discovery registrieren
- [ ] `mainServiceAi.py` für `WEB_SEARCH_MEDIA` erweitern
- [ ] `searchImages` Action erstellen
- [ ] Action in `methodAi.py` registrieren
- [ ] RBAC / Permissions: nicht betroffen (nutzt bestehende AI-Berechtigung)
- [ ] Neutralisierung betroffen? nein
- [ ] Navigation / Routing: nicht betroffen
- [ ] Billing-Impact? prüfen (API-Kosten pro Query)

## Akzeptanzkriterien

| # | Kriterium (Given-When-Then) | Prio |
|---|---------------------------|------|
| 1 | Given ein AI Agent mit `searchImages` Tool, When der User "Suche Bilder von Zürich" eingibt, Then gibt der Agent eine Liste von Bild-URLs zurück | must |
| 2 | Given kein Google API Key konfiguriert, When `WEB_SEARCH_MEDIA` aufgerufen wird, Then wird ein klarer Fehler zurückgegeben | must |
| 3 | Given `maxResults=5` und `imageType=photo`, When die Suche ausgeführt wird, Then werden max. 5 Fotos zurückgegeben | should |

## Testplan

| ID | AC | Art | Automatisiert | Repo-Pfad | Status |
|----|----|-----|--------------|-----------|--------|
| T1 | 1  | integration | ja | platform-core/tests/test_google_connector.py | pending |
| T2 | 2  | unit | ja | platform-core/tests/test_google_connector.py | pending |
| T3 | 3  | api | ja | platform-core/tests/test_search_images_action.py | pending |

## Links

- Google Custom Search API: https://developers.google.com/custom-search/v1/overview
- Bestehender Tavily Connector: `platform-core/modules/aicore/aicorePluginTavily.py`

## Abschluss

- [ ] b-reference/platform-core/ai-agent.md aktualisiert (neuer OperationType)
- [ ] TOPICS.md aktualisiert (falls neues Thema)
- [ ] Dieses Dokument → z-archive/ verschoben