Quickstart — developer guide

From first access to deployment.

OpenAI, Mistral, Gemini, or Claude — bring your own key from the trial phase onward. Zero ethical rules to code, zero crisis orientation to maintain.

Get sk_test_ →SDK & Pricing

Decision-maker or CTO? Guarantees → · Pricing → · Reference →

What you will not need to do

— Choose your LLM provider — bring your own key (OpenAI, Mistral, Gemini, or Claude). BYOK mandatory from trial.
— Write ethical rules or security prompts
— Implement crisis detection or crisis orientation (emergency services)
— Code user memory persistence
— Build the ethical pipeline — it is included in every call

The steps

Get your builder access

Sandbox: create your app in the developer portal. Get your sk_test_ key immediately — no credit card, capped at 1,000 MAU. Full pipeline active, 8 prohibitions live. You receive: ELYSEA_API_KEY, ELYSEA_API_SECRET, ELYSEA_APP_ID, ELYSEA_BASE_URL and the onboarding documentation.

Production (sk_live_): individual review of your use case. Duration: 24–72h. That is what guarantees ecosystem integrity.

Developer portal →

Installation

JavaScript / TypeScript — Node.js 18+ or browser.

bash

npm install @elysea/core
# sk_test_ key required — developer portal

Configuration

Three parameters. EU region is required — EU data infrastructure.

typescript

import { createElyseaClient } from '@elysea/core';

const elysea = createElyseaClient({
  baseUrl:     process.env.ELYSEA_BASE_URL!,
  auth: {
    apiKey:    process.env.ELYSEA_API_KEY!,
    apiSecret: process.env.ELYSEA_API_SECRET!,
  },
  appId:       process.env.ELYSEA_APP_ID!,
  countryCode: 'GB',
  region:      'EU',
});

Resolve user identity

ELYSÉA resolves an anonymised coreUserId from your JWT. You do not transmit email or personal data.

typescript

// From your auth middleware
const { coreUserId } = await elysea.identity.resolve({
  userJwt: req.headers.authorization,
});
// coreUserId → anonymised ELYSÉA internal identifier
// Never the email nor real user data

First cognitive pipeline call

The complete pipeline — signal interpretation, canon verification, generation, ethical post-processing. No model to select.

typescript

const result = await elysea.pipeline.run({
  userInput:           userMessage,
  coreUserId,
  conversationHistory: previousMessages,  // optional
});

// result.response         → canon-compliant response
// result.posture          → applied posture (e.g. 'present_neutral')
// result.guardianAction   → 'pass'|'warn'|'block' (if block: errorCode + errorMessage)
// result.canonConformance → true if compliant with ELYSÉA canons

Memory write — optional

If your app enriches the user's context, you can write to ELYSÉA memory — with explicit consent and mandatory TTL. Direct memory read is impossible (P2).

typescript

await elysea.memory.write({
  coreUserId,
  appId: process.env.ELYSEA_APP_ID,
  item: {
    type:       'useful_context',            // one of the 5 permitted types
    content:    'Prefers short responses.',
    expires_at: '2027-01-01T00:00:00Z',    // mandatory TTL
  },
  consentToken: req.body.consentToken,      // user consent
});

Full example — integration in 30 lines

Copy this file into your project — it is a complete functional integration.

typescript

// elysea.ts — complete ELYSEA CERVEAU integration
import { createElyseaClient, type PipelineResult } from '@elysea/core';

const elysea = createElyseaClient({
  baseUrl:     process.env.ELYSEA_BASE_URL!,
  auth: {
    apiKey:    process.env.ELYSEA_API_KEY!,
    apiSecret: process.env.ELYSEA_API_SECRET!,
  },
  appId:       process.env.ELYSEA_APP_ID!,
  countryCode: 'GB',
  region:      'EU',
});

type Message = { role: 'user' | 'assistant'; content: string };

export async function chat(
  userJwt:  string,
  message:  string,
  history:  Message[] = [],
): Promise<PipelineResult> {
  // 1. Resolve identity — never the email, never real data
  const { coreUserId } = await elysea.identity.resolve({ userJwt });

  // 2. Cognitive pipeline call — ethics engraved, not configured
  const result = await elysea.pipeline.run({
    userInput:           message,
    coreUserId,
    conversationHistory: history,
  });

  // result.response         → canon-compliant response, ready to display
  // result.posture          → runtime posture (present_neutral, firm_safety…)
  // result.guardianAction   → 'pass'|'warn'|'block' (if block: errorCode + errorMessage)
  // result.canonConformance → true if compliant with ELYSÉA canons
  return result;
}

// Usage in your API handler:
// const result = await chat(req.headers.authorization, req.body.message, history);
// res.json({ reply: result.response });

What you receive in the result

result.response

The response

Response generated by the ELYSÉA cognitive pipeline — canon-compliant, post-processed, validated by the Guardian SDK.

result.posture

The posture

Applied runtime posture (e.g.: present_neutral, firm_safety, containment_soft). Read-only — the builder cannot force it.

result.guardianAction

The Guardian action

'pass', 'warn' or 'block'. If 'block': errorCode + errorMessage available. Final decision of the ethical pipeline.

result.canonConformance

Canon conformance

true if the response is compliant with ELYSÉA canons. Useful for your internal audit.

The 7 runtime postures

The pipeline selects the posture automatically based on the interpreted signal. The builder can suggest an initial posture — ELYSÉA retains the final decision.

present_neutralSober presence, grounding

clarifierA single raw question

direct_no_bsDirect, firm, no moralising

silent_holdMicro-exits / silence

firm_safetyEmergency orientation (emergency services) — non-deactivatable

containment_softSoft de-escalation

meta_repairDirect relational reframing

Source: ELYSEA.SDK.ELYSEAID.v1 §2 (Component 3 — Canon postures)

sk_test_ immediately via the portal — no credit card. Production on individual review (24-72h).

sk_test_ via the developer portal — immediately, no credit card, capped at 1,000 MAU. sk_live_: individual review of your use case, 24-72h.

Developer portal →SDK Docs →PDF Documentation →