OrgGraph AI: A Zero-Hardcoding Agentic Knowledge Graph for HR Data

Large companies hold more data about their people than ever, and staffing still comes down to guesswork. HR hierarchies sit in Workday. Project allocations live in Jira. Skills, proficiency levels and certifications are stranded in old training portals. Then a high-priority AI project lands, and a delivery lead asks who in the Mumbai or Pune office has advanced Python, holds an AWS certification, knows AI/ML, has worked on banking projects and still has spare capacity.

Answering that takes about a week, if it happens at all. The facts exist, but they're buried in separate silos that can't reason about how things relate to each other.

OrgGraph AI is a system built to close that gap. It accepts raw organizational data in any Excel or CSV form, has an LLM work out the graph schema on its own, loads everything into Neo4j and then answers questions in plain language. No domain logic is hardcoded anywhere.

Relationships matter more than records

Standard HR tools sit on flat SQL tables. Asking for every employee in Bangalore, or everyone who lists Python, is easy for them. They stumble on intersectional questions, the ones that require walking across several dimensions of relationships at once. A knowledge graph opens up four kinds of work:

1. Precise staffing. Find the one person who matches skill A, certification B, location C and has free bandwidth, in a single traversal instead of four separate joins.
2. Early skill-gap detection. Compare current skills with what upcoming projects need. You might learn the Data & AI division doesn't have enough Kubernetes expertise for the Q3 pipeline while there's still time to act.
3. Succession planning and collaboration. Pair a junior developer in Sydney with a senior architect nearby who shares a tech stack, or locate internal experts for quick consulting rather than hiring outside contractors.
4. Organizational network analysis. Draw reporting chains, spot single points of failure in management structures and see which star performers are over-allocated before they burn out.

What zero hardcoding means

Most knowledge graph projects share an awkward secret: the schema is hardcoded. An engineer reads the spreadsheet, decides employees are nodes, skills are nodes and a HAS_SKILL edge links them, writes custom Cypher for each entity and ships it. Then HR adds a Certifications sheet, or renames PrimarySkill to TechStack, and the whole pipeline stops working.

OrgGraph AI flips this. The LLM decides what the schema should be. Given any tabular file, the system:

1. profiles the data, including column types, cardinality and foreign key candidates
2. infers a graph schema through structured LLM output validated by Pydantic
3. generates and runs Cypher MERGE queries dynamically
4. introspects the finished graph so a chat agent can query it

Nobody maps anything by hand and no Cypher is written in advance. Swap the HR data for supply-chain logistics tomorrow and the same codebase builds a completely different graph. The test dataset was synthetic, roughly a dozen sheets, and the pipeline absorbs whatever it's given.

Four phases

The system runs in four phases, orchestrated with Python, LangChain, LangGraph, Pydantic and Neo4j.

Phase 1: profiling the metadata

Before any LLM is involved, a MetadataProfiler analyzes the raw data locally and produces a compact structural fingerprint. This is a deliberate privacy decision. Real employee records never reach the model. It gets column names, data types, how many distinct values each column has, and a few sample values.

The profiler's most valuable trick is automatic foreign key detection. It flags a column as a likely foreign key when its values are mostly contained in a primary key column elsewhere:

# 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),
    })

In the HR dataset, this reveals that Manager_Employee_ID in the Employees table matches Employee_ID at better than 80%, which suggests a self-referencing REPORTS_TO relationship. The hint goes to the LLM, which couldn't deduce a hierarchy from bare column names.

Phase 2: schema discovery

The profile goes to an LLM, configurable between OpenAI GPT-4o, Google Gemini and Groq, with a prompt casting it as a principal graph database architect.

The key engineering problem is that LLMs produce free-form text and graph databases demand strict structure. LangChain's with_structured_output() bridges the two by forcing the model to return a validated Pydantic object:

# 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

That GraphMappingModel acts as the contract for the whole system. The schema agent produces it and the ingestion engine consumes it. If validation fails, the LLM is asked again, so no malformed schema reaches Neo4j.

Phase 3: dynamic Cypher ingestion

With a validated schema, the engine writes parameterized Cypher on the fly. There are no templates and no switch statement per entity type. It reads the mapping and builds MERGE plus SET statements for each node and relationship type:

# 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)

Since the inferred schema names primary keys, the engine uses MERGE and not CREATE, which makes the pipeline idempotent. Running it three times on the same data yields the same graph without duplicates. It also casts types (toInteger(), toFloat()), turns NaN into None and skips rows whose primary key is null.

The demo dataset isn't a toy: 151 employees across 13 interconnected tables, including 935 skill mappings, 285 project assignments, 107 certifications, 313 reviews and 453 training entries, spread over 10 departments and 10 global offices.

Phase 4: the agentic GraphRAG chat

The chat layer is more than a text-to-Cypher translator. It's a four-node LangGraph state machine with error recovery built in:

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
└──────────────┘

Three properties make it adaptable.

Runtime schema introspection. At startup, the agent pulls the live schema from Neo4j, covering which node and relationship types exist, their properties and how they connect. That schema goes into every prompt, so the agent never assumes what the database contains.

Self-generated few-shot examples. Many GraphRAG systems hardcode Cypher examples. Here the LLM writes its own few-shot examples from the live schema and sampled data, and they regenerate automatically after a new upload changes the schema.

Error-aware retries. If a generated query fails, the error message flows back into the CypherGen node, which fixes the query and tries again, up to two times. That makes the agent notably resilient against edge-case syntax problems.

Enterprise concerns

Privacy. The LLM sees structure, not people. Column names, types and cardinality are all that leave the profiler, and the personal data stays on your server.

Provider flexibility. An LLM Factory pattern allows switching between OpenAI, Gemini and Groq by changing one environment variable:

# .env: LLM_PROVIDER=gemini | openai | groq
llm = get_llm()  # Returns the configured ChatModel

No code changes and no vendor lock-in.

Messy data. Corporate spreadsheets are never clean. The ingestion engine copes with trailing whitespace, mixed date formats, unexpected NaN values and null primary keys, skipping or converting troublesome rows instead of crashing.

From upload to answers

The front end is a Streamlit dashboard. A user uploads an Excel or CSV file in the sidebar and watches the pipeline run live: profiling, schema discovery, ingestion, then agent initialization. After that, they just chat.

A separate showcase demo uses Vis.js for physics-based graph rendering and GSAP for scroll-triggered animation. Nodes load with gravity and repulsion forces in a staged reveal. Clicking any node opens a panel with its properties and connected relationships. A simulated chat shows both the natural language answer and the Cypher query generated behind it.

Beyond HR

The architecture isn't tied to HR. The same code could build a knowledge graph for IT asset management, mapping servers, applications, teams and dependencies. It could track suppliers, materials, warehouses and logistics routes in a supply chain, or connect researchers, papers, institutions and funding sources in a research network.

Data pipelines that adapt to the data, instead of engineers forcing data into rigid schemas, are where agentic architectures are heading, and this project is one blueprint for it.