motia-iii/docs/DOCUMENT_SYNC_XAI_STATUS.md

Document Sync mit xAI Collections - Implementierungs-Status

✅ Implementiert

1. Webhook Endpunkte

• POST /vmh/webhook/document/create
• POST /vmh/webhook/document/update
• POST /vmh/webhook/document/delete

2. Event Handler (document_sync_event_step.py)

• Queue Topics: vmh.document.{create|update|delete}
• Redis Distributed Locking
• Vollständiges Document Loading von EspoCRM

3. Sync Utilities (document_sync_utils.py)

• ✅ Datei-Status Prüfung: "Neu", "Geändert" → xAI-Sync erforderlich
• ✅ Hash-basierte Change Detection: MD5/SHA Vergleich für Updates
• ✅ Related Entities Discovery: Many-to-Many Attachments durchsuchen
• ✅ Collection Requirements: Automatische Ermittlung welche Collections nötig sind

⏳ In Arbeit

4. Preview-Generierung (generate_thumbnail())

✅ Implementiert - Bereit zum Installieren der Dependencies

Konfiguration:

• Feld in EspoCRM: preview (Attachment)
• Format: WebP (bessere Kompression als PNG/JPEG)
• Größe: 600x800px (behält Aspect Ratio)
• Qualität: 85% (guter Kompromiss zwischen Qualität und Dateigröße)

Unterstützte Formate:

• ✅ PDF: Erste Seite als Preview
• ✅ DOCX/DOC: Konvertierung zu PDF, dann erste Seite
• ✅ Images (JPG, PNG, etc.): Resize auf Preview-Größe
• ❌ Andere: Kein Preview (TODO: Generic File-Icons)

Benötigte Dependencies:

# Python Packages
pip install pdf2image Pillow docx2pdf

# System Dependencies (Ubuntu/Debian)
apt-get install poppler-utils libreoffice

Installation:

cd /opt/motia-iii/bitbylaw
/opt/bin/uv pip install pdf2image Pillow docx2pdf

# System packages
sudo apt-get update
sudo apt-get install -y poppler-utils libreoffice

❌ Noch nicht implementiert

5. xAI Service (xai_service.py)

Anforderungen:

• File Upload zu xAI (basierend auf test_xai_collections_api.py)
• Add File zu Collections
• Remove File von Collections
• File Download von EspoCRM

Referenz-Code vorhanden:

• /opt/motia-iii/bitbylaw/test_xai_collections_api.py (630 Zeilen, alle xAI Operations getestet)

Implementierungs-Plan:

class XAIService:
    def __init__(self, context=None):
        self.management_key = os.getenv('XAI_MANAGEMENT_KEY')
        self.api_key = os.getenv('XAI_API_KEY')
        self.context = context
    
    async def upload_file(self, file_content: bytes, filename: str) -> str:
        """Upload File zu xAI → returns file_id"""
        # Multipart/form-data upload
        # POST https://api.x.ai/v1/files
        pass
    
    async def add_to_collection(self, collection_id: str, file_id: str):
        """Add File zu Collection"""
        # POST https://management-api.x.ai/v1/collections/{collection_id}/documents/{file_id}
        pass
    
    async def remove_from_collection(self, collection_id: str, file_id: str):
        """Remove File von Collection"""
        # DELETE https://management-api.x.ai/v1/collections/{collection_id}/documents/{file_id}
        pass
    
    async def download_from_espocrm(self, attachment_id: str) -> bytes:
        """Download File von EspoCRM Attachment"""
        # GET https://crm.bitbylaw.com/api/v1/Attachment/file/{attachment_id}
        pass

📋 Integration Checklist

Vollständiger Upload-Flow:

1. ✅ Webhook empfangen → Event emittieren
2. ✅ Event Handler: Lock acquire
3. ✅ Document laden von EspoCRM
4. ✅ Entscheidung: Sync nötig? (Datei-Status, Hash-Check, Collections)
5. ⏳ Download File von EspoCRM
6. ⏳ Hash berechnen (MD5/SHA)
7. ⏳ Thumbnail generieren
8. ❌ Upload zu xAI (falls neu oder Hash changed)
9. ❌ Add zu Collections
10. ⏳ Update EspoCRM Metadaten (xaiFileId, xaiCollections, xaiSyncedHash, thumbnail)
11. ✅ Lock release

Datei-Stati in EspoCRM:

• "Neu": Komplett neue Datei → xAI Upload + Collection Add
• "Geändert": File-Inhalt geändert → xAI Re-Upload + Collection Update
• "Gesynct": Erfolgreich gesynct, keine Änderungen
• "Fehler": Sync fehlgeschlagen (mit Error-Message)

EspoCRM Custom Fields:

Erforderlich für Document Entity:

• dateiStatus (Enum): "Neu", "Geändert", "Gesynct", "Fehler"
• md5 (String): MD5 Hash des Files
• sha (String): SHA Hash des Files
• xaiFileId (String): xAI File ID
• xaiCollections (Array): JSON Array von Collection IDs
• xaiSyncedHash (String): Hash beim letzten erfolgreichen Sync
• xaiSyncStatus (Enum): "syncing", "synced", "failed"
• xaiSyncError (Text): Fehlermeldung bei Sync-Fehler
• preview (Attachment): Vorschaubild im WebP-Format (600x800px)

🚀 Nächste Schritte

Priorität 1: xAI Service

• Code aus test_xai_collections_api.py extrahieren
• In services/xai_service.py übertragen
• EspoCRM Download-Funktion implementieren

Priorität 2: Thumbnail-Generator

• Dependencies installieren
• PDF-Thumbnail implementieren
• EspoCRM Upload-Methode erweitern

Priorität 3: Integration testen

• Document in EspoCRM anlegen
• Datei-Status auf "Neu" setzen
• Webhook triggern
• Logs analysieren

📚 Referenzen

• xAI API Tests: /opt/motia-iii/bitbylaw/test_xai_collections_api.py
• EspoCRM API: services/espocrm.py
• Beteiligte Sync (Referenz-Implementierung): steps/vmh/beteiligte_sync_event_step.py