# Langdock + ShinrAI

Ausgewählte Modellaufrufe und Dokumentübertragungen mit ShinrAI schützen. Version **0.1.0**, MIT-Lizenz, direkt aus diesem Paket installierbar. Eine Verfügbarkeit im Marktplatz wird nicht behauptet.

**Prüfstand:** Der öffentliche HTTPS-Endpunkt wurde mit echten Modellaufrufen, beiden Antwortmodi und Streaming geprüft. Upload-, Fehler- und Weiterleitungstests bestehen. Die Einrichtung in einem echten Langdock-Arbeitsbereich, BYOK-Aktivierung, Wissensindizierung und Bedienabläufe sind **bis zur Bereitstellung des Zugangs offen**. Das Paket bleibt bis dahin eine Vorschau.

## Was wird geschützt?

| Einrichtung | Geschützte Übertragung | Wo Originale verbleiben |
| --- | --- | --- |
| Langdock → eigene Relay-Instanz → Modellanbieter | Nachrichten und abgerufener Text für das ausgewählte Modell | Langdock erhält Eingaben in seiner Oberfläche und bereits hochgeladene Inhalte |
| Lokale Datei → ShinrAI → Upload-Helfer | Geschützter Text oder eine geschwärzte PDF-Kopie vor dem Upload | Die lokale Originaldatei bleibt erhalten |
| Eigene Anwendung → Relay → Langdock Completion API | Unterstützte Modellnachrichten vor dem Versand an Langdock | Originaleingaben bleiben in Ihrer Anwendung |

Das Relay unterstützt Text, Funktionsaufrufe mit JSON-Argumenten, Streaming und Folgefragen. Rohe Bild-, Audio- und Dateiinhalte sowie unbekannte Schemafelder werden abgewiesen. Dokumente vorher separat schützen. Protokollkennungen und JSON-Feldnamen müssen feste technische Bezeichner sein. Wiederhergestellte Werkzeugargumente sind für lokale Werkzeuge bestimmt; spätere externe Übertragungen müssen erneut geschützt werden.

## Eigene geschützte Modelle mit BYOK

1. ShinrAI-Schlüssel in der Konsole erstellen. Den vorhandenen Modellanbieter-Schlüssel im eigenen Relay hinterlegen. Zusätzlich einen zufälligen Relay-Schlüssel erzeugen; ausschließlich dieser wird in Langdock eingetragen.
2. `relay.env.example` nach `relay.env` kopieren, Verbindungen, Schlüssel und Modell eintragen, mit `chmod 600 relay.env` schützen. Mit `docker compose up -d --build relay` starten. Das benachbarte Verzeichnis `python` ist Teil des Installationspakets und wird zum Bauen benötigt.
3. Das Relay über den eigenen HTTPS-Eingang erreichbar machen. `Caddyfile.example` zeigt eine Konfiguration für Caddy auf dem Host und Port 4010. Öffentlich werden ausschließlich die beiden authentifizierten API-Routen bereitgestellt. Ein gültiges öffentlich erreichbares TLS-Zertifikat ist erforderlich.
4. BYOK für den Langdock-Arbeitsbereich aktivieren lassen. In den Modelleinstellungen zwei OpenAI-kompatible Modelle anlegen. Basis-URL: `https://relay.ihr-unternehmen.example/v1`. API-Schlüssel: Relay-Schlüssel. Modellkennungen: `shinrai-private` und `shinrai-restored`. Anzeigenamen: **ShinrAI – Pseudonyme beibehalten** und **ShinrAI – Antworten wiederherstellen**. Kontextgröße entsprechend dem verwendeten Modell setzen; Bildeingaben deaktivieren.
5. Beide Modelle testen und speichern. Sichtbarkeit für die vorgesehenen Personen/Gruppen setzen. Standardmodelle und sämtliche Ausweichmodelle prüfen: ausschließlich weitere geschützte Relay-Verbindungen verwenden oder Ausweichverbindungen entfernen. Eine direkte Verbindung zum Modellanbieter würde den Schutz umgehen. Externe Werkzeuge in der Referenzeinrichtung deaktivieren.
6. Das ausgewählte Modell bitten, `max.mustermann@example.org` zu wiederholen. Der private Modus liefert einen Ersatzwert; der Wiederherstellungsmodus die erkannte Originaladresse. Anschließend Wissensabfrage, Quellenangabe, Folgefrage und einen absichtlich nicht erreichbaren Relay-Endpunkt testen. Letzterer muss einen Fehler auslösen.

Offizielle Anleitungen: [Endpunkt](https://docs.langdock.com/en/admin/byok/setup-guides), [Aktivierung](https://docs.langdock.com/en/admin/byok/byok-setup), [Modelle und Sichtbarkeit](https://docs.langdock.com/en/admin/byok/adding-models), [Ausweichmodelle](https://docs.langdock.com/en/admin/byok/fallback-models).

## Geschützte Wissens-Uploads

Dem Langdock-Schlüssel den Knowledge-Folder-API-Bereich und Bearbeitungszugriff auf die Ziel-Wissensbasis geben. Python-Paket mit `pip install ../python` installieren. `SHINRAI_API_KEY` und `LANGDOCK_API_KEY` in einer privaten Umgebungskonfiguration oder über ihre `_FILE`-Varianten bereitstellen:

```sh
shinrai-langdock check --language de
shinrai-langdock upload kundenakte.pdf --folder IHRE_ORDNER_ID --format text --language de
shinrai-langdock upload scan.pdf --folder IHRE_ORDNER_ID --format pdf --language de
```

`check` prüft ShinrAI mit synthetischen Daten und bestätigt keinen Langdock-Arbeitsbereich. Unterstützt werden TXT, PDF und DOCX bis 10 MB, 100 Seiten und 125.000 extrahierten Zeichen. Textausgabe eignet sich für die Wissenssuche; PDF-Ausgabe ist eine abgeflachte geschwärzte Kopie. Originaldateiname, Quell-URL und Zuordnungstabelle werden nicht übertragen. Bearbeitbare DOCX-Ausgabe ist nicht enthalten. Unvollständige Verarbeitung bricht den Upload ab. Temporäre ShinrAI-Aufträge werden nach dem Download gelöscht; liegengebliebene Ergebnisse verfallen spätestens nach 24 Stunden.

Mit Docker: `knowledge.env.example` nach `knowledge.env` kopieren und schützen, ausgewählte Dateien in `input/` ablegen, dann `docker compose run --rm knowledge upload /input/kundenakte.pdf --folder IHRE_ORDNER_ID --language de` ausführen. `upload-folder.sh` verarbeitet ausdrücklich ausgewählte Dateien nacheinander und stoppt beim ersten Fehler.

Ziel ist die [Knowledge-Upload-API](https://docs.langdock.com/en/developer/knowledge-folder-api/upload-file). Nach einem unterbrochenen Upload zuerst die Wissensbasis prüfen: Die geschützte Datei könnte bereits angekommen sein. Originale werden bei Fehlern niemals als Ersatz hochgeladen.

## Eigene Anwendungen und Fehlerbehebung

Für Anwendungen, die Langdock aufrufen, eine separate Relay-Instanz mit den Completion-API-Werten aus `relay.env.example` einrichten. Die Anwendung verwendet Relay-URL, Relay-Schlüssel und eine ShinrAI-Modellkennung. Langdock-Schlüssel, Zielregion und Modell verbleiben in der Relay-Konfiguration. Die [Completion-API-Dokumentation](https://docs.langdock.com/en/developer/completion-api/openai) beschreibt die Modellauswahl. Ein BYOK-Modell darf nicht über Langdock auf dasselbe Relay zurückverweisen; das würde eine Schleife erzeugen.

401: Zuordnung der drei getrennten Schlüssel prüfen. 400: Nicht unterstützte Inhalte prüfen, keinen ungeschützten Ersatzweg aktivieren. 503: ShinrAI-Verbindung, Guthaben und Ablauf des Schlüssels prüfen. 502: Modellanbieter und Modell prüfen. Upload 403: Freigabe und Bearbeitungsrechte der Wissensbasis prüfen. Öffentliche Verbindung fehlgeschlagen: TLS, Endung `/v1`, Sichtbarkeit und BYOK-Aktivierung prüfen.

QA-Endpunkt: `https://api-sbx.shinrai.innovius.io/integrations/langdock/v1`. Der Relay-Schlüssel steht ausschließlich in der geschützten Übergabe. `reports/langdock03-endpoint.json` trennt bestandene Endpunktprüfungen von der offenen Arbeitsbereichsprüfung. Screenshots aus einem echten Langdock-Arbeitsbereich können erst nach Zugang erstellt werden; simulierte Screenshots werden nicht als Nachweis verwendet.