Metadata-Version: 2.4
Name: gbt-core
Version: 0.1.0
Summary: GBT (Graph Build Tool) - A framework for coordinating and synchronizing graph-structured data.
License: MIT
License-File: LICENSE
Keywords: neo4j,graph,gbt,data-engineering,lineage
Author: Rye
Author-email: ldcanh03042001@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: neo4j
Provides-Extra: postgres
Provides-Extra: trino
Requires-Dist: Jinja2 (==3.1.6)
Requires-Dist: PyYAML (==6.0.3)
Requires-Dist: click (==8.4.1)
Requires-Dist: mkdocs (>=1.6.0,<2.0.0) ; extra == "docs"
Requires-Dist: mkdocs-material (>=9.6.0,<10.0.0) ; extra == "docs"
Requires-Dist: mypy (>=1.17.0,<2.0.0) ; extra == "dev"
Requires-Dist: neo4j (==6.2) ; extra == "neo4j"
Requires-Dist: pandas (>=2.3.0,<3.0.0)
Requires-Dist: pre-commit (>=4.3.0,<5.0.0) ; extra == "dev"
Requires-Dist: psycopg[binary] (>=3.2.0,<4.0.0) ; extra == "postgres"
Requires-Dist: py2neo (==2021.2.4) ; extra == "neo4j"
Requires-Dist: pydantic (>=2.11.0,<3.0.0)
Requires-Dist: pytest (>=9.0.3,<10.0.0) ; extra == "dev"
Requires-Dist: pytest-cov (>=6.2.0,<7.0.0) ; extra == "dev"
Requires-Dist: python-dotenv (>=1.2.2,<2.0.0)
Requires-Dist: requests (>=2.33.1,<3.0.0)
Requires-Dist: ruff (>=0.12.0,<1.0.0) ; extra == "dev"
Requires-Dist: sqlalchemy (>=2.0.0,<3.0.0) ; extra == "postgres"
Requires-Dist: sqlalchemy (>=2.0.0,<3.0.0) ; extra == "trino"
Requires-Dist: structlog (>=25.4.0,<26.0.0)
Requires-Dist: tenacity (>=9.1.0,<10.0.0)
Requires-Dist: tqdm (>=4.66.0,<5.0.0)
Requires-Dist: trino (>=0.336.0,<1.0.0) ; extra == "trino"
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/gbt-logo.jpeg" alt="GBT Logo" width="200" />
</p>

# Graph Build Tool (GBT)

## 📖 What is GBT?

**Graph Build Tool (GBT)** is a transformative workflow framework designed specifically for graph databases, beginning with **Neo4j**. Inspired by modern analytics engineering practices, GBT brings software engineering principles—such as declarative configurations, modularity, templatization, and version control—into graph data engineering.

**Purpose**: GBT empowers data engineers, graph developers, and analysts to build, maintain, and document graph schemas (DDL) and transform graph data (DML) reliably and efficiently. By defining your graph structures in YAML and your transformations in templated Cypher/SQL, GBT reduces complexity and standardizes graph deployments.

---

## 🚀 Getting Started

### Installation

Install `gbt-core` utilizing `pip` or your favorite Python package manager:

```bash
pip install gbt-core
```

If you are using **Poetry** (as used in this repository):

```bash
poetry add gbt-core
```

### Quick Start

1. **Initialize a Project**: Set up your project structure. (See `example/` for a reference structure including `gbt_project.yaml` and `profiles.yaml`).
2. **Define Models**: Create your node and relationship models inside the `models/` directory using Cypher, SQL, and YAML schemas.
3. **Run Transformations**: Execute the CLI commands to parse, compile, and run your graph models:

```bash
gbt compile
gbt run
```

---

## 🏗 Architecture

<p align="center">
  <img src="assets/architecture-flow.png" alt="Architecture Flow" />
</p>

---

## ✨ Current Features

- **Neo4j Native Integration**: A robust Neo4j connector capable of handling complex executions seamlessly.
- **DDL Engine**: Automated Schema Management supporting label operations, index creation, and constraint management defined purely in YAML configurations.
- **DML Engine**: Dynamic data manipulation supporting various materialization strategies including node/relationship **append**, **delete**, and **merge**.
- **Jinja2 Templating**: Leverage Jinja templates (`.cypher.j2`) to build dynamic, reusable, and modular Cypher queries.
- **Manifest Parser**: Advanced compiler that resolves lineage, macros, and dependencies across your `gbt` project into a unified manifest model.
- **Command Line Interface (CLI)**: Intuitive CLI application providing core commands like `gbt compile` and `gbt run`.

---

## 🔮 Future Developments

The journey doesn't stop here. The future roadmap for GBT includes:

- **Multi-Graph Database Support**: Expanding connector capabilities to AWS Neptune, Memgraph, TigerGraph, and more.
- **Data Testing & Quality Checks**: Declarative testing to enforce unique entity constraints, relationship existence, and property data-type validations.
- **Automated Data Lineage UI**: A visual dashboard to explore the dependency graphs (DAG) of the models and relationships.
- **Plugin & Macro Ecosystem**: A package management system allowing the community to share reusable graph algorithm configurations, macros, and transformations.
- **Orchestration Integrations**: Native hooks and operators for popular orchestrators like Apache Airflow, Prefect, and Dagster.
- **Advanced CI/CD Features**: Enhanced slim-CI runs and automatic deployment states.

