breakpilot-pwa/ai-content-generator/README.md

AI Content Generator Service

Automatische Generierung von H5P-Lerninhalten mit Claude AI und YouTube-Integration.

Übersicht

Der AI Content Generator analysiert hochgeladene Lernmaterialien und generiert automatisch alle 8 H5P-Content-Typen:

1. Quiz - Multiple Choice Fragen
2. Interactive Video - YouTube-Videos mit Interaktionen
3. Course Presentation - Präsentationsfolien
4. Flashcards - Lernkarten
5. Timeline - Chronologische Darstellungen
6. Drag and Drop - Zuordnungsaufgaben
7. Fill in the Blanks - Lückentexte
8. Memory Game - Memory-Paare

Funktionen

Material-Analyse

• PDF: Textextraktion aus mehrseitigen PDFs
• Images: OCR-Texterkennung (Tesseract)
• DOCX: Word-Dokument Analyse
• Text: Plain-Text Dateien

YouTube-Integration

• Automatische Video-Suche (optional)
• Transkript-Analyse (deutsch/englisch)
• KI-generierte Interaktionen mit Zeitstempeln

Claude AI Integration

• Altersgerechte Content-Generierung
• Basiert auf hochgeladenen Materialien
• JSON-strukturierte Ausgaben

Installation

Lokale Entwicklung

cd ai-content-generator

# Virtual Environment erstellen
python3 -m venv venv
source venv/bin/activate

# Dependencies installieren
pip install -r requirements.txt

# Tesseract OCR installieren (für Image-Analyse)
# macOS:
brew install tesseract tesseract-lang

# Ubuntu/Debian:
sudo apt-get install tesseract-ocr tesseract-ocr-deu

Umgebungsvariablen

Kopiere .env.example zu .env:

cp .env.example .env

Setze deinen Anthropic API Key:

ANTHROPIC_API_KEY=your-api-key-here

Docker

# Content Services starten (inkl. AI Generator)
docker-compose -f docker-compose.content.yml up -d

# Nur AI Generator neu bauen
docker-compose -f docker-compose.content.yml up -d --build ai-content-generator

API Endpoints

Health Check

GET /health

Content Generierung starten

POST /api/generate-content
Content-Type: multipart/form-data

# Form Data:
- topic: string (z.B. "Das Auge")
- description: string (optional)
- target_grade: string (z.B. "5-6", "7-8")
- materials: File[] (PDFs, Images, DOCX)

Beispiel:

curl -X POST http://localhost:8004/api/generate-content \
  -F "topic=Das Auge" \
  -F "description=Biologie Thema für Klasse 7" \
  -F "target_grade=7-8" \
  -F "materials=@auge_skizze.pdf" \
  -F "materials=@auge_text.docx"

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Content generation started"
}

Generation Status prüfen

GET /api/generation-status/{job_id}

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "progress": 50,
  "current_step": "Generating Quiz questions..."
}

Generierte Inhalte abrufen

GET /api/generated-content/{job_id}

Response:

{
  "topic": "Das Auge",
  "target_grade": "7-8",
  "generated_at": "2025-01-15T10:30:00Z",
  "content_types": {
    "quiz": {
      "type": "quiz",
      "title": "Quiz: Das Auge",
      "questions": [...]
    },
    "interactive_video": {
      "type": "interactive-video",
      "videoUrl": "https://youtube.com/watch?v=...",
      "interactions": [...]
    },
    "flashcards": {...},
    "timeline": {...},
    "drag_drop": {...},
    "fill_blanks": {...},
    "memory": {...},
    "course_presentation": {...}
  }
}

YouTube Video-Suche

POST /api/youtube-search
Content-Type: application/json

{
  "query": "Das Auge Biologie",
  "max_results": 5
}

Content-Typen Struktur

Quiz

{
  "type": "quiz",
  "title": "Quiz: Das Auge",
  "questions": [
    {
      "question": "Was ist die Funktion der Pupille?",
      "options": ["A", "B", "C", "D"],
      "correct_answer": 0,
      "explanation": "..."
    }
  ]
}

Interactive Video

{
  "type": "interactive-video",
  "videoUrl": "https://youtube.com/watch?v=xyz",
  "interactions": [
    {
      "time": "01:30",
      "seconds": 90,
      "type": "question",
      "title": "Verständnisfrage",
      "content": "Was wurde gerade erklärt?"
    }
  ]
}

Flashcards

{
  "type": "flashcards",
  "cards": [
    {
      "id": 1,
      "front": "Begriff",
      "back": "Definition"
    }
  ]
}

Timeline

{
  "type": "timeline",
  "events": [
    {
      "id": 1,
      "year": "1800",
      "title": "Ereignis",
      "description": "..."
    }
  ]
}

Drag and Drop

{
  "type": "drag-drop",
  "title": "Zuordnung",
  "zones": [
    {"id": 1, "name": "Kategorie 1"}
  ],
  "draggables": [
    {"id": 1, "text": "Element", "correctZoneId": 1}
  ]
}

Fill in the Blanks

{
  "type": "fill-blanks",
  "title": "Lückentext",
  "text": "Das Auge hat eine *Linse* und eine *Netzhaut*.",
  "hints": "Tipps..."
}

Memory Game

{
  "type": "memory",
  "pairs": [
    {
      "id": 1,
      "card1": "Begriff 1",
      "card2": "Zugehöriger Begriff"
    }
  ]
}

Course Presentation

{
  "type": "course-presentation",
  "slides": [
    {
      "id": 1,
      "title": "Folie 1",
      "content": "...",
      "backgroundColor": "#ffffff"
    }
  ]
}

Technologie-Stack

• FastAPI: Web Framework
• Anthropic Claude: AI Content Generation
• youtube-transcript-api: YouTube Transkript-Analyse
• PyPDF2: PDF-Verarbeitung
• Pillow + Tesseract: OCR für Bilder
• python-docx: Word-Dokument Verarbeitung

Entwicklung

Tests ausführen

# Unit Tests (TODO)
pytest tests/

# Integration Tests (TODO)
pytest tests/integration/

Service lokal starten

source venv/bin/activate
uvicorn app.main:app --reload --port 8004

API-Dokumentation: http://localhost:8004/docs

Limitierungen

• YouTube API: Ohne API Key wird Fallback verwendet
• OCR: Erfordert Tesseract Installation
• Anthropic API: Kostenpflichtig (Claude API Key erforderlich)
• Job Store: In-Memory (TODO: Redis Backend)

TODO

• Redis Backend für Job Store
• Celery für Background Tasks
• Rate Limiting
• Unit & Integration Tests
• API Authentication
• Webhook Notifications
• Batch Processing
• Content Quality Validation

Support

Bei Fragen oder Problemen:

• GitHub Issues
• Dokumentation: /docs/ai-content-generator/