Holarch

Referencja

Klient Python

Odczytuj projekty Holarch, przeszukuj elementy i proponuj zmiany do przeglądu ze skryptów Pythona za pomocą bezpłatnego pakietu holarch-api; instalacja, logowanie, każda metoda, propozycje, błędy i limity.

Jak z niego korzystać →

Na tej stronie
  1. Przegląd
  2. Pojęcia
  3. Jak z niego korzystać
    1. Kiedy i dlaczego
    2. Instalacja i logowanie
    3. Odczyt projektu
    4. Proponowanie zmian
    5. Przykład: demo CubeSat EO-1
    6. Projekty SysML v2
    7. Wskazówki i dobre praktyki
    8. Typowe błędy
  4. Referencja
    1. Klient
    2. Propozycja
    3. Błędy
  5. Limity
  6. Powiązane strony

Przegląd

holarch-api to mały pakiet Python dla REST API Holarch. Odczytuje projekty, elementy, dokumenty i wyniki kontroli, wyszukuje i proponuje zmiany. Jest bezpłatny; samo API jest dostępne w planach, które je obejmują, a pakiet używa Twojego osobistego tokenu dostępu.

Zmiany wprowadzane przez pakiet są zawsze propozycjami: zbierają się na serwerze, a właściciele projektu przeglądają je i stosują w Holarch, dokładnie tak jak zmiany od klientów AI, a jedno polecenie Cofnij wycofuje każdą zastosowaną propozycję. Pakiet nie ma metod zmieniających projekt bezpośrednio. Skrypty, które muszą zapisywać bezpośrednio, używają wywołań zapisu REST API.

Pojęcia

  • Klient: jeden token na jednym serwerze Holarch. Każda metoda wysyła jedno żądanie (lub jedno na stronę) i zwraca JSON z API jako słowniki i listy Python.
  • Odpowiedzi z typami: pakiet zawiera informacje o typach (kształty TypedDict, takie jak Entity i ProjectSummary), więc edytory uzupełniają nazwy pól, a narzędzia sprawdzania typów, takie jak mypy, je sprawdzają. Pola dodane później przez serwer po prostu pojawiają się w słownikach.
  • Propozycja: Twoja otwarta propozycja w jednym projekcie. Każde wywołanie dodaje jedną zmianę; send() przekazuje propozycję właścicielom projektu do przeglądu. Jeden token ma najwyżej jedną otwartą propozycję na projekt.
  • Odwołania: encja utworzona w propozycji jeszcze nie istnieje. create() zwraca odwołanie (new:1, new:2, …), którego późniejsze zmiany w tej samej propozycji używają zamiast id.

Jak z niego korzystać

Kiedy i dlaczego

Używaj klienta do skryptów wokół projektu: raportów i eksportów we własnym formacie, kontroli w nocnym zadaniu, importów z innego narzędzia, które człowiek powinien przejrzeć przed ich wprowadzeniem. Ponieważ zmiany przychodzą jako propozycje, skrypt nigdy nie zaskakuje zespołu: właściciele widzą każdą zmianę przed jej zastosowaniem.

Instalacja i logowanie

  1. Zainstaluj Python 3.9 lub nowszy, a następnie pakiet: python3 -m pip install holarch-api. Nie potrzebuje niczego poza Pythonem.
  2. W Holarch otwórz Ustawienia konta → Tokeny API i utwórz token: Tylko do odczytu dla skryptów, które tylko odczytują, Odczyt i zapis dla skryptów proponujących zmiany. Ogranicz go do projektów potrzebnych skryptowi.
  3. Umieść token w zmiennej środowiskowej HOLARCH_API_KEY.
  4. Sprawdź połączenie:
from holarch_api import Client

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

Odczyt projektu

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 pobiera każde dopasowanie stronami; entities zwraca jedną stronę (entities, total, offset, limit). search(pid, "thermal") znajduje encje, których nazwa, numer, opis lub klasa zawierają tekst.

Proponowanie zmian

  1. Rozpocznij propozycję: p = c.proposal(pid).
  2. Dodaj zmiany. Każde wywołanie jest od razu sprawdzane przez serwer i kończy się błędem, gdy klasa, relacja lub atrybut nie istnieją:
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. Zobacz, co zebrano: p.get()["changes"]. Projekt się nie zmienił.
  2. Wyślij ją: view = p.send("Add a TVAC test", "Covers the two thermal requirements."). view["review"] to łącze otwierające przegląd w Holarch.

Właściciele otrzymują powiadomienie i przeglądają propozycję z menu ✦ AI ▾; zobacz Propozycje od klientów AI. Aby odrzucić propozycję przed jej wysłaniem, wywołaj p.discard(). Aby sprawdzić ją później, c.get_proposal(pid, view["id"])["status"] ma wartość ready, applied, rejected lub expired.

Przykład: demo CubeSat EO-1

  1. Utwórz token tylko do odczytu dla projektu CubeSat i ustaw HOLARCH_API_KEY.
  2. Wyświetl ustalenia kontroli modelu dotyczące wymagań:
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. Oceń wymagania: c.quality(pid)["results"] wymienia każde wymaganie z jego oceną i ustaleniami.
  2. Z tokenem do odczytu i zapisu zaproponuj przypadek testowy dla wymagania, które go nie ma, jak w sekcji Proponowanie zmian, i wyślij propozycję. Gdy właściciel ją zastosuje, kontrole modelu przestają wymieniać to wymaganie.

Projekty SysML v2

Ten sam klient odczytuje projekty SysML v2: model(pid) (pakiety i liczby), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) i sysml_text(pid, root="Vehicles"). check_sysml(pid, text) sprawdza tekst bez proponowania go. Aby zaproponować zmianę, wyślij nowy tekst pakietu przez p.sysml_text(text, root="Vehicles") lub edycje obiektów przez p.sysml_edits([...]); silnik sprawdza każdą zmianę i odrzuca zmianę z błędami. Zobacz API i MCP w projektach SysML v2.

Wskazówki i dobre praktyki

  • Najpierw odczytaj schemat (c.schema(pid)): wymienia on nazwy klas, atrybutów i relacji używanych w projekcie.
  • Daj każdemu skryptowi własny token, tylko do odczytu tam, gdzie tylko odczytuje.
  • Zbieraj powiązane zmiany w jednej propozycji i wysyłaj ją z tytułem i podsumowaniem wyjaśniającymi cel: recenzent widzi od razu całą zmianę.
  • Nie umieszczaj tokenów w plikach źródłowych; dlatego klient odczytuje HOLARCH_API_KEY.

Typowe błędy

  • ApiError z kodem read-only-token: token jest tylko do odczytu; dla propozycji utwórz token do odczytu i zapisu.
  • ApiError z kodem not-found dla projektu, który możesz otworzyć w Holarch: token jest ograniczony do innych projektów.
  • Utworzonej encji nie można znaleźć przez entity(): istnieje ona tylko w propozycji, dopóki właściciel jej nie zastosuje.

Referencja

Klient

Client(token=None, server=None, timeout=30.0, retries=3). token ma domyślnie wartość HOLARCH_API_KEY, server wartość HOLARCH_SERVER lub https://app.holarch.app. Serwer musi mieć adres https.

MetodaZwraca
me()Konto tokenu, dostęp i wygaśnięcie
projects()Twoje projekty: id, nazwa, rola, liczba elementów, język, łącze
project(pid)Nazwa, opis, rola, liczba elementów, elementy na klasę, liczba dokumentów
schema(pid)Klasy z atrybutami i dozwolonymi relacjami; relacje
entities(pid, cls=None, label=None, q=None, limit=100, offset=0)Jedna strona encji (najwyżej 500)
iter_entities(pid, cls=None, label=None, q=None, page_size=500)Każda pasująca encja
search(pid, text, cls=None, limit=100)Encje, których nazwa, numer, opis lub klasa zawierają tekst
entity(pid, id)Jedna encja z atrybutami, etykietami i relacjami
documents(pid)Dokumenty z typem i liczbą sekcji
document(pid, id)Jeden dokument z sekcjami w kolejności, numerowanymi, jako zwykły tekst
model_checks(pid, cls=None, rule=None, limit=500, offset=0)Ustalenia kontroli modelu z podsumowaniem
quality(pid, ids=None)Kontrola jakości wymagań, dla podanych wymagań lub wszystkich
versions(pid)Zapisane wersje przechowywane w ramach planu projektu
configurations(pid)Linia produktów: cechy, reguły i konfiguracje z wyborem, werdyktem i zakresem obowiązywania
proposal(pid)Proposal dla Twojej otwartej propozycji w projekcie
get_proposal(pid, proposal_id=None)Otwarta propozycja lub propozycja o danym id, ze statusem i zmianami
request(method, path, params=None, body=None)Dowolne inne wywołanie API, względem /api/v1

project, entities, iter_entities, search, entity, documents, document, model_checks i quality przyjmują też configuration= (numer, nazwa lub id konfiguracji) i effectivity= ("sn:23" lub "date:2027-03-01"), aby odczytać model tak, jak pokazuje go jedna konfiguracja linii produktów (Linie produktów).

Propozycja

MetodaCo proponuje
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None)Nową encję; relationships jako pary (relation, target); zwraca jej odwołanie
update(entity, name=None, number=None, description=None, labels=None, attributes=None)Zmienione pola; pominięte pola pozostają, atrybut ustawiony na None traci wartość
delete(entity)Przeniesienie encji do kosza projektu
relate(source, relation, target, attributes=None)Nową relację, nazwaną od strony źródła
unrelate(relationship)Usunięcie relacji (jej id z entity())
get()Nic: zwraca propozycję z jej zmianami
send(title, summary="")Nic więcej: wysyła propozycję do przeglądu i zwraca ją z łączem do przeglądu
discard()Nic: odrzuca otwartą propozycję

create i update przyjmują też applies_to= ("F-3 and not F-5"; "" czyści) i effectivity= ({"serials": "1-20, 25"}; {} czyści), a każda zmiana przyjmuje configuration=, aby zaproponować ją jako edycję w tej konfiguracji (Linie produktów).

Błędy

Każde odrzucone żądanie zgłasza holarch_api.ApiError z message (tekst serwera), code, status i body. Kody są takie jak w REST API. Żądanie odrzucone z 429 rate-limited jest ponawiane po czasie podanym przez serwer, do retries razy, zanim zostanie zgłoszony błąd.

Limity

  • Obowiązują limity API (API i MCP): szybkość żądań, najwyżej 500 encji na stronę i limit elementów projektu przy stosowaniu propozycji.
  • Propozycja wygasa 7 dni po jej rozpoczęciu.
  • Klient działa z usługą hostowaną.