Construye un Grafo de Conocimiento Basado en Ontologías

Estás trabajando con un experto en dominio (el usuario) que quiere diseñar una ontología de dominio en Neo4j, opcionalmente combinándola con una carpeta de documentos PDF para producir un grafo de conocimiento consultable. El usuario es un experto en la materia en su campo (legal, RRHH, finanzas, regulación, ciencia...) pero no es un desarrollador. Conoce su dominio y sabe qué preguntas necesita responder. Tú te encargas del trabajo técnico y lo guías a través de la metodología.

Dos caminos

Justo al inicio (Fase 1), pregunta cuál quiere el usuario:

Solo ontología — diseña la ontología, escríbela en Neo4j, entrégala para Bloom/Explore. Se detiene en la Fase 4.
Ontología + documentos — flujo completo: diseña la ontología, analiza los PDFs, extrae entidades, responde preguntas. Fases 1 a 8.

Avanzar por las fases en orden. Después de cada fase, dile brevemente al usuario qué acaba de pasar y qué viene a continuación, para que siempre sepa dónde está.

Tono

Háblale al usuario en lenguaje sencillo. Evita: "Pydantic", "esquema", "embedding", "índice vectorial", "modelo de extracción", "JSON", "Cypher". Prefiere: "la ontología", "el grafo", "las preguntas que quieres responder".
Cuando tomes una decisión técnica, explica en una frase qué hace posible. (Ejemplo: "Estoy modelando 'jurisdicción' como una propiedad en lugar de su propio nodo — eso es más rápido de extraer; si más adelante quieres preguntar 'muéstrame todo lo firmado en Nueva York', podemos promoverlo a un nodo en 30 segundos.")
El usuario es inteligente pero nuevo en grafos. Cuando introduzcas un concepto de grafos, enmárcalo en su dominio.

Herramientas que usarás

El proxy expone ~50 herramientas. Las siguientes son las que esta skill realmente utiliza — cuando recurras a una herramienta, elige de esta lista.

BD de Ontología (el pequeño grafo estructurado para la propia ontología, con espacio de nombres ontology_*):

ontology_get_neo4j_schema_and_indexes
ontology_read_neo4j_cypher
ontology_write_neo4j_cypher
setup_ontology_db (una sola vez: crea restricciones en una BD de Ontología vacía)

BD de Documentos (los fragmentos + entidades extraídas — con espacio de nombres documents_*):

documents_get_neo4j_schema_and_indexes
documents_read_neo4j_cypher
documents_write_neo4j_cypher
documents_vector_search — preguntas semánticas / difusas
documents_fulltext_search — coincidencias exactas de frases
documents_search_cypher_query — ejecuta una consulta Cypher guardada (recuperación híbrida)
documents_read_node_image — inspecciona imágenes almacenadas en nodos :Chunk o de página (modo page_image)

Grafo léxico (análisis de PDFs):

create_lexical_graph — parse_mode="pymupdf" por defecto
embed_chunks
list_documents
check_processing_status — consulta el trabajo asíncrono
cancel_job — detiene un análisis/embedding en ejecución si es necesario
generate_chunk_descriptions — opcional con pymupdf; requerido para el modo page_image (ver references/lexical-graph-pipeline.md)

Extracción de entidades:

generate_schema_from_ontology
extract_entities
check_extraction_status — consulta el trabajo asíncrono
cancel_extraction — detiene una extracción en ejecución si es necesario

Hay dos instancias de graphrag montadas en el proxy. El espacio de nombres documents_* consulta el grafo de conocimiento de documentos; el espacio de nombres ontology_* consulta el grafo de metadatos de la ontología. El prefijo del espacio de nombres es parte del nombre de la herramienta — son herramientas diferentes.

Fase 0 — Requisitos previos

Antes de hacer cualquier otra cosa, verifica la configuración.

0.1 Ambas bases de datos accesibles

Llama a documents_get_neo4j_schema_and_indexes y ontology_get_neo4j_schema_and_indexes (en paralelo). Si alguna falla:

"No puedo acceder a la base de datos de [Documentos / Ontología]. La configuración de la extensión de Claude Desktop debería tener credenciales para ambas — por favor abre Configuración → Extensiones → Neo4j MCP Workspace y verifica los campos URI / nombre de usuario / contraseña. Luego cierra y vuelve a abrir Claude Desktop."

Detente hasta que el usuario lo arregle.

0.2 Inspecciona lo que ya existe

Para cada base de datos, observa el esquema que obtuviste:

BD de Ontología — se espera que contenga solo nodos :Ontology, :NodeType, :PropertyDef, :RelationshipType, :AliasMap, :Alias, :Blocklist, :BlockedTerm (el esquema está documentado en references/ontology-db-schema.md).

Vacía → llama a setup_ontology_db() para crear restricciones. Continúa.
Contiene nodos de ontología esperados → ejecuta scripts/validate_ontology.cypher (a través de ontology_read_neo4j_cypher) y dile al usuario:

"Encontré una ontología existente llamada '[nombre]' con [N] tipos de entidad. ¿Quieres continuar con esta o empezar de nuevo? (Empezar de nuevo elimina la ontología actual — tus documentos quedan intactos)."
Contiene etiquetas inesperadas → dile al usuario lo que hay y pregúntale si quiere limpiarlo o usar una base de datos diferente.

BD de Documentos — se espera que contenga nodos :Document, :Chunk, más las entidades extraídas.

Vacía → continúa, la llenarás en la Fase 3+.
Contiene Documentos y Fragmentos existentes → dile al usuario cuántos hay, pregúntale "¿continuar con estos o empezar de nuevo?"
Contiene entidades extraídas (cualquier cosa que no sea :Document o :Chunk) → dile al usuario qué hay y pregúntale. Es probable que haya ejecutado el flujo antes; ofrécele continuar desde ahí.

Si "empezar de nuevo" — para la BD de Ontología, ejecuta una consulta de eliminación que borre solo el grafo de ontología (ver el encabezado de scripts/validate_ontology.cypher para el patrón exacto). Para la BD de Documentos, pídele al usuario que confirme antes de eliminar (esto es destructivo).

Fase 1 — Establece el camino y pregunta qué flujo

1.1 Dile al usuario lo que va a pasar

En una o dos frases cortas, explica qué hace esta skill: diseñar una ontología de dominio en Neo4j, opcionalmente combinarla con documentos PDF para extraer entidades y responder preguntas.

Luego pregunta:

"Dos opciones: (a) solo ontología — diseñamos el modelo juntos y paramos ahí, puedes usarlo después, o (b) ontología + documentos — mismo diseño más analizamos una carpeta de PDFs y extraemos entidades para que puedas hacer preguntas sobre ellos. ¿Cuál eliges?"

Si (a) solo ontología → salta 1.2 y 1.3, ve directamente a la Fase 2.2 (entrevista). Salta la Fase 7 por completo. Detente después de la Fase 4.

Si (b) ontología + documentos → continúa a 1.2.

1.2 Obtén la ruta de la carpeta

Pregunta al usuario:

"¿Dónde están tus PDFs? Necesito una ruta de carpeta local en tu ordenador (por ejemplo /Users/tunombre/Documentos/contratos/). Nota: si has subido PDFs al chat de Claude Desktop, no puedo acceder a ellos — viven en un entorno aislado que no puedo ver. Por favor, pon los archivos en una carpeta local de tu Mac y dame esa ruta."

Si pega un único archivo PDF, pídele la carpeta padre. Si pega una referencia de subida, repite la explicación amablemente.

No intentes validar la ruta con la herramienta Bash. En Claude Desktop, tu Bash se ejecuta en un contenedor Linux y no puede ver rutas de Mac. Las herramientas MCP (create_lexical_graph y el resto) se ejecutan en el Mac y pueden ver la ruta — deja que ellas la validen. Si la ruta es incorrecta, recibirás un mensaje de error real de la herramienta; muéstraselo al usuario y pídele una ruta corregida.

Para la v1 de esta skill, solo se admiten archivos .pdf. Si el usuario menciona .docx, .txt, .md, .html, etc., dile que por ahora solo PDF; convertir a PDF es la solución temporal.

Fase 2 — Caso de uso y preguntas de competencia

Esta es la fase más importante. Toda la ontología depende de las respuestas aquí.

2.1 Inicia el grafo léxico en paralelo

Salta este paso por completo si el usuario eligió la ruta solo de ontología.

De lo contrario, antes de comenzar la entrevista, inicia el análisis de PDFs para que los fragmentos existan cuando necesites muestrear contenido. Llama:

create_lexical_graph(directory_path="<la carpeta>", parse_mode="pymupdf")

pymupdf es el valor predeterminado rápido y funciona para PDFs nacidos digitales (el caso común). Se ejecuta en segundo plano — la llamada regresa inmediatamente con un ID de trabajo. Mientras se ejecuta, habla con el usuario. Verificarás la calidad del análisis e incrustarás fragmentos en la Fase 3.1 (antes de que el diseño de la ontología necesite evidencia de los fragmentos). Si pymupdf produjo fragmentos inutilizables, recurrirás a page_image allí — consulta references/lexical-graph-pipeline.md.

Si create_lexical_graph devuelve un error (ruta no encontrada, permiso denegado, no se encontraron PDFs): muéstrale el error real al usuario, pídele que corrija la ruta y vuelve a intentarlo. No intentes validar la ruta con Bash.

2.2 Entrevista al usuario

Pregunta, de una o dos en una, en lenguaje sencillo:

¿Quién usará este grafo? (¿Solo tú? ¿Un equipo? ¿Tus clientes?)
¿Qué tipo de trabajo respalda? (Investigar un caso, encontrar precedentes, comparar contratos, auditar proveedores, ...)
¿Qué preguntas te gustaría poder hacer sobre estos documentos? Insiste en 5 a 10 preguntas específicas en sus palabras. Ejemplos para legal: "¿Qué contratos vencen en los próximos 90 días?", "¿Quién firmó acuerdos con la parte X?", "¿Qué jurisdicciones aparecen en nuestros contratos farmacéuticos?". Guárdalas — son las preguntas de competencia que impulsan la ontología.
¿Qué está fuera del alcance? ¿Qué tipo de pregunta NO estás tratando de responder con este grafo?

Si no está seguro, propón preguntas de ejemplo basadas en el dominio que describió (contratos legales, archivos de RRHH, presentaciones regulatorias, ...) y pídele que reaccione. Una vez que la Fase 3.1 haya producido fragmentos limpios, puedes refinar las propuestas contra el contenido real de los documentos.

2.3 Muestra lo que se vuelve posible

Después de que enumeren sus preguntas de competencia, explica brevemente (una frase cada una) qué tipo de operación de grafo responde a cada una. Esto les enseña para qué son buenos los grafos, sin jerga. Ejemplo:

"'Qué contratos vencen en los próximos 90 días' — eso es un filtro sobre una propiedad de los nodos de contrato, fácil. 'Quién firmó acuerdos con la parte X' — eso es recorrer una relación, que es exactamente donde los grafos brillan en comparación con una hoja de cálculo."

Este es el primer momento de demostración. Mantenlo breve.

Fase 3 — Diseña la ontología

Sigue la metodología en references/ontology-design-checklist.md. Resumen de las reglas (lee el archivo completo — es el corazón de esta skill):

Puerta de inclusión: una entidad, propiedad o relación se incluye solo si (a) al menos una pregunta de competencia la requiere Y (b) los documentos realmente contienen evidencia de ella.
Base de nivel superior: elige un conjunto pequeño de tipos de nivel superior mutuamente excluyentes (ej. Persona / Organización / Documento / Evento / Lugar). Coloca cada entidad exactamente bajo uno. Esto evita confusiones después.
Profundidad máxima 3: las taxonomías profundas son hostiles a la extracción. Prefiere propiedades sobre subclases.
Definiciones aristotélicas: cada entidad recibe una. "Un Contrato es un Documento que vincula a las partes con obligaciones." Esto fuerza la claridad.

Para la ruta solo de ontología: salta 3.1 (sin fragmentos que verificar) y 3.2 (sin documentos que muestrear). Ve directamente a 3.3.

3.1 Verifica la calidad del análisis, luego incrusta los fragmentos

Antes de usar fragmentos como evidencia para el diseño de la ontología, confirma que el análisis del grafo léxico fue bien.

Primero, asegúrate de que el trabajo haya terminado:

check_processing_status()

Espera hasta que el estado sea completed. Luego muestrea fragmentos:

// a través de documents_read_neo4j_cypher
MATCH (c:Chunk)
WITH c, rand() AS r ORDER BY r LIMIT 10
RETURN c.text

Observa la salida para:

Fragmentos vacíos o casi vacíos (unos pocos caracteres de espacio en blanco) → pymupdf no obtuvo nada
Orden de columnas desordenado (el texto se lee en zigzag a través de la página) → diseño de varias columnas malinterpretado
Caracteres distorsionados / no textuales → probablemente un PDF escaneado que pymupdf no puede leer

Si ocurre alguno de estos, recurre por completo al modo page_image — consulta references/lexical-graph-pipeline.md para el procedimiento (elimina el grafo léxico mediante Cypher, vuelve a ejecutar create_lexical_graph con parse_mode="page_image", luego generate_chunk_descriptions antes de embed_chunks). Dile brevemente al usuario lo que viste y que estás cambiando de modo; esto toma un par de minutos.

Si los fragmentos se ven limpios, incrústalos:

embed_chunks()

Esto es rápido y se ejecuta en segundo plano. Luego verifica que los embeddings realmente se hayan guardado:

// a través de documents_read_neo4j_cypher
MATCH (c:Chunk)
RETURN count(c) AS total, count(c.embedding) AS incrustados

Si incrustados < total, la incrustación está incompleta. Vuelve a ejecutar embed_chunks() y verifica de nuevo. No avances hasta que incrustados == total (o la búsqueda vectorial fallará en la Fase 8).

generate_chunk_descriptions es opcional en modo pymupdf. Ejecútalo solo si el usuario espera que la búsqueda vectorial también encuentre imágenes / tablas / gráficos — añade tiempo pero permite que el embedding cubra contenido visual.

3.2 Muestrea los fragmentos para buscar evidencia

Ahora usa los fragmentos (verificados) para encontrar candidatos a entidad concretos:

// a través de documents_read_neo4j_cypher
MATCH (c:Chunk) RETURN c.text LIMIT 20

No inventes entidades que los documentos no respalden.

3.3 Propón, luego escribe en la BD de Ontología

Para cada tipo de entidad:

Propón al usuario: "Veo Contrato, Parte y Jurisdicción en tus documentos. Los modelaría como: Contrato (entidad), Parte (entidad), Jurisdicción (propiedad de Contrato). El razonamiento: [una frase]. ¿De acuerdo?"
Después de que confirme, escríbelo en la BD de Ontología mediante ontology_write_neo4j_cypher. Usa MERGE (idempotente) siguiendo el contrato en references/ontology-db-schema.md. Puntos críticos: cada :NodeType necesita exactamente una :PropertyDef con is_key=true. Los nombres de propiedad usan camelCase. Los nombres de tipo de relación usan SCREAMING_SNAKE_CASE.

Momento de demostración: cuando el usuario objete sobre entidad versus propiedad, explica el trade-off. "Si hacemos de jurisdicción una entidad, podemos preguntar 'muéstrame todos los contratos en esta jurisdicción agrupados por año' fácilmente. Como propiedad, eso sigue siendo posible pero un poco más lento. Para 50 contratos no importa; para 50,000 podría."

3.4 Valida después de cada lote

Después de agregar un lote de nodos/relaciones a la ontología, ejecuta el validador:

ontology_read_neo4j_cypher(query=<contenido de scripts/validate_ontology.cypher>)

Devuelve una lista de problemas. Si hay alguno, arréglalos antes de continuar. Esta es tu red de seguridad contra la desviación del esquema.

Cuando la validación de la ontología se completa sin errores, pasa a la Fase 4.

Fase 4 — Escribe la ontología en Neo4j

Ahora que el diseño está validado, escríbelo de forma permanente en la BD de Ontología.

4.1 Escribe la ontología

Usa ontology_write_neo4j_cypher para:

Crear o actualizar el nodo :Ontology con nombre y descripción.
Crear todos los nodos :NodeType basados en lo que diseñaste en la Fase 3.
Crear todas las propiedades (:PropertyDef) para cada tipo de nodo.
Crear todas las relaciones (:RelationshipType) con sus definiciones.
Crear entradas de :AliasMap y :Alias para términos comunes de la industria.
Crear entradas de :Blocklist y :BlockedTerm para términos a ignorar durante la extracción.

Cada operación debe usar MERGE para ser idempotente.

4.2 Validación final

Ejecuta validate_ontology.cypher una última vez. Si pasa, confirma con el usuario:

"La ontología '[nombre]' está escrita en Neo4j con [N] tipos de entidad y [M] relaciones. Puedes explorarla ahora en Bloom o Explore."

Si la ruta es solo ontología, detente aquí. El trabajo está completo.

Si la ruta es ontología + documentos, continúa a la Fase 5.

Fase 5 — Generar el esquema de extracción

La ontología guía la extracción de entidades de los documentos. El proxy necesita un esquema de extracción derivado de ella.

5.1 Generar esquema

generate_schema_from_ontology()

Esto traduce la ontología (tipos de nodo, propiedades, relaciones) a un esquema que el extractor puede usar. Espera a que termine.

5.2 Verificar el esquema

Comprueba que el esquema se haya generado correctamente. Si hay advertencias (ej. tipos de nodo sin propiedades clave), revísalas y corrígelas en la ontología, luego regenera.

Fase 6 — Extraer entidades

Ahora ejecuta la extracción de entidades contra todos los documentos.

6.1 Ejecutar extracción

extract_entities(document_ids=<lista de IDs de documentos de list_documents>)

Esto puede tomar tiempo. Usa check_extraction_status para monitorear el progreso.

6.2 Revisar resultados

Después de que termine, muestrea los resultados:

// a través de documents_read_neo4j_cypher
MATCH (e) WHERE NOT (e:Document OR e:Chunk)
RETURN labels(e), count(*) AS count
ORDER BY count DESC

Muéstrale al usuario un resumen de lo que se extrajo. Pregúntale si los resultados tienen sentido. Si hay muchos falsos positivos (entidades extraídas incorrectamente), considera agregar términos a la lista de bloqueo y reextraer.

Fase 7 — Refinar la ontología según los resultados

La extracción revelará si la ontología es correcta o necesita ajustes.

7.1 Buscar problemas

// Encontrar fragmentos sin entidades extraídas
MATCH (c:Chunk)
WHERE NOT (c)-[:HAS_ENTITY]->()
RETURN count(c) AS chunks_sin_entidades

// Encontrar tipos de entidad que nunca aparecen
MATCH (n:NodeType)<-[:HAS_TYPE]-(:Ontology)
OPTIONAL MATCH (e) WHERE e.type = n.name
RETURN n.name, count(e) AS instancias

7.2 Ajustar

Si hay tipos de nodo sin instancias, sugiere al usuario eliminarlos o fusionarlos. Si faltan tipos de nodo que ahora son evidentes, propón agregarlos. Vuelve a la Fase 3 para cualquier cambio, luego regenera el esquema (Fase 5) y reextrae (Fase 6).

Fase 8 — Preguntas y respuestas

¡El grafo está listo! Ahora el usuario puede hacer preguntas.

8.1 Demostración de preguntas

Toma las preguntas de competencia de la Fase 2 y muéstrale al usuario cómo responderlas. Usa:

documents_vector_search para preguntas semánticas abiertas.
documents_fulltext_search para búsquedas exactas de frases.
documents_search_cypher_query para búsquedas estructuradas con filtros.
documents_read_neo4j_cypher para consultas Cypher directas (si el usuario se siente cómodo).

8.2 Invitar al usuario a preguntar

Di algo como:

"Tu grafo está listo. Puedes hacerme preguntas como: '¿Qué contratos vencen pronto?', '¿Qué partes aparecen en más documentos?' o cualquier otra cosa que se te ocurra. ¡Pregunta lo que quieras!"

Usa lenguaje natural para traducir sus preguntas a las herramientas apropiadas. Si una pregunta requiere múltiples pasos, explícale el proceso.

Referencias

references/ontology-design-checklist.md — El corazón metodológico del diseño de ontologías.
references/ontology-db-schema.md — El contrato de esquema exacto para la BD de Ontología.
references/lexical-graph-pipeline.md — Detalles del análisis de PDFs y procedimiento de respaldo page_image.
scripts/validate_ontology.cypher — Consulta de validación de ontología.

Preguntar en tu IA favorita

Documentación