graphforge 0.1.0

Composable graph tooling for analysis, construction, and refinement

GraphForge

Composable graph tooling for analysis, construction, and refinement

A lightweight, embedded, openCypher-compatible graph engine for research and investigative workflows

---

Why GraphForge?

Modern data science and ML workflows increasingly produce graph-shaped data—entities and relationships extracted from text, tables, and LLM outputs. Yet practitioners face a painful choice:

	NetworkX	Production DBs (Neo4j, Memgraph)
Durability	Manual serialization only	✓ Persistent
Query language	None	Cypher
Operational overhead	Minimal	High (services, config)
Notebook-friendly	✓	✗
Iterative analysis	✓	Poor

GraphForge fills the gap—embedded, durable, and declarative—without running external services.

We are not building a database for applications.
We are building a graph execution environment for thinking.

---

Features

• Embedded & local-first — No server, no daemon. Runs entirely inside your Python process.
• openCypher subset — Declarative pattern matching with semantic correctness validated against the TCK.
• Graph-native execution — Adjacency-based traversal, not relational joins.
• Durable but disposable — Persist graphs across restarts; treat them as analytical artifacts.
• Python-first — Designed for notebooks, scripts, and agentic pipelines.

Planned v1 Scope

• MATCH (nodes, relationships, directionality)
• WHERE (boolean logic, comparisons, property access)
• RETURN, LIMIT, SKIP
• Node and relationship materialization
• Optional Pydantic-backed data models for validation

---

Installation

# Using uv (recommended)
uv add graphforge

# Using pip
pip install graphforge

Requirements: Python 3.10+

---

Quick Start

from graphforge import GraphForge

# Create a graph (API in development)
db = GraphForge("my-graph.db")

# Execute openCypher queries
rows = db.execute("""
  MATCH (n:Person)
  WHERE n.age > 30
  RETURN n.name
  LIMIT 5
""")

Note: GraphForge is early in development. The core API and storage layer are being built out per the requirements document.

---

Design Principles

• Spec-driven correctness — openCypher semantics over performance.
• Deterministic & reproducible — Stable behavior across runs.
• Inspectable — Query plans, storage layout, and execution behavior are observable.
• Replaceable internals — Minimal operational overhead, stable APIs.

---

Links

• Requirements document — Full scope, TCK strategy, and design rationale
• openCypher AST spec
• Runtime value model

---

License

MIT © David Spencer