Holarch

הפניה

לקוח ה-Python

קריאת פרויקטים של Holarch, חיפוש פריטים והצעת שינויים לסקירה מסקריפטים של Python עם החבילה החינמית holarch-api; התקנה, כניסה, כל שיטה, הצעות, שגיאות ומגבלות.

אופן השימוש ←

בדף זה
  1. סקירה כללית
  2. מושגים
  3. איך להשתמש בה
    1. מתי ולמה
    2. התקנה וכניסה
    3. קריאת פרויקט
    4. הצעת שינויים
    5. דוגמה מעשית: הדגמת CubeSat EO-1
    6. פרויקטי SysML v2
    7. עצות ושיטות עבודה טובות
    8. טעויות נפוצות
  4. הפניה
    1. Client
    2. Proposal
    3. שגיאות
  5. מגבלות
  6. דפים קשורים

סקירה כללית

holarch-api היא חבילת Python קטנה עבור ה-REST API של Holarch. היא קוראת פרויקטים, פריטים, מסמכים ותוצאות בדיקות, מחפשת ומציעה שינויים. היא חינמית; ה-API עצמו כלול בתוכניות שכוללות אותו, והחבילה משתמשת באסימון הגישה האישי שלך.

שינויים שנעשים דרך החבילה הם תמיד הצעות: הם נאספים בשרת, והבעלים של הפרויקט סוקרים ומחילים אותם ב-Holarch, בדיוק כמו שינויים מלקוחות AI, וביטול פעולה אחד מבטל כל הצעה שהוחלה. לחבילה אין מתודות שמשנות פרויקט ישירות. סקריפטים שחייבים לכתוב ישירות משתמשים בקריאות הכתיבה של ה-REST API.

מושגים

  • Client: אסימון אחד בשרת Holarch אחד. כל מתודה שולחת בקשה אחת (או אחת לכל עמוד) ומחזירה את ה-JSON של ה-API כמילונים ורשימות של Python.
  • תשובות עם טיפוסים: החבילה נושאת מידע על טיפוסים (צורות TypedDict כגון Entity ו-ProjectSummary), כך שעורכים משלימים שמות שדות ובודקי טיפוסים כגון mypy בודקים אותם. שדות שהשרת יוסיף בהמשך פשוט מופיעים במילונים.
  • Proposal: ההצעה הפתוחה שלך בפרויקט אחד. כל קריאה מוסיפה שינוי אחד; send() מעביר את ההצעה לבעלים של הפרויקט לסקירה. לאסימון אחד יש לכל היותר הצעה פתוחה אחת לכל פרויקט.
  • הפניות: ישות שנוצרה בהצעה עדיין אינה קיימת. create() מחזיר הפניה (new:1, new:2, …) ששינויים מאוחרים יותר באותה הצעה משתמשים בה במקום מזהה.

איך להשתמש בה

מתי ולמה

משתמשים בלקוח לסקריפטים סביב פרויקט: דוחות וייצואים בפורמט שלך, בדיקות במשימה לילית, ייבואים מכלי אחר שאדם צריך לסקור לפני שהם נכנסים. מכיוון ששינויים מגיעים כהצעות, סקריפט אף פעם אינו מפתיע את הצוות: הבעלים רואים כל שינוי לפני שהוא מוחל.

התקנה וכניסה

  1. יש להתקין Python 3.9 ואילך, ואז את החבילה: python3 -m pip install holarch-api. היא אינה צריכה שום דבר מלבד Python.
  2. ב-Holarch, יש לפתוח את הגדרות החשבון ← אסימוני API וליצור אסימון: קריאה בלבד לסקריפטים שרק קוראים, קריאה וכתיבה לסקריפטים שמציעים שינויים. יש להגביל אותו לפרויקטים שהסקריפט צריך.
  3. יש לשים את האסימון במשתנה הסביבה HOLARCH_API_KEY.
  4. יש לבדוק את החיבור:
from holarch_api import Client

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

קריאת פרויקט

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 מביא כל התאמה עמוד אחר עמוד; entities מחזיר עמוד אחד (entities, total, offset, limit). search(pid, "thermal") מוצא ישויות שהשם, המספר, התיאור או המחלקה שלהן מכילים את הטקסט.

הצעת שינויים

  1. מתחילים הצעה: p = c.proposal(pid).
  2. מוסיפים שינויים. כל קריאה נבדקת מיד על ידי השרת ונכשלת עם שגיאה כשהמחלקה, הקשר או המאפיין אינם קיימים:
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. בודקים מה נאסף: p.get()["changes"]. הפרויקט לא השתנה.
  2. שולחים אותה: view = p.send("Add a TVAC test", "Covers the two thermal requirements."). view["review"] הוא הקישור שפותח את הסקירה ב-Holarch.

הבעלים מקבלים התראה וסוקרים את ההצעה מהתפריט ✦ AI ▾; ראו הצעות מלקוחות AI. כדי להשליך הצעה לפני שהיא נשלחת, קוראים ל-p.discard(). כדי לעקוב אחר כך, c.get_proposal(pid, view["id"])["status"] הוא ready, applied, rejected או expired.

דוגמה מעשית: הדגמת CubeSat EO-1

  1. יש ליצור אסימון קריאה בלבד לפרויקט CubeSat ולהגדיר את HOLARCH_API_KEY.
  2. הצגת ממצאי הדרישות של בדיקות המודל:
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. מתן ציון לדרישות: c.quality(pid)["results"] מפרט כל דרישה עם הציון והממצאים שלה.
  2. עם אסימון קריאה וכתיבה, מציעים מקרה בדיקה לדרישה שאין לה, כמו בהצעת שינויים, ושולחים אותו. אחרי שבעלים מחיל אותו, בדיקות המודל כבר אינן מפרטות את הדרישה.

פרויקטי SysML v2

אותו לקוח קורא פרויקטי SysML v2: model(pid) (חבילות וספירות), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) ו-sysml_text(pid, root="Vehicles"). check_sysml(pid, text) בודק טקסט בלי להציע אותו. כדי להציע שינוי, שולחים את הטקסט החדש של חבילה עם p.sysml_text(text, root="Vehicles"), או עריכות רכיבים עם p.sysml_edits([...]); המנוע בודק כל שינוי ודוחה שינוי עם שגיאות. ראו ה-API וה-MCP בפרויקטים של SysML v2.

עצות ושיטות עבודה טובות

  • קוראים קודם את הסכמה (c.schema(pid)): היא מפרטת את שמות המחלקות, המאפיינים והקשרים שהפרויקט משתמש בהם.
  • כדאי לתת לכל סקריפט אסימון משלו, קריאה בלבד כשהוא רק קורא.
  • כדאי לאסוף שינויים קשורים בהצעה אחת ולשלוח אותה עם כותרת וסיכום שמסבירים למה: הסוקר רואה את כל השינוי בבת אחת.
  • אסימונים אינם צריכים להופיע בקובצי מקור; הלקוח קורא את HOLARCH_API_KEY מהסיבה הזו.

טעויות נפוצות

  • ApiError עם הקוד read-only-token: האסימון הוא לקריאה בלבד; להצעות יש ליצור אסימון קריאה וכתיבה.
  • ApiError עם הקוד not-found בפרויקט שאפשר לפתוח ב-Holarch: האסימון מוגבל לפרויקטים אחרים.
  • אי אפשר למצוא ישות שנוצרה עם entity(): היא קיימת רק בהצעה עד שבעלים מחיל אותה.

הפניה

Client

Client(token=None, server=None, timeout=30.0, retries=3). ברירת המחדל של token היא HOLARCH_API_KEY, ושל server היא HOLARCH_SERVER או https://app.holarch.app. השרת חייב להיות כתובת https.

שיטהמחזירה
me()החשבון, הגישה והתפוגה של האסימון
projects()הפרויקטים שלך: מזהה, שם, תפקיד, מספר פריטים, שפה, קישור
project(pid)שם, תיאור, תפקיד, מספר פריטים, פריטים לכל מחלקה, מספר המסמכים
schema(pid)מחלקות עם מאפיינים וקשרים מותרים; קשרים
entities(pid, cls=None, label=None, q=None, limit=100, offset=0)עמוד אחד של ישויות (לכל היותר 500)
iter_entities(pid, cls=None, label=None, q=None, page_size=500)כל ישות תואמת
search(pid, text, cls=None, limit=100)ישויות שהשם, המספר, התיאור או המחלקה שלהן מכילים את הטקסט
entity(pid, id)ישות אחת עם מאפיינים, תוויות וקשרים
documents(pid)מסמכים עם סוג ומספר מקטעים
document(pid, id)מסמך אחד עם המקטעים שלו לפי הסדר, ממוספרים, כטקסט פשוט
model_checks(pid, cls=None, rule=None, limit=500, offset=0)ממצאי בדיקות המודל עם סיכום
quality(pid, ids=None)בדיקת איכות הדרישות, לדרישות שצוינו או לכולן
versions(pid)גרסאות שמורות שהתוכנית של הפרויקט שומרת
configurations(pid)קו המוצרים: מאפיינים (features), כללים ותצורות עם בחירה, פסיקה ותחולה
proposal(pid)Proposal עבור ההצעה הפתוחה שלך בפרויקט
get_proposal(pid, proposal_id=None)ההצעה הפתוחה, או אחת לפי מזהה, עם סטטוס ושינויים
request(method, path, params=None, body=None)כל קריאת API אחרת, ביחס ל-/api/v1

project, entities, iter_entities, search, entity, documents, document, model_checks ו-quality מקבלים גם configuration= (המספר, השם או המזהה של תצורה) ו-effectivity= ("sn:23" או "date:2027-03-01") כדי לקרוא את המודל כפי שתצורה אחת של קו מוצרים מציגה אותו (קווי מוצרים).

Proposal

שיטהמה היא מציעה
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None)ישות חדשה; relationships כזוגות (relation, target); מחזיר את ההפניה שלה
update(entity, name=None, number=None, description=None, labels=None, attributes=None)שדות שהשתנו; שדות שהושמטו נשארים, מאפיין שהוגדר כ-None מאבד את הערך שלו
delete(entity)העברת הישות לסל המחזור של הפרויקט
relate(source, relation, target, attributes=None)קשר חדש, שנקרא מצד המקור
unrelate(relationship)הסרת קשר (המזהה שלו מ-entity())
get()כלום: מחזיר את ההצעה עם השינויים שלה
send(title, summary="")שום דבר נוסף: שולח את ההצעה לסקירה ומחזיר אותה עם קישור הסקירה
discard()כלום: משליך את ההצעה הפתוחה

create ו-update מקבלים גם applies_to= ("F-3 and not F-5"; "" מנקה אותו) ו-effectivity= ({"serials": "1-20, 25"}; {} מנקה אותו), וכל שינוי מקבל configuration= כדי להציע אותו כעריכה בתצורה הזו (קווי מוצרים).

שגיאות

כל בקשה שנדחית מעלה holarch_api.ApiError עם message (הטקסט של השרת), code, status ו-body. הקודים הם אלה של ה-REST API. בקשה שנדחתה עם 429 rate-limited מנוסה שוב אחרי הזמן שהשרת מציין, עד retries פעמים, לפני שהיא מעלה שגיאה.

מגבלות

  • המגבלות של ה-API חלות (API ו-MCP): קצב בקשות, לכל היותר 500 ישויות לעמוד, ומגבלת הפריטים של הפרויקט כשהצעה מוחלת.
  • תוקפה של הצעה פג 7 ימים אחרי שהתחילה.
  • הלקוח פועל עם השירות המתארח.