Aller au contenu
Connexion
Documentation SDK — ELYSÉA CERVEAU

La référence est le contrat.
Tout ce qui n'est pas ici n'existe pas dans le SDK.

Authentification, API surface, 8 prohibitions Guardian, paliers, trust mark, sandbox et codes d'erreur. Source : canons SDK figés — aucun contenu généré par IA.

QuickstartTélécharger la doc (PDF)SDK & Tarifs

§1 — Authentification

Clé de test sk_test_

Sandbox uniquement. Aucune donnée utilisateur réelle. Aucune facturation UAM. Toutes les prohibitions Guardian sont actives (le sandbox est un test de conformité, pas un mode permissif).

Clé de production sk_live_

Production uniquement. Facturation UAM active (token LLM à la charge du constructeur — Décision KJ). Mélanger sk_test_ en production ou sk_live_ en sandbox lève immédiatement ELYSEA_ENV_MISMATCH.

typescript
import { ElyseaClient } from '@elysea/sdk';

const elysea = new ElyseaClient({
  apiKey:      process.env.ELYSEA_API_KEY!,   // sk_test_… ou sk_live_…
  appId:       process.env.ELYSEA_APP_ID!,
  region:      'EU',                           // requis — hébergement EU strict
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
});

Le champ regionest obligatoire. ELYSÉA opère exclusivement en EU — aucun fallback vers des régions hors-UE n'est disponible.

§2 — API surface

identity.resolve()

typescript
const { coreUserId } = await elysea.identity.resolve({
  userJwt: req.headers.authorization, // JWT émis par votre auth provider
});
// coreUserId : identifiant opaque dérivé de l'ELYSEAID
// Jamais le pseudonyme réel — jamais l'identité sous-jacente

pipeline.run()

typescript
const result = await elysea.pipeline.run({
  userInput:           message,
  coreUserId,
  conversationHistory: history,   // Message[] — { role, content }[]
});

// result : PipelineResult
// {
//   response:        string,           // réponse texte
//   posture:         string,           // posture Guardian active
//   signal:          string | null,    // signal Guardian si déclenchement
//   canonConformance: boolean,
//   guardianLog:     GuardianLog,
// }

memory.write()

typescript
await elysea.memory.write({
  coreUserId,
  type:     'context',         // l'un des 5 types autorisés (FIGÉ)
  content:  'Travaille en UTC+2, équipe distribuée.',  // ≤ 256 caractères
  ttlDays:  90,                // TTL obligatoire — pas de persistance infinie
  scope:    'your-app-id',     // scopé à votre app uniquement
});
// Requiert le consentement scopé actif de l'utilisateur (P7 sinon)

guardian.audit()

typescript
const log = await elysea.guardian.audit({
  coreUserId,
  event: 'session_close',
});
// Retourne le GuardianLog de la session
// Utile pour la conformité et le débogage — lecture seule
ELYSEA.ARCH.CANON_GUARDIAN_SDK.v1 — FIGÉ

§3 — 8 prohibitions

Un tiers peut RESTREINDRE — jamais affaiblir.

Vous pouvez configurer ELYSÉA pour être plus strict que la baseline (bloquer des sujets, réduire les types de mémoire utilisés, exiger un consentement plus fin). Vous ne pouvez pas configurer ELYSÉA pour être moins protecteur. C'est architecturalement impossible : le Guardian SDK rejette toute configuration qui affaiblirait une prohibition existante.

Comportement de bloc : le Guardian ne retourne jamais HTTP 403. Il retourne une réponse pipeline normale — posture: “present_neutral”, signal: “guardian_block”. L'utilisateur ne sait pas qu'une tentative de contournement a eu lieu. Le log interne, lui, le sait.

P1BLOC immédiat

Contourner ou modifier D0

Toute tentative de remplacer, neutraliser ou court-circuiter la directive éthique socle (D0). D0 ne peut être restreinte — jamais affaiblie.

signal: P1_D0_OVERRIDE_ATTEMPT
P2BLOC immédiat

Accéder à la mémoire brute

Lecture directe des items mémoire d'un utilisateur sans passer par le pipeline de résolution consentie. Aucun endpoint SDK n'existe pour ça.

signal: P2_MEMORY_RAW_ACCESS
P3BLOC immédiat

Bypass de la safety gate

Toute requête conçue pour contourner les garde-fous (jailbreak de prompt, injection système, wrapping LLM externe non signé).

signal: P3_SAFETY_GATE_BYPASS_ATTEMPT
P4WARN

LLM sans signature conforme

Appel pipeline vers un modèle LLM ne présentant pas de watermark ELYSÉA valide. Loggé — escalade si récurrent.

signal: P4_NON_CONFORM_LLM_SIGNATURE
P5BLOC

Watermark absent dans la sortie

Réponse pipeline renvoyée sans métadonnée de traçabilité ELYSÉA. La chaîne de conformité est rompue.

signal: P5_WATERMARK_MISSING
P6BLOC immédiat

Croisement cross-constructeur sans consentement

Exploitation des données mémoire issues d'une autre app de l'écosystème sans consentement scopé actif de l'utilisateur.

signal: P6_CROSS_BUILDER_CONSENT_MISSING
P7BLOC

Appel sans token de consentement

Requête pipeline ou memory.write lancée sans fournir le token de consentement ELYSÉA valide pour l'utilisateur concerné.

signal: P7_MISSING_CONSENT_TOKEN
P8WARN → RÉVOCATION

Badge non certifié affiché

Affichage d'un trust mark ELYSÉA (Powered by / Certified Ethical) sans certification valide. Warn d'abord — révocation immédiate si fraude confirmée.

signal: P8_UNCERTIFIED_BADGE_USAGE

Source : ELYSEA.ARCH.CANON_GUARDIAN_SDK.v1 §3 — ELYSEA.SDK.INTEGRITY_PROTECTION.v1 §4. Ce canon est figé — ELYSÉA ne peut pas retirer une prohibition par décision commerciale.

§4 — Paliers & accès

PalierPrixCléEnvironnementQuotaBadge
DiscoveryGratuitsk_test_Sandbox · jusqu'à 1 000 MAU/mois1 app · communautairePowered by ELYSÉA
Montée en charge2,50 €/MAUsk_live_Production · auto au-delà de 1 000 MAUSans engagement · Stripe autoPowered by ELYSÉA
Pro Start99 €/mois + 1,80 €/MAUsk_live_Production · jusqu'à 3 appsSupport emailPowered by ELYSÉA
Pro Scale299 €/mois + 1,50 €/MAUsk_live_Production · apps illimitéesSupport prioritaire · Skills betaPowered by ELYSÉA
EnterpriseÀ partir de 1 500 €/moissk_live_Production · SLA contractuelSur devis · on-premise possibleCertified Ethical (audit inclus)
Genesis

Programme fermé — co-développement avec ELYSÉA

29 €/mois à viesk_live_Production · accès avant-première50 premiers · 5 ans bloquésGenesis Partner

BYOK obligatoire (Décision KJ) — les tokens LLM sont toujours à la charge du constructeur. Discovery gratuit jusqu'à 1 000 MAU/mois, puis 2,50 €/MAU. Enterprise à partir de 1 500 €/mois sur devis — seul palier sur devis. Source : ELYSEA.ID.PRICING_MODEL.v1 (figé).

§5 — Trust mark & badges

Powered by ELYSÉA

Discovery et supérieur

Badge de premier niveau. Indique que l'app intègre le SDK ELYSÉA avec les 8 prohibitions actives. Vérifiable par l'utilisateur via son portail ID.

Genesis Partner

Programme Genesis uniquement

Réservé aux partenaires co-développeurs invités. Indique un accès avant-première et une participation active à l'élaboration des canons.

Certified Ethical

Audit complet validé

Niveau maximal. Audit par ELYSÉA des pratiques de consentement, de l'absence de détournement mémoire, et de la conformité Guardian. Processus distinct de l'abonnement.

Révocation

Révocation immédiate

P1, P2, P3 (tentative active de contournement) et P8 (fraude de badge confirmée). Aucun délai de grâce.

Délai de 10 jours

P4, P5, P6, P7 — infractions non-frauduleuses. Le constructeur reçoit une notification et dispose de 10 jours pour corriger avant révocation.

Appel — 15 jours

Toute révocation peut être contestée dans un délai de 15 jours calendaires suivant la notification. Procédure décrite dans le contrat partenaire.

Source : ELYSEA.SDK.TRUST_MARK.v1 §3, §5. Voir aussi : page Trust mark.

trust.verify() — vérification programmatique

Le namespace trustdu SDK permet de vérifier le statut de certification d’une app et de valider l’authenticité d’une attestation HMAC côté Core. Usage typique : afficher le badge correct à l’utilisateur, ou auditer un partenaire tiers.

trust.fetchAttestation(appId)

→ Promise<TrustMarkAttestation | null>

Récupère l'attestation trust mark depuis le Core pour un appId donné. Retourne null si le Core est inaccessible ou l'appId inconnu.

trust.getStatus(attestation)

→ CertificationStatus

Dérive le statut de certification depuis une attestation. Fonction pure — aucun appel réseau. Résultat : 'powered_by' | 'genesis_partner' | 'certified_ethical' | 'none'.

trust.verify(attestation)

→ Promise<{ valid: boolean }>

Vérifie l'attestationToken HMAC auprès du Core (POST /verify/attestation). Le Core contrôle la signature côté serveur. Retourne { valid: false } sur tout échec — aucune exception levée.

typescript
// Vérifier le trust mark d'une app partenaire
const attestation = await elysea.trust.fetchAttestation('app_a40a8bd4-008c-4ef4-aef7-b9666d6846a8');

if (!attestation) {
  // App inconnue ou Core inaccessible
  return { certified: false };
}

const status = elysea.trust.getStatus(attestation);
// status → 'powered_by' | 'genesis_partner' | 'certified_ethical' | 'none'

const { valid } = await elysea.trust.verify(attestation);
// valid → true si le HMAC est confirmé côté Core
// valid → false si le token est invalide, expiré, ou falsifié
ELYSEA.SDK.SANDBOX_PARTNER.v1 — FIGÉ

§6 — Sandbox — 5 invariants

I-SB-1

firm_safety toujours actif

Le mode de sécurité principal ne peut pas être désactivé en sandbox. Toute tentative de passer firm_safety: false est ignorée silencieusement.

I-SB-2

D0 active sans exception

La directive éthique socle (D0) est active en sandbox exactement comme en production. Le comportement Guardian est identique.

I-SB-3

Guardian SDK actif

Tous les blocs Guardian sont fonctionnels en sk_test_. Le sandbox est un vrai test de conformité — pas un bac à sable permissif.

I-SB-4

8 prohibitions actives

P1 à P8 sont intégralement appliquées. Les signaux d'erreur retournés sont identiques à la production.

I-SB-5

Garantie K intacte

La mémoire sacrée de l'utilisateur (items marqués K) est inaccessible en sandbox comme en production. Aucun endpoint de test ne contourne cette règle.

Erreur de mismatch environnement

typescript
// Lève ELYSEA_ENV_MISMATCH si la clé et l'environment ne correspondent pas
// sk_test_ avec environment:'production'  →  erreur
// sk_live_ avec environment:'sandbox'     →  erreur

try {
  const elysea = new ElyseaClient({
    apiKey:      'sk_test_abc123',
    appId:       'my-app',
    region:      'EU',
    environment: 'production', // ← MISMATCH avec sk_test_
  });
} catch (err) {
  // err.code === 'ELYSEA_ENV_MISMATCH'
}

§7 — Codes d'erreur

CodeTypeCauseAction recommandée
ELYSEA_ENV_MISMATCHConfigClé et environnement incompatiblesAligner apiKey et environment dans ElyseaClient
P1_D0_OVERRIDE_ATTEMPTGuardian BLOCTentative de bypass D0Violation P1 — révision architecture requise
P2_MEMORY_RAW_ACCESSGuardian BLOCLecture directe mémoire utilisateurUtiliser uniquement le pipeline de résolution consentie
P3_SAFETY_GATE_BYPASS_ATTEMPTGuardian BLOCContournement safety gate détectéRevue complète du prompt et de l'architecture LLM
P4_NON_CONFORM_LLM_SIGNATUREGuardian WARNLLM sans watermark ELYSÉAUtiliser uniquement les modèles certifiés ELYSÉA
P5_WATERMARK_MISSINGGuardian BLOCRéponse pipeline sans métadonnée de traçabilitéVérifier l'intégration — ne pas modifier la réponse pipeline brute
P6_CROSS_BUILDER_CONSENT_MISSINGGuardian BLOCCroisement mémoire inter-app sans consentement scopéVérifier le token de consentement cross-app actif
P7_MISSING_CONSENT_TOKENGuardian BLOCAppel sans token de consentement ELYSÉA valideRecueillir le consentement utilisateur avant tout appel
P8_UNCERTIFIED_BADGE_USAGEGuardian WARNBadge affiché sans certification valideRetirer le badge — initier le processus de certification

Les blocs Guardian ne génèrent pas de HTTP 4xx. La réponse est toujours un PipelineResult valide avec signal: “guardian_block” et posture: “present_neutral”.

Une question sur la conformité ? Un cas limite non documenté ?

Parler à l'équipeTélécharger la doc (PDF)Quickstart dev