Guía parcial — vista pública

Esta es una guía parcial de uso y operación. La guía completa está reservada a suscriptores y usuarios activos de la plataforma. Ofrecemos esta selección pública para que quien evalúe el sistema obtenga una primera noción de sus capacidades y flujos. El contenido de la guía privada puede variar con las mejoras continuas del producto.

Ontología — how-to aprobado

El banco de ontología es banco de ontología (Knowledge Explorer), pin 4a886d97 bajo infra/ontology-catalog/. En pantalla no se pinta la marca: «Explorador de Ontología». En esta guía interna sí se nombra, porque hay que operarlo.

Esto no sustituye Explorar y no es el manual del producto aguas arriba. Es cómo SiS usa el banco: cargar el contrato (sis-core + formas), validar SHACL, consultar SPARQL. El resto de workspaces se nombra y se deja.

1. Abrir

Dos caminos, el mismo sitio:

1. https://onto.identia.do o https://onto.legaldesign.do
2. Botón Ontología en la Consola (izquierda de Explorar) — atajo. Visible solo con dev:write.

Pestaña nueva → proveedor de identidad (OIDC) → el correo tiene que estar en correos-autorizados.txt (generado de SOCIETY_ADMIN_EMAILS). Hoy: dandrade@legaldesign.do. Ampliar: una línea en ese fichero y container orchestration up -d oauth2-proxy.

Si el botón sale apagado: falta SOCIETY_SEMANTICA_PUBLIC_URL en el .env y en el compose de la caja. El title al pasar el ratón dice el motivo.

El explorador no vive bajo /ontology-catalog/app/. Su SPA llama /api/… en absoluto. Servirlo bajo una ruta de la Consola da pestaña en blanco con HTTP 200.

Development local: 127.0.0.1:8000 + almacén de grafo del catálogo :6379. Dockerfile con Python 3.14 falla gensim; pin 3.12. SPA no manda X-API-Key → SEMANTICA_ALLOW_ANONYMOUS=true en localhost. En cliente: false (falla cerrada).

2. Qué hay que cargar

Los artefactos viven en el repo SiS, no dentro de la imagen del explorer:

Fichero	Oficio
ontology/sis-core.jsonld	Ontología del Society Graph. Namespace https://w3id.org/sis/ns#. ~45 clases, ~50 propiedades de objeto.
ontology/sis-shapes.ttl	Formas SHACL (dominio, rango, cardinalidad, vocabulario cerrado).

En el explorer: Ontology hub → cargar / importar esos dos ficheros (JSON-LD y Turtle). No esperes que el deploy los deje ya dentro: el grafo de cliente se desplegó vacío a propósito.

Lo hace una orden, por la API (2026-09-26): tools/ops/cargar-ontology-catalog.py carga la ontología ya aplanada (ver la trampa de abajo) y el grafo de ejemplo docs/ejemplos/sis-grafo-ejemplo.ontology-catalog.json (un nodo de cada clase, sin datos reales, con los ids prefijados ejemplo.). Mide antes y después y no duplica si se repite. En Development va sin clave; en una caja, --url y --env con el .env de banco de ontología (la clave no se imprime). Medido en Development: de 0 a 165 nodos y 264 aristas, y «SIS core» con 46 clases y 65 propiedades en el registro.

Trampa al parsear sis-core.jsonld. Un Graph de rdflib ve 25 tripletas y un solo sujeto (la cabecera): los nodos viven en un grafo con nombre (@id + @graph). Sin aviso. Con Dataset son cientos de tripletas. Validar contra lo primero da un verde perfecto sobre nada. tools/check_shacl.py ya usa el camino correcto; el workbench, si importa «plano», puede no.

3. Tour mínimo (lo que importa a SiS)

Workspace	Para qué en SiS
Ontology hub	Cargar sis-core / formas; ver clases y propiedades del contrato
SHACL (pestaña del hub)	Validar el grafo contra sis-shapes.ttl
SPARQL (Analyze)	Consultar el catálogo ya materializado
Graph (Explore)	Ver el grafo del catálogo — no es Explorar de la Consola

El resto existe y se nombra para no buscarlo: Vocabulary, Reasoning, Decisions, Import/Merge, Registry, Entity resolution, Lineage, KG overview. No clones el skill/manual de banco de ontología; ábrelos el día que haga falta.

Validar SHACL — inference=none

rdfs:range no es una restricción: es una regla de entailment. Todo objeto de la propiedad se convierte en la clase del rango. Con inference=rdfs, cualquier sh:class sobre esa propiedad es tautológica.

Medido con una violación inyectada:

inference=rdfs  →  0 violaciones
inference=none  →  1 violación

El entailment materializa el tipo como triple real: ni sh:node que exija rdf:type explícito lo distingue. Las formas de SiS se validan con inference=none. Está escrito en sis-shapes.ttl y en tools/check_shacl.py (ci-check).

Si el workbench ofrece un interruptor de inferencia RDFS, déjalo apagado para estas formas.

Qué ve de verdad la validación (parches 0005, 0006 y 0008, 2026-09-29/30)

Hasta ese día la pestaña SHACL no validaba el contrato de SiS, por dos motivos medidos:

• Respondía «unavailable»: a la imagen le faltaba pyshacl. Lo añade el parche 0006-pyshacl-en-la-imagen.
• Y con pyshacl, daba un verde vacío. banco de ontología no valida el fichero que cargas, sino un grafo que reconstruye de su memoria, y al cargar solo guardaba de cada clase la etiqueta, el comentario y los padres. sis:NodoDeclarado mira sis:emittedAs, así que no seleccionaba nada (0 de 34 sujetos) y decía «conforma» aunque se quitara "task" de la lista cerrada. Lo arregla 0005-carga-conserva-anotaciones: 34 sujetos vistos, y sin "task" da 1 violación.
• Y con otros datos cargados volvía a responder «unavailable» (2026-09-30). Contaba la sesión entera contra un tope de 5.000, y en Development el grafo vivo trae 5.274 aristas junto a los 124 nodos de la ontología. El parche 0008-shacl-cuenta-solo-la-ontologia cuenta solo la ontología pedida: con el grafo vivo cargado valida, y sin "task" da 1 violación.

Límite que queda: guarda un valor por anotación y como texto, sin tipo de dato ni idioma. Una forma con sh:datatype xsd:integer sobre sis:size daría 37 violaciones falsas. sis-shapes.ttl no usa sh:datatype. El contrato de verdad sigue siendo ci-check y make shacl-grafo-vivo; esta pestaña es para explorar.

4. Qué no hace

• No es Explorar. El grafo vivo se recalcula de SQL; esto mira un catálogo ya materializado.
• No sustituye el Society Graph.
• No hay sync automático SiS → catálogo. [P][Parcial]
• No hay tenancy dentro del motor: un almacén, un grafo. Mezclar los dos clientes colisiona identificadores (22 medidas). Aislamiento = una instalación por cliente.
• MCP hacia los agentes no está en la imagen agents-host.
• El explorador no guarda nada: su grafo vive en memoria. Lo dice su código (ontology-catalog/explorer/app.py, también en la versión anterior): no abre conexión a almacén de grafo del catálogo. Cada arranque del contenedor lo deja vacío, tenga almacén de grafo del catálogo el volumen que tenga; se repuebla con tools/ops/cargar-ontology-catalog.py, y una vez desplegado el paquete nuevo lo hace solo el servicio ontology-catalog-cargador, que mira cada 5 minutos. En Development carga además el grafo vivo de SIS, sin el texto de los casos, si hay un fichero en sis/vivo/ (tools/ops/exportar-grafo-a-ontology-catalog.py --escribir; se refresca regenerándolo y reiniciando el explorador). En las cajas de cliente no: su cargador corre con --sin-vivo. El volumen de almacén de grafo del catálogo, corregido el 2026-09-26, persiste, pero hoy nada de lo que se ve en el explorador vive ahí.
• Cabecera de docs/ontology-catalog-EVALUACION.md («estudio, no adopción») está desfasada: está en los dos clientes. El how-to es este, no ese estudio.

5. Borde y deploy

sis-interna es internal: true: orquestador de contenedores acepta ports: y no los aplica. Por eso ontology-catalog-rele (socat) publica 127.0.0.1:8010.

proxy de entrada → oauth2-proxy (quién) → rele → explorer. La clave se inyecta detrás. Apps proveedor de identidad (OIDC) distintas: onto-identia / onto-legaldesign.

Parches en infra/ontology-catalog/patches/. No forkear.

Despliegue del servicio: . Runbook 27 entero.