OrgGraph AI: Un grafo de conocimiento basado en agentes sin codificación previa para datos de recursos humanos.
Cómo un LLM descubre un esquema de grafo a partir de cualquier archivo Excel o CSV, lo carga en Neo4j con Cypher dinámico y responde a preguntas sobre personalización mediante un agente de chat LangGraph.
Fuentes: Building a Fully Agentic Employee Knowledge Graph: **OrgGraph AI — using LangGraph & Neo4j**
Las grandes empresas poseen más datos sobre sus empleados que nunca, pero la gestión del personal sigue basándose en conjeturas. Las jerarquías de recursos humanos se encuentran en Workday; las asignaciones de proyectos, en Jira. Las habilidades, los niveles de competencia y las certificaciones quedan atrapadas en portales de formación obsoletos. Luego llega un proyecto de IA de alta prioridad, y el responsable del desarrollo pregunta quién en la oficina de Mumbai o Pune domina Python avanzado, cuenta con una certificación AWS, conoce IA/ML, ha trabajado en proyectos bancarios y aún tiene capacidad disponible.
Responder a esa pregunta lleva aproximadamente una semana, si es que se responde alguna vez. Los datos existen, pero están enterrados en sistemas aislados que no pueden analizar cómo se relacionan entre sí.
OrgGraph AI es un sistema creado para cerrar esa brecha. Acepta datos organizativos en bruto en cualquier formato de Excel o CSV, cuenta con un LLM que determina por sí mismo el esquema del grafo, carga todo en Neo4j y luego responde a las preguntas en lenguaje sencillo. No existe ninguna lógica de dominio codificada de antemano.
Las relaciones son más importantes que los registros
Las herramientas estándar de recursos humanos se basan en tablas SQL planas. Pedir la lista de todos los empleados en Bangalore o de quienes conocen Python es algo sencillo para ellas. Sin embargo, tropiezan con preguntas interseccionales, aquellas que requieren analizar varias dimensiones de relaciones al mismo tiempo. Un grafo de conocimiento abre cuatro tipos de tareas:
- Distribución precisa del personal. Encontrar a la única persona que cumpla con la habilidad A, la certificación B, la ubicación C y tenga capacidad disponible, en una sola búsqueda en lugar de cuatro uniones separadas.
Qué significa no tener codificación fija
La mayoría de los proyectos de grafos de conocimiento comparten un secreto incómodo: el esquema está codificado de forma fija. Un ingeniero lee la hoja de cálculo, decide que los empleados son nodos, las habilidades también son nodos y un enlace HAS_SKILL los conecta, escribe Cypher personalizado para cada entidad y lo envía. Luego, Recursos Humanos agrega una hoja de Certificaciones o renombra PrimarySkill a TechStack, y todo el proceso deja de funcionar.
OrgGraph AI invierte esta situación. El LLM decide cuál debe ser el esquema. Dado cualquier archivo tabular, el sistema:
- analiza los datos, incluyendo los tipos de columnas, la cardinalidad y los candidatos a claves foráneas
- infiere un esquema de grafo a partir de la salida estructurada del LLM, validada por Pydantic
- genera y ejecuta consultas Cypher
MERGEde forma dinámica - examina el grafo final para que un agente de chat pueda consultarlo
Nadie dibuja nada a mano y ningún código se escribe con antelación. Si mañana se reemplazan los datos de recursos humanos por los de logística de cadena de suministro, la misma base de código genera un grafo completamente diferente. El conjunto de datos de prueba era sintético, aproximadamente una docena de hojas, y el pipeline procesa todo lo que se le proporciona.
Cuatro fases
El sistema funciona en cuatro fases, orquestado con Python, LangChain, LangGraph, Pydantic y Neo4j.
Fase 1: perfilado de los metadatos
Antes de que participe cualquier LLM, un MetadataProfiler analiza los datos brutos localmente y genera una huella estructural compacta. Esta es una decisión deliberada en materia de privacidad: los registros reales de los empleados nunca llegan al modelo. El modelo obtiene los nombres de las columnas, los tipos de datos, cuántos valores distintos tiene cada columna y algunos valores de ejemplo.
La técnica más valiosa del analizador es la detección automática de claves foráneas. Marca una columna como posible clave foránea cuando sus valores se encuentran en su mayor parte en una columna de clave primaria en otro lugar:
# Simplified FK detection logic from profiler.py
overlap = col_values & ref_values
if len(overlap) / len(col_values) >= 0.8:
fk_candidates.append({
"source_table": tname,
"source_column": col,
"target_table": ref_table,
"target_column": ref_col,
"match_pct": round(len(overlap) / len(col_values) * 100, 1),
})
En el conjunto de datos de recursos humanos, esto revela que Manager_Employee_ID en la tabla Employees coincide con Employee_ID en más del 80% de los casos, lo que sugiere una relación REPORTS_TO de autorreferencia. La pista se dirige al LLM, el cual no pudo deducir una jerarquía a partir únicamente de los nombres de las columnas.
Fase 2: descubrimiento del esquema
El perfil se envía a un LLM, configurable entre OpenAI GPT-4o, Google Gemini y Groq, mediante una instrucción que lo presenta como arquitecto principal de bases de datos gráficas.
El problema técnico clave es que los LLM generan texto de formato libre, mientras que las bases de datos gráficas exigen una estructura estricta. with_structured_output() de LangChain conecta ambos aspectos al obligar al modelo a devolver un objeto Pydantic validado:
# The LLM is coerced to return this exact structure
class GraphMappingModel(BaseModel):
nodes: List[NodeMapping] # What becomes a Node?
relationships: List[RelationshipMapping] # What becomes an Edge?
notes: str # LLM's reasoning notes
class NodeMapping(BaseModel):
label: str # e.g., "Employee"
source_table: str # e.g., "Employees"
primary_key_column: str # e.g., "Employee_ID"
properties: List[PropertyMapping] # All columns to map
class RelationshipMapping(BaseModel):
type: str # e.g., "HAS_SKILL"
from_node_label: str # e.g., "Employee"
to_node_label: str # e.g., "Skill"
from_key_column: str # FK column in source table
to_key_column: str # PK column of target node
properties: List[PropertyMapping] # Edge properties
Ese GraphMappingModel funciona como el contrato para todo el sistema. El agente de esquema lo genera y el motor de ingestión lo consume. Si la validación falla, se vuelve a solicitar al LLM, de modo que ningún esquema mal formado llegue a Neo4j.
Fase 3: ingestión dinámica de Cypher
Con un esquema validado, el motor escribe Cypher parametrizado en tiempo real. No existen plantillas ni instrucciones condicionales por tipo de entidad. Lee el mapeo y genera sentencias MERGE además de SET para cada tipo de nodo y relación:
# Dynamically generated Cypher from the mapping — zero hardcoding
UNWIND $rows AS row
MERGE (n:Employee {employee_id: row.employee_id})
SET n.full_name = row.full_name,
n.designation = row.designation,
n.date_of_joining = row.date_of_joining,
n.annual_ctc_lpa = toFloat(row.annual_ctc_lpa)
Dado que los nombres del esquema inferido son claves primarias, el motor utiliza MERGE y no CREATE, lo que hace que el proceso sea idempotente. Ejecutarlo tres veces sobre los mismos datos genera el mismo grafo sin duplicados. También realiza conversiones de tipo (toInteger(), toFloat()), convierte NaN en None y omite las filas cuya clave primaria es nula.
El conjunto de datos de demostración no es un ejemplo simplificado: 151 empleados distribuidos en 13 tablas interconectadas, que incluyen 935 mapeos de habilidades, 285 asignaciones de proyectos, 107 certificaciones, 313 reseñas y 453 registros de capacitación, repartidos entre 10 departamentos y 10 oficinas globales.
Fase 4: el chat agente de GraphRAG
La capa de chat es más que un traductor de texto a Cypher. Se trata de una máquina de estados LangGraph con cuatro nodos y recuperación de errores integrada:
User Question
↓
┌─────────────┐
│ Planner │ → Analyzes intent, extracts entities, maps to schema
└──────┬──────┘
↓
┌─────────────┐
│ CypherGen │ → Generates Cypher query using schema + few-shot examples
└──────┬──────┘
↓
┌─────────────┐ ┌─── Error? ───→ Retry CypherGen (up to 2x)
│ Executor │ ────┤
└──────┬──────┘ └─── Success ──→
↓
┌──────────────┐
│ Synthesizer │ → Formats raw graph data into natural language
└──────────────┘
Tres características lo hacen adaptable.
Introspección de esquema en tiempo de ejecución. Al iniciar, el agente obtiene el esquema actualizado desde Neo4j, que indica qué tipos de nodos y relaciones existen, sus propiedades y cómo se conectan. Ese esquema se incluye en cada solicitud, por lo que el agente nunca asume qué contiene la base de datos.
Ejemplos de pocos casos generados automáticamente. Muchos sistemas GraphRAG incluyen ejemplos de Cypher codificados directamente. Aquí, el LLM crea sus propios ejemplos a partir del esquema actualizado y de datos extraídos, y estos se regeneran automáticamente cuando una nueva carga modifica el esquema.
Reintentos conscientes de los errores. Si una consulta generada falla, el mensaje de error vuelve al nodo CypherGen, que corrige la consulta e intenta nuevamente, hasta un máximo de dos veces. Esto hace que el agente sea notablemente resistente a los problemas de sintaxis en casos extremos.
Preocupaciones empresariales
Privacidad. El LLM percibe la estructura, no a las personas. Solo los nombres de las columnas, sus tipos y su cardinalidad salen del perfilador, mientras que los datos personales permanecen en su servidor.
Flexibilidad del proveedor. Un patrón de LLM Factory permite cambiar entre OpenAI, Gemini y Groq modificando una variable de entorno:
# .env: LLM_PROVIDER=gemini | openai | groq
llm = get_llm() # Returns the configured ChatModel
No se requieren cambios en el código y no hay dependencia de un proveedor específico.
Datos desordenados. Las hojas de cálculo corporativas nunca están limpias. El motor de ingestión maneja espacios en blanco al final, formatos de fecha mixtos, valores NaN inesperados y claves primarias nulas, omitiendo o convirtiendo las filas problemáticas en lugar de colapsar.
De la carga a las respuestas
La interfaz de usuario es un panel de control de Streamlit. El usuario carga un archivo Excel o CSV en la barra lateral y observa cómo se ejecuta el proceso en tiempo real: análisis de perfiles, descubrimiento de esquemas, ingestión y, posteriormente, inicialización del agente. Después de eso, simplemente pueden chatear.
Una demostración separada utiliza Vis.js para la representación de grafos basada en física y GSAP para animaciones desencadenadas por el desplazamiento. Los nodos se cargan con fuerzas de gravedad y repulsión en una revelación gradual. Al hacer clic en cualquier nodo se abre un panel con sus propiedades y las relaciones de conexión. Un chat simulado muestra tanto la respuesta en lenguaje natural como la consulta Cypher generada detrás de ella.
Más allá de RR. HH.
La arquitectura no está vinculada a los recursos humanos. El mismo código podría crear un grafo de conocimiento para la gestión de activos informáticos, mapeando servidores, aplicaciones, equipos y dependencias. También podría rastrear proveedores, materiales, almacenes y rutas logísticas en una cadena de suministro, o conectar investigadores, artículos científicos, instituciones y fuentes de financiación en una red de investigación.
Los pipelines de datos que se adaptan a los datos, en lugar de que los ingenieros fuercen los datos dentro de esquemas rígidos, son la dirección hacia la que evolucionan las arquitecturas agentes, y este proyecto es un modelo a seguir para ello.
Lecturas relacionadas
- Un agente financiero de QuickBooks que funciona con un LLM local mediante Ollama y LangChain — Un agente ReAct en Qwen 3.5 9B y una RTX 4070 que lee datos en tiempo real de QuickBooks sin ningún costo relacionado con la nube. Consulte el código, los resultados y las limitaciones conocidas.
- Su primer agente LangGraph: un asistente de fútbol con herramientas y enrutamiento — Tutorial paso a paso de LangGraph: estado compartido, herramientas, un nodo planificador, bordes condicionales y un resumen en formato Markdown, desarrollado alrededor de un asistente ficticio para estadísticas de fútbol.