Repository Public
1# Contrat frontend ⇄ backend — MacLustr LLM API23Le site est **100 % statique** (HTML + CSS + modules ES, aucun build, aucune dépendance npm, aucun CDN),4servi par FastAPI depuis `web/`. Tout ce qui est dynamique vient des endpoints ci-dessous.56## Contraintes dures78- **CSP** : `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;9 font-src 'self'; connect-src 'self'`. Donc : **aucun `<script>` inline, aucun `onclick=`**, aucun script,10 police ou image externe. Scripts en `<script type="module" src="/assets/…">`. SVG inline dans le HTML : OK.11- Polices : pile système (`ui-sans-serif, -apple-system, "SF Pro Display", …` et `ui-monospace, "SF Mono", …`).12- Mode sombre **et** clair (`prefers-color-scheme` + bascule manuelle mémorisée en `localStorage`, attribut13 `data-theme` sur `<html>`), `prefers-reduced-motion` respecté, responsive (iPhone d'abord), accessible14 (contrastes AA, focus visibles, navigation clavier, `aria-*`, cibles tactiles ≥ 44 px).15- Jetons de design partagés : `web/assets/tokens.css` (déjà écrit — l'importer, ne pas le dupliquer).16- Ne jamais afficher une donnée inventée : un chiffre absent s'affiche « — » ; une mesure non disponible17 (ex. température) s'affiche « non mesurable ». Aucune métrique de démonstration codée en dur.18- Langue de l'interface : documentation publique en **anglais** (hero imposé : « MacLustr AI — Intelligence,19 running locally. » / « High-performance AI inference powered by Apple Silicon and MLX. ») ; Dashboard,20 connexion et activation en **français**.2122## Pages servies (routage serveur)2324| URL | Fichier | Notes |25|---|---|---|26| `/` | `web/index.html` | page d'accueil (hero, exemple, statut live) |27| `/docs`, `/docs/<section>`, `/changelog` | `web/docs.html` | coquille unique, routage client par `location.pathname` |28| `/playground` | `web/playground.html` | utilise la vraie API |29| `/status` | `web/status.html` | |30| `/admin`, `/admin/<vue>` | `web/admin.html` | coquille ; ne contient aucune donnée |31| `/setup/<token>` | `web/setup.html` | activation / récupération par lien unique |32| 404 | `web/404.html` | |33| `/assets/*` | `web/assets/` | statique |34| `/changelog.json` | `web/changelog.json` | `[{version, date (YYYY-MM-DD), title, changes: [..]}]`, plus récent en premier |3536Sections de documentation (slugs de `/docs/<slug>`) : `overview`, `getting-started`, `authentication`, `models`,37`chat-completions`, `streaming`, `tool-calling`, `structured-outputs`, `sdk-examples`, `error-handling`,38`rate-limits`, `performance`, `changelog`, `status`, `playground` (ces deux derniers peuvent pointer vers39`/status` et `/playground`).4041## Endpoints publics4243- `GET /api/status` → `{status: "operational"|"unavailable", api_version, models: [{id, display_name,44 quantization, context_window, available}], engine, last_updated (date ou null), checked_at (epoch s)}`45- `GET /openapi.json` → contrat OpenAPI 3.1 généré depuis le backend. `x-error-codes` =46 `{code: {status, description}}` ; `x-limits` = limites serveur ; `components.schemas.ChatRequest` = schéma de47 requête réel (à utiliser pour générer les tables de paramètres — ne pas les recopier à la main).48- `GET /health` → `{status:"ok"}` ; `GET /ready` → 200/503.4950## API d'inférence (compatible OpenAI) — utilisée par le Playground5152Authentification : `Authorization: Bearer mlx_sk_…` **ou** session admin (cookie same-origin + en-tête53`X-CSRF-Token`, voir plus bas). Le Playground propose donc : coller une clé API (gardée en `sessionStorage`54uniquement), ou, si une session admin existe (`GET /admin/api/session` → `authenticated:true`), l'utiliser.5556- `GET /v1/models` → `{object:"list", data:[{id, display_name, context_window, max_output_tokens, quantization,57 license, source:{repo,revision}, capabilities:{chat,streaming,tools,thinking,json_mode}, description}]}`58- `POST /v1/chat/completions` — champs : `model`, `messages`, `stream`, `stream_options.include_usage`,59 `max_tokens`/`max_completion_tokens`, `temperature` (0–2), `top_p`, `top_k`, `min_p`, `stop`, `seed`,60 `presence_penalty`, `frequency_penalty`, `repetition_penalty`, `tools`, `tool_choice` (`auto`|`none`61 seulement), `response_format` (`json_object` | `json_schema` — **validé côté serveur, pas contraint par62 grammaire** ; garantie de validité en non-streaming seulement, 422 `json_validation_failed` sinon),63 `logprobs`, `top_logprobs`.64 - Non-streaming : objet `chat.completion` standard, `usage.prompt_tokens_details.cached_tokens` inclus,65 `message.reasoning_content` si le modèle raisonne, `message.tool_calls[{id,type,function:{name,arguments}}]`.66 - Streaming SSE : lignes `data: {chat.completion.chunk}`, des commentaires `: keepalive` pendant le prefill,67 1er chunk `delta:{role:"assistant",content:""}`, puis `delta.content` / `delta.reasoning_content` /68 `delta.tool_calls` (chaque tool call arrive **entier** dans un chunk, avec `index`), chunk final69 `finish_reason`, puis (si `include_usage`) un chunk `choices:[]` + `usage`, puis `data: [DONE]`.70 Erreur en cours de flux : `data: {"error":{…}}` puis fin.71 - En-têtes de réponse : `x-request-id`, `x-ratelimit-limit-requests`, `x-ratelimit-remaining-requests`,72 `x-ratelimit-limit-tokens`, `x-ratelimit-remaining-tokens`, `Retry-After` sur 429/503.73- `POST /v1/completions` (texte brut : `prompt`, mêmes paramètres d'échantillonnage).74- Erreurs : `{"error": {"message", "type", "param", "code", "request_id"}}`. Types :75 `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `rate_limit_error`,76 `overloaded_error`, `api_error`.7778## Activation par lien unique (`/setup/<token>`)7980Le token est le dernier segment de l'URL. Séquence :81821. `POST /api/setup/status {token}` → `{valid:false}` ou `{valid:true, purpose:"setup"|"recovery", expires_at}`.83 Invalide → écran « lien invalide, expiré ou déjà utilisé » (expliquer qu'un nouveau lien se génère sur le Mac84 mini avec `maclustr-llm setup-link` ou `maclustr-llm recover`).852. Bouton « Configurer ma clé d'accès » → `POST /api/setup/options {token}` →86 `{challenge_id, publicKey}` (options WebAuthn JSON : décoder base64url → ArrayBuffer pour `challenge`,87 `user.id`, `excludeCredentials[].id`) → `navigator.credentials.create({publicKey})`.883. `POST /api/setup/complete {challenge_id, credential, name}` où `credential` = sérialisation JSON standard89 (`id`, `rawId` b64url, `type`, `response:{clientDataJSON, attestationObject, transports}` en b64url,90 `authenticatorAttachment`, `clientExtensionResults`). `name` = nom libre de la clé (proposer un défaut selon91 l'appareil, ex. « iPhone », « Mac »). Succès → `{ok:true, csrf_token}` + cookie de session posé →92 écran de réussite puis redirection vers `/admin`.9394Utiliser `PublicKeyCredential.parseCreationOptionsFromJSON` / `toJSON()` s'ils existent, avec repli manuel.95Ne **jamais** dessiner un faux écran Touch ID / Face ID : on déclenche la feuille système, c'est tout.9697## Dashboard (`/admin/api/*`) — session requise9899Cookie de session `HttpOnly` (invisible du JS). Toute requête non-GET envoie `X-CSRF-Token: <csrf_token>`.100Le jeton CSRF s'obtient de `GET /admin/api/session` (renouvelé à chaque appel — le rappeler après un 403101`csrf_failed`), de la connexion, ou de l'activation.102103Erreurs d'auth : 401 `not_authenticated` → écran de connexion ; 401 `reauth_required` → déclencher la104ré-authentification Passkey puis rejouer l'action ; 403 `csrf_failed` ; 429 `too_many_attempts`.105106| Méthode + chemin | Rôle |107|---|---|108| `GET /admin/api/session` | `{authenticated:false, activated}` ou `{authenticated:true, csrf_token, expires_at, recent_auth, reauth_window_s}` |109| `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) |110| `POST /admin/api/reauth/options`, `POST /admin/api/reauth/verify {challenge_id, credential}` | authentification récente (actions critiques) |111| `POST /admin/api/logout` | |112| `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:{<id>:{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"|"warn"|"critical", free_percent}, swap:{total_bytes, used_bytes}, disk:{total_bytes, free_bytes}, network:{rx_bytes_per_s, tx_bytes_per_s}, gpu:{utilization_pct, in_use_memory_bytes, allocated_memory_bytes}|null, thermal:{state, cpu_speed_limit_pct, temperature_c:null, temperature_note}}, hardware:{chip, model, macos, cpu_cores, performance_cores, efficiency_cores, memory_bytes}}` — à rafraîchir toutes les 3 à 5 s sur la vue générale |113| `GET /admin/api/system/history?hours=6` | `{samples:[{ts, cpu:{percent,load_1m}, memory:{…}, swap, disk, network, gpu}]}` (1 point/minute, 7 jours max) |114| `GET /admin/api/analytics?range=1h|24h|7d|30d[&key_id=]` | `{range, step_s, since, series:[{t, requests, errors, prompt_tokens, completion_tokens, cached_tokens, avg_ttft_ms, avg_latency_ms, avg_queue_ms, tokens_per_second}], by_key:[{k, name, app, requests, errors, prompt_tokens, completion_tokens}], by_model:[…], by_endpoint:[…]}` (les intervalles sans trafic sont absents de `series` : les combler à 0 côté client) |115| `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 |116| `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"|"disabled"|"expired"|"revoked", usage:{active, rpm_used, tpm_used, day_tokens, month_tokens}}], models:[ids]}` |117| `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 |118| `PATCH /admin/api/keys/{id}` | mêmes champs (+ `disabled`) |119| `POST /admin/api/keys/{id}/revoke` ; `POST /admin/api/keys/{id}/rotate` → `{key, secret}` | **auth récente** |120| `GET /admin/api/keys/{id}` | `{key, usage, series (7 j, pas 1 h), requests (50)}` |121| `GET /admin/api/models` | `{models:[{…modèle public…, available, engines[], engine_stats}], benchmarks:[{file, summary, meta}]}` |122| `POST /admin/api/engine/reload` | **auth récente** ; rechargement contrôlé du moteur (confirmation explicite) |123| `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}]}` |124| `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`) |125| `POST /admin/api/sessions/revoke-all` | **auth récente** ; révoque toutes les autres sessions |126| `GET /admin/api/audit?limit=200[&before=<id>]` | `{entries:[{id, ts, actor, event, detail, ip}]}` |127128Valeurs : `priority` ∈ `admin|internal|client|background` ; `endpoints` ∈ `chat.completions|completions|models|*` ;129quotas à 0 = illimité ; horodatages = secondes epoch.130131Résumé de benchmark (`benchmarks[].summary`, si présent) : `{model, single:{ttft_ms, tokens_per_second},132concurrency:[{clients, aggregate_tps, per_request_tps, ttft_p50_ms, ttft_p95_ms, latency_p95_ms, error_rate}],133peak_memory_bytes, recommended:{max_active}}` ; `meta` = `{date, host, chip, mlx, mlx_lm}`.134