Incrusta un diagrama UML correcto en tus documentos
A los agentes se les pide constantemente "añadir un diagrama" a la documentación — y suelen obtener el modelado sutilmente incorrecto (multiplicidades inválidas, flechas invertidas, herencia al revés) o devuelven un bloque de código que nunca se renderiza como imagen. Esta habilidad produce un diagrama de clases correcto y una imagen incrustable real.
Alcance
- Solo diagramas de clases, por ahora — clases, atributos, asociaciones, multiplicidades, herencia. Otros tipos de diagramas UML (máquinas de estado, objetos, secuencia, actividad, …) quedan fuera del alcance de esta habilidad.
- Siempre a través de BESSER B-UML. Cada diagrama se construye primero como un
DomainModelde B-UML y luego se entrega. Pasar por el modelo es lo que hace que el diagrama sea correcto y reutilizable como código.
Dónde puede comenzar
- Una descripción — el usuario explica el dominio; el agente escribe el modelo.
- Código existente — el agente lee el código fuente y construye el modelo B-UML a partir de su estructura. (No hay un escáner de código automático; el agente realiza el modelado a partir de lo que lee — no es un importador de un solo clic).
- Una ruta compatible hacia B-UML — PlantUML, Draw.io o un mockup de interfaz.
Dos formas de entregar
Modela una vez, luego entrega como código B-UML incrustado (Entrega A) o una imagen renderizada (Entrega B) — ambos a partir del mismo modelo, por lo que nunca entran en conflicto. Elige según el contexto (un documento de diseño que debe seguir siendo ejecutable → código; un README que debe mostrar una imagen → imagen), o proporciona ambos. Los detalles están en las secciones de Entrega a continuación.
Dónde colocar el resultado. Si el usuario nombra un documento destino (un README, un documento
de diseño), incrusta en ese archivo. Si no nombra ninguno — o pide un diagrama independiente
de un repositorio/sistema — por defecto entrega un nuevo .md autocontenido (p. ej.
docs/<modelo>.md): la imagen renderizada (Entrega B) y/o el código B-UML
(Entrega A), más una línea o dos explicando lo que muestra el diagrama. Así convierte una simple
solicitud "diagrama mi repositorio" en un documento consolidable en lugar de un SVG suelto.
Cuando crees un nuevo archivo, indica dónde lo colocaste (y ofrece la alternativa —
incrustarlo en un documento existente — si puede ser lo que el usuario quería).
Flujo de trabajo
1. Construye el modelo B-UML — a partir de una descripción, código existente que el agente
lea, o mediante una ruta compatible hacia B-UML (PlantUML / Draw.io / mockup)
2. model.validate() → confirma que es estructuralmente correcto
Luego entrega uno (o ambos):
A) Incrusta el código: coloca el DomainModel Python en un bloque delimitado en el .md
B) Incrusta una imagen: envía el modelo al endpoint headless SVG de BESSER (una
llamada HTTP — sin navegador), guarda el SVG devuelto (p. ej. docs/img/data-model.svg),
incrusta 
3. Cuando el modelo cambie, actualiza el modelo y vuelve a entregar — una única fuente de verdad
1. Construye el modelo
Un diagrama correcto comienza con un modelo correcto. La forma mínima:
from besser.BUML.metamodel.structural import (
DomainModel, Class, Property, Multiplicity,
BinaryAssociation, Generalization, StringType, IntegerType,
)
publication = Class(name="Publication", attributes={Property(name="title", type=StringType)})
book = Class(name="Book", attributes={Property(name="pages", type=IntegerType)})
author = Class(name="Author", attributes={Property(name="name", type=StringType)})
book_is_a = Generalization(general=publication, specific=book) # Book es una Publication
# Un Book está escrito por 1..* Authors; un Author escribe 0..* Books
written_by = Property(name="writtenBy", type=author, multiplicity=Multiplicity(1, "*"))
writes = Property(name="writes", type=book, multiplicity=Multiplicity(0, "*"))
book_author = BinaryAssociation(name="book_author", ends={written_by, writes})
model = DomainModel(
name="Library",
types={publication, book, author},
associations={book_author},
generalizations={book_is_a},
)
assert model.validate()["success"]
Nombres: sin espacios, sin guiones. Para todo lo más allá de esta forma mínima —
enumeraciones, todos los patrones de multiplicidad/composición, clases de asociación,
conjuntos de generalización, métodos, detalles de validación — consulta
references/class-diagram.md (incluido con esta habilidad). Para tipos de modelo
que no son de clases (objeto, característica, despliegue, OCL, …), consulta la habilidad
besser-user de la plataforma BESSER.
Forma importable — requerida para ambas rutas de entrega. Escribe cada
Class(...),BinaryAssociation(...)yGeneralization(...)como una asignación explícita de nivel superior, exactamente como se muestra arriba. El importador de BESSER (usado por el endpoint SVG y por el editor en Importar) lee la estructura del archivo — no lo ejecuta — por lo que las relaciones construidas dentro de una función auxiliar o un bucle son invisibles: las clases se importan pero las asociaciones desaparecen silenciosamente. Una sentencia literal por relación.Debido a que el importador nunca ejecuta el archivo,
model.validate()no se ejecuta en la ruta de renderizado — no necesitas BESSER instalado para renderizar mediante el endpoint. Mantén la llamadavalidate()para cuando sí tengas BESSER localmente (y antes de generar código); es un no-op para el endpoint, no un requisito.
De dónde viene el modelo:
- Desde una descripción — escríbelo como arriba.
- Desde código existente — lee el código fuente y traduce su estructura (clases, campos, relaciones, herencia) al modelo B-UML. El agente realiza el modelado; no hay un escáner de código automático.
- Desde PlantUML / Draw.io / un mockup de interfaz — usa la conversión correspondiente hacia B-UML (disponible a través de la plataforma BESSER), luego continúa.
Ahora entrégalo de una de las dos maneras.
Entrega A — incrusta el código B-UML en el documento
Coloca el modelo directamente dentro de un bloque delimitado ```python en el .md. Es
correcto, validado con validate(), re-ejecutable e importable en el editor. Ideal
cuando el documento debe contener el modelo en sí (un documento de diseño, una especificación):
## Modelo de datos
```python
# (el DomainModel de arriba)
```
Este modelo B-UML es la fuente de verdad para el dominio — validado con `validate()`,
y la entrada para cualquier generador de BESSER.
Entrega B — incrusta una imagen renderizada
El modelo se convierte en una imagen real a través del renderizador de BESSER, por lo que la imagen siempre coincide con el modelo. Dos formas — elige según quieras un proceso automatizado o ajustado manualmente.
B1. Renderízalo automáticamente (por defecto) — una llamada HTTP, sin navegador
BESSER expone un endpoint headless B-UML → SVG. El agente envía el archivo .py del modelo
mediante POST y obtiene un SVG de vuelta — sin editor, sin pasos manuales, sin nada que el usuario
deba hacer clic:
curl -X POST https://editor.besser-pearl.org/besser_api/get-svg \
-F "[email protected];type=text/x-python" \
-o docs/img/data-model.svg
El endpoint analiza el B-UML, lo maqueta automáticamente y devuelve image/svg+xml.
Guárdalo en el repositorio e incrústalo:

- El archivo del modelo debe estar en forma importable (ver el aviso en §1) — la misma forma que importa el editor. Solo diagramas de clases.
- La maquetación es automática. Cuando la colocación importe, ajústalo manualmente con B2.
- Guarda el
.pycomo UTF-8 sin BOM — una marca de orden de bytes inicial hace que el endpoint rechace el archivo (HTTP 400). - Omite
default_value=...de literales de enumeración en un modelo que renderices aquí — el endpoint actualmente falla con ello (HTTP 500). Es correcto para generación de código; un enumerado simple usado como tipo de atributo se renderiza bien. - Una respuesta no-200 es un pequeño JSON de error, no un SVG (
{ "detail": ... }) — verifica el estado antes de guardar.
B2. Exportación ajustada manualmente desde el editor (cuando la maquetación importa)
Abre https://editor.besser-pearl.org, Importa el .py (elige el formato B-UML),
arrastra cajas y líneas de ruta a tu gusto, luego Exporta y elige un formato:
- SVG — nítido a cualquier tamaño; ideal para documentos y la web.
- PNG — fondo transparente.
- PNG (fondo blanco) — para superficies que necesiten una imagen opaca.
Guárdalo en el repositorio e incrústalo de la misma manera. (El editor también puede exportar el modelo como B-UML o JSON — esos son el modelo, no una imagen.)
De cualquier manera, SVG y PNG se renderizan en todos los lugares donde las imágenes Markdown lo hacen — GitHub, GitLab, sitios de documentación, wikis, diapositivas — sin necesidad de complementos.
Evita que se desvíe
Sea cual sea el modo que elijas, el modelo es la fuente de verdad. Cuando los requisitos cambien, actualiza el modelo y vuelve a entregar (vuelve a pegar el código, o vuelve a exportar la imagen) — nunca edites manualmente un SVG/PNG exportado; es generado.
El beneficio más allá de una imagen
Debido a que el diagrama es un modelo B-UML real, el mismo artefacto puede generar código funcional — clases Python, SQL, un backend FastAPI, Django, React y más. Un diagrama que dibujaste para explicar el sistema puede convertirse en el sistema. Para generar código a partir de él, consulta la habilidad besser-generators.
Cuándo recurrir a habilidades relacionadas
- Construcción de modelos en profundidad (enumeraciones, herencia, métodos, OCL, modelos de objeto / característica / despliegue / NN / cuánticos) → la habilidad besser-user.
- Generación de código a partir del modelo → la habilidad besser-generators.
- Errores (problemas de importación/validación/editor) → la habilidad besser-troubleshooting.