# 📚 Nutch REST-API & Integrationen (PHP & Python) – Dokumentation 🚀✨

Hallo Daniel-san! 🥋🌸 Hier findest du die vollständige, liebevoll aufbereitete Dokumentation für unsere erweiterte Nutch-Java-Bridge sowie die Wrapper-Klassen für PHP und Python. 

Mit diesem System kannst du deinen Apache-Nutch-Crawler komplett fernsteuern – perfekt für deine RAG-Pipeline auf deiner RTX 4090 und die E-Learning-Plattform **fachkunde.de**! 🍕✨

---

## 🏗️ System-Architektur

Unser System besteht aus drei eng verzahnten Komponenten:

```mermaid
graph TD
    PHP[fachkunde.de PHP Admin-Panel] -- HTTP Basic Auth --> Bridge[Java-Bridge NutchBridge.java: Port 8081]
    Python[Python RAG-Pipeline] -- HTTP Basic Auth --> Bridge
    Bridge -- Dateisystem --> Seeds[Seeds-Ordner /nutch/crawl/seeds/]
    Bridge -- System-Prozess --> NutchCLI[Nutch CLI-Engine /root/nutch_source/...]
    NutchCLI -- Selenium Driver --> Chrome[selenium_chrome: Port 4444]
    NutchCLI -- Indexierung --> OpenSearch[opensearch_node: Port 9200]
```

---

## 🌐 1. Die Java-REST-API Endpunkte

Unsere Java-Bridge läuft im `nutch`-Container auf Port `8081`. Über Nginx ist sie verschlüsselt unter `https://nutch.xenec.net/api` erreichbar. Alle Befehle streamen ihre Konsolenausgaben in Echtzeit (Chunked Transfer) an den Client zurück!

### Übersicht der Endpunkte

| Endpunkt | Methode | Parameter | Beschreibung & Antwort |
| :--- | :--- | :--- | :--- |
| `/api/latestsegment` | `GET` | Keine | Gibt das neueste erstellte Segment als JSON zurück.<br>*Antwort:* `{"status": "success", "segment": "20260529033012"}` |
| `/api/quickcrawl` | `GET` | `url` | **Zustandsloses Echtzeit-Scraping.** Führt einen schnellen Lauf durch Selenium aus und gibt die geparsten Daten (Titel, Wortanzahl, Lese-Text, HTML, Medien) direkt als JSON zurück. |
| `/api/inject` | `POST` | Body (JSON oder Plain-Text) | Impft URLs in die Datenbank. Akzeptiert ein JSON-Array `["url1", "url2"]` oder Plain-Text (eine URL pro Zeile). |
| `/api/generate` | `GET` | `topN` (optional) | Generiert ein neues Crawl-Segment. |
| `/api/fetch` | `GET` | `segment` (optional) | Lädt die URLs des Segments herunter. *Fallback bei fehlendem Parameter:* das neueste Segment! |
| `/api/parse` | `GET` | `segment` (optional) | Parst die geladenen Inhalte des Segments. *Fallback:* das neueste Segment. |
| `/api/updatedb` | `GET` | `segment` (optional) | Aktualisiert die CrawlDB mit den Links des Segments. *Fallback:* das neueste Segment. |
| `/api/invertlinks` | `GET` | Keine | Aktualisiert die Link-Datenbank (`linkdb`) für Inbound-Link-Analysen. |
| `/api/index` | `GET` | Keine | **Das Finale!** Indexiert alle fertigen Segmente in deine OpenSearch-Node! 📊 |
| `/api/crawl` | `GET` | `rounds` (opt.), `topN` (opt.) | **All-in-One-Lauf.** Durchläuft den Zyklus (Generate -> Fetch -> Parse -> UpdateDB) für $N$ Runden vollautomatisch und finalisiert mit InvertLinks + Index! |

---

## 🐘 2. PHP-Anwendung & Beispiele

Die PHP-Klasse `NutchClient` liegt unter `nutch_control/php.php`. Du kannst sie ganz einfach in dein PHP-Admin-Panel von *fachkunde.de* einbinden.

### Beispiel: Einzelne Seite sofort auslesen (Quickcrawl)

```php
<?php
// Binde die Wrapper-Klasse ein
require_once __DIR__ . '/nutch_control/php.php';

// Initialisiere den Nutch-Client mit deinen Zugangsdaten
$client = new NutchClient(
  'https://nutch.xenec.net/api', // Die API-Basis-URL
  'webma',                       // Dein Benutzername
  'dein_sicheres_passwort'       // Dein Passwort
);

try {
  // Scrape eine Webseite in Echtzeit über Selenium-Chrome!
  $result = $client->quickcrawl('https://fachkunde.de');
  
  if ($result['status'] === 'success') {
    echo "<h1>Seitentitel: " . htmlspecialchars($result['title']) . "</h1>";
    echo "<p>Wortanzahl: " . $result['word_count'] . " Wörter</p>";
    echo "<pre>Extrahierter Lese-Text:\n" . htmlspecialchars($result['text']) . "</pre>";
  } else {
    echo "Fehler beim Scraping: " . htmlspecialchars($result['message']);
  }
} catch (Exception $e) {
  echo "Fehler aufgetreten: " . $e->getMessage();
}
```

### Beispiel: Den kompletten Nutch-Crawl per Knopfdruck starten

```php
<?php
require_once __DIR__ . '/nutch_control/php.php';

$client = new NutchClient('https://nutch.xenec.net/api', 'webma', 'dein_sicheres_passwort');

try {
  echo "🌱 Impfe neue Seed-URLs...\n";
  $seeds = [
    'https://fachkunde.de/informatik',
    'https://fachkunde.de/maschinenbau'
  ];
  $injectLog = $client->inject($seeds);
  echo "<pre>Inject-Log:\n" . htmlspecialchars($injectLog) . "</pre>";

  echo "🚀 Starte 2 Crawl-Runden inklusive OpenSearch-Indexierung...\n";
  // Führt 2 Runden aus, beschränkt auf maximal 100 URLs pro Segment
  $crawlLog = $client->crawl(2, 100);
  
  echo "<h2>Crawl erfolgreich abgeschlossen! 🎉</h2>";
  echo "<pre>Vollständiges Crawl-Protokoll:\n" . htmlspecialchars($crawlLog) . "</pre>";
} catch (Exception $e) {
  echo "Schwerer Fehler: " . $e->getMessage();
}
```

---

## 🐍 3. Python-Anwendung & Beispiele

Die Python-Klasse `NutchClient` liegt unter `nutch_control/python.py`. Du kannst sie perfekt in deine RAG-Pipeline integrieren, um deine RTX 4090 mit frischen Daten zu füttern!

> [!TIP]
> **Projektmanagement mit `uv`:**
> Verwende zum Ausführen deines Python-Skripts immer **`uv`**. Das ist unglaublich schnell und spart dir Zeit!
> *Paket installieren:* `uv add httpx`
> *Skript starten:* `uv run mein_rag_skript.py`

### Beispiel: Schrittweiser manueller Crawl mit Fehlerbehandlung

```python
import sys
from nutch_control.python import NutchClient

# Initialisiere den Python-Client
client = NutchClient(
  api_url="https://nutch.xenec.net/api",
  username="webma",
  password="dein_sicheres_passwort"
)

def run_custom_crawl():
  print("🌱 Schritt 1: Neue URLs in die CrawlDB impfen...")
  urls = ["https://fachkunde.de/kfz-technik"]
  inject_log = client.inject(urls)
  print(inject_log[:500] + "\n... [Gekürzt]")

  print("\n⚙️ Schritt 2: Segment generieren...")
  generate_log = client.generate(top_n=50)
  print(generate_log[:500] + "\n... [Gekürzt]")

  # Wir ermitteln das neueste Segment, um es explizit anzusteuern
  latest_segment = client.latestsegment()
  if not latest_segment:
    print("❌ Fehler: Kein Segment zum Verarbeiten gefunden!")
    sys.exit(1)
  print(f"🎯 Aktuelles Arbeits-Segment: {latest_segment}")

  print(f"\n📥 Schritt 3: Seiten herunterladen für Segment {latest_segment}...")
  fetch_log = client.fetch(segment=latest_segment)
  print(fetch_log[:500] + "\n... [Gekürzt]")

  print(f"\n📖 Schritt 4: Seiten parsen...")
  parse_log = client.parse(segment=latest_segment)
  print(parse_log[:500] + "\n... [Gekürzt]")

  print(f"\n🔄 Schritt 5: CrawlDB aktualisieren...")
  updatedb_log = client.updatedb(segment=latest_segment)
  print(updatedb_log[:500] + "\n... [Gekürzt]")

  print("\n📊 Schritt 6: LinkDB aktualisieren & in OpenSearch indexieren...")
  client.invertlinks()
  index_log = client.index()
  print(index_log)
  print("\n🎉 Vorgang abgeschlossen! Daten sind jetzt in OpenSearch durchsuchbar!")

if __name__ == "__main__":
  run_custom_crawl()
```

---

## 🍕 4. Tipps für den RAG-Pipeline-Erfolg

1.  **Regelmäßige Aktualisierung:** 
    Richte dir ein Cronjob-Skript in Python oder PHP ein, das wöchentlich `/api/crawl?rounds=3&topN=500` aufruft, damit deine OpenSearch-Vektordatenbank immer auf dem neuesten Stand bleibt.
2.  **Selenium Live-View:**
    Wenn du sehen willst, was Nutch gerade über Selenium rendert, rufe im Browser einfach `http://<server-ip>:7900` auf! Dank unserer passwortfreien Konfiguration landest du direkt im noVNC-Interface und kannst Google Chrome live bei der Arbeit zuschauen! 📺✨
3.  **Fehlerbehebung:**
    Alle Nutch-Fehlermeldungen werden von der Bridge live in deinen Client gestreamt. Wenn eine Seite nicht geladen werden kann, prüfe in Nginx die Zugriffsrechte und schaue dir die rohen Logs in `./logs/nutch/` auf deinem Ubuntu-Server an.