GraphForge¶

Composable graph tooling for analysis, construction, and refinement

What is GraphForge?¶

GraphForge is a Python library that provides composable graph tooling for analysis, construction, and refinement. It implements the openCypher query language, allowing you to work with graph data using a familiar, SQL-like syntax.

Key Features¶

openCypher Query Language - Industry-standard graph query language
Real-World Datasets - Built-in support for SNAP, Neo4j, and benchmark datasets
Type-Safe - Built with Pydantic for data validation
Pure Python - No external database dependencies
TCK Compliant - Implements openCypher specification
Composable - Designed for Python workflows

Quick Example¶

from graphforge import GraphForge

# Create a graph
graph = GraphForge()

# Query with openCypher
result = graph.execute("""
    MATCH (p:Person {name: 'Alice'})-[:KNOWS]->(friend)
    RETURN friend.name
""")

for row in result:
    print(row['friend.name'])

Or Load a Real Dataset¶

# Load a SNAP dataset (auto-downloads and caches)
graph = GraphForge.from_dataset("snap-ego-facebook")

# Analyze immediately
result = graph.execute("""
    MATCH (n)-[r]->()
    RETURN n.id, count(r) AS connections
    ORDER BY connections DESC
    LIMIT 5
""")

Getting Started¶

Installation - Install GraphForge
Quick Start - Your first graph queries
Tutorial - Step-by-step learning path
Cypher Guide - Learn the query language

Documentation¶

User Guide¶

Overview - Understand GraphForge capabilities
Cypher Query Language - Complete Cypher reference
Graph Construction - Build and manipulate graphs

Datasets¶

Dataset Overview - Work with real-world datasets
LDBC - Benchmark datasets
Neo4j Examples - Learning datasets
NetworkRepository - Research networks
SNAP - Stanford network datasets

Architecture¶

Architecture Overview - System design
Storage - Data persistence
AST & Planning - Query compilation
Execution Model - Query execution

Reference¶

API Documentation - Complete API reference
OpenCypher Compatibility - Supported features
TCK Compliance - Test suite status
Changelog - Version history

Design Principles¶

Spec-driven correctness - openCypher semantics over performance
Deterministic behavior - Stable results across runs
Inspectable - Observable query plans and execution
Minimal dependencies - Keep the dependency tree small
Python-first - Optimize for Python workflows

Project Status¶

GraphForge is under active development. Current openCypher TCK compliance: 16.6% (638/3,837 scenarios).

See the Changelog for recent updates.

Contributing¶

We welcome contributions! See our Contributing Guide to get started.

License¶

MIT License - see LICENSE for details.