Holarch

Referencia

El cliente de Python

Lea proyectos de Holarch, busque elementos y proponga cambios para su revisión desde scripts de Python con el paquete gratuito holarch-api; instalación, inicio de sesión, todos los métodos, propuestas, errores y límites.

Cómo usarlo →

En esta página
  1. Resumen
  2. Conceptos
  3. Cómo usarlo
    1. Cuándo y por qué
    2. Instalar e iniciar sesión
    3. Leer un proyecto
    4. Proponer cambios
    5. Ejemplo práctico: la demostración CubeSat EO-1
    6. Proyectos SysML v2
    7. Consejos y buenas prácticas
    8. Errores habituales
  4. Referencia
    1. Cliente
    2. Propuesta
    3. Errores
  5. Límites
  6. Páginas relacionadas

Resumen

holarch-api es un pequeño paquete de Python para la API REST de Holarch. Lee proyectos, elementos, documentos y resultados de comprobaciones, busca y propone cambios. Es gratuito; la API en sí viene con los planes que la incluyen, y el paquete usa su token de acceso personal.

Los cambios hechos mediante el paquete son siempre propuestas: se reúnen en el servidor, y los propietarios del proyecto los revisan y aplican en Holarch, exactamente como los cambios de los clientes de IA, y un solo Deshacer revierte cada propuesta aplicada. El paquete no tiene métodos que cambien un proyecto directamente. Los scripts que deben escribir directamente usan las llamadas de escritura de la API REST.

Conceptos

  • Cliente: un token en un servidor de Holarch. Cada método envía una solicitud (o una por página) y devuelve el JSON de la API como diccionarios y listas de Python.
  • Respuestas tipadas: el paquete incluye información de tipos (formas TypedDict como Entity y ProjectSummary), de modo que los editores completan los nombres de campo y los comprobadores de tipos como mypy los comprueban. Los campos que el servidor añada más adelante aparecen sin más en los diccionarios.
  • Propuesta: su propuesta abierta en un proyecto. Cada llamada añade un cambio; send() entrega la propuesta a los propietarios del proyecto para su revisión. Un token tiene como máximo una propuesta abierta por proyecto.
  • Referencias: una entidad creada en una propuesta todavía no existe. create() devuelve una referencia (new:1, new:2, …) que los cambios posteriores de la misma propuesta usan en lugar de un id.

Cómo usarlo

Cuándo y por qué

Use el cliente para scripts en torno a un proyecto: informes y exportaciones en su propio formato, comprobaciones en un trabajo nocturno, importaciones desde otra herramienta que una persona deba revisar antes de que entren. Como los cambios llegan como propuestas, un script nunca sorprende al equipo: los propietarios ven cada cambio antes de que se aplique.

Instalar e iniciar sesión

  1. Instale Python 3.9 o posterior y después el paquete: python3 -m pip install holarch-api. No necesita nada más que Python.
  2. En Holarch, abra Ajustes de la cuenta → Tokens de API y cree un token: Solo lectura para scripts que solo leen, Lectura y escritura para scripts que proponen cambios. Limítelo a los proyectos que el script necesita.
  3. Ponga el token en la variable de entorno HOLARCH_API_KEY.
  4. Compruebe la conexión:
from holarch_api import Client

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

Leer un proyecto

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 obtiene todas las coincidencias, una página cada vez; entities devuelve una página (entities, total, offset, limit). search(pid, "thermal") encuentra las entidades cuyo nombre, número, descripción o clase contienen el texto.

Proponer cambios

  1. Inicie una propuesta: p = c.proposal(pid).
  2. Añada cambios. El servidor comprueba cada llamada en el acto, y esta falla con un error cuando la clase, la relación o el atributo no 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. Mire lo que se ha reunido: p.get()["changes"]. El proyecto no ha cambiado.
  2. Envíela: view = p.send("Add a TVAC test", "Covers the two thermal requirements."). view["review"] es el enlace que abre la revisión en Holarch.

Los propietarios reciben una notificación y revisan la propuesta desde el menú ✦ IA ▾; consulte Propuestas de clientes de IA. Para descartar una propuesta antes de enviarla, llame a p.discard(). Para hacer el seguimiento más tarde, c.get_proposal(pid, view["id"])["status"] es ready, applied, rejected o expired.

Ejemplo práctico: la demostración CubeSat EO-1

  1. Cree un token de solo lectura para el proyecto CubeSat y establezca HOLARCH_API_KEY.
  2. Enumere los hallazgos de requisitos de las comprobaciones del 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. Puntúe los requisitos: c.quality(pid)["results"] enumera cada requisito con su puntuación y sus hallazgos.
  2. Con un token de lectura y escritura, proponga un caso de prueba para un requisito que no tiene ninguno, como en Proponer cambios, y envíelo. Después de que un propietario lo aplique, las comprobaciones del modelo ya no enumeran el requisito.

Proyectos SysML v2

El mismo cliente lee proyectos SysML v2: model(pid) (paquetes y recuentos), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) y sysml_text(pid, root="Vehicles"). check_sysml(pid, text) comprueba texto sin proponerlo. Para proponer un cambio, envíe el texto nuevo de un paquete con p.sysml_text(text, root="Vehicles"), o ediciones de elementos con p.sysml_edits([...]); el motor comprueba cada cambio y rechaza los que tienen errores. Consulte La API y MCP en proyectos SysML v2.

Consejos y buenas prácticas

  • Lea primero el esquema (c.schema(pid)): enumera los nombres de clases, atributos y relaciones que usa el proyecto.
  • Dé a cada script su propio token, de solo lectura donde solo lee.
  • Reúna los cambios relacionados en una propuesta y envíela con un título y un resumen que digan por qué: el revisor ve todo el cambio a la vez.
  • Mantenga los tokens fuera de los archivos de código fuente; por ese motivo, el cliente lee HOLARCH_API_KEY.

Errores habituales

  • ApiError con el código read-only-token: el token es de solo lectura; cree un token de lectura y escritura para las propuestas.
  • ApiError con el código not-found en un proyecto que puede abrir en Holarch: el token está limitado a otros proyectos.
  • Una entidad creada no se encuentra con entity(): solo existe en la propuesta hasta que un propietario la aplica.

Referencia

Cliente

Client(token=None, server=None, timeout=30.0, retries=3). token toma de forma predeterminada HOLARCH_API_KEY, y server, HOLARCH_SERVER o https://app.holarch.app. El servidor debe ser una dirección https.

MétodoDevuelve
me()La cuenta, el acceso y la caducidad del token
projects()Sus proyectos: id, nombre, rol, número de elementos, idioma, enlace
project(pid)Nombre, descripción, rol, número de elementos, elementos por clase, número de documentos
schema(pid)Clases con atributos y relaciones permitidas; relaciones
entities(pid, cls=None, label=None, q=None, limit=100, offset=0)Una página de entidades (como máximo 500)
iter_entities(pid, cls=None, label=None, q=None, page_size=500)Todas las entidades que coinciden
search(pid, text, cls=None, limit=100)Entidades cuyo nombre, número, descripción o clase contienen el texto
entity(pid, id)Una entidad con atributos, etiquetas y relaciones
documents(pid)Documentos con tipo y número de secciones
document(pid, id)Un documento con sus secciones en orden, numeradas, como texto sin formato
model_checks(pid, cls=None, rule=None, limit=500, offset=0)Hallazgos de las comprobaciones del modelo con un resumen
quality(pid, ids=None)La comprobación de calidad de los requisitos, para los requisitos indicados o para todos
versions(pid)Las versiones guardadas que conserva el plan del proyecto
configurations(pid)La línea de productos: características, reglas y configuraciones con selección, veredicto y aplicabilidad
proposal(pid)Un Proposal para su propuesta abierta en el proyecto
get_proposal(pid, proposal_id=None)La propuesta abierta, o una por id, con estado y cambios
request(method, path, params=None, body=None)Cualquier otra llamada a la API, relativa a /api/v1

project, entities, iter_entities, search, entity, documents, document, model_checks y quality también aceptan configuration= (el número, el nombre o el id de una configuración) y effectivity= ("sn:23" o "date:2027-03-01") para leer el modelo tal como lo muestra una configuración de una línea de productos (Líneas de productos).

Propuesta

MétodoQué propone
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None)Una entidad nueva; relationships como pares (relation, target); devuelve su referencia
update(entity, name=None, number=None, description=None, labels=None, attributes=None)Campos cambiados; los campos omitidos se mantienen, y un atributo establecido en None pierde su valor
delete(entity)Mover la entidad a la Papelera del proyecto
relate(source, relation, target, attributes=None)Una relación nueva, nombrada desde el origen
unrelate(relationship)Quitar una relación (su id de entity())
get()Nada: devuelve la propuesta con sus cambios
send(title, summary="")Nada más: envía la propuesta a revisión y la devuelve con el enlace de revisión
discard()Nada: descarta la propuesta abierta

create y update también aceptan applies_to= ("F-3 and not F-5"; "" lo borra) y effectivity= ({"serials": "1-20, 25"}; {} la borra), y todo cambio acepta configuration= para proponerlo como edición en esa configuración (Líneas de productos).

Errores

Toda solicitud rechazada lanza holarch_api.ApiError con message (el texto del servidor), code, status y body. Los códigos son los de la API REST. Una solicitud rechazada con 429 rate-limited se reintenta después del tiempo que indica el servidor, hasta retries veces, antes de lanzar el error.

Límites

  • Se aplican los límites de la API (API y MCP): la frecuencia de solicitudes, como máximo 500 entidades por página y el límite de elementos del proyecto cuando se aplica una propuesta.
  • Una propuesta caduca 7 días después de iniciarse.
  • El cliente funciona con el servicio alojado.