grai-build 0.5.0

Declarative knowledge graph modeling tool inspired by dbt

grai.build

Schema-as-code for graph databases — Define schemas in YAML, generate docs like dbt, manage migrations like Alembic.

What is grai.build?

grai.build manages your graph schema, not your data. Define entities and relations in YAML, and grai.build:

• Validates schema for consistency before deployment
• Compiles to Cypher constraints and indexes
• Generates interactive documentation (like dbt docs)
• Tracks lineage with visualizations
• Manages migrations with version control

What it's not: An ETL tool. Use Airflow, Prefect, or dbt for data loading — grai.build handles the schema layer.

Quick Start

pip install grai-build

# Initialize a project
grai init my-graph-project
cd my-graph-project

# Validate and build
grai build

# Generate documentation
grai docs --serve

# Deploy to Neo4j
grai run --uri bolt://localhost:7687 --user neo4j --password secret

Project Structure

my-graph-project/
├── grai.yml              # Project configuration
├── entities/
│   ├── customer.yml      # Node definitions
│   └── product.yml
├── relations/
│   └── purchased.yml     # Relationship definitions
└── target/
    └── neo4j/
        └── compiled.cypher

Schema Definition

Entity (entities/customer.yml):

entity: customer
source: analytics.customers
keys: [customer_id]
properties:
  - name: customer_id
    type: string
  - name: name
    type: string
  - name: region
    type: string

Relation (relations/purchased.yml):

relation: PURCHASED
from: customer
to: product
source: analytics.orders
mappings:
  from_key: customer_id
  to_key: product_id
properties:
  - name: order_id
    type: string
  - name: order_date
    type: datetime

Compiled output (target/neo4j/compiled.cypher):

MERGE (n:customer {customer_id: row.customer_id})
SET n.name = row.name, n.region = row.region;

MATCH (from:customer {customer_id: row.customer_id})
MATCH (to:product {product_id: row.product_id})
MERGE (from)-[r:PURCHASED]->(to)
SET r.order_id = row.order_id, r.order_date = row.order_date;

Features

Feature	Description
Schema validation	Catch reference errors and type mismatches before deployment
Cypher compilation	Generate constraints, indexes, and merge statements
Documentation	Interactive HTML docs with entity catalog and graph visualization
Lineage tracking	Dependency graphs and impact analysis
Migrations	Version-controlled schema changes with up/down scripts
Build caching	Incremental builds for faster iteration

CLI Commands

grai init <name>       # Create new project
grai validate          # Validate schema
grai build             # Compile project
grai run               # Deploy to Neo4j
grai docs              # Generate documentation
grai lineage           # Show dependency graph
grai migrate-generate  # Create migration from changes
grai migrate-apply     # Apply pending migrations

CI/CD Integration

# .github/workflows/deploy-schema.yml
name: Deploy Graph Schema

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Schema
        run: grai validate

      - name: Deploy to Production
        run: |
          grai run --schema-only \
            --uri ${{ secrets.NEO4J_URI }} \
            --user ${{ secrets.NEO4J_USER }} \
            --password ${{ secrets.NEO4J_PASSWORD }}

Development

git clone https://github.com/asantora05/grai.build.git
cd grai.build
pip install -e ".[dev]"
pytest

Roadmap

• YAML schema definition and validation
• Cypher compilation for Neo4j
• Documentation generation
• Lineage tracking and visualization
• Schema migrations

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.