Metadata-Version: 2.4
Name: gibsgraph
Version: 0.3.4
Summary: GraphRAG + LangGraph agent for intelligent knowledge graph reasoning over Neo4j
Project-URL: Homepage, https://github.com/gibbrdev/gibsgraph
Project-URL: Documentation, https://gibbrdev.github.io/gibsgraph
Project-URL: Repository, https://github.com/gibbrdev/gibsgraph
Project-URL: Bug Tracker, https://github.com/gibbrdev/gibsgraph/issues
Project-URL: Changelog, https://github.com/gibbrdev/gibsgraph/blob/main/CHANGELOG.md
Author-email: Victor Gibson <victor@gibs.dev>
License: MIT License
        
        Copyright (c) 2026 Gibbr AB
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: gnn,graphrag,knowledge-graph,langgraph,llm,neo4j
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain-anthropic>=0.2.0
Requires-Dist: langchain-openai>=0.2.0
Requires-Dist: langgraph>=0.2.5
Requires-Dist: neo4j-graphrag[all]>=1.0.0
Requires-Dist: neo4j>=5.26
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pydantic>=2.10
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.9.0
Requires-Dist: structlog>=24.4.0
Requires-Dist: tenacity>=9.0.0
Provides-Extra: dev
Requires-Dist: bandit>=1.8.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: bandit>=1.8.0; extra == 'full'
Requires-Dist: hypothesis>=6.100.0; extra == 'full'
Requires-Dist: mypy>=1.13.0; extra == 'full'
Requires-Dist: pcst-fast>=1.0.7; extra == 'full'
Requires-Dist: peft>=0.13.0; extra == 'full'
Requires-Dist: pre-commit>=4.0.0; extra == 'full'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'full'
Requires-Dist: pytest-cov>=6.0.0; extra == 'full'
Requires-Dist: pytest-mock>=3.14.0; extra == 'full'
Requires-Dist: pytest>=8.3.0; extra == 'full'
Requires-Dist: pyvis>=0.3.2; extra == 'full'
Requires-Dist: ruff>=0.7.0; extra == 'full'
Requires-Dist: streamlit>=1.39.0; extra == 'full'
Requires-Dist: torch-geometric>=2.6.0; extra == 'full'
Requires-Dist: torch>=2.4.0; extra == 'full'
Requires-Dist: transformers>=4.45.0; extra == 'full'
Provides-Extra: gnn
Requires-Dist: pcst-fast>=1.0.7; extra == 'gnn'
Requires-Dist: peft>=0.13.0; extra == 'gnn'
Requires-Dist: torch-geometric>=2.6.0; extra == 'gnn'
Requires-Dist: torch>=2.4.0; extra == 'gnn'
Requires-Dist: transformers>=4.45.0; extra == 'gnn'
Provides-Extra: mistral
Requires-Dist: langchain-mistralai>=0.2.0; extra == 'mistral'
Provides-Extra: ui
Requires-Dist: pyvis>=0.3.2; extra == 'ui'
Requires-Dist: streamlit>=1.39.0; extra == 'ui'
Description-Content-Type: text/markdown

# GibsGraph

> **Natural language queries for any Neo4j graph — automatically.**
> Built by [V.Gibson](https://gibs.dev) at Gibbr AB

[![CI](https://github.com/gibbrdev/gibsgraph/actions/workflows/ci.yml/badge.svg)](https://github.com/gibbrdev/gibsgraph/actions)
[![Coverage](https://codecov.io/gh/gibbrdev/gibsgraph/branch/main/graph/badge.svg)](https://codecov.io/gh/gibbrdev/gibsgraph)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

GibsGraph connects to any Neo4j knowledge graph, auto-discovers its schema, and lets
you ask questions in plain English. 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](CHANGELOG.md)** | **[Contributing](CONTRIBUTING.md)**

---

## What it does (v0.3.4)

- **Natural language queries** — ask anything about your Neo4j graph
- **Text-to-graph ingestion** — `g.ingest("any text")` extracts entities and relationships into Neo4j automatically
- **Expert knowledge graph** — 920 records: 36 clauses, 133 functions, 446 examples, 23 modeling patterns, 318 best practices
- **Bundled expert data** — works out of the box without loading data into Neo4j first (quality-filtered to ~849 records)
- **4-stage validation** — syntactic → structural → semantic → domain, with enterprise severity levels
- **Auto schema discovery** — connects and learns your graph structure automatically
- **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
- PCST subgraph pruning

---

## Quick start

```bash
pip install gibsgraph
```

```python
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()
```

---

## Configuration

Set environment variables (or pass them directly):

```bash
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

```bash
pip install gibsgraph
```

Optional extras:

```bash
pip install "gibsgraph[mistral]"  # Mistral LLM support
pip install "gibsgraph[gnn]"      # G-Retriever GNN (needs GPU/CUDA)
pip install "gibsgraph[ui]"       # Streamlit demo UI
pip install "gibsgraph[full]"     # everything including dev tools
```

### Docker

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

---

## Architecture

```
User Query
    |
    v
LangGraph Agent (agent.py)
    +-- retrieval/     <- Auto schema discovery + text-to-Cypher + vector search
    +-- 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
    +-- gnn/           <- G-Retriever inference (planned)
    |
    v
Neo4j Knowledge Graph
```

---

## Examples

| Example | Description |
|---------|-------------|
| [`examples/regulatory_kg.py`](examples/regulatory_kg.py) | EU regulatory knowledge graph (gibs.dev use case) |

---

## Testing

150 unit tests, 52% coverage.

```bash
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](CONTRIBUTING.md) first.

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

---

## License

MIT — see [LICENSE](LICENSE)

---

## Acknowledgements

Built on:
- [neo4j-graphrag-python](https://github.com/neo4j/neo4j-graphrag-python)
- [LangGraph](https://github.com/langchain-ai/langgraph)
- [G-Retriever](https://arxiv.org/abs/2402.07630) (He et al., 2024)
