TypeScript-SDK-Design

laya-client ist ein abhängigkeitsfreier HTTP-Client für einen selbst gehosteten laya-serve-Server. Er nutzt den Endpoint POST /v1/systemone und bringt keinen Python-Produktionscode und keine Server-Abhängigkeiten mit. Das npm-Paket startet bei Version 0.1.0, unabhängig von Python-Releases.

Abgrenzungen

Komponente	Verantwortung
`sdk/typescript`	Frage-/Antworttypen, Presets, Validierung, natives fetch, Fehler und Abbruch
`laya/serve.py`	Vorhandener HTTP-Endpoint, Bearer-Authentifizierung, Health und Anfragelimits
`laya/router.py`	Checkpoint-Auswahl, Laden und Inferenz-Routing
`laya/agent.py`	Tokenisierung, PyTorch-Inferenz und kalibrierte Antwortformatierung
`laya/presets.py`	Quelle für die fünf generierten TypeScript-Frage-Presets

flowchart LR
    A[JavaScript or TypeScript application] --> B[laya-client]
    B -->|POST /v1/systemone| C[Existing Laya server]
    C --> E[Router and local checkpoint]

Das SDK exportiert predict und eine Laya-spezifische health-Sonde. Es liefert ESM, CommonJS und Deklarationen und behält abgeleitete Frage-IDs und choice-Labels. Nutze laya-client, wenn eine JavaScript- oder TypeScript-Anwendung über HTTP mit einem selbst gehosteten Python laya-serve spricht. Nutze laya-ts, wenn die Inferenz direkt in JavaScript über seine lokale ONNX-Runtime laufen soll, ohne Python-Server.

Gemeinsamer Vertrag

Anfragen enthalten state und questions. Sofern nicht konfiguriert oder für eine Vorhersage mitgegeben, lässt laya-client model weg und überlässt laya-serve die Auswahl eines lokalen Checkpoints. Ein model auf Client- oder Aufrufebene kann einen lokalen Checkpoint auswählen, ebenso wie die übrigen Per-Request-Steuerungen in der Tabelle unten. Choice-Label-Arrays werden vor dem Transport auf Maps mit null-Beschreibungen normalisiert.

Antworten bewahren model, answers und Token-usage. Layas routing und das Antwortfeld action sind optionale Erweiterungen; die noul-Konfidenz ist ebenfalls optional. Choice- und Score-Konfidenz, Verteilungen und Score-Legenden bleiben erforderlich. Jede Antwort trägt answer_confidence, die max(p)-Masse auf der gemeldeten Antwort, die bei allen drei Fragetypen dieselbe Größe ist. Ein Aufruf, dem min_confidence mitgegeben wurde, meldet abstention und abstention_threshold auf jeder seiner Antworten und low_confidence: true auf denen unter dem Schwellenwert; ohne gesetzten Schwellenwert wird keiner dieser drei Schlüssel gesendet, und diese Abwesenheit ist der Bericht. Optionale Erweiterungen werden validiert, wenn sie vorhanden sind.

/v1/systemone ist der einzige Endpoint, den der Client aufruft, und er hat keine eigenständige Routing-Methode: laya-client stellt predict und health bereit und sonst nichts, und der Live-Integrationstest stellt sicher, dass der Server 404 für /v1/route antwortet. Die Steuerungen, die der Endpoint tatsächlich beachtet, sind per Request, und jede wird nur gesendet, wenn der Aufrufer die Option mitgegeben hat – eine fehlende Option lässt die eigenen Router(...)-Einstellungen des Deployments zuständig, statt sie mit einem clientseitigen Standard zu überschreiben:

Option	Request-Feld
`model`	`model`
`task`	`task`
`lang`	`lang`
`langGuess`	`lang_guess`
`maxLen`	`max_len`
`headMaxLen`	`head_max_len`
`minConfidence`	`min_confidence`

Eine Option, die nichts bedeuten kann, wird lokal abgelehnt, bevor die Anfrage hinausgeht: ein leeres task, ein Budget, das keine positive ganze Zahl ist, ein Schwellenwert außerhalb von [0, 1], oder eine Threshold-Map, die leer ist oder einen Wert außerhalb von [0, 1] enthält. Nichts wird still ignoriert. Layas öffentliches /health gibt status, loaded und device zurück. Eine Vorhersage prüft nie zuerst den Health-Zustand.

FastAPI-Detailstrings und Validierungs-Arrays werden als LayaAPIError-Meldungen/-Details bewahrt. Strukturierte Fehler-Hüllen kompatibler Backends werden ebenfalls akzeptiert. Anfragen haben konfigurierbare Fristen und Abbruch durch den Aufrufer und werden nie automatisch wiederholt.

Verifikation und Release

Unit-Tests decken Anfrageaufbau, alle Antwortformen, Laya-Erweiterungen, FastAPI-Fehler, JSON-Validierung, Fristen und Abbruch ab und halten die Steuertabelle dieser Seite an die Felder, die der Client tatsächlich auf die Leitung legt. Typprüfungen decken optionale Metadaten, abgeleitete Antworttypen und ESM-/CommonJS-Konsumenten ab. Der Live-Integrationstest startet die unveränderte laya.serve-Anwendung mit einem winzigen Offline-Checkpoint, vergleicht SDK- Vorhersagen mit direkter Python-Inferenz und übt Routing, Presets, Authentifizierung und Anfragelimits. CI führt die SDK-Checks auf Node.js 22 und 24 aus.

Winzige Zufallsgewichte verifizieren Transport und numerische Parität, nicht die Qualität oder Leistung des vorab trainierten Modells.

Siehe den SDK-Leitfaden für Einrichtung, Beispiele und npm- Veröffentlichung. Das Paket wird unter dem Namen laya-client veröffentlicht. Python-Release-Workflows bleiben unverändert.