Holarch

Referência

O cliente Python

Leia projetos do Holarch, pesquise itens e proponha mudanças para revisão a partir de scripts Python com o pacote gratuito holarch-api; instalação, login, cada método, propostas, erros e limites.

Como usá-lo →

Nesta página
  1. Visão geral
  2. Conceitos
  3. Como usá-lo
    1. Quando e por quê
    2. Instalar e entrar
    3. Ler um projeto
    4. Propor alterações
    5. Exemplo prático: a demonstração CubeSat EO-1
    6. Projetos SysML v2
    7. Dicas e boas práticas
    8. Erros comuns
  4. Referência
    1. Client
    2. Proposal
    3. Erros
  5. Limites
  6. Páginas relacionadas

Visão geral

holarch-api é um pequeno pacote Python para a API REST do Holarch. Ele lê projetos, itens, documentos e resultados de checagens, pesquisa e propõe alterações. É gratuito; a própria API vem com os planos que a incluem, e o pacote usa o seu token de acesso pessoal.

As alterações feitas pelo pacote são sempre propostas: elas se acumulam no servidor, e os proprietários do projeto as revisam e aplicam no Holarch, exatamente como as alterações de clientes de IA, e um único Desfazer reverte cada proposta aplicada. O pacote não tem métodos que alterem um projeto diretamente. Scripts que precisam gravar diretamente usam as chamadas de escrita da API REST.

Conceitos

  • Client: um token em um servidor Holarch. Cada método envia uma solicitação (ou uma por página) e retorna o JSON da API como dicts e listas Python.
  • Respostas tipadas: o pacote traz informações de tipo (formas TypedDict como Entity e ProjectSummary), de modo que os editores completam nomes de campos e verificadores de tipos como o mypy os checam. Campos que o servidor acrescentar depois simplesmente aparecem nos dicts.
  • Proposal: sua proposta aberta em um projeto. Cada chamada acrescenta uma alteração; send() entrega a proposta aos proprietários do projeto para revisão. Um token tem no máximo uma proposta aberta por projeto.
  • Referências: uma entidade criada em uma proposta ainda não existe. create() retorna uma referência (new:1, new:2, …) que as alterações seguintes da mesma proposta usam no lugar de um id.

Como usá-lo

Quando e por quê

Use o cliente para scripts em torno de um projeto: relatórios e exportações no seu próprio formato, checagens em uma tarefa noturna, importações de outra ferramenta que uma pessoa deve revisar antes de entrarem. Como as alterações chegam como propostas, um script nunca surpreende a equipe: os proprietários veem cada alteração antes que ela seja aplicada.

Instalar e entrar

  1. Instale o Python 3.9 ou posterior e depois o pacote: python3 -m pip install holarch-api. Ele não precisa de nada além do Python.
  2. No Holarch, abra Ajustes da conta → Tokens de API e crie um token: Somente leitura para scripts que só leem, Leitura e escrita para scripts que propõem alterações. Limite-o aos projetos de que o script precisa.
  3. Coloque o token na variável de ambiente HOLARCH_API_KEY.
  4. Verifique a conexão:
from holarch_api import Client

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

Ler um projeto

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 busca todas as correspondências, uma página por vez; entities retorna uma página (entities, total, offset, limit). search(pid, "thermal") encontra entidades cujo nome, número, descrição ou classe contém o texto.

Propor alterações

  1. Inicie uma proposta: p = c.proposal(pid).
  2. Acrescente alterações. Cada chamada é checada pelo servidor na hora e falha com um erro quando a classe, a relação ou o atributo não existe:
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. Veja o que foi reunido: p.get()["changes"]. O projeto não mudou.
  2. Envie-a: view = p.send("Add a TVAC test", "Covers the two thermal requirements."). view["review"] é o link que abre a revisão no Holarch.

Os proprietários recebem uma notificação e revisam a proposta pelo menu ✦ IA ▾; veja Propostas de clientes de IA. Para descartar uma proposta antes de enviá-la, chame p.discard(). Para acompanhar depois, c.get_proposal(pid, view["id"])["status"] é ready, applied, rejected ou expired.

Exemplo prático: a demonstração CubeSat EO-1

  1. Crie um token somente leitura para o projeto CubeSat e defina HOLARCH_API_KEY.
  2. Liste as constatações de requisitos das Checagens do modelo:
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. Pontue os requisitos: c.quality(pid)["results"] lista cada requisito com sua pontuação e constatações.
  2. Com um token de leitura e escrita, proponha um caso de teste para um requisito que não tem nenhum, como em Propor alterações, e envie-o. Depois que um proprietário o aplica, as Checagens do modelo deixam de listar o requisito.

Projetos SysML v2

O mesmo cliente lê projetos SysML v2: model(pid) (pacotes e contagens), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) e sysml_text(pid, root="Vehicles"). check_sysml(pid, text) checa um texto sem propô-lo. Para propor uma alteração, envie o novo texto de um pacote com p.sysml_text(text, root="Vehicles"), ou edições de elementos com p.sysml_edits([...]); o motor checa cada alteração e recusa uma que tenha erros. Veja A API e o MCP em projetos SysML v2.

Dicas e boas práticas

  • Leia o esquema primeiro (c.schema(pid)): ele lista os nomes de classes, atributos e relações que o projeto usa.
  • Dê a cada script o seu próprio token, somente leitura onde ele só lê.
  • Reúna alterações relacionadas em uma proposta e envie-a com um título e um resumo que digam por quê: o revisor vê a alteração inteira de uma vez.
  • Mantenha os tokens fora dos arquivos de código-fonte; é por isso que o cliente lê HOLARCH_API_KEY.

Erros comuns

  • ApiError com o código read-only-token: o token é somente leitura; crie um token de leitura e escrita para propostas.
  • ApiError com o código not-found em um projeto que você consegue abrir no Holarch: o token está limitado a outros projetos.
  • Uma entidade criada não é encontrada com entity(): ela só existe na proposta até que um proprietário a aplique.

Referência

Client

Client(token=None, server=None, timeout=30.0, retries=3). token tem como padrão HOLARCH_API_KEY, server tem como padrão HOLARCH_SERVER ou https://app.holarch.app. O servidor precisa ser um endereço https.

MétodoRetorna
me()A conta, o acesso e a validade do token
projects()Seus projetos: id, nome, papel, contagem de itens, linguagem, link
project(pid)Nome, descrição, papel, contagem de itens, itens por classe, número de documentos
schema(pid)Classes com atributos e relações permitidas; relações
entities(pid, cls=None, label=None, q=None, limit=100, offset=0)Uma página de entidades (no máximo 500)
iter_entities(pid, cls=None, label=None, q=None, page_size=500)Todas as entidades correspondentes
search(pid, text, cls=None, limit=100)Entidades cujo nome, número, descrição ou classe contém o texto
entity(pid, id)Uma entidade com atributos, rótulos e relacionamentos
documents(pid)Documentos com tipo e número de seções
document(pid, id)Um documento com suas seções em ordem, numeradas, como texto simples
model_checks(pid, cls=None, rule=None, limit=500, offset=0)Constatações das Checagens do modelo com um resumo
quality(pid, ids=None)A checagem de qualidade de requisitos, para os requisitos informados ou todos
versions(pid)Versões salvas que o plano do projeto mantém
configurations(pid)A linha de produtos: características, regras e configurações com seleção, veredito e efetividade
proposal(pid)Um Proposal para a sua proposta aberta no projeto
get_proposal(pid, proposal_id=None)A proposta aberta, ou uma pelo id, com status e alterações
request(method, path, params=None, body=None)Qualquer outra chamada da API, relativa a /api/v1

project, entities, iter_entities, search, entity, documents, document, model_checks e quality também aceitam configuration= (o número, nome ou id de uma configuração) e effectivity= ("sn:23" ou "date:2027-03-01") para ler o modelo como uma configuração de uma linha de produtos o mostra (Linhas de produtos).

Proposal

MétodoO que propõe
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None)Uma nova entidade; relationships como pares (relation, target); retorna sua referência
update(entity, name=None, number=None, description=None, labels=None, attributes=None)Campos alterados; os campos omitidos permanecem, um atributo definido como None perde seu valor
delete(entity)Mover a entidade para a Lixeira do projeto
relate(source, relation, target, attributes=None)Um novo relacionamento, nomeado a partir da origem
unrelate(relationship)Remover um relacionamento (seu id de entity())
get()Nada: retorna a proposta com suas alterações
send(title, summary="")Nada além disso: envia a proposta para revisão e a retorna com o link da revisão
discard()Nada: descarta a proposta aberta

create e update também aceitam applies_to= ("F-3 and not F-5"; "" o limpa) e effectivity= ({"serials": "1-20, 25"}; {} a limpa), e toda alteração aceita configuration= para propô-la como uma edição nessa configuração (Linhas de produtos).

Erros

Toda solicitação recusada lança holarch_api.ApiError com message (o texto do servidor), code, status e body. Os códigos são os da API REST. Uma solicitação recusada com 429 rate-limited é tentada novamente depois do tempo indicado pelo servidor, até retries vezes, antes de lançar o erro.

Limites

  • Os limites da API valem (API e MCP): taxa de solicitações, no máximo 500 entidades por página, e o limite de itens do projeto quando uma proposta é aplicada.
  • Uma proposta expira 7 dias depois de iniciada.
  • O cliente funciona com o serviço hospedado.