Documentation Développeur

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

Tester le SDK maintenant

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 /pricing
  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

json
{
  "meta": {
    "seed": 1234567890,
    "name": "Projection Capital 2025",
    "description": "Simulation avec taux variables"
  }
}

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.

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.

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.

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": [...]
  }'

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": [...]
  }'

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

SDK Python

Installation

Prérequis: Python 3.10+

bash
pip install beausoftsubspace

Initialisation

python
from beausoftsubspace import BSCE

# Production (par défaut)
client = BSCE(api_key="be_live_...")

# Tests locaux (optionnel)
client = BSCE(
    api_key="be_live_...",
    base_url="http://localhost:8000"
)

project() - Projection Unique

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

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'])

simulate() - Simulation Monte Carlo

Exécute des simulations Monte Carlo (multi-scénarios) avec statistiques complètes.

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']}")
print(f"P95: {result['statistics']['capital']['percentiles']['95']}")

project_batch() - Batch Mode

Exécute plusieurs projections avec des paramètres variables.

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']}")

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';

// Production (par défaut)
const client = new BSCE('be_live_...');

// Tests locaux (optionnel)
const client = new BSCE('be_live_...', 'http://localhost:8000');

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);

simulate() - Simulation Monte Carlo

Exécute des simulations Monte Carlo (multi-scénarios) avec statistiques complètes.

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}`);
console.log(`P95: ${result.statistics.capital.percentiles[95]}`);

projectBatch() - Batch Mode

Exécute plusieurs projections avec des paramètres variables. Disponible sur les plans Business et Enterprise uniquement.

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

typescript
const validation = await client.validate(spec);
if (validation.is_valid) {
  console.log('✅ Valid');
} else {
  console.log(`❌ Errors: ${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

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
// Lister les runs (avec filtres optionnels)
const runs = await client.listRuns('proj_123', undefined, 10, 0);

// Obtenir une run
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 →