gibsgraph 0.4.0

Natural language to Neo4j — query and build knowledge graphs automatically

GibsGraph

Natural language to Neo4j — query and build knowledge graphs automatically. Built by V.Gibson at Gibbr AB

GibsGraph connects to any Neo4j knowledge graph, auto-discovers its schema, and lets you ask questions in plain English — or build new graphs from unstructured text. It generates Cypher automatically, retrieves the relevant subgraph, and returns a grounded answer with the Cypher shown so you can verify what was queried.

Changelog | Contributing

---

What it does (v0.4.0)

• Natural language queries — ask anything about your Neo4j graph
• Intent classification — LLM-powered NL understanding extracts industry, region, regulations, and goal from free-form input
• Text-to-graph ingestion — g.ingest("any text") extracts entities and relationships into Neo4j automatically
• Post-ingest validation — checks generated graphs against Neo4j conventions (PascalCase labels, UPPER_SNAKE_CASE relationships, generic label detection)
• Schema introspection — g.schema() returns node labels, relationship types, counts, and properties per label
• Expert knowledge graph — 991 records: 36 clauses, 133 functions, 477 examples, 23 modeling patterns, 322 best practices
• Bundled expert data — works out of the box without loading data into Neo4j first (quality-filtered to ~800 records)
• Training data pipelines — EUR-Lex (1,106 pairs), MITRE ATT&CK (2,351 pairs), NL-to-graph (43 curated pairs from 12 verified schemas)
• 4-stage validation — syntactic → structural → semantic → domain, with enterprise severity levels
• Auto schema discovery — connects and learns your graph structure automatically
• PCST subgraph pruning — prunes vector neighbourhoods to the most query-relevant subset (opt-in, requires gibsgraph[gnn])
• Dual retrieval — vector search (when index exists) with text-to-Cypher fallback
• Cypher self-healing — if generated Cypher fails, the error is sent back to the LLM for correction
• Cypher transparency — see exactly what was queried
• Visualization — Mermaid diagrams and Neo4j Bloom deep links
• Secure by default — read-only transactions, parameterized Cypher, injection validation
• LLM flexibility — OpenAI, Anthropic, Mistral, xAI/Grok — auto-detected from env keys

Planned (not yet implemented)

• G-Retriever GNN reasoning (training data ready, model pending)

---

Quick start

pip install gibsgraph

from gibsgraph import Graph

# Connect — auto-detects LLM from your env keys
g = Graph("bolt://localhost:7687", password="your-password")

# Ask anything
result = g.ask("What movies did Tom Hanks act in?")
print(result)              # the answer
print(result.cypher)       # Cypher that was run
print(result.confidence)   # 0.0-1.0
print(result.visualization) # Mermaid diagram string

g.close()  # or use: with Graph(...) as g:

# Ingest text into your graph
g = Graph("bolt://localhost:7687", password="your-password", read_only=False)
g.ingest("Apple acquired Beats Electronics for $3 billion in 2014.", source="news")
g.close()

---

Expert knowledge graph

GibsGraph ships with a curated knowledge graph of 991 Neo4j records (~800 after quality filtering): Cypher clauses, functions, query examples, modeling patterns, and best practices. This expertise is bundled as JSONL — no extra setup needed.

When you ask a question, the agent retrieves relevant expert knowledge to generate better Cypher, validate results, and avoid common mistakes. This is what separates GibsGraph from a raw LLM — it reasons with real Neo4j expertise, not just training data.

---

Configuration

Set environment variables (or pass them directly):

export NEO4J_URI=bolt://localhost:7687
export NEO4J_PASSWORD=your_password
export OPENAI_API_KEY=sk-...     # or ANTHROPIC_API_KEY, MISTRAL_API_KEY, XAI_API_KEY

Or use a .env file — copy .env.example to get started.

---

Installation

pip install gibsgraph

Optional extras:

pip install "gibsgraph[mistral]"  # Mistral LLM support
pip install "gibsgraph[gnn]"      # PCST pruning + G-Retriever GNN
pip install "gibsgraph[ui]"       # Streamlit demo UI
pip install "gibsgraph[full]"     # everything including dev tools

Docker

cp .env.example .env
# Edit .env with your Neo4j password and API key
docker compose up
# Open http://localhost:8501

---

Architecture

User Query (natural language, any quality)
    |
    v
LangGraph Agent (agent.py)
    +-- classify       <- Intent classification (industry, region, regulations, goal)
    +-- retrieval/     <- Auto schema discovery + text-to-Cypher + vector search + PCST pruning
    +-- tools/         <- Cypher validator, Mermaid visualizer
    +-- training/      <- 4-stage validation (syntactic/structural/semantic/domain)
    +-- expert.py      <- ExpertStore + BundledExpertStore (JSONL fallback)
    +-- data/          <- Bundled expert JSONL (clauses, functions, examples, patterns, practices)
    +-- kg_builder/    <- Text to Neo4j via SimpleKGPipeline + post-ingest validation
    +-- gnn/           <- G-Retriever inference (planned)
    |
    v
Neo4j Knowledge Graph

---

Examples

Example	Description
examples/regulatory_kg.py	EU regulatory knowledge graph (gibs.dev use case)

---

Testing

299 tests, 80% coverage.

pytest                          # All tests
pytest tests/unit/              # Unit only
pytest tests/integration/       # Integration (requires Neo4j)
pytest --cov --cov-report=html  # With coverage report

---

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

pip install -e ".[dev]"
ruff check src/ tests/
mypy src/gibsgraph
pytest

---

License

MIT — see LICENSE

---

Acknowledgements

Built on:

• neo4j-graphrag-python
• LangGraph
• G-Retriever (He et al., 2024)