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 자체는 API가 포함된 요금제에 들어 있고, 패키지는 개인 액세스 토큰을 사용합니다.

패키지를 통한 변경은 항상 제안입니다. 서버에 모이며, 프로젝트 소유자가 AI 클라이언트의 변경과 똑같이 Holarch에서 검토하고 적용하며, 적용한 각 제안은 실행 취소 한 번으로 되돌립니다. 패키지에는 프로젝트를 직접 변경하는 메서드가 없습니다. 직접 써야 하는 스크립트는 REST API의 쓰기 호출을 사용합니다.

개념

  • 클라이언트: 하나의 Holarch 서버에 대한 하나의 토큰입니다. 모든 메서드는 요청 하나(또는 페이지마다 하나)를 보내고 API의 JSON을 Python dict와 list로 반환합니다.
  • 타입이 지정된 응답: 패키지에는 타입 정보(Entity, ProjectSummary 같은 TypedDict 형태)가 있어 편집기가 필드 이름을 자동 완성하고 mypy 같은 타입 검사기가 이를 검사합니다. 서버가 나중에 추가하는 필드는 dict에 그대로 나타납니다.
  • 제안: 한 프로젝트에서 열려 있는 내 제안입니다. 호출마다 변경 하나가 추가되며, send()가 제안을 프로젝트 소유자에게 검토용으로 넘깁니다. 토큰 하나는 프로젝트당 최대 하나의 열린 제안을 가집니다.
  • 참조: 제안에서 만든 엔터티는 아직 존재하지 않습니다. 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는 일치하는 모든 항목을 한 페이지씩 가져오고, 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([...])로 요소 편집을 보냅니다. 엔진이 각 변경을 검사하고 오류가 있는 변경은 거부합니다. 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일 후 만료됩니다.
  • 클라이언트는 호스팅 서비스에서 작동합니다.