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, aucunonclick=, 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", …etui-monospace, "SF Mono", …). - Mode sombre et clair (
prefers-color-scheme+ bascule manuelle mémorisée enlocalStorage, attributdata-themesur<html>),prefers-reduced-motionrespecté, 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|noneseulement),response_format(json_object|json_schema— validé côté serveur, pas contraint par grammaire ; garantie de validité en non-streaming seulement, 422json_validation_failedsinon),logprobs,top_logprobs.- Non-streaming : objet
chat.completionstandard,usage.prompt_tokens_details.cached_tokensinclus,message.reasoning_contentsi le modèle raisonne,message.tool_calls[{id,type,function:{name,arguments}}]. - Streaming SSE : lignes
data: {chat.completion.chunk}, des commentaires: keepalivependant le prefill, 1er chunkdelta:{role:"assistant",content:""}, puisdelta.content/delta.reasoning_content/delta.tool_calls(chaque tool call arrive entier dans un chunk, avecindex), chunk finalfinish_reason, puis (siinclude_usage) un chunkchoices:[]+usage, puisdata: [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-Aftersur 429/503.
- Non-streaming : objet
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 :
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 avecmaclustr-llm setup-linkoumaclustr-llm recover).- Bouton « Configurer ma clé d'accès » →
POST /api/setup/options {token}→{challenge_id, publicKey}(options WebAuthn JSON : décoder base64url → ArrayBuffer pourchallenge,user.id,excludeCredentials[].id) →navigator.credentials.create({publicKey}). POST /api/setup/complete {challenge_id, credential, name}oùcredential= sérialisation JSON standard (id,rawIdb64url,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}.