Documentation Développeur

Intégrez Beausoft Subspace Computing Engine dans vos applications avec nos SDK Python/TypeScript ou l'API REST.

Introduction

Qu'est-ce que Beausoft Subspace Computing Engine ?

Beausoft Subspace Computing Engine (BSCE) est un moteur de calcul haute performance pour projections de données et simulations massives.

En 3 points :

  • Déclaratif : Décrivez quoi calculer en JSON, pas comment le programmer
  • Rapide : Exécute des milliers de scénarios en parallèle en quelques millisecondes
  • Reproductible : Même modèle + même seed = mêmes résultats

Cas d'usage principaux

  • Actuariat : Projections de réserves, calculs de provisions, évaluation de régimes de retraite
  • Finance : Valorisation d'options, analyse de risques
  • Optimisation : Projections budgétaires, analyse de coûts

Quick Start (5 minutes)

Étape 1 : Obtenir une Clé API

  1. Visitez la page Tarifs
  2. Choisissez un plan
  3. Générez votre clé API

Étape 2 : Installer un SDK

Choisissez le SDK qui correspond à votre stack technique :

Python (3.10+)

bash
pip install beausoftsubspace

TypeScript/JavaScript (Node.js)

bash
npm install @beausoft/subspace

Étape 3 : Premier Appel

Choisissez votre langage :

python
from beausoftsubspace import BSCE

# Initialiser le client
client = BSCE(api_key="be_live_...")

# Projection simple
result = client.project({
    "scenarios": 1,
    "steps": 12,
    "variables": [
        {
            "name": "capital",
            "init": 1000.0,
            "formula": "capital[t-1] * 1.05"
        }
    ]
})

print(f"Capital final: {'$'}{result['final_values']['capital']:,.2f}")

Résultat : Capital final: $1,795.86

SP Models

Qu'est-ce qu'un SP Model ?

Un SP Model est un format JSON déclaratif qui décrit votre projection de données. Vous décrivez quoi calculer, pas comment le calculer.

Déclaratif
Portable
Reproductible
Flexible
Puissant

Structure de base

Un SP Model est un format JSON déclaratif qui décrit votre projection de données.

json
{
  "scenarios": 1000,
  "steps": 12,
  "variables": [
    {
      "name": "capital",
      "init": 1000.0,
      "formula": "capital[t-1] * (1 + taux)"
    }
  ]
}

Structure de base

Un SP Model est un format JSON déclaratif qui décrit votre projection de données.

json
{
  "scenarios": 1000,
  "steps": 12,
  "variables": [
    {
      "name": "capital",
      "init": 1000.0,
      "formula": "capital[t-1] * (1 + taux)"
    }
  ]
}

Types de variables

1. Variable Déterministe

Valeur fixe avec évolution optionnelle via une formule.

json
{
    "name": "capital",
    "init": 1000.0,
    "formula": "capital[t-1] * 1.05"
}

2. Variable Aléatoire

Distribution statistique avec génération aléatoire. Distributions disponibles: uniform, normal.

json
{
    "name": "taux",
    "dist": "uniform",
    "params": {"min": 0.03, "max": 0.07},
    "per": "scenario"
}

3. Time Series

Valeurs explicites définies par période.

json
{
    "name": "inflation",
    "values": [0.02, 0.025, 0.03, 0.035, 0.04]
}

Références temporelles

Dans les formules, vous pouvez référencer des valeurs à différentes périodes :

var[t]

Valeur actuelle

var[t-1]

Période précédente

var[0]

Valeur initiale

var[start:end]

Slice temporel (agrégation)

json
{"formula": "capital[t-1] * 1.05"}
{"formula": "capital[t] - capital[0]"}
{"formula": "sum(primes_payees[0:t+1])"}

Fonctions et opérateurs

Opérateurs mathématiques

+, -, *, /, ** (puissance), % (modulo)

Fonctions mathématiques

abs(x), max(x, y), min(x, y), round(x, n), floor(x, n), ceil(x, n), truncate(x, n), sqrt(x), pow(x, y), exp(x), log(x), ln(x)

Agrégations temporelles

sum(array[start:end]), mean(array[start:end]), std(array[start:end]), var(array[start:end])

Options avancées

meta (optionnel)

Métadonnées du modèle : seed, name, description. Pour regrouper plusieurs runs sous une même projection, utilisez meta.name ou meta.projection_id.

  • meta.name : Si une projection avec ce nom existe déjà pour votre compte, elle est réutilisée. Sinon, une nouvelle projection est créée avec ce nom.
  • meta.projection_id : Réutilise explicitement cette projection (UUID récupérable via GET /projections ou list_projections()). Si l’ID est invalide ou inaccessible, une nouvelle projection est créée.
json
{
  "meta": {
    "seed": 1234567890,
    "name": "Projection Capital 2025",
    "description": "Simulation avec taux variables",
    "projection_id": "uuid-optionnel-pour-reutiliser-une-projection"
  }
}

final_metrics (optionnel)

Métriques calculées uniquement à la fin de la simulation.

json
{
  "final_metrics": {
    "capital_final": "capital[t_final]",
    "profit_total": "capital[t_final] - capital[0]",
    "taux_moyen": "mean(taux[0:t_final+1])"
  }
}

API REST

Authentification

Base URL : https://api.subspacecomputing.com

Toutes les requêtes nécessitent une clé API dans le header X-API-Key (sauf endpoints publics).

bash
X-API-Key: be_live_XXXXXXXX...

Endpoints publics (pas besoin d'API key) : GET /health, GET /examples, POST /validate

POST /project - Projection Unique

Exécute une projection unique (1 scénario) sans statistiques. scenarios doit être exactement 1. Avec une clé API valide, la réponse contient un champ optionnel run_id (UUID) permettant de récupérer ou suivre la run via GET /projection-runs/{run_id}.

bash
curl -X POST "https://api.subspacecomputing.com/project" \
  -H "X-API-Key: be_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scenarios": 1,
    "steps": 12,
    "variables": [
      {
        "name": "capital",
        "init": 1000.0,
        "formula": "capital[t-1] * 1.05"
      }
    ]
  }'

POST /simulate - Simulation Monte Carlo

Exécute des simulations Monte Carlo (multi-scénarios) avec statistiques complètes. Avec une clé API valide, la réponse contient un champ optionnel run_id (UUID) pour récupérer la run via GET /projection-runs/{run_id}.

bash
curl -X POST "https://api.subspacecomputing.com/simulate" \
  -H "X-API-Key: be_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scenarios": 1000,
    "steps": 12,
    "variables": [
      {
        "name": "taux",
        "dist": "uniform",
        "params": {"min": 0.03, "max": 0.07},
        "per": "scenario"
      },
      {
        "name": "capital",
        "init": 1000.0,
        "formula": "capital[t-1] * (1 + taux)"
      }
    ]
  }'

POST /project/batch - Projections Batch

Exécute plusieurs projections individuelles avec des paramètres variables. Disponible sur les plans Business et Unlimited uniquement. La réponse contient run_id (run parent) et run_ids (tableau des runs enfants) pour suivre chaque entité via GET /projection-runs/{run_id}.

bash
curl -X POST "https://api.subspacecomputing.com/project/batch" \
  -H "X-API-Key: be_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "batch_params": [
      {"entity_id": "emp_001", "age": 45, "salary": 60000},
      {"entity_id": "emp_002", "age": 50, "salary": 80000}
    ],
    "template": {
      "scenarios": 1,
      "steps": "65 - batch_params.age",
      "variables": [...]
    },
    "aggregations": [...]
  }'

run_id et Gestion des Runs

run_id dans la réponse : Les endpoints POST /project, POST /simulate et POST /project/batch retournent un champ optionnel run_id (UUID) lorsque l'appel est fait avec une clé API valide. Ce run_id permet de récupérer ou mettre à jour la run via GET /projection-runs/{run_id} (voir CRUD Projections et Runs plus bas).

run_id dans le spec (requête) : Vous pouvez passer run_id dans le body du spec pour mettre à jour une run existante au lieu d'en créer une nouvelle. Flux typique : créer une run côté portail → lancer le calcul avec ce run_id → l'API met à jour la run (status, result_summary, artefact_id).

Batch : POST /project/batch retourne run_id (run parent) et run_ids (tableau des runs enfants, une par entité).

meta.name : Si vous fournissez meta.name dans le body du spec, une projection existante portant ce nom est réutilisée pour y attacher la run ; sinon une nouvelle projection est créée avec ce nom (identification dans votre tableau de bord).

meta.projection_id : En passant meta.projection_id (UUID) dans le body, vous réutilisez explicitement cette projection pour la nouvelle run. L’UUID est récupérable via GET /projections. Si l’ID est invalide, une nouvelle projection est créée.

POST /validate - Valider un SP Model

Valide votre SP Model sans l'exécuter. Endpoint public (pas besoin d'API key).

bash
curl -X POST "https://api.subspacecomputing.com/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarios": 100,
    "steps": 12,
    "variables": [...]
  }'

Réponse typique :

json
{
  "valid": true,
  "errors": [],
  "warnings": [],
  "estimated_scenarios": 3,
  "estimated_duration_ms": 0
}

valid indique si le modèle est valide. errors liste les erreurs (champ et message), warnings les avertissements éventuels. Les champs estimated_scenarios et estimated_duration_ms donnent une idée du coût avant d'exécuter une simulation.

Gestion des erreurs

200 : Succès

400 : Erreur de validation (SP Model invalide)

401 : Authentification requise (API key manquante ou invalide)

429 : Rate limit dépassé

500 : Erreur serveur

Quota : Seuls simulate() et POST /project/batch consomment votre quota mensuel. project() (1 scénario) et validate() ne consomment pas de quota.

SDK Python

Installation

Prérequis: Python 3.10+

bash
pip install beausoftsubspace

Initialisation

python
from beausoftsubspace import BSCE

# Initialiser le client (production)
client = BSCE(api_key="be_live_...")

project() - Projection Unique

Exécute une projection unique (1 scénario, gratuit). Le paramètre scenarios doit être exactement 1. La réponse contient run_id (UUID) pour récupérer la run plus tard.

python
spec = {
    "scenarios": 1,  # DOIT être 1
    "steps": 12,
    "variables": [
        {
            "name": "capital",
            "init": 1000.0,
            "formula": "capital[t-1] * 1.05"
        }
    ]
}

result = client.project(spec)
print(result['final_values']['capital'])
# Récupérer la run (status, result_summary, etc.)
if result.get('run_id'):
    run = client.get_run(result['run_id'])

simulate() - Simulation Monte Carlo

Exécute des simulations Monte Carlo (multi-scénarios) avec statistiques complètes. La réponse contient run_id pour récupérer ou suivre la run.

python
spec = {
    "scenarios": 1000,
    "steps": 12,
    "variables": [
        {
            "name": "taux",
            "dist": "uniform",
            "params": {"min": 0.03, "max": 0.07},
            "per": "scenario"
        },
        {
            "name": "capital",
            "init": 1000.0,
            "formula": "capital[t-1] * (1 + taux)"
        }
    ]
}

result = client.simulate(spec)
print(f"Moyenne: {result['last_mean']['capital']}")
print(f"Médiane: {result['statistics']['capital']['median']}")
# Récupérer la run après simulate (status, result_summary, artefact_id, etc.)
if result.get('run_id'):
    run = client.get_run(result['run_id'])

project_batch() - Batch Mode

Exécute plusieurs projections avec des paramètres variables. La réponse contient run_id (run parent) et run_ids (runs enfants) pour suivre chaque entité.

python
template = {
    "scenarios": 1,
    "steps": "65 - batch_params.age",
    "variables": [
        {
            "name": "capital_retraite",
            "init": 0.0,
            "formula": "capital_retraite[t-1] * 1.05 + batch_params.salary * 0.10"
        }
    ]
}

batch_params = [
    {"entity_id": "emp_001", "age": 45, "salary": 60000},
    {"entity_id": "emp_002", "age": 50, "salary": 80000}
]

result = client.project_batch(
    template=template,
    batch_params=batch_params
)

for entity in result['entities']:
    print(f"{entity['_entity_id']}: {entity['final_values'][0]['capital_retraite']}")

Regrouper les runs sous une projection

Par défaut, chaque appel à project() ou simulate() crée une nouvelle projection. Pour attacher plusieurs runs à une même projection (par exemple pour les retrouver ensemble dans votre tableau de bord), utilisez meta.name ou meta.projection_id dans le spec.

Option A : Regrouper par nom (meta.name)

Si une projection avec ce nom existe déjà pour votre compte, elle est réutilisée. Sinon, une nouvelle projection est créée avec ce nom.

python
spec = {
    "scenarios": 1,
    "steps": 12,
    "meta": {"name": "Capital 2025 - Scénario conservateur"},
    "variables": [
        {"name": "capital", "init": 1000.0, "formula": "capital[t-1] * 1.05"}
    ]
}
result = client.project(spec)
# Les prochains appels avec le même meta.name attacheront leurs runs à la même projection.

Option B : Regrouper par ID (meta.projection_id)

Réutilisez explicitement une projection dont vous avez l’UUID (récupéré via list_projections() ou le tableau de bord). Si l’ID est invalide, une nouvelle projection est créée.

python
# Récupérer l'ID d'une projection existante
projections = client.list_projections(10, 0)
proj_id = projections["items"][0]["id"]  # ou un ID connu

spec = {
    "scenarios": 1,
    "steps": 12,
    "meta": {"projection_id": proj_id},
    "variables": [
        {"name": "capital", "init": 1000.0, "formula": "capital[t-1] * 1.05"}
    ]
}
result = client.project(spec)
# La run est attachée à la projection proj_id.

validate() - Valider un SP Model

Vérifiez votre modèle avant de lancer une simulation. Vous obtenez un indicateur de validité, les erreurs éventuelles, des avertissements et une estimation du nombre de scénarios et de la durée.

python
validation = client.validate(spec)
if validation.get('valid'):
    print("✅ SP Model valide")
    if validation.get('estimated_scenarios'):
        print(f"   Scénarios estimés: {validation['estimated_scenarios']}")
    if validation.get('warnings'):
        print(f"   Avertissements: {validation['warnings']}")
else:
    print(f"❌ Erreurs: {validation['errors']}")

Gestion des erreurs

python
from beausoftsubspace import (
    BSCE,
    QuotaExceededError,
    RateLimitError,
    AuthenticationError,
    ValidationError
)

try:
    result = client.simulate(spec)
except QuotaExceededError:
    print("Quota mensuel dépassé")
except RateLimitError as e:
    print(f"Rate limit: {e}")
except AuthenticationError:
    print("Clé API invalide")
except ValidationError as e:
    print(f"Erreur de validation: {e.detail}")

SDK TypeScript

Installation

Prérequis: Node.js 18+

bash
npm install @beausoft/subspace

Pour la version beta : npm install @beausoft/subspace@beta

Initialisation

typescript
import { BSCE } from '@beausoft/subspace';

// Initialiser le client (production)
const client = new BSCE('be_live_...');

project() - Projection Unique

Exécute une projection unique (1 scénario, gratuit). Le paramètre scenarios doit être exactement 1.

typescript
const spec = {
  scenarios: 1,  // DOIT être 1
  steps: 12,
  variables: [
    {
      name: 'capital',
      init: 1000.0,
      formula: 'capital[t-1] * 1.05'
    }
  ]
};

const result = await client.project(spec);
console.log(result.final_values.capital);
// Récupérer la run (status, result_summary, etc.)
if (result.run_id) {
  const run = await client.getRun(result.run_id);
}

simulate() - Simulation Monte Carlo

Exécute des simulations Monte Carlo (multi-scénarios) avec statistiques complètes. La réponse contient run_id pour récupérer la run.

typescript
const spec = {
  scenarios: 1000,
  steps: 12,
  variables: [
    {
      name: 'taux',
      dist: 'uniform',
      params: { min: 0.03, max: 0.07 },
      per: 'scenario'
    },
    {
      name: 'capital',
      init: 1000.0,
      formula: 'capital[t-1] * (1 + taux)'
    }
  ]
};

const result = await client.simulate(spec);
console.log(`Moyenne: ${result.last_mean.capital}`);
console.log(`Médiane: ${result.statistics.capital.median}`);
// Récupérer la run après simulate (status, result_summary, artefact_id, etc.)
if (result.run_id) {
  const run = await client.getRun(result.run_id);
}

projectBatch() - Batch Mode

Exécute plusieurs projections avec des paramètres variables. Disponible sur les plans Business et Enterprise uniquement. La réponse contient run_id (run parent) et run_ids (runs enfants).

typescript
const template = {
  scenarios: 1,
  steps: '65 - batch_params.age',
  variables: [
    {
      name: 'age_actuel',
      init: 'batch_params.age'
    },
    {
      name: 'salaire',
      init: 'batch_params.salary',
      formula: 'salaire[t-1] * 1.03'
    },
    {
      name: 'capital_retraite',
      init: 0.0,
      formula: 'capital_retraite[t-1] * 1.05 + salaire[t] * 0.10'
    }
  ]
};

const batchParams = [
  { entity_id: 'emp_001', age: 45, salary: 60000 },
  { entity_id: 'emp_002', age: 50, salary: 80000 }
];

const aggregations = [
  { name: 'capital_total', formula: 'sum(capital_retraite[t_final])' }
];

const result = await client.projectBatch(template, batchParams, aggregations);

result.entities.forEach(entity => {
  console.log(`${entity._entity_id}: ${entity.final_values[0].capital_retraite}`);
});

Méthodes Utilitaires

validate() - Valider un SP Model

Vérifiez votre modèle avant de lancer une simulation. Vous obtenez un indicateur de validité, les erreurs éventuelles, des avertissements et une estimation du nombre de scénarios et de la durée.

typescript
const validation = await client.validate(spec);
if (validation.valid) {
  console.log('✅ SP Model valide');
  if (validation.estimated_scenarios != null) {
    console.log(`   Scénarios estimés: ${validation.estimated_scenarios}`);
  }
  if (validation.warnings?.length) {
    console.log(`   Avertissements: ${validation.warnings}`);
  }
} else {
  console.log(`❌ Erreurs: ${validation.errors}`);
}

getExamples() - Obtenir des exemples

Endpoint public (pas d'API key requise)

typescript
const examples = await client.getExamples();
console.log(`Available: ${examples.examples.length}`);

getUsage() - Obtenir usage et quotas

typescript
const usage = await client.getUsage();
console.log(`Used: ${usage.quota.used}/${usage.quota.limit}`);
console.log(`Remaining: ${usage.quota.remaining}`);

getPlans() - Obtenir les plans

Endpoint public

typescript
const plans = await client.getPlans();
plans.plans.forEach(plan => {
  console.log(`${plan.name}: $${plan.price_monthly}/month`);
});

CRUD Projections et Runs

Les réponses de project() et simulate() contiennent un champ run_id. Vous pouvez utiliser getRun(run_id) pour récupérer la run (équivalent à GET /projection-runs/{run_id}) et suivre son statut, result_summary, etc.

Gestion des Projections

typescript
// Lister les projections
const projections = await client.listProjections(10, 0);

// Obtenir une projection
const projection = await client.getProjection('proj_123');

// Supprimer une projection
await client.deleteProjection('proj_123');

Gestion des Runs

typescript
// run_id retourné par project() / simulate() → récupérer la run
const result = await client.simulate(spec);
if (result.run_id) {
  const run = await client.getRun(result.run_id);  // GET /projection-runs/{run_id}
}

// Lister les runs d'une projection
const runs = await client.listRuns('proj_123', undefined, 10, 0);

// Obtenir une run par ID
const run = await client.getRun('run_123');

// Supprimer une run
await client.deleteRun('run_123');

Helpers

typescript
// Obtenir info rate limit depuis dernière réponse
await client.project(spec);
const rateLimit = client.getRateLimitInfo();
if (rateLimit) {
  console.log(`Limit: ${rateLimit.remaining}/${rateLimit.limit}`);
}

// Obtenir info quota depuis dernière réponse
await client.simulate(spec);
const quota = client.getQuotaInfo();
if (quota) {
  console.log(`Quota: ${quota.used}/${quota.limit}`);
}

Gestion des erreurs

typescript
import {
  BSCEError,
  QuotaExceededError,
  RateLimitError,
  AuthenticationError,
  ValidationError
} from '@beausoft/subspace';

try {
  const result = await client.simulate(spec);
} catch (error) {
  if (error instanceof QuotaExceededError) {
    console.error(`Quota dépassé: ${error.message}`);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limit dépassé: ${error.message}`);
    const retryAfter = error.response?.headers.get('Retry-After');
  } else if (error instanceof AuthenticationError) {
    console.error(`Clé API invalide: ${error.message}`);
  } else if (error instanceof ValidationError) {
    console.error(`Erreur validation: ${error.detail}`);
  } else if (error instanceof BSCEError) {
    console.error(`Erreur API: ${error.message}`);
  }
}

Besoin de plus de détails ?

Consultez la référence API complète pour tous les endpoints et paramètres.

Voir la référence API →