संदर्भ
Python क्लाइंट
निःशुल्क holarch-api पैकेज से Python स्क्रिप्ट के ज़रिए Holarch प्रोजेक्ट पढ़ें, आइटम खोजें और समीक्षा के लिए परिवर्तन प्रस्तावित करें; इंस्टॉलेशन, साइन-इन, हर मेथड, प्रस्ताव, त्रुटियां और सीमाएं।
इस पृष्ठ पर
अवलोकन
holarch-api Holarch REST API के लिए एक छोटा Python पैकेज है। यह प्रोजेक्ट, आइटम, दस्तावेज़ और जांच परिणाम पढ़ता है, खोजता है, और परिवर्तन प्रस्तावित करता है। यह निःशुल्क है; API स्वयं उन प्लान के साथ आता है जिनमें यह शामिल है, और पैकेज आपके पर्सनल एक्सेस टोकन का उपयोग करता है।
पैकेज से किए गए परिवर्तन हमेशा प्रस्ताव होते हैं: वे सर्वर पर जमा होते हैं, और प्रोजेक्ट के स्वामी Holarch में उनकी समीक्षा करते हैं और उन्हें लागू करते हैं, ठीक AI क्लाइंट के परिवर्तनों की तरह, और हर लागू प्रस्ताव को एक ही बार पूर्ववत करके वापस लिया जा सकता है। पैकेज में कोई ऐसी विधि नहीं है जो प्रोजेक्ट को सीधे बदले। जिन स्क्रिप्ट को सीधे लिखना ज़रूरी है वे REST API की लिखने वाली कॉल का उपयोग करती हैं।
अवधारणाएं
- क्लाइंट: एक Holarch सर्वर पर एक टोकन। हर विधि एक अनुरोध (या हर पेज के लिए एक) भेजती है और API का JSON Python dict और list के रूप में लौटाती है।
- टाइप किए गए उत्तर: पैकेज में टाइप जानकारी होती है (
EntityऔरProjectSummaryजैसेTypedDictआकार), ताकि एडिटर फ़ील्ड नाम पूरे करें और mypy जैसे टाइप चेकर उन्हें जांचें। सर्वर बाद में जो फ़ील्ड जोड़ता है वे बस dict में दिखते हैं। - प्रस्ताव: किसी एक प्रोजेक्ट में आपका खुला प्रस्ताव। हर कॉल एक परिवर्तन जोड़ती है;
send()प्रस्ताव को समीक्षा के लिए प्रोजेक्ट के स्वामियों को सौंपता है। एक टोकन का हर प्रोजेक्ट में अधिकतम एक खुला प्रस्ताव होता है। - संदर्भ: किसी प्रस्ताव में बनाई गई एंटिटी अभी मौजूद नहीं है।
create()एक संदर्भ (new:1,new:2, …) लौटाता है जिसे उसी प्रस्ताव के बाद के परिवर्तन id की जगह उपयोग करते हैं।
इसका उपयोग कैसे करें
कब और क्यों
किसी प्रोजेक्ट के इर्द-गिर्द स्क्रिप्ट के लिए क्लाइंट का उपयोग करें: अपने फ़ॉर्मेट में रिपोर्ट और निर्यात, रात के जॉब में जांच, किसी अन्य टूल से आयात जिनकी किसी व्यक्ति को आने से पहले समीक्षा करनी चाहिए। क्योंकि परिवर्तन प्रस्ताव के रूप में आते हैं, स्क्रिप्ट कभी टीम को चौंकाती नहीं: स्वामी हर परिवर्तन लागू होने से पहले देखते हैं।
इंस्टॉल करें और साइन इन करें
- Python 3.9 या बाद का संस्करण इंस्टॉल करें, फिर पैकेज:
python3 -m pip install holarch-api। इसे Python के अलावा कुछ नहीं चाहिए। - Holarch में खाता सेटिंग्स → API टोकन खोलें और एक टोकन बनाएं: केवल पढ़ने वाली स्क्रिप्ट के लिए केवल पढ़ें, परिवर्तन प्रस्तावित करने वाली स्क्रिप्ट के लिए पढ़ें और लिखें। इसे उन प्रोजेक्ट तक सीमित करें जिनकी स्क्रिप्ट को ज़रूरत है।
- टोकन को
HOLARCH_API_KEYएनवायरनमेंट वेरिएबल में रखें। - कनेक्शन जांचें:
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") वे एंटिटी ढूंढता है जिनके नाम, नंबर, विवरण या क्लास में टेक्स्ट हो।
परिवर्तन प्रस्तावित करें
- एक प्रस्ताव शुरू करें:
p = c.proposal(pid)। - परिवर्तन जोड़ें। हर कॉल सर्वर द्वारा तुरंत जांची जाती है और क्लास, संबंध या एट्रिब्यूट मौजूद न होने पर त्रुटि के साथ विफल होती है:
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…")
- देखें कि क्या जमा हुआ है:
p.get()["changes"]। प्रोजेक्ट नहीं बदला है। - इसे भेजें:
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 डेमो
- CubeSat प्रोजेक्ट के लिए एक केवल-पढ़ने वाला टोकन बनाएं और
HOLARCH_API_KEYसेट करें। - मॉडल जांच के आवश्यकता निष्कर्ष सूचीबद्ध करें:
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")
- आवश्यकताओं को स्कोर दें:
c.quality(pid)["results"]हर आवश्यकता को उसके स्कोर और निष्कर्षों के साथ सूचीबद्ध करता है। - पढ़ने-और-लिखने वाले टोकन के साथ, बिना टेस्ट केस वाली किसी आवश्यकता के लिए एक टेस्ट केस प्रस्तावित करें, जैसे परिवर्तन प्रस्तावित करें में, और उसे भेजें। किसी स्वामी के लागू करने के बाद मॉडल जांच उस आवश्यकता को सूचीबद्ध नहीं करती।
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([...]) से भेजें; इंजन हर परिवर्तन जांचता है और त्रुटियों वाले को अस्वीकार करता है। देखें SysML v2 प्रोजेक्ट में API और MCP।
सुझाव और अच्छे तरीके
- पहले स्कीमा पढ़ें (
c.schema(pid)): यह प्रोजेक्ट द्वारा उपयोग किए जाने वाले क्लास, एट्रिब्यूट और संबंध नाम सूचीबद्ध करता है। - हर स्क्रिप्ट को उसका अपना टोकन दें, जहाँ वह केवल पढ़ती है वहाँ केवल-पढ़ने वाला।
- संबंधित परिवर्तनों को एक प्रस्ताव में जमा करें और उसे ऐसे शीर्षक और सारांश के साथ भेजें जो कारण बताए: समीक्षक पूरा परिवर्तन एक साथ देखता है।
- टोकन को सोर्स फ़ाइलों से बाहर रखें; इसी कारण क्लाइंट
HOLARCH_API_KEYपढ़ता है।
सामान्य ग़लतियां
read-only-tokenकोड के साथApiError: टोकन केवल-पढ़ने वाला है; प्रस्तावों के लिए पढ़ने-और-लिखने वाला टोकन बनाएं।- Holarch में खोल सकने वाले प्रोजेक्ट पर
not-foundकोड के साथApiError: टोकन अन्य प्रोजेक्ट तक सीमित है। - बनाई गई एंटिटी
entity()से नहीं मिलती: जब तक कोई स्वामी उसे लागू न करे, वह केवल प्रस्ताव में मौजूद है।
संदर्भ
क्लाइंट
Client(token=None, server=None, timeout=30.0, retries=3)। token का डिफ़ॉल्ट HOLARCH_API_KEY है, server का HOLARCH_SERVER या https://app.holarch.app। सर्वर एक https पता होना चाहिए।
| विधि | लौटाता है |
|---|---|
me() | टोकन का खाता, पहुँच और समाप्ति |
projects() | आपके प्रोजेक्ट: id, नाम, भूमिका, आइटम गिनती, भाषा, लिंक |
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) | प्रोडक्ट लाइन: चयन, निर्णय और प्रभावी सीमा के साथ सुविधाएं, नियम और कॉन्फ़िगरेशन |
proposal(pid) | प्रोजेक्ट में आपके खुले प्रस्ताव के लिए एक Proposal |
get_proposal(pid, proposal_id=None) | खुला प्रस्ताव, या id से एक, स्थिति और परिवर्तनों के साथ |
request(method, path, params=None, body=None) | कोई अन्य API कॉल, /api/v1 के सापेक्ष |
project, entities, iter_entities, search, entity, documents, document, model_checks और quality मॉडल को वैसे पढ़ने के लिए configuration= (किसी कॉन्फ़िगरेशन का नंबर, नाम या id) और effectivity= ("sn:23" या "date:2027-03-01") भी लेते हैं जैसा किसी प्रोडक्ट लाइन का एक कॉन्फ़िगरेशन उसे दिखाता है (प्रोडक्ट लाइन)।
प्रस्ताव
| विधि | यह क्या प्रस्तावित करता है |
|---|---|
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() से उसका id) |
get() | कुछ नहीं: प्रस्ताव को उसके परिवर्तनों के साथ लौटाता है |
send(title, summary="") | और कुछ नहीं: प्रस्ताव को समीक्षा के लिए भेजता है और उसे समीक्षा लिंक के साथ लौटाता है |
discard() | कुछ नहीं: खुला प्रस्ताव छोड़ देता है |
create और update applies_to= ("F-3 and not F-5"; "" इसे साफ़ करता है) और effectivity= ({"serials": "1-20, 25"}; {} इसे साफ़ करता है) भी लेते हैं, और हर परिवर्तन उसे उस कॉन्फ़िगरेशन में संपादन के रूप में प्रस्तावित करने के लिए configuration= लेता है (प्रोडक्ट लाइन)।
त्रुटियां
हर अस्वीकार किया गया अनुरोध message (सर्वर का टेक्स्ट), code, status और body के साथ holarch_api.ApiError उठाता है। कोड REST API के ही हैं। 429 rate-limited के साथ अस्वीकार किया गया अनुरोध त्रुटि उठाने से पहले सर्वर द्वारा बताए समय के बाद, retries बार तक, फिर से भेजा जाता है।
सीमाएं
- API की सीमाएं लागू होती हैं (API और MCP): अनुरोध दर, प्रति पेज अधिकतम 500 एंटिटी, और प्रस्ताव लागू होने पर प्रोजेक्ट की आइटम सीमा।
- प्रस्ताव शुरू होने के 7 दिन बाद समाप्त हो जाता है।
- क्लाइंट होस्टेड सेवा के साथ काम करता है।