Automatisation, CLI sans interface et feuille de route des SDK

Equarith Headless est disponible pour les recherches sans surveillance, scripts shell, tâches planifiées et intégrations locales. Il exécute le même EquarithEngine que l’application graphique, conserve les données et les calculs sur la machine et n’ouvre jamais de port HTTP ou TCP.

L’interface en ligne de commande décrite dans cette page est disponible dès maintenant. Les paquets SDK officiels ne font pas partie de cette release ; leurs langages prévus sont indiqués dans SDK — bientôt disponibles.

Installer et vérifier Equarith Headless

Les installateurs autonomes contiennent l’environnement Java nécessaire : l’utilisateur final n’a besoin ni d’un JDK ni de l’application graphique.

Windows x64 : MSI ou EXE par utilisateur, avec intégration gérée au PATH ;
macOS x64 et ARM64 : PKG signé et notarisé, installant /Applications/EquarithHeadless.app et /usr/local/bin/equarith-headless ;
Linux glibc x64 et ARM64 : DEB ou RPM, installant /usr/bin/equarith-headless.

Après l’installation, ouvrez un nouveau terminal puis exécutez :

equarith-headless version
equarith-headless --help
equarith-headless capabilities

version identifie le runtime et le protocole local. capabilities constitue le contrat de référence lisible par une machine pour le moteur installé : métriques, fonctions, options de recherche, limites, formats d’export et parallélisme effectif configuré pour cette commande.

Un développeur qui construit les sources peut employer le JAR ombré :

./mvnw -pl equarith-cli -am package
java -jar equarith-cli/target/equarith-cli.jar --help

Ce JAR de développement exige le JDK 25. Dans les exemples suivants, remplacez equarith-headless par java -jar equarith-cli/target/equarith-cli.jar si vous l’utilisez.

Référence des commandes

Les options acceptent --nom=valeur ou --nom valeur. Une option ne peut pas être répétée. --threads doit être un entier positif et utilise par défaut les processeurs accessibles au processus. Définissez ce nombre sur la commande ; ne comptez pas sur constraints.cpuThreads pour redimensionner le moteur intégré.

Afficher les versions
```
equarith-headless version
```

Décrire les capacités du moteur

equarith-headless capabilities [--threads=<n>]

Gérer la licence partagée

equarith-headless license status [--threads=<n>]
equarith-headless license activate [--key-stdin] [--device-name=<nom>] [--threads=<n>]
equarith-headless license refresh [--device-name=<nom>] [--threads=<n>]
equarith-headless license deactivate [--threads=<n>]

Inspecter une importation

equarith-headless dataset inspect --data=<chemin> [--import=<json>] [--threads=<n>]

Valider une requête de recherche

equarith-headless validate --request=<json> [--resume-from=<checkpoint>] [--threads=<n>]

Exécuter une recherche bloquante

equarith-headless search --request=<json> --solutions=<jsonl>
    [--events=<jsonl|->] [--checkpoint-out=<fichier>]
    [--resume-from=<fichier>] [--threads=<n>]

Appliquer une solution enregistrée à un jeu compatible

equarith-headless predict --data=<chemin> --solutions=<jsonl> --solution=<uuid>
    --output=<csv> [--import=<json>] [--label=<nom>] [--threads=<n>]

Exporter les solutions enregistrées

equarith-headless export --solutions=<jsonl> --format=<format> --output=<chemin>
    [--ids=<uuid,uuid,...>]

Démarrer le protocole local persistant

equarith-headless serve --stdio [--threads=<n>]

Licence et limites Démo

Le runtime sans interface et l’application graphique partagent l’identité d’installation et l’état de licence lorsqu’ils s’exécutent sous le même compte système et pour la même version. Vérifiez cet état avec :

equarith-headless license status

Reliée à un terminal interactif, la commande license activate lit la clé sans l’afficher. Aucune option n’accepte la clé elle-même. Pour une automatisation, utilisez --key-stdin et alimentez l’entrée standard depuis un gestionnaire de secrets ou un descripteur de fichier protégé afin de garder la clé hors des arguments du processus ; ne placez pas une clé littérale dans une commande que le shell pourrait enregistrer dans son historique. refresh renouvelle un certificat admissible et deactivate libère l’installation.

Sans activation, une recherche Free/Démo utilise au maximum les 200 premières lignes source et quatre variables d’entrée. Les licences Academic et Pro retirent ces deux quotas, mais pas les limites normales de mémoire et de sécurité du moteur. Données et calculs restent locaux. Seule une opération de licence explicitement demandée communique avec le service de licence.

Tutoriel CLI de bout en bout

Créez un dossier de traitement contenant un fichier numérique comme measurements.csv et le fichier request.json suivant :

{
  "schemaVersion": 1,
  "dataset": {
    "path": "measurements.csv"
  },
  "target": "y",
  "inputs": ["x1", "x2"],
  "metric": "rmse",
  "trainTest": {
    "mode": "FRACTION",
    "trainingFraction": 0.8,
    "sampleMethod": "RANDOM",
    "randomSeed": 42
  },
  "evaluateTestObjectivesDuringSearch": true,
  "constraints": {
    "maximumFormulaComplexity": 40,
    "randomSeed": 42,
    "candidateBudget": 100000,
    "timeLimitMillis": 60000
  },
  "searchOptions": {
    "population_size": 512,
    "evaluation_strategy": "auto",
    "constant_optimization_preset": "balanced"
  }
}

Les chemins relatifs dataset.path et resumeFrom sont résolus depuis le dossier de request.json, ce qui permet de déplacer le dossier de traitement comme un tout. La cible et les entrées peuvent être désignées par un nom de colonne non ambigu ou par les UUID retournés par dataset inspect. Si inputs est omis, toutes les colonnes sauf la cible sont utilisées.

1. Inspecter les données

equarith-headless dataset inspect \
  --data=measurements.csv \
  --threads=8

Le résultat JSON décrit le dialecte détecté, les diagnostics d’importation, l’empreinte du contenu, le nombre de lignes et de colonnes, ainsi que l’UUID et les statistiques de chaque colonne. Vérifiez que noms, nombres, valeurs manquantes et colonne cible ont le sens attendu.

2. Valider la requête

equarith-headless validate \
  --request=request.json \
  --threads=8

La validation charge la requête et les données, construit la requête typée et applique les contrôles annoncés par les capacités du moteur à la métrique, au découpage, aux fonctions, aux contraintes, au budget d’arrêt et aux limites de licence. Lorsque chargement et construction réussissent, la commande retourne valid, issues et une description des données. Un rejet de syntaxe, de colonne, d’enum, d’entrée-sortie ou de construction peut au contraire se terminer par un diagnostic sur stderr et le code non nul applicable, avant la production de ce JSON. Si --resume-from est fourni, le checkpoint est lu avec les protections de format et de taille ; sa compatibilité sémantique et certaines contraintes croisées ne sont contrôlées qu’au démarrage de search.

3. Exécuter la recherche

equarith-headless search \
  --request=request.json \
  --solutions=solutions.jsonl \
  --events=events.jsonl \
  --checkpoint-out=latest.equarith-checkpoint \
  --threads=8

search reste bloquante jusqu’à la réussite, l’annulation ou l’échec. Le front de Pareto final est écrit dans solutions.jsonl, à raison d’une solution versionnée par ligne. Un résumé JSON est écrit sur stdout. Avec --events=<fichier>, les enveloppes d’événements de recherche sont diffusées vers ce fichier JSON Lines. Sans cette option, une ligne de progression lisible est écrite sur stderr environ une fois par seconde.

Utilisez --events=- si un autre programme doit lire les événements JSON Lines sur stdout. Le bref résumé humain passe alors sur stderr afin que stdout reste lisible par une machine.

Un Ctrl+C demande d’abord une annulation coopérative. Si --checkpoint-out est présent, le chemin d’arrêt tente de conserver le dernier checkpoint. Les solutions déjà publiées restent valides même si la progression interne la plus récente ne peut pas être récupérée.

Reprenez un traitement compatible avec :

equarith-headless validate \
  --request=request.json \
  --resume-from=latest.equarith-checkpoint

equarith-headless search \
  --request=request.json \
  --resume-from=latest.equarith-checkpoint \
  --solutions=solutions.jsonl \
  --checkpoint-out=latest.equarith-checkpoint

--resume-from est prioritaire sur resumeFrom dans la requête. La reprise a lieu si le moteur, le format, les données, la séparation, la métrique, les fonctions et coûts, les contraintes et le budget restant sont compatibles. Une incompatibilité sémantique de la requête ou un budget inférieur déjà épuisé produit un avertissement puis lance une nouvelle recherche. Un moteur ou format de checkpoint non pris en charge, ou une charge utile mal formée ou invalide, échoue explicitement.

4. Exporter les solutions

Cette commande exporte tout le front chargé sous forme de module Python :

equarith-headless export \
  --solutions=solutions.jsonl \
  --format=python \
  --output=equarith_solutions.py

Utilisez --ids=<uuid,uuid,...> pour ne retenir que certaines solutions. Sans cette option, toutes les solutions du fichier JSON Lines sont exportées. Les identifiants de format sont insensibles à la casse et les tirets deviennent des underscores :

CSV JSON PLAIN_TEXT LATEX
PYTHON R JULIA MATLAB OCTAVE SAS EXCEL WOLFRAM
C CPP FORTRAN JAVA KOTLIN SWIFT PHP CSHARP RUST GO
JAVASCRIPT TYPESCRIPT LUA VBA POSTGRESQL IEC_61131_ST

Ainsi, --format=plain-text et --format=iec-61131-st sont valides. CSV, JSON, texte brut et LaTeX sont des exports de présentation ou structurés ; les autres cibles produisent du code source exécutable ou un classeur Excel. L’export JSON n’est pas le fichier de solutions JSON Lines rechargeable attendu par predict et les futurs appels à export.

Consultez Exporter les données et les formules pour les versions cibles, helpers générés, sémantiques numériques et contrôles de déploiement.

5. Prédire avec une solution

Copiez l’UUID voulu depuis solutions.jsonl, puis appliquez la solution à un autre fichier numérique compatible :

equarith-headless predict \
  --data=new-measurements.csv \
  --solutions=solutions.jsonl \
  --solution=<uuid-solution> \
  --output=predictions.csv \
  --label=prediction \
  --threads=8

Le CSV de sortie contient les colonnes importées, suivies de la colonne de prédiction. Le nouveau fichier doit fournir les symboles de colonnes employés par la formule. Une prédiction non finie produit une cellule de prédiction vide ; le résultat JSON de la commande indique validCount et invalidCount afin que l’automatisation puisse la détecter.

Surcharger les paramètres d’importation

L’importation automatique est utilisée par défaut. Pour un dialecte connu, créez import.json :

{
  "delimiter": "SEMICOLON",
  "quoteCharacter": "\"",
  "headerMode": "PRESENT",
  "charsetName": "UTF-8",
  "decimalStyle": "COMMA",
  "missingValueTokens": ["", "NA", "NaN"],
  "trimWhitespace": true,
  "skipBlankRows": true,
  "maximumDiagnostics": 1000
}

Passez-le à dataset inspect ou predict avec --import=import.json, ou placez le même objet dans dataset.import au sein de la requête. Les délimiteurs possibles sont AUTO, COMMA, SEMICOLON, TAB et WHITESPACE ; les modes d’en-tête sont AUTO, PRESENT et ABSENT ; les styles décimaux sont AUTO, DOT et COMMA.

Réglages de recherche du JSON

Les champs les plus utiles sont :

metric : rmse par défaut ; les identifiants actuels sont rmse, mse, mae, nmse, sse, r_squared, squared_correlation, pearson et hybrid ;
trainTest.mode : NO_TEST, FRACTION ou FIXED_TRAINING_ROWS ; choisissez un échantillonnage SEQUENTIAL ou RANDOM avec graine selon les données ;
constraints.candidateBudget et constraints.timeLimitMillis : bornent le travail ; la recherche s’arrête à la première limite applicable ;
les champs structurels sous constraints : complexité maximale des formules, profondeur des expressions, occurrences des variables, nombre de variables distinctes et nombre de constantes ;
constraints.normalizeDataset, constraints.forceAllInputVariables et constraints.integerConstantsOnly : restrictions booléennes facultatives ;
constraints.randomSeed : contrôle le hasard de la recherche ; trainTest.randomSeed contrôle séparément une partition aléatoire ;
functionComplexities : définit le coût de chaque fonction. Lorsqu’une map non vide est fournie, ses clés forment aussi l’ensemble de fonctions activées ;
searchOptions.population_size : 512 par défaut, actuellement de 64 à 8 192 par pas de 64 ;
searchOptions.evaluation_strategy : auto, full ou progressive ;
searchOptions.constant_optimization_preset : fast, balanced ou accurate ;
searchOptions.checkpoint_interval : cinq générations par défaut ; zéro désactive les checkpoints périodiques, mais un checkpoint final peut encore être créé à la fin normale, à la limite de temps ou lors d’un arrêt coopératif.

Le schéma versionné prévoit des champs compatibles avec de futures évolutions, mais le moteur intégré prend actuellement en charge la régression ainsi que les métriques et fonctions intégrées. Interrogez capabilities au lieu de supposer qu’un futur runtime conserve les mêmes identifiants ou bornes.

Fichiers, limites et reproductibilité

Les JSON de requête et d’importation sont limités à 16 Mio et refusent les clés dupliquées.
Le JSON Lines de solutions rechargeable est limité à 64 Mio, 100 000 enregistrements et quatre millions de caractères par ligne.
Une recherche conserve au maximum 256 solutions de Pareto en mémoire, avec le meilleur représentant de chaque complexité.
Les lignes dont la cible ou une entrée sélectionnée n’est pas finie sont exclues avant la séparation.
Les limites effectives de lignes, cellules, colonnes et workers dépendent du runtime et de la mémoire ; consultez capabilities pour les valeurs actuelles.
Fichiers de solutions, checkpoints, prédictions et exports terminés sont écrits dans un fichier temporaire voisin, puis remplacés atomiquement lorsque le système de fichiers le permet, avec un remplacement ordinaire de secours. Les événements JSON Lines sont diffusés en flux et peuvent donc s’arrêter après le dernier enregistrement complet en cas d’interruption.
Lorsque la reproductibilité importe, conservez la requête, l’empreinte d’entrée, la version du runtime, les graines, le nombre de workers, les solutions et le checkpoint. Un autre runtime, JDK, matériel ou nombre de workers peut modifier l’ordre des découvertes.

Codes de sortie

0 : succès ;
1 : échec inattendu ou interne ;
2 : syntaxe, option, paramètre ou validation de recherche incorrect ;
3 : erreur de fichier ou d’entrée-sortie ;
4 : échec du calcul de recherche ou de prédiction ;
5 : échec d’une opération de licence ;
130 : interruption ou recherche annulée.

Basez l’automatisation sur ces codes et sur stdout lisible par une machine. Le texte humain de stderr sert au diagnostic et ne constitue pas une API stable.

Protocole local persistant

Pour enchaîner plusieurs opérations dans un même processus durable, exécutez :

equarith-headless serve --stdio --threads=8

Le processus échange un objet JSON-RPC 2.0 UTF-8 par ligne sur stdin et stdout. Stdout est réservé au protocole ; les diagnostics vont sur stderr. Un client commence par :

{"jsonrpc":"2.0","id":1,"method":"system.handshake","params":{}}

Le handshake annonce le protocole 1.3, les versions du runtime et du moteur, les méthodes, formats d’export ainsi que les limites de messages et de concurrence. engine.capabilities indique le parallélisme configuré du moteur. system.describe retourne la description OpenRPC embarquée. Le protocole couvre licence, capacités, chargement local des données, validation, recherche et checkpoints, stockage et export des solutions, ainsi que prédiction par blocs.

Un processus accepte une seule recherche active. Pour des tâches concurrentes, démarrez plusieurs processus avec des nombres de threads explicites. Le protocole n’emploie aucun port, authentification distante, découverte réseau ou calcul distant.

SDK — bientôt disponibles

Les SDK officiels seront bientôt disponibles pour Python, TypeScript, JavaScript sous Node.js, Java, C#/.NET, C++ et Lua. Ils piloteront le runtime Equarith Headless installé localement, sans embarquer ni télécharger une seconde copie du moteur.

En attendant la publication des paquets et de leurs métadonnées, utilisez les commandes CLI ci-dessus ou le protocole JSON-RPC local sur stdin/stdout. Ne considérez pas un instantané source d’un SDK non publié comme un paquet de production pris en charge.

Pour le stockage de la licence et la liste complète des fonctions réseau explicites, consultez Licence, confidentialité et accès réseau. Pour interpréter et valider les formules, consultez Comprendre les résultats et l’analyse.

Documentation d’Equarith.