Holarch

Riferimento

Il client Python

Leggere progetti Holarch, cercare elementi e proporre modifiche da rivedere da script Python con il pacchetto gratuito holarch-api; installazione, accesso, ogni metodo, proposte, errori e limiti.

Come usarlo →

In questa pagina
  1. Panoramica
  2. Concetti
  3. Come usarlo
    1. Quando e perché
    2. Installare e accedere
    3. Leggere un progetto
    4. Proporre modifiche
    5. Esempio pratico: la demo CubeSat EO-1
    6. Progetti SysML v2
    7. Suggerimenti e buone pratiche
    8. Errori comuni
  4. Riferimento
    1. Client
    2. Proposta
    3. Errori
  5. Limiti
  6. Pagine correlate

Panoramica

holarch-api è un piccolo pacchetto Python per la REST API di Holarch. Legge progetti, elementi, documenti e risultati dei controlli, esegue ricerche e propone modifiche. È gratuito; l'API stessa è inclusa nei piani che la comprendono e il pacchetto usa il proprio token di accesso personale.

Le modifiche effettuate tramite il pacchetto sono sempre proposte: si raccolgono sul server e i proprietari del progetto le esaminano e le applicano in Holarch, esattamente come le modifiche dai client di IA, e un solo annullamento revoca ogni proposta applicata. Il pacchetto non ha metodi che modificano direttamente un progetto. Gli script che devono scrivere direttamente usano le chiamate di scrittura della REST API.

Concetti

  • Client: un token su un server Holarch. Ogni metodo invia una richiesta (o una per pagina) e restituisce il JSON dell'API come dizionari e liste Python.
  • Risposte tipizzate: il pacchetto contiene informazioni sui tipi (forme TypedDict come Entity e ProjectSummary), così gli editor completano i nomi dei campi e i type checker come mypy li controllano. I campi che il server aggiunge in seguito compaiono semplicemente nei dizionari.
  • Proposta: la propria proposta aperta in un progetto. Ogni chiamata aggiunge una modifica; send() consegna la proposta ai proprietari del progetto per la revisione. Un token ha al massimo una proposta aperta per progetto.
  • Riferimenti: un'entità creata in una proposta non esiste ancora. create() restituisce un riferimento (new:1, new:2, …) che le modifiche successive nella stessa proposta usano al posto di un id.

Come usarlo

Quando e perché

Usare il client per gli script attorno a un progetto: report ed esportazioni nel proprio formato, controlli in un'attività notturna, importazioni da un altro strumento che una persona dovrebbe esaminare prima che vengano applicate. Poiché le modifiche arrivano come proposte, uno script non sorprende mai il team: i proprietari vedono ogni modifica prima che venga applicata.

Installare e accedere

  1. Installare Python 3.9 o successivo, poi il pacchetto: python3 -m pip install holarch-api. Non richiede altro oltre a Python.
  2. In Holarch, aprire Impostazioni account → Token API e creare un token: Sola lettura per gli script che si limitano a leggere, Lettura e scrittura per gli script che propongono modifiche. Limitarlo ai progetti di cui lo script ha bisogno.
  3. Inserire il token nella variabile d'ambiente HOLARCH_API_KEY.
  4. Verificare la connessione:
from holarch_api import Client

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

Leggere un progetto

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 recupera ogni corrispondenza una pagina alla volta; entities restituisce una pagina (entities, total, offset, limit). search(pid, "thermal") trova le entità il cui nome, numero, descrizione o classe contengono il testo.

Proporre modifiche

  1. Avviare una proposta: p = c.proposal(pid).
  2. Aggiungere modifiche. Ogni chiamata viene controllata subito dal server e fallisce con un errore quando la classe, la relazione o l'attributo non esiste:
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. Guardare cosa è stato raccolto: p.get()["changes"]. Il progetto non è cambiato.
  2. Inviarla: view = p.send("Add a TVAC test", "Covers the two thermal requirements."). view["review"] è il link che apre la revisione in Holarch.

I proprietari ricevono una notifica ed esaminano la proposta dal menu ✦ IA ▾; vedere Proposte dai client di IA. Per scartare una proposta prima dell'invio, chiamare p.discard(). Per seguirla in seguito, c.get_proposal(pid, view["id"])["status"] è ready, applied, rejected o expired.

Esempio pratico: la demo CubeSat EO-1

  1. Creare un token di sola lettura per il progetto CubeSat e impostare HOLARCH_API_KEY.
  2. Elencare i rilievi sui requisiti dei controlli del modello:
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. Assegnare un punteggio ai requisiti: c.quality(pid)["results"] elenca ogni requisito con il suo punteggio e i rilievi.
  2. Con un token di lettura e scrittura, proporre un caso di test per un requisito che non ne ha, come in Proporre modifiche, e inviarlo. Dopo che un proprietario lo ha applicato, i controlli del modello non elencano più il requisito.

Progetti SysML v2

Lo stesso client legge i progetti SysML v2: model(pid) (package e conteggi), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) e sysml_text(pid, root="Vehicles"). check_sysml(pid, text) controlla un testo senza proporlo. Per proporre una modifica, inviare il nuovo testo di un package con p.sysml_text(text, root="Vehicles"), oppure modifiche agli elementi con p.sysml_edits([...]); il motore controlla ogni modifica e rifiuta quelle con errori. Vedere API e MCP nei progetti SysML v2.

Suggerimenti e buone pratiche

  • Leggere prima lo schema (c.schema(pid)): elenca i nomi di classi, attributi e relazioni usati dal progetto.
  • Dare a ogni script il proprio token, di sola lettura dove si limita a leggere.
  • Raccogliere le modifiche correlate in un'unica proposta e inviarla con un titolo e un riepilogo che ne spieghino il motivo: il revisore vede l'intera modifica in una volta.
  • Tenere i token fuori dai file sorgente; il client legge HOLARCH_API_KEY per questo motivo.

Errori comuni

  • ApiError con codice read-only-token: il token è di sola lettura; creare un token di lettura e scrittura per le proposte.
  • ApiError con codice not-found su un progetto che si può aprire in Holarch: il token è limitato ad altri progetti.
  • Un'entità creata non si trova con entity(): esiste solo nella proposta finché un proprietario non la applica.

Riferimento

Client

Client(token=None, server=None, timeout=30.0, retries=3). token ha come valore predefinito HOLARCH_API_KEY, server HOLARCH_SERVER o https://app.holarch.app. Il server deve essere un indirizzo https.

MetodoRestituisce
me()L'account, l'accesso e la scadenza del token
projects()I propri progetti: id, nome, ruolo, numero di elementi, linguaggio, link
project(pid)Nome, descrizione, ruolo, numero di elementi, elementi per classe, numero di documenti
schema(pid)Classi con attributi e relazioni consentite; relazioni
entities(pid, cls=None, label=None, q=None, limit=100, offset=0)Una pagina di entità (al massimo 500)
iter_entities(pid, cls=None, label=None, q=None, page_size=500)Ogni entità corrispondente
search(pid, text, cls=None, limit=100)Le entità il cui nome, numero, descrizione o classe contengono il testo
entity(pid, id)Un'entità con attributi, etichette e relazioni
documents(pid)Documenti con tipo e numero di sezioni
document(pid, id)Un documento con le sue sezioni in ordine, numerate, come testo semplice
model_checks(pid, cls=None, rule=None, limit=500, offset=0)Rilievi dei controlli del modello con un riepilogo
quality(pid, ids=None)Il controllo di qualità dei requisiti, per i requisiti indicati o per tutti
versions(pid)Le versioni salvate che il piano del progetto conserva
configurations(pid)La linea di prodotti: funzionalità, regole e configurazioni con selezione, esito e applicabilità
proposal(pid)Una Proposal per la propria proposta aperta nel progetto
get_proposal(pid, proposal_id=None)La proposta aperta, o una tramite id, con stato e modifiche
request(method, path, params=None, body=None)Qualsiasi altra chiamata API, relativa a /api/v1

project, entities, iter_entities, search, entity, documents, document, model_checks e quality accettano anche configuration= (il numero, il nome o l'id di una configurazione) ed effectivity= ("sn:23" o "date:2027-03-01") per leggere il modello come lo mostra una configurazione di una linea di prodotti (Linee di prodotti).

Proposta

MetodoCosa propone
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None)Una nuova entità; relationships come coppie (relation, target); restituisce il suo riferimento
update(entity, name=None, number=None, description=None, labels=None, attributes=None)Campi modificati; i campi omessi restano, un attributo impostato su None perde il suo valore
delete(entity)Lo spostamento dell'entità nel cestino del progetto
relate(source, relation, target, attributes=None)Una nuova relazione, nominata dal punto di vista dell'origine
unrelate(relationship)La rimozione di una relazione (il suo id da entity())
get()Nulla: restituisce la proposta con le sue modifiche
send(title, summary="")Nulla di più: invia la proposta per la revisione e la restituisce con il link di revisione
discard()Nulla: scarta la proposta aperta

create e update accettano anche applies_to= ("F-3 and not F-5"; "" lo cancella) ed effectivity= ({"serials": "1-20, 25"}; {} la cancella), e ogni modifica accetta configuration= per proporla come modifica in quella configurazione (Linee di prodotti).

Errori

Ogni richiesta rifiutata solleva holarch_api.ApiError con message (il testo del server), code, status e body. I codici sono quelli della REST API. Una richiesta rifiutata con 429 rate-limited viene ritentata dopo il tempo indicato dal server, fino a retries volte, prima di sollevare l'errore.

Limiti

  • Si applicano i limiti dell'API (API e MCP): frequenza delle richieste, al massimo 500 entità per pagina e il limite di elementi del progetto quando una proposta viene applicata.
  • Una proposta scade 7 giorni dopo il suo avvio.
  • Il client funziona con il servizio ospitato.