リファレンス
Python クライアント
無料の holarch-api パッケージを使い、Python スクリプトから Holarch プロジェクトを読み取り、項目を検索し、レビュー用の変更を提案します。インストール、サインイン、すべてのメソッド、提案、エラー、制限について説明します。
このページの内容
概要
holarch-api は、Holarch の REST API 用の小さな Python パッケージです。プロジェクト、項目、ドキュメント、チェック結果を読み取り、検索し、変更を提案します。無料です。API 自体はそれを含むプランに付属し、パッケージはあなたの個人用アクセストークンを使います。
パッケージを通じて行う変更は常に提案です:サーバーに集められ、プロジェクトのオーナーが Holarch でレビューし、AI クライアントからの変更とまったく同じく適用します。適用した各提案は 1 回の元に戻すで取り消せます。パッケージには、プロジェクトを直接変更するメソッドはありません。直接書き込む必要があるスクリプトは、REST API の書き込み呼び出しを使います。
概念
- クライアント:1 つの Holarch サーバー上の 1 つのトークン。各メソッドは 1 つのリクエスト(またはページごとに 1 つ)を送り、API の JSON を Python の辞書とリストとして返します。
- 型付きの応答:パッケージは型情報(
EntityやProjectSummaryなどのTypedDictの形)を持つので、エディターがフィールド名を補完し、mypy などの型チェッカーがそれを確認します。サーバーが後で追加するフィールドは、そのまま辞書に現れます。 - 提案:1 つのプロジェクトでの開いている提案。各呼び出しで 1 つの変更を追加します。
send()は提案をプロジェクトのオーナーにレビューのために渡します。1 つのトークンが持てる開いている提案は、プロジェクトあたり最大 1 つです。 - 参照:提案内で作成したエンティティはまだ存在しません。
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 は、一致するすべてのものを 1 ページずつ取得します。entities は 1 ページ(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)):プロジェクトが使うクラス、属性、関係の名前が一覧表示されます。 - 各スクリプトには専用のトークンを与え、読み取るだけのものは読み取り専用にします。
- 関連する変更は 1 つの提案にまとめ、理由がわかるタイトルと要約を付けて送ります:レビュー担当者は変更全体を一度に確認できます。
- トークンをソースファイルに入れないようにします。クライアントが
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) | エンティティの 1 ページ(最大 500) |
iter_entities(pid, cls=None, label=None, q=None, page_size=500) | 一致するすべてのエンティティ |
search(pid, text, cls=None, limit=100) | 名前、番号、説明、またはクラスにそのテキストを含むエンティティ |
entity(pid, id) | 属性、ラベル、関係を含む 1 つのエンティティ |
documents(pid) | 種類とセクション数を含むドキュメント |
document(pid, id) | セクションを順番どおり、番号付きで、プレーンテキストとして含む 1 つのドキュメント |
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")も指定でき、プロダクトラインの 1 つの構成が示すとおりのモデルを読み取れます(プロダクトライン)。
提案
| 手法 | 提案する内容 |
|---|---|
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):リクエストの頻度、1 ページあたり最大 500 エンティティ、および提案の適用時のプロジェクトの項目数の上限です。
- 提案は開始から 7 日後に期限切れになります。
- クライアントはホスト型サービスで機能します。