Holarch

Référence

Le client Python

Lisez des projets Holarch, recherchez des éléments et proposez des modifications à examiner depuis des scripts Python avec le package gratuit holarch-api ; installation, connexion, toutes les méthodes, propositions, erreurs et limites.

Utilisation →

Sur cette page
  1. Vue d'ensemble
  2. Concepts
  3. Mode d'emploi
    1. Quand et pourquoi
    2. Installer et se connecter
    3. Lire un projet
    4. Proposer des modifications
    5. Exemple complet : la démo CubeSat EO-1
    6. Projets SysML v2
    7. Conseils et bonnes pratiques
    8. Erreurs courantes
  4. Référence
    1. Client
    2. Proposition
    3. Erreurs
  5. Limites
  6. Pages associées

Vue d'ensemble

holarch-api est un petit paquet Python pour l'API REST de Holarch. Il lit les projets, les éléments, les documents et les résultats de contrôle, effectue des recherches et propose des modifications. Il est gratuit ; l'API elle-même est fournie avec les offres qui l'incluent, et le paquet utilise votre jeton d'accès personnel.

Les modifications faites par le paquet sont toujours des propositions : elles s'accumulent sur le serveur, et les propriétaires du projet les examinent et les appliquent dans Holarch, exactement comme les modifications des clients d'IA, et une seule annulation défait chaque proposition appliquée. Le paquet n'a aucune méthode qui modifie directement un projet. Les scripts qui doivent écrire directement utilisent les appels d'écriture de l'API REST.

Concepts

  • Client : un jeton sur un serveur Holarch. Chaque méthode envoie une requête (ou une par page) et renvoie le JSON de l'API sous forme de dict et de listes Python.
  • Réponses typées : le paquet fournit des informations de type (des formes TypedDict telles que Entity et ProjectSummary) : les éditeurs complètent donc les noms de champs et les vérificateurs de types comme mypy les contrôlent. Les champs que le serveur ajoute plus tard apparaissent simplement dans les dict.
  • Proposition : votre proposition ouverte dans un projet. Chaque appel ajoute une modification ; send() remet la proposition aux propriétaires du projet pour revue. Un jeton a au plus une proposition ouverte par projet.
  • Références : une entité créée dans une proposition n'existe pas encore. create() renvoie une référence (new:1, new:2, …) que les modifications suivantes de la même proposition utilisent à la place d'un id.

Mode d'emploi

Quand et pourquoi

Utilisez le client pour les scripts autour d'un projet : rapports et exportations dans votre propre format, contrôles dans une tâche nocturne, importations depuis un autre outil qu'une personne doit examiner avant leur arrivée. Comme les modifications arrivent sous forme de propositions, un script ne surprend jamais l'équipe : les propriétaires voient chaque modification avant qu'elle soit appliquée.

Installer et se connecter

  1. Installez Python 3.9 ou une version ultérieure, puis le paquet : python3 -m pip install holarch-api. Il n'a besoin de rien d'autre que Python.
  2. Dans Holarch, ouvrez Paramètres du compte → Jetons API et créez un jeton : Lecture seule pour les scripts qui ne font que lire, Lecture et écriture pour les scripts qui proposent des modifications. Limitez-le aux projets dont le script a besoin.
  3. Placez le jeton dans la variable d'environnement HOLARCH_API_KEY.
  4. Vérifiez la connexion :
from holarch_api import Client

c = Client()
print(c.me()["user"]["email"])
for p in c.projects():
    print(p["id"], p["name"], p["role"])

Lire un projet

c = Client()
pid = "…"                                   # the project id from c.projects()
info = c.project(pid)                       # name, description, items per class
for e in c.iter_entities(pid, cls="Requirement"):
    print(e["number"], e["name"])
req = c.entity(pid, "…")                    # one entity with attributes and relationships
for r in req["relationships"]:
    print(r["relation"], r["other"]["name"])

iter_entities récupère chaque correspondance une page à la fois ; entities renvoie une seule page (entities, total, offset, limit). search(pid, "thermal") trouve les entités dont le nom, le numéro, la description ou la classe contiennent le texte.

Proposer des modifications

  1. Commencez une proposition : p = c.proposal(pid).
  2. Ajoutez des modifications. Chaque appel est vérifié aussitôt par le serveur et échoue avec une erreur lorsque la classe, la relation ou l'attribut n'existe pas :
p = c.proposal(pid)
tc = p.create("Test Case", "Thermal vacuum test", description="Soak at -40 C for 8 hours.",
              relationships=[("verifies", "…requirement id…")])
p.update("…", attributes={"Status": "Approved"})
p.relate(tc, "verifies", "…another requirement id…")
  1. Regardez ce qui a été rassemblé : p.get()["changes"]. Le projet n'a pas changé.
  2. Envoyez-la : view = p.send("Add a TVAC test", "Covers the two thermal requirements."). view["review"] est le lien qui ouvre la revue dans Holarch.

Les propriétaires reçoivent une notification et examinent la proposition depuis le menu ✦ IA ▾ ; voir Propositions des clients d'IA. Pour abandonner une proposition avant son envoi, appelez p.discard(). Pour en suivre l'évolution plus tard, c.get_proposal(pid, view["id"])["status"] vaut ready, applied, rejected ou expired.

Exemple complet : la démo CubeSat EO-1

  1. Créez un jeton en lecture seule pour le projet CubeSat et définissez HOLARCH_API_KEY.
  2. Listez les constats des Contrôles du modèle sur les exigences :
c = Client()
pid = next(p["id"] for p in c.projects() if p["name"].startswith("CubeSat"))
checks = c.model_checks(pid, cls="Requirement")
print(checks["total"], "findings")
  1. Notez les exigences : c.quality(pid)["results"] liste chaque exigence avec son score et ses constats.
  2. Avec un jeton en lecture et écriture, proposez un cas de test pour une exigence qui n'en a pas, comme dans Proposer des modifications, et envoyez la proposition. Une fois qu'un propriétaire l'a appliquée, les Contrôles du modèle ne listent plus l'exigence.

Projets SysML v2

Le même client lit les projets SysML v2 : model(pid) (packages et décomptes), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) et sysml_text(pid, root="Vehicles"). check_sysml(pid, text) vérifie un texte sans le proposer. Pour proposer une modification, envoyez le nouveau texte d'un package avec p.sysml_text(text, root="Vehicles"), ou des modifications d'éléments avec p.sysml_edits([...]) ; le moteur vérifie chaque modification et refuse celle qui comporte des erreurs. Voir L'API et MCP dans les projets SysML v2.

Conseils et bonnes pratiques

  • Lisez d'abord le schéma (c.schema(pid)) : il liste les noms de classes, d'attributs et de relations qu'utilise le projet.
  • Donnez à chaque script son propre jeton, en lecture seule là où il ne fait que lire.
  • Rassemblez les modifications liées dans une seule proposition et envoyez-la avec un titre et un résumé qui en expliquent la raison : le relecteur voit toute la modification d'un coup.
  • Gardez les jetons hors des fichiers source ; c'est pourquoi le client lit HOLARCH_API_KEY.

Erreurs courantes

  • ApiError avec le code read-only-token : le jeton est en lecture seule ; créez un jeton en lecture et écriture pour les propositions.
  • ApiError avec le code not-found sur un projet que vous pouvez ouvrir dans Holarch : le jeton est limité à d'autres projets.
  • Une entité créée est introuvable avec entity() : elle n'existe que dans la proposition jusqu'à ce qu'un propriétaire l'applique.

Référence

Client

Client(token=None, server=None, timeout=30.0, retries=3). token vaut par défaut HOLARCH_API_KEY, et server HOLARCH_SERVER ou https://app.holarch.app. Le serveur doit être une adresse https.

MéthodeRenvoie
me()Le compte, l'accès et l'expiration du jeton
projects()Vos projets : id, nom, rôle, nombre d'éléments, langage, lien
project(pid)Nom, description, rôle, nombre d'éléments, éléments par classe, nombre de documents
schema(pid)Classes avec leurs attributs et leurs relations autorisées ; relations
entities(pid, cls=None, label=None, q=None, limit=100, offset=0)Une page d'entités (au plus 500)
iter_entities(pid, cls=None, label=None, q=None, page_size=500)Chaque entité correspondante
search(pid, text, cls=None, limit=100)Entités dont le nom, le numéro, la description ou la classe contiennent le texte
entity(pid, id)Une entité avec ses attributs, ses étiquettes et ses relations
documents(pid)Documents avec leur type et leur nombre de sections
document(pid, id)Un document avec ses sections dans l'ordre, numérotées, en texte brut
model_checks(pid, cls=None, rule=None, limit=500, offset=0)Constats des Contrôles du modèle avec un résumé
quality(pid, ids=None)Le contrôle de la qualité des exigences, pour les exigences données ou pour toutes
versions(pid)Les versions enregistrées que conserve l'offre du projet
configurations(pid)La ligne de produits : caractéristiques, règles et configurations avec leur sélection, leur verdict et leur applicabilité
proposal(pid)Un Proposal pour votre proposition ouverte dans le projet
get_proposal(pid, proposal_id=None)La proposition ouverte, ou une proposition par son id, avec son statut et ses modifications
request(method, path, params=None, body=None)Tout autre appel API, relatif à /api/v1

project, entities, iter_entities, search, entity, documents, document, model_checks et quality acceptent aussi configuration= (le numéro, le nom ou l'id d'une configuration) et effectivity= ("sn:23" ou "date:2027-03-01") pour lire le modèle tel qu'une configuration d'une ligne de produits le présente (Lignes de produits).

Proposition

MéthodeCe qu'il propose
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None)Une nouvelle entité ; relationships sous forme de paires (relation, target) ; renvoie sa référence
update(entity, name=None, number=None, description=None, labels=None, attributes=None)Champs modifiés ; les champs omis restent inchangés, un attribut défini à None perd sa valeur
delete(entity)Placer l'entité dans la corbeille du projet
relate(source, relation, target, attributes=None)Une nouvelle relation, nommée depuis la source
unrelate(relationship)Retirer une relation (son id provenant de entity())
get()Rien : renvoie la proposition avec ses modifications
send(title, summary="")Rien de plus : envoie la proposition pour revue et la renvoie avec le lien de revue
discard()Rien : abandonne la proposition ouverte

create et update acceptent aussi applies_to= ("F-3 and not F-5" ; "" l'efface) et effectivity= ({"serials": "1-20, 25"} ; {} l'efface), et chaque modification accepte configuration= pour la proposer comme modification dans cette configuration (Lignes de produits).

Erreurs

Chaque requête refusée lève holarch_api.ApiError avec message (le texte du serveur), code, status et body. Les codes sont ceux de l'API REST. Une requête refusée avec 429 rate-limited est retentée après le délai indiqué par le serveur, jusqu'à retries fois, avant de lever l'erreur.

Limites

  • Les limites de l'API s'appliquent (API et MCP) : fréquence des requêtes, au plus 500 entités par page, et limite d'éléments du projet lorsqu'une proposition est appliquée.
  • Une proposition expire 7 jours après avoir été commencée.
  • Le client fonctionne avec le service hébergé.