SPB Git

Repository Public

FRONTEND_CONTRACT.md 12.4 KB

# Contrat frontend ⇄ backend — MacLustr LLM API

Le site est 100 % statique (HTML + CSS + modules ES, aucun build, aucune dépendance npm, aucun CDN), servi par FastAPI depuis web/. Tout ce qui est dynamique vient des endpoints ci-dessous.

# Contraintes dures

  • CSP : default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'. Donc : aucun <script> inline, aucun onclick=, aucun script, police ou image externe. Scripts en <script type="module" src="/assets/…">. SVG inline dans le HTML : OK.
  • Polices : pile système (ui-sans-serif, -apple-system, "SF Pro Display", … et ui-monospace, "SF Mono", …).
  • Mode sombre et clair (prefers-color-scheme + bascule manuelle mémorisée en localStorage, attribut data-theme sur <html>), prefers-reduced-motion respecté, responsive (iPhone d'abord), accessible (contrastes AA, focus visibles, navigation clavier, aria-*, cibles tactiles ≥ 44 px).
  • Jetons de design partagés : web/assets/tokens.css (déjà écrit — l'importer, ne pas le dupliquer).
  • Ne jamais afficher une donnée inventée : un chiffre absent s'affiche « — » ; une mesure non disponible (ex. température) s'affiche « non mesurable ». Aucune métrique de démonstration codée en dur.
  • Langue de l'interface : documentation publique en anglais (hero imposé : « MacLustr AI — Intelligence, running locally. » / « High-performance AI inference powered by Apple Silicon and MLX. ») ; Dashboard, connexion et activation en français.

# Pages servies (routage serveur)

URL Fichier Notes
/ web/index.html page d'accueil (hero, exemple, statut live)
/docs, /docs/<section>, /changelog web/docs.html coquille unique, routage client par location.pathname
/playground web/playground.html utilise la vraie API
/status web/status.html
/admin, /admin/<vue> web/admin.html coquille ; ne contient aucune donnée
/setup/<token> web/setup.html activation / récupération par lien unique
404 web/404.html
/assets/* web/assets/ statique
/changelog.json web/changelog.json [{version, date (YYYY-MM-DD), title, changes: [..]}], plus récent en premier

Sections de documentation (slugs de /docs/<slug>) : overview, getting-started, authentication, models, chat-completions, streaming, tool-calling, structured-outputs, sdk-examples, error-handling, rate-limits, performance, changelog, status, playground (ces deux derniers peuvent pointer vers /status et /playground).

# Endpoints publics

  • GET /api/status → {status: "operational"|"unavailable", api_version, models: [{id, display_name, quantization, context_window, available}], engine, last_updated (date ou null), checked_at (epoch s)}
  • GET /openapi.json → contrat OpenAPI 3.1 généré depuis le backend. x-error-codes = {code: {status, description}} ; x-limits = limites serveur ; components.schemas.ChatRequest = schéma de requête réel (à utiliser pour générer les tables de paramètres — ne pas les recopier à la main).
  • GET /health → {status:"ok"} ; GET /ready → 200/503.

# API d'inférence (compatible OpenAI) — utilisée par le Playground

Authentification : Authorization: Bearer mlx_sk_… ou session admin (cookie same-origin + en-tête X-CSRF-Token, voir plus bas). Le Playground propose donc : coller une clé API (gardée en sessionStorage uniquement), ou, si une session admin existe (GET /admin/api/session → authenticated:true), l'utiliser.

  • GET /v1/models → {object:"list", data:[{id, display_name, context_window, max_output_tokens, quantization, license, source:{repo,revision}, capabilities:{chat,streaming,tools,thinking,json_mode}, description}]}
  • POST /v1/chat/completions — champs : model, messages, stream, stream_options.include_usage, max_tokens/max_completion_tokens, temperature (0–2), top_p, top_k, min_p, stop, seed, presence_penalty, frequency_penalty, repetition_penalty, tools, tool_choice (auto|none seulement), response_format (json_object | json_schema — validé côté serveur, pas contraint par grammaire ; garantie de validité en non-streaming seulement, 422 json_validation_failed sinon), logprobs, top_logprobs.
    • Non-streaming : objet chat.completion standard, usage.prompt_tokens_details.cached_tokens inclus, message.reasoning_content si le modèle raisonne, message.tool_calls[{id,type,function:{name,arguments}}].
    • Streaming SSE : lignes data: {chat.completion.chunk}, des commentaires : keepalive pendant le prefill, 1er chunk delta:{role:"assistant",content:""}, puis delta.content / delta.reasoning_content / delta.tool_calls (chaque tool call arrive entier dans un chunk, avec index), chunk final finish_reason, puis (si include_usage) un chunk choices:[] + usage, puis data: [DONE]. Erreur en cours de flux : data: {"error":{…}} puis fin.
    • En-têtes de réponse : x-request-id, x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-limit-tokens, x-ratelimit-remaining-tokens, Retry-After sur 429/503.
  • POST /v1/completions (texte brut : prompt, mêmes paramètres d'échantillonnage).
  • Erreurs : {"error": {"message", "type", "param", "code", "request_id"}}. Types : invalid_request_error, authentication_error, permission_error, not_found_error, rate_limit_error, overloaded_error, api_error.

# Activation par lien unique (/setup/<token>)

Le token est le dernier segment de l'URL. Séquence :

  1. POST /api/setup/status {token} → {valid:false} ou {valid:true, purpose:"setup"|"recovery", expires_at}. Invalide → écran « lien invalide, expiré ou déjà utilisé » (expliquer qu'un nouveau lien se génère sur le Mac mini avec maclustr-llm setup-link ou maclustr-llm recover).
  2. Bouton « Configurer ma clé d'accès » → POST /api/setup/options {token} → {challenge_id, publicKey} (options WebAuthn JSON : décoder base64url → ArrayBuffer pour challenge, user.id, excludeCredentials[].id) → navigator.credentials.create({publicKey}).
  3. POST /api/setup/complete {challenge_id, credential, name} où credential = sérialisation JSON standard (id, rawId b64url, type, response:{clientDataJSON, attestationObject, transports} en b64url, authenticatorAttachment, clientExtensionResults). name = nom libre de la clé (proposer un défaut selon l'appareil, ex. « iPhone », « Mac »). Succès → {ok:true, csrf_token} + cookie de session posé → écran de réussite puis redirection vers /admin.

Utiliser PublicKeyCredential.parseCreationOptionsFromJSON / toJSON() s'ils existent, avec repli manuel. Ne jamais dessiner un faux écran Touch ID / Face ID : on déclenche la feuille système, c'est tout.

# Dashboard (/admin/api/*) — session requise

Cookie de session HttpOnly (invisible du JS). Toute requête non-GET envoie X-CSRF-Token: <csrf_token>. Le jeton CSRF s'obtient de GET /admin/api/session (renouvelé à chaque appel — le rappeler après un 403 csrf_failed), de la connexion, ou de l'activation.

Erreurs d'auth : 401 not_authenticated → écran de connexion ; 401 reauth_required → déclencher la ré-authentification Passkey puis rejouer l'action ; 403 csrf_failed ; 429 too_many_attempts.

Méthode + chemin Rôle
GET /admin/api/session {authenticated:false, activated} ou {authenticated:true, csrf_token, expires_at, recent_auth, reauth_window_s}
POST /admin/api/login/options → {challenge_id, publicKey} ; POST /admin/api/login/verify {challenge_id, credential} → {ok, csrf_token} connexion Passkey (navigator.credentials.get, identifiants découvrables, pas de nom d'utilisateur)
POST /admin/api/reauth/options, POST /admin/api/reauth/verify {challenge_id, credential} authentification récente (actions critiques)
POST /admin/api/logout
GET /admin/api/overview `{api_version, uptime_s, models[], scheduler:{active, queued, max_queue, rejected, queue_timeouts, pressure, engines:[{id, models, healthy, active, max_active, tokens_in_flight, token_budget, capacity, served, last_error}]}, engines:{:{ready, healthy, uptime_s, pid, model, warmup_s, mlx:{active_bytes, peak_bytes, cache_bytes}, prompt_cache:{entries, bytes}, decode_concurrency, prompt_concurrency, versions}}, totals:{requests, errors, prompt_tokens, completion_tokens}, live:{window_s, requests, errors, requests_last_minute, completion_tokens_last_minute, prompt_tokens, completion_tokens, cached_tokens, ttft_ms:{p50,p95,p99}, latency_ms:{p50,p95,p99}, tokens_per_second:{p50,p95}}, system:{ts, cpu:{percent, load_1m, per_core[]}, memory:{total_bytes, used_bytes, available_bytes, wired_bytes, pressure:"normal"
GET /admin/api/system/history?hours=6 {samples:[{ts, cpu:{percent,load_1m}, memory:{…}, swap, disk, network, gpu}]} (1 point/minute, 7 jours max)
`GET /admin/api/analytics?range=1h 24h
GET /admin/api/requests?limit=100[&key_id=] {requests:[{id, ts, key_id, model, endpoint, status, error_code, stream, prompt_tokens, completion_tokens, cached_tokens, queue_ms, ttft_ms, latency_ms, tps, engine}]} — métadonnées seulement, jamais de contenu
GET /admin/api/keys `{keys:[{id, name, app, prefix, priority, models[], endpoints[], rpm, tpm, daily_tokens, monthly_tokens, max_concurrency, expires_at, disabled, created_at, revoked_at, last_used_at, rotated_from, status:"active"
POST /admin/api/keys {name, app, priority, models, endpoints, rpm, tpm, daily_tokens, monthly_tokens, max_concurrency, expires_at} auth récente ; → 201 {key, secret} : afficher secret une seule fois avec bouton copier et avertissement
PATCH /admin/api/keys/{id} mêmes champs (+ disabled)
POST /admin/api/keys/{id}/revoke ; POST /admin/api/keys/{id}/rotate → {key, secret} auth récente
GET /admin/api/keys/{id} {key, usage, series (7 j, pas 1 h), requests (50)}
GET /admin/api/models {models:[{…modèle public…, available, engines[], engine_stats}], benchmarks:[{file, summary, meta}]}
POST /admin/api/engine/reload auth récente ; rechargement contrôlé du moteur (confirmation explicite)
GET /admin/api/security {passkeys:[{id, name, created_at, last_used_at, synced, device_type, transports, credential_id}], sessions:[{id, created_at, expires_at, last_seen_at, ip, user_agent, current}]}
POST /admin/api/passkeys/options → options ; POST /admin/api/passkeys {challenge_id, credential, name} ; DELETE /admin/api/passkeys/{id} auth récente ; ajout / suppression d'une Passkey (la dernière ne peut pas être supprimée : 409 last_passkey)
POST /admin/api/sessions/revoke-all auth récente ; révoque toutes les autres sessions
GET /admin/api/audit?limit=200[&before=<id>] {entries:[{id, ts, actor, event, detail, ip}]}

Valeurs : priority ∈ admin|internal|client|background ; endpoints ∈ chat.completions|completions|models|* ; quotas à 0 = illimité ; horodatages = secondes epoch.

Résumé de benchmark (benchmarks[].summary, si présent) : {model, single:{ttft_ms, tokens_per_second}, concurrency:[{clients, aggregate_tps, per_request_tps, ttft_p50_ms, ttft_p95_ms, latency_p95_ms, error_rate}], peak_memory_bytes, recommended:{max_active}} ; meta = {date, host, chip, mlx, mlx_lm}.

Files main
Menu

Theme