Holarch

リファレンス

Python クライアント

無料の holarch-api パッケージを使い、Python スクリプトから Holarch プロジェクトを読み取り、項目を検索し、レビュー用の変更を提案します。インストール、サインイン、すべてのメソッド、提案、エラー、制限について説明します。

使い方 →

このページの内容
  1. 概要
  2. 概念
  3. 使い方
    1. 使う場面と理由
    2. インストールとサインイン
    3. プロジェクトを読み取る
    4. 変更を提案する
    5. 実例:CubeSat EO-1 のデモ
    6. SysML v2 プロジェクト
    7. ヒントとよい進め方
    8. よくある間違い
  4. リファレンス
    1. クライアント
    2. 提案
    3. エラー
  5. 制限事項
  6. 関連ページ

概要

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 の代わりにそれを使います。

使い方

使う場面と理由

クライアントは、プロジェクトに関わるスクリプトに使います:独自の形式でのレポートとエクスポート、夜間ジョブでのチェック、取り込む前に人がレビューすべき別のツールからのインポートです。変更は提案として届くので、スクリプトがチームを驚かせることはありません:オーナーは適用前にすべての変更を確認します。

インストールとサインイン

  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 は、一致するすべてのものを 1 ページずつ取得します。entities は 1 ページ(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([...]) で要素の編集を送ります。エンジンが各変更をチェックし、エラーのあるものは拒否します。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 日後に期限切れになります。
  • クライアントはホスト型サービスで機能します。