### Verify Example Scripts

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/sessions/session-2026-01-31-documentation.md

These commands were used to test the functionality of the provided Python example scripts. Ensure NetworkX is installed for the migration example.

```bash
python examples/01_social_network.py    # ✅ Works
```

```bash
python examples/02_knowledge_graph.py   # ✅ Works
```

```bash
python examples/03_data_lineage.py      # ✅ Works
```

```bash
python examples/04_citation_network.py  # ✅ Works
```

```bash
python examples/05_migration_from_networkx.py  # ✅ Works (requires NetworkX)
```

--------------------------------

### Initial Development Setup

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/workflow.md

Clone the repository, install dependencies using uv, and set up pre-commit hooks for code quality checks.

```bash
git clone https://github.com/DecisionNerd/graphforge.git
cd graphforge

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync --all-extras

# Install pre-commit hooks (recommended)
uv run pre-commit install

# Run tests to verify setup
uv run pytest
```

--------------------------------

### Run Example Script

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/releases/phase-1-complete.md

Execute the basic usage example script. This demonstrates how to use the graph store and verifies its functionality.

```bash
# Run example
PYTHONPATH=src python examples/basic_usage.py
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/testing.md

Commands to install all development dependencies, including optional extras. Use `uv sync --all-extras` for faster synchronization or `pip install -e "[dev]"` for standard pip installation.

```bash
uv sync --all-extras
# or
pip install -e ".[dev]"
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/decisionnerd/graphforge/blob/main/CONTRIBUTING.md

Install project dependencies using uv (recommended) or pip. The `.[dev]` extra installs development-specific dependencies.

```bash
# Using uv (recommended)
uv sync --all-extras

# Or using pip
pip install -e ".[dev]"
```

--------------------------------

### Install Graphforge from Source

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/getting-started/installation.md

Clone the repository and install development dependencies to build Graphforge from its source code.

```bash
git clone https://github.com/DecisionNerd/graphforge.git
cd graphforge
uv sync --dev        # installs dev + test dependencies
make pre-push        # verify everything passes locally
```

--------------------------------

### Cypher Query with WITH Clause at Query Start (Working Example)

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/phase-1a-completion-report.md

Demonstrates a valid Cypher query where the WITH clause is used at the beginning, successfully returning a list.

```cypher
WITH [1, 2, 3] AS list RETURN list
# Returns: [{'list': CypherList([1, 2, 3])}]
```

--------------------------------

### Install Graphforge using uv

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/getting-started/installation.md

Use this command to install the Graphforge package using uv, the recommended package installer.

```bash
uv add graphforge
```

--------------------------------

### Verify Package Installation

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/release-process.md

Install the released package in a fresh environment using uv and run a quick test to confirm basic functionality.

```bash
uv venv test-env
source test-env/bin/activate
uv pip install graphforge==0.2.0
python -c "from graphforge import GraphForge; print(GraphForge.__name__)"
```

--------------------------------

### Complete E-Commerce Agent Example

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/use-cases/agent-tool-recall.md

This example demonstrates building a tool graph for an e-commerce agent, simulating agent interactions, and using GraphForge to find and chain tools based on user intent. It covers tool creation, capability mapping, and sequential tool execution.

```python
from graphforge import GraphForge

# --- Build tool graph ---
db = GraphForge("ecommerce-tools.db")

db.execute("""
    CREATE (search:Tool {name: 'search_products', description: 'Search product catalog',
                         endpoint: 'catalog/search', version: '3.0', deprecated: false,
                         cost_per_call: 2, latency_ms: 120})
    CREATE (check:Tool  {name: 'check_inventory',  description: 'Check stock levels',
                         endpoint: 'inventory/check', version: '2.1', deprecated: false,
                         cost_per_call: 1, latency_ms: 45})
    CREATE (order:Tool  {name: 'place_order',       description: 'Place a customer order',
                         endpoint: 'orders/create', version: '1.5', deprecated: false,
                         cost_per_call: 5, latency_ms: 200})

    CREATE (search)-[:CAN_DO]->(:Capability {name: 'find_products', category: 'read'})
    CREATE (check)-[:CAN_DO]->(:Capability {name: 'query_stock', category: 'read'})
    CREATE (order)-[:CAN_DO]->(:Capability {name: 'purchase', category: 'write'})

    CREATE (search)-[:PRODUCES]->(:DataModel {name: 'Product'})
    CREATE (check)-[:REQUIRES]->(:DataModel {name: 'Product'})
    CREATE (order)-[:REQUIRES]->(:DataModel {name: 'Product'})

    CREATE (order)-[:DEPENDS_ON {type: 'required'}]->(check)
""")

registry = ToolRegistry(db=db)

# --- Agent loop ---
available_data = []
intent = "I want to buy a laptop"

# 1. Find tools for intent
candidates = registry.find_by_capability("find_products")
print("Candidates:", [t['name'] for t in candidates])
# ['search_products']

# 2. Agent calls search_products → gets Product back
available_data.append('Product')

# 3. What can we do now?
follow_ups = registry.next_tools('search_products')
print("Next:", [t['name'] for t in follow_ups])
# ['check_inventory', 'place_order']

# 4. check_inventory first (place_order depends on it)
# 5. place_order to complete purchase

```

--------------------------------

### Example Unit Test for Node Creation

Source: https://github.com/decisionnerd/graphforge/blob/main/tests/README.md

An example of a unit test for node creation. It demonstrates arranging test data, performing an action (getting a property), and asserting the expected outcome.

```python
import pytest

@pytest.mark.unit
def test_node_creation():
    """Test that nodes can be created with labels and properties."""
    # Arrange
    node = Node(labels={"Person"}, properties={"name": "Alice"})

    # Act
    result = node.get_property("name")

    # Assert
    assert result == "Alice"
```

--------------------------------

### Install Dev Dependencies and Run Tests

Source: https://github.com/decisionnerd/graphforge/blob/main/tests/README.md

Install development dependencies using uv sync and run all tests with pytest. This is a quick start for setting up and executing the test suite.

```bash
uv sync --all-extras

pytest
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/testing-setup-complete.md

Installs all project dependencies, including optional extras, using uv. This command is typically run after cloning the repository to set up the development environment.

```bash
uv sync --all-extras
```

--------------------------------

### Install and Run Pre-commit Hooks

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/sessions/session-2026-01-31-cicd-infrastructure.md

Commands to install, run, and update pre-commit hooks for local code validation.

```bash
# Install
uv run pre-commit install

# Run manually
uv run pre-commit run --all-files

# Update hooks
uv run pre-commit autoupdate
```

--------------------------------

### Install GraphForge with uv or pip

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/getting-started/tutorial.md

Use uv or pip to install the GraphForge library. uv is recommended for faster dependency management.

```bash
# Using uv
uv add graphforge
```

```bash
# Using pip
pip install graphforge
```

--------------------------------

### Installing GraphForge with Development Dependencies

Source: https://github.com/decisionnerd/graphforge/blob/main/README.md

Command to install GraphForge along with development dependencies using uv.

```bash
# Install with dev dependencies
uv sync --dev
```

--------------------------------

### Create DURATION from Components (Examples)

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/05-data-types.md

Examples of creating DURATION values from component maps.

```cypher
RETURN duration({days: 7}) AS oneWeek
```

```cypher
RETURN duration({hours: -3}) AS negativeThreeHours
```

--------------------------------

### Install GraphForge

Source: https://github.com/decisionnerd/graphforge/blob/main/README.md

Install GraphForge using pip or uv. Requires Python 3.10-3.14.

```bash
pip install graphforge
# or
uv add graphforge
```

--------------------------------

### Verify Installation with Pytest

Source: https://github.com/decisionnerd/graphforge/blob/main/CONTRIBUTING.md

Run unit tests using pytest to verify the installation.

```bash
pytest -m unit
```

--------------------------------

### Define Beta Release Version

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/release-process.md

Example of defining a beta version string.

```bash
version = "0.3.0-beta.1"
```

--------------------------------

### Install Zstandard for LDBC Datasets

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/getting-started/installation.md

Install the zstandard package if you need Zstandard compression for LDBC .tar.zst datasets.

```bash
pip install zstandard
```

--------------------------------

### Verify GraphForge Installation

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/getting-started/tutorial.md

Run this Python code to confirm that GraphForge has been installed correctly.

```python
from graphforge import GraphForge
print("GraphForge installed successfully!")
```

--------------------------------

### Install Graphforge using pip

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/getting-started/installation.md

Use this command to install the Graphforge package using pip.

```bash
pip install graphforge
```

--------------------------------

### OpenCypher Basic STRING Examples

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/05-data-types.md

Provides examples of basic string literals and multi-line strings in OpenCypher. Strings are UTF-8 encoded and case-sensitive.

```cypher
RETURN 'Alice' AS name
```

```cypher
RETURN "Hello, World!" AS greeting
```

```cypher
RETURN 'Multi\nLine\nString' AS multiline
```

--------------------------------

### Define Release Candidate Version

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/release-process.md

Example of defining a release candidate version string.

```bash
version = "0.3.0-rc.1"
```

--------------------------------

### OpenCypher MAP Property Access Examples

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/05-data-types.md

Provides examples of accessing map properties using both dot and bracket notation, including handling non-existent keys.

```cypher
WITH {name: 'Alice', age: 30, city: 'NYC'} AS person
RETURN person.name AS name,            // 'Alice'
       person['age'] AS age,           // 30
       person.country AS missing       // null (non-existent key)

```

--------------------------------

### OpenCypher Basic MAP Examples

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/05-data-types.md

Illustrates the creation and return of basic maps with key-value pairs.

```cypher
RETURN {name: 'Alice', age: 30, city: 'NYC'} AS person

```

--------------------------------

### Cypher Query Examples for WITH Clause at Query Start

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/v0.4-revised-plan.md

These examples demonstrate failing Cypher queries that attempt to use the WITH clause at the beginning of a query, which is currently not supported.

```cypher
WITH [1, 2, 3] AS list
RETURN list[0]
```

```cypher
WITH 1 AS x, 2 AS y
RETURN x + y
```

```cypher
WITH {name: 'Alice'} AS person
MATCH (n:Person {name: person.name})
RETURN n
```

--------------------------------

### Verify Publication

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/release-process.md

Wait for the publish workflow to complete, check PyPI for the new version, and test the installation.

```bash
gh run list --workflow=publish.yaml --limit 1
open https://pypi.org/project/graphforge/
pip install graphforge==0.2.0
```

--------------------------------

### String Matching Operators Example

Source: https://github.com/decisionnerd/graphforge/blob/main/CHANGELOG.md

Provides an example of using string matching operators like STARTS WITH, ENDS WITH, and CONTAINS for pattern matching in string properties.

```cypher
MATCH (n) WHERE n.email ENDS WITH '@example.com'
```

--------------------------------

### Semantic Versioning Example

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/release-process.md

Illustrates the MAJOR.MINOR.PATCH format for versioning, indicating the purpose of each component.

```plaintext
MAJOR.MINOR.PATCH

Example: 1.2.3
         │ │ └─── PATCH: Backwards-compatible bug fixes
         │ └───── MINOR: New features, backwards-compatible
         └─────── MAJOR: Breaking changes
```

--------------------------------

### List Slicing Examples

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/implementation-status/operators.md

Demonstrates list slicing with different start and end points, including open-ended slices. Slicing uses a start..end notation.

```cypher
RETURN [1, 2, 3, 4, 5][1..3]
```

```cypher
RETURN [1, 2, 3][..2]
```

```cypher
RETURN [1, 2, 3][1..]
```

--------------------------------

### Start Phase 2 Development

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/releases/phase-1-complete.md

Instructions to begin Phase 2, which involves parser and AST development. Refer to the roadmap for detailed tasks.

```bash
# Start Phase 2
# See docs/roadmap.md section "Week 3-4"
```

--------------------------------

### View Full Architecture Overview

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/documentation-update-summary.md

Use this command to view the complete architecture overview of the system.

```bash
cat docs/architecture-overview.md
```

--------------------------------

### List Slicing Example

Source: https://github.com/decisionnerd/graphforge/blob/main/CHANGELOG.md

Demonstrates list slicing with start and end indices, including open-ended slicing.

```cypher
RETURN [1, 2, 3, 4, 5][1..3]
```

--------------------------------

### Migrating from NetworkX Example

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/sessions/session-2026-01-31-documentation.md

Provides a side-by-side comparison of common graph operations between NetworkX and GraphForge, highlighting key differences and trade-offs. Useful for users considering migration or choosing between the libraries.

```python
# This example demonstrates conceptual differences and common operations.
# Actual code would involve importing both libraries and performing equivalent tasks.

# --- Conceptual Comparison: NetworkX vs. GraphForge ---

# 1. Graph Initialization
# NetworkX:
# import networkx as nx
# nx_graph = nx.Graph()

# GraphForge:
# from graphforge import GraphForge
# gf_graph = GraphForge()

# 2. Adding Nodes
# NetworkX (nodes can be any hashable object, attributes are dicts):
# nx_graph.add_node(1, label='Person', city='New York')
# nx_graph.add_node('Alice', label='Person', city='New York')

# GraphForge (nodes have labels and properties):
# gf_graph.create_node('Person', {'name': 'Alice', 'city': 'New York'})
# gf_graph.create_node('Company', {'name': 'TechCorp', 'industry': 'Technology'})

# 3. Adding Edges (Relationships)
# NetworkX (edges connect nodes, attributes are dicts):
# nx_graph.add_edge(1, 2, relationship='FRIENDS', since=2020)
# nx_graph.add_edge('Alice', 'Bob', relationship='FRIENDS', since=2020)

# GraphForge (relationships connect nodes, have types and properties):
# gf_graph.create_relationship(node_alice_ref, node_bob_ref, 'FRIENDS', {'since': 2020})

# 4. Querying Nodes
# NetworkX (iterating or using filters):
# for node, data in nx_graph.nodes(data=True):
#     if data.get('city') == 'New York':
#         print(node, data)

# GraphForge (using Cypher-like queries):
# query = "MATCH (p:Person {city: 'New York'}) RETURN p.name"
# results = gf_graph.execute(query)
# for row in results:
#     print(row['name'])

# 5. Querying Edges
# NetworkX:
# for u, v, data in nx_graph.edges(data=True):
#     if data.get('relationship') == 'FRIENDS':
#         print(f"{u} is friends with {v}")

# GraphForge:
# query = "MATCH (p1:Person)-[r:FRIENDS]->(p2:Person) RETURN p1.name, p2.name"
# results = gf_graph.execute(query)
# for row in results:
#     print(f"{row['p1.name']} is friends with {row['p2.name']}")

# 6. Graph Algorithms (e.g., PageRank)
# NetworkX:
# import networkx.algorithms.centrality as centrality
# pagerank = centrality.pagerank(nx_graph)

# GraphForge (often integrated into Cypher or specific methods):
# query = "CALL algo.pageRank(null, null, {defaultValue: 0.15}) YIELD node, score RETURN node.name, score ORDER BY score DESC"
# results = gf_graph.execute(query)

# --- Key Differences & Trade-offs ---

# NetworkX:
# - Pros: Mature, extensive algorithms, flexible node/edge representation, pure Python.
# - Cons: Can be slower for very large graphs, less suited for complex relationship patterns, no native graph database query language.

# GraphForge:
# - Pros: Optimized for graph traversal and complex pattern matching (Cypher-like queries), potentially better performance for large, connected graphs, designed for graph database interactions.
# - Cons: Newer library, algorithm support might be less extensive than NetworkX, different data modeling approach (labels/properties vs. arbitrary attributes).

# --- When to Choose Which ---

# Choose NetworkX when:
# - You need a wide array of graph algorithms readily available.
# - Your graph structure is relatively simple or doesn't involve deep, complex relationships.
# - You prefer a pure Python, object-oriented approach.
# - You are working with moderately sized graphs.

# Choose GraphForge when:
# - You need to perform complex pattern matching and traversals efficiently.
# - Your data naturally fits a labeled property graph model.
# - You are interacting with or migrating towards a graph database.
# - Performance on large, highly connected graphs is critical.

# Interoperability (Future Feature):
# The goal is to allow seamless conversion between GraphForge and NetworkX objects in the future.

# Example of closing GraphForge connection:
# gf_graph.close()

```

--------------------------------

### Get n-Hop Neighborhood of an Entity

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/use-cases/llm-workflows.md

Retrieve entities within a specified number of hops from a starting entity. This is useful for building context for LLMs.

```python
def get_neighbourhood(db, canonical: str, hops: int = 2) -> list[dict]:
    """Return all entities reachable within `hops` steps from `canonical`. """
    rows = db.execute(
        "MATCH (seed:Entity {canonical: $canonical})-[r*1.." + str(hops) + "]-(neighbour:Entity) "
        "WHERE neighbour.canonical <> $canonical "
        "RETURN DISTINCT "
        "    neighbour.name AS name, "
        "    neighbour.canonical AS canonical, "
        "    labels(neighbour)  AS labels",
        {"canonical": canonical},
    )
    return [
        {
            "name":      row["name"].value,
            "canonical": row["canonical"].value,
            "labels":    [lbl.value for lbl in row["labels"].value],
        }
        for row in rows
    ]


neighbours = get_neighbourhood(db, "graphforge", hops=2)
# [{'name': 'Alice Chen', 'canonical': 'alice-chen', 'labels': ['Entity', 'Person']}, ...]
```

--------------------------------

### Full Release Checklist

Source: https://github.com/decisionnerd/graphforge/blob/main/RELEASING.md

Follow these steps to create a new release: ensure main is clean, bump the version, update the changelog, commit, push, tag, and create a GitHub release.

```bash
git checkout main
git pull
pytest tests/
python scripts/bump_version.py minor
git add pyproject.toml CHANGELOG.md
git commit -m "chore(release): bump version to X.Y.Z"
git push origin main
git tag -a vX.Y.Z -m "Release version X.Y.Z"
git push origin vX.Y.Z
gh release create vX.Y.Z --title "GraphForge vX.Y.Z" --notes "See CHANGELOG.md"
open https://pypi.org/project/graphforge/
```

--------------------------------

### Cypher Query Before WITH Clause Implementation

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/phase-1a-completion-report.md

This example shows a Cypher query that would fail to parse before the 'WITH at query start' feature was implemented, due to the parser not expecting 'WITH' in that context.

```cypher
WITH [1, 2, 3] AS list RETURN list
# Error: No terminal matches 'W' in the current parser context
```

--------------------------------

### List Slicing: Extract Sub-lists

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/03-operators.md

Extract a portion of a list using range-based slicing with inclusive start and exclusive end indices. Supports positive, negative, and open-ended ranges. Useful for getting segments of data, like middle elements of a path.

```cypher
// Range slice
RETURN [1, 2, 3, 4, 5][1..3] AS result    // [2, 3]

// From start
RETURN [1, 2, 3, 4, 5][2..] AS result     // [3, 4, 5]

// To end
RETURN [1, 2, 3, 4, 5][..3] AS result     // [1, 2, 3]

// Full slice (copy)
RETURN [1, 2, 3][..] AS result            // [1, 2, 3]

// Negative indices
RETURN [1, 2, 3, 4, 5][-3..] AS result    // [3, 4, 5]
RETURN [1, 2, 3, 4, 5][..-2] AS result    // [1, 2, 3]

// With path functions
MATCH path = (a)-[:KNOWS*]-(b)
RETURN nodes(path)[1..-1] AS middle_nodes
```

```cypher
RETURN NULL[1..3]                         // NULL
RETURN [1, 2, 3][NULL..2]                 // NULL
RETURN [][1..3]                           // []
```

--------------------------------

### View Implementation Plan (Phase 5)

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/documentation-update-summary.md

Use this command to view the implementation plan, specifically focusing on Phase 5, by grepping the roadmap document.

```bash
cat docs/project-status-and-roadmap.md | grep -A 50 "Phase 5"
```

--------------------------------

### CLI Usage for Listing and Loading Datasets

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/datasets/neo4j-examples.md

Command-line interface commands for interacting with Neo4j example datasets. The first command lists available datasets from the 'neo4j-examples' source, and the second loads the 'neo4j-movie-graph' dataset.

```bash
# List Neo4j example datasets
graphforge list-datasets --source neo4j-examples

# Load movie graph
graphforge load-dataset neo4j-movie-graph
```

--------------------------------

### Instantiate GraphForge with SQLite Backend

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/architecture/storage.md

Initialize the GraphForge with a specified database file and 'sqlite' backend. This allows for easy switching to other backends if needed.

```python
db = GraphForge("graph.db", backend="sqlite")
```

--------------------------------

### STARTS WITH Operator

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/03-operators.md

Test if a string starts with a specific prefix using the STARTS WITH operator. This operation is case-sensitive. It returns NULL if either operand is NULL.

```cypher
MATCH (p:Person)
WHERE p.name STARTS WITH 'A'
RETURN p.name
```

```cypher
MATCH (p:Person)
WHERE p.email STARTS WITH 'admin'
RETURN p.name, p.email
```

```cypher
MATCH (product:Product)
WHERE product.sku STARTS WITH 'ELEC'
RETURN product.name
```

```cypher
RETURN 'Hello' STARTS WITH ''    // true
```

--------------------------------

### Initialize GraphForge Database Connection

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/getting-started/tutorial.md

Sets up a connection to a GraphForge database file, preparing it for subsequent operations.

```python
from graphforge import GraphForge

db = GraphForge("citation-network.db")
```

--------------------------------

### Basic Usage: Loading a Dataset

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/datasets/networkrepository.md

Demonstrates the basic usage of creating a GraphForge instance and loading a dataset. Requires GraphForge and load_dataset.

```python
from graphforge import GraphForge
from graphforge.datasets import load_dataset

# Create a GraphForge instance
gf = GraphForge()
```

--------------------------------

### Unit Test Example

Source: https://github.com/decisionnerd/graphforge/blob/main/CONTRIBUTING.md

Example of a unit test using pytest, marking it with `@pytest.mark.unit`.

```python
import pytest

@pytest.mark.unit
def test_node_creation():
    node = Node(labels={"Person"})
    assert "Person" in node.labels
```

--------------------------------

### Run LLM Workflow Pipeline

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/use-cases/llm-workflows.md

Example of how to instantiate GraphForge, define a corpus of documents, ingest them using the ingest_documents function, and then print a summary of the resulting knowledge graph.

```python
if __name__ == "__main__":
    db = GraphForge()   # in-memory for this example

    corpus = [
        {
            "id":    "doc-001",
            "title": "About GraphForge",
            "text":  "Alice Chen at DecisionNerd created GraphForge.",
        },
        {
            "id":    "doc-002",
            "title": "Community update",
            "text":  "Bob Lim uses GraphForge in his research pipeline.",
        },
        # Re-processing doc-001 should not create duplicates
        {
            "id":    "doc-001",
            "title": "About GraphForge (updated)",
            "text":  "Alice Chen at DecisionNerd created GraphForge.",
        },
    ]

    ingest_documents(db, corpus)
    print(summarise_graph(db))
```

--------------------------------

### Loading Datasets with GraphForge

Source: https://github.com/decisionnerd/graphforge/blob/main/README.md

Shows how to load pre-registered datasets into a GraphForge instance and list available datasets.

```python
from graphforge import GraphForge
from graphforge.datasets import load_dataset, list_datasets

db = GraphForge()

# Load any pre-registered dataset (auto-downloads and caches)
load_dataset(db, "snap-ego-facebook")   # Facebook ego networks (SNAP)
load_dataset(db, "ldbc-snb-sf0.1")      # Social network benchmark (LDBC)
load_dataset(db, "netrepo-karate")      # Karate club (NetworkRepository)

# Browse available datasets
for ds in list_datasets(source="snap")[:3]:
    print(f"{ds.name}: {ds.nodes:,} nodes, {ds.edges:,} edges")

# Analyze immediately
results = db.execute("""
    MATCH (n)-[r]->()
    RETURN n.id AS user, count(r) AS degree
    ORDER BY degree DESC LIMIT 5
""")
```

--------------------------------

### Cypher Query Example

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/architecture/ast-and-planning.md

This is an example of a Cypher query that will be parsed into an AST and then lowered into a logical plan.

```cypher
MATCH (a:Person)-[:KNOWS]->(b:Person)
WHERE a.age > 30 AND b.city = "Lehi"
RETURN b.name AS name
LIMIT 10
```

--------------------------------

### Verify Graphforge Installation

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/getting-started/installation.md

Run this Python code to verify that Graphforge has been installed correctly and to check its version.

```python
import graphforge
print(graphforge.__version__)   # 0.3.9
```

--------------------------------

### Initialize GraphForge Instance

Source: https://context7.com/decisionnerd/graphforge/llms.txt

Create an in-memory or SQLite-backed graph engine. Passing a file path enables persistence. The optimizer can be disabled for debugging.

```python
from graphforge import GraphForge

# In-memory graph — fast, no disk I/O
db = GraphForge()

# Persistent graph — saved to SQLite on close()
db = GraphForge("research.db")

# Disable optimizer (useful for debugging query plans)
db = GraphForge(enable_optimizer=False)

# Reload an existing graph
db = GraphForge("research.db")
result = db.execute("MATCH (n) RETURN count(n) AS c")
print(result[0]['c'].value)  # number of nodes from previous session
db.close()
```

--------------------------------

### Execute Version Bumping Script

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/release-process.md

Examples of how to run the version bumping script for different types of version increments.

```bash
python scripts/bump-version.py patch  # 0.1.1 → 0.1.2
```

```bash
python scripts/bump-version.py minor  # 0.1.1 → 0.2.0
```

```bash
python scripts/bump-version.py major  # 0.1.1 → 1.0.0
```

--------------------------------

### GraphForge Storage Options

Source: https://github.com/decisionnerd/graphforge/blob/main/CLAUDE.md

Illustrates how to initialize GraphForge for in-memory or persistent SQLite storage.

```python
# In-memory (fast, volatile)
gf = GraphForge()

# Persistent (SQLite backend)
gf = GraphForge("path/to/db.db")
```

--------------------------------

### Integration Test Example

Source: https://github.com/decisionnerd/graphforge/blob/main/CONTRIBUTING.md

Example of an integration test using pytest, marking it with `@pytest.mark.integration` and utilizing a database fixture.

```python
import pytest

@pytest.mark.integration
def test_query_execution(db):
    result = db.execute("MATCH (n) RETURN n")
    assert result is not None
```

--------------------------------

### List and Get Info for NetworkRepository Datasets

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/datasets/networkrepository.md

Shows how to list all available datasets and retrieve metadata for a specific NetworkRepository dataset.

```python
from graphforge.datasets import list_datasets, get_dataset_info

# List all NetworkRepository datasets
all_datasets = list_datasets()
netrepo_datasets = [d for d in all_datasets if d.startswith("netrepo-")]
print(f"Found {len(netrepo_datasets)} NetworkRepository datasets")

# Get metadata for a specific dataset
info = get_dataset_info("netrepo-karate")
print(f"Dataset: {info.name}")
print(f"Description: {info.description}")
print(f"Nodes: {info.nodes}, Edges: {info.edges}")
print(f"Category: {info.category}")
print(f"Size: {info.size_mb} MB")
```

--------------------------------

### Initialize and Execute Queries with GraphForge API

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/architecture/overview.md

Demonstrates how to initialize GraphForge for in-memory or durable graphs and execute openCypher queries. The results can be iterated over for processing.

```python
from graphforge import GraphForge

# In-memory graph (current implementation)
db = GraphForge()

# Durable graph (future: Phase 5)
db = GraphForge("analysis.db")

# Execute queries
results = db.execute("""
    MATCH (p:Person)-[:KNOWS]->(f:Person)
    WHERE p.age > 30
    RETURN p.name, f.name
    ORDER BY p.name
    LIMIT 10
""")

for row in results:
    print(row["p.name"], row["f.name"])

```

--------------------------------

### Remove Example Test File

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/testing-setup-complete.md

Deletes the example test file `tests/unit/test_example.py`. This is a placeholder and should be removed once real tests are implemented.

```bash
rm tests/unit/test_example.py
```

--------------------------------

### Define and Create 'place_order' Tool Node with Dependencies

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/use-cases/agent-tool-recall.md

Creates a 'place_order' tool node, including its parameters, capabilities, required data models, permissions, and a runtime dependency on the 'check_inventory' tool. This demonstrates how to model tool dependencies.

```python
db.execute("""
    CREATE (t:Tool {
        name: 'place_order',
        description: 'Place an order for a product',
        endpoint: 'api.orders.create',
        version: '1.5',
        cost_per_call: 5,
        latency_ms: 200,
        deprecated: false
    })
    CREATE (t)-[:HAS_PARAMETER]->(:Parameter {name: 'product_id', type: 'string', required: true})
    CREATE (t)-[:HAS_PARAMETER]->(:Parameter {name: 'quantity', type: 'int', required: true})
    CREATE (t)-[:CAN_DO]->(:Capability {name: 'purchase', category: 'write'})
    CREATE (t)-[:REQUIRES]->(:DataModel {name: 'Product'})
    CREATE (t)-[:REQUIRES]->(:DataModel {name: 'PaymentMethod'})
    CREATE (t)-[:DEPENDS_ON {type: 'required'}]->(:Tool {name: 'check_inventory'})
    CREATE (t)-[:REQUIRES_PERMISSION]->(:Role {name: 'customer', level: 1})
""")
```

--------------------------------

### STARTS WITH NULL Handling

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/03-operators.md

Demonstrates NULL handling for the STARTS WITH operator. Any NULL operand results in a NULL return value.

```cypher
RETURN 'Hello' STARTS WITH NULL  // NULL
```

```cypher
RETURN NULL STARTS WITH 'He'     // NULL
```

--------------------------------

### Initializing GraphForge Database (Python)

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/architecture/overview.md

Shows the simple, zero-configuration initialization of a GraphForge database instance, which works directly with SQLite.

```python
# Just works
db = GraphForge("analysis.db")
```

--------------------------------

### Access Specific Path Elements

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/05-data-types.md

Accesses specific nodes and relationships within a matched path using list indexing. `pathNodes[0]` gets the first node, `pathNodes[-1]` gets the last node, and `pathRels[1]` gets the second relationship.

```cypher
MATCH p = (a)-[:KNOWS*3]->(b)
WITH nodes(p) AS pathNodes, relationships(p) AS pathRels
RETURN pathNodes[0] AS start,
       pathNodes[-1] AS end,
       pathRels[1] AS secondRelationship
```

--------------------------------

### Create DURATION from ISO 8601 String (Examples)

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/05-data-types.md

Examples of creating DURATION values using ISO 8601 string representations.

```cypher
RETURN duration('P1Y2M3D') AS period
```

```cypher
RETURN duration('PT12H30M') AS timespan
```

--------------------------------

### Quick Release Script Execution

Source: https://github.com/decisionnerd/graphforge/blob/main/CONTRIBUTING.md

This bash script demonstrates the steps for a quick release, including version bumping, changelog editing, committing, tagging, and creating a GitHub release.

```bash
python scripts/bump_version.py minor
# Edit CHANGELOG.md
git commit -am "chore(release): bump version to X.Y.Z"
git push origin main
git tag -a vX.Y.Z -m "Release version X.Y.Z"
git push origin vX.Y.Z
gh release create vX.Y.Z --title "GraphForge vX.Y.Z"
```

--------------------------------

### Implement MATCH-CREATE with Git Commands

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/QUICKSTART_V0.2.md

Commands for formalizing and testing the MATCH-CREATE functionality. Focus on integration tests and edge cases, then commit and create a PR.

```bash
git checkout main && git pull
git checkout -b feature/23-match-create

# Focus on:
# - 15+ integration tests
# - Edge cases (multiple matches, no matches)
# - Documentation

# When done: commit and PR with "Closes #23"
```

--------------------------------

### Case-Insensitive STARTS WITH

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/03-operators.md

Perform a case-insensitive check if a string starts with a prefix by converting both the string and the prefix to the same case using toLower() or toUpper().

```cypher
MATCH (p:Person)
WHERE toLower(p.name) STARTS WITH 'a'
RETURN p.name
```

--------------------------------

### Load SNAP Dataset into GraphForge

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/datasets/snap.md

Demonstrates two methods to load a SNAP dataset: during GraphForge initialization or into an existing instance using `load_dataset`. The loaded dataset can be immediately queried.

```python
from graphforge import GraphForge

# Method 1: Load during initialization
gf = GraphForge.from_dataset("snap-ego-facebook")

# Method 2: Load into existing instance
gf = GraphForge()
from graphforge.datasets import load_dataset
load_dataset(gf, "snap-ego-facebook")

# Start querying immediately
results = gf.execute("""
    MATCH (n)-[r]->(m)
    RETURN count(DISTINCT n) AS users, count(r) AS connections
""")

print(f"Users: {results[0]['users'].value:,}")
print(f"Connections: {results[0]['connections'].value:,}")
```

--------------------------------

### Get Relationship Count in Path

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/changelog.md

Use the length() function to get the number of relationships in a path. For strings or lists, use size() instead.

```cypher
length(path)
```

--------------------------------

### Define and Create 'check_inventory' Tool Node

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/use-cases/agent-tool-recall.md

Initializes GraphForge and creates a 'check_inventory' tool node with its parameters, return type, capabilities, domain, required data model, and permissions. This example demonstrates how to define a tool's metadata and relationships.

```python
from graphforge import GraphForge

db = GraphForge()  # or GraphForge("tools.db") for persistence

db.execute("""
    CREATE (t:Tool {
        name: 'check_inventory',
        description: 'Check current stock levels for a product',
        endpoint: 'api.inventory.check',
        version: '2.1',
        cost_per_call: 1,
        latency_ms: 45,
        deprecated: false
    })
    CREATE (t)-[:HAS_PARAMETER]->(:Parameter {
        name: 'product_id',
        type: 'string',
        required: true,
        description: 'Unique identifier for the product'
    })
    CREATE (t)-[:RETURNS]->(:OutputType {name: 'StockLevel', type: 'int'})
    CREATE (t)-[:CAN_DO]->(:Capability {name: 'query_stock', category: 'read'})
    CREATE (t)-[:CAN_DO]->(:Capability {name: 'verify_availability', category: 'read'})
    CREATE (t)-[:BELONGS_TO_DOMAIN]->(:Domain {name: 'inventory_management'})
    CREATE (t)-[:REQUIRES]->(:DataModel {name: 'Product'})
    CREATE (t)-[:REQUIRES_PERMISSION]->(:Role {name: 'customer', level: 1})
""")
```

--------------------------------

### Invalid Property Storage Examples

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/05-data-types.md

Shows examples of attempting to store unsupported data types as properties, such as heterogeneous lists, maps, and graph elements.

```cypher
// Heterogeneous list - ERROR
CREATE (p:Person {data: [1, 'hello', true]})  // ERROR: Unsupported property value type

// Map - ERROR
CREATE (p:Person {metadata: {key: 'value'}})  // ERROR: Cannot store MAP directly

// Node/Relationship - ERROR
CREATE (p:Person {friend: otherNode})  // ERROR: Cannot store nodes as properties
```

--------------------------------

### Create Nodes and Save Graph

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/getting-started/tutorial.md

Demonstrates creating nodes in a graph database and then closing the database to save changes to disk.

```python
db.execute("CREATE (p:Person {name: 'Alice', age: 30})")
db.execute("CREATE (p:Person {name: 'Bob', age: 25})")

# Save to disk
db.close()
```

--------------------------------

### Example Workflow for PR Merging and Release

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/release-strategy.md

Demonstrates the typical workflow for a Pull Request from creation to being included in a release, including automated label and milestone management.

```bash
# 1. PR is created
gh pr create --label "release:minor"

# 2. PR is merged
# GitHub Action automatically adds "release:pending"

# 3. When release is created
# GitHub Action automatically:
#   - Removes "release:pending"
#   - Adds "release:included"
#   - Adds milestone "v0.2.0"
```

--------------------------------

### Conventional Commits Example: Fix

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/workflow.md

An example of a commit message following the Conventional Commits specification for a bug fix. It details the type, scope, subject, and the issue it resolves.

```git
fix(executor): correct column aliasing in RETURN projection

Fixed bug where RETURN aliases were ignored, causing
integration test failures.

Fixes #124
```

--------------------------------

### Load and Explore LDBC Dataset in Python

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/datasets/ldbc.md

Demonstrates how to load a small LDBC dataset using GraphForge and execute a basic query to explore the social network. Ensure the 'graphforge' library is installed.

```python
from graphforge import GraphForge
from graphforge.datasets import load_dataset

# Load a small LDBC dataset
gf = GraphForge()
load_dataset(gf, "ldbc-snb-sf001")

# Explore the social network
results = gf.execute("""
    MATCH (p:Person)-[:KNOWS]->(friend:Person)
    RETURN p.firstName, p.lastName, count(friend) AS friendCount
    ORDER BY friendCount DESC
    LIMIT 10
")
```

--------------------------------

### Conventional Commits Example: Feature

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/workflow.md

An example of a commit message following the Conventional Commits specification for a new feature. It includes type, scope, subject, body, and footer.

```git
feat(executor): implement WITH clause for query chaining

Add support for WITH clause enabling multi-part queries.
Includes projection, filtering, sorting, and pagination.

Fixes #123
```

--------------------------------

### Load Dataset using GraphForge convenience method

Source: https://github.com/decisionnerd/graphforge/blob/main/CHANGELOG.md

Use the `GraphForge.from_dataset()` method for a convenient way to load datasets. This method handles automatic dataset download, caching, and registration.

```python
gf = GraphForge.from_dataset("snap-ego-facebook")
```

--------------------------------

### View Available Make Targets

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/contributing.md

View all available targets in the Makefile by running `make help`.

```bash
# View all available targets
make help
```

--------------------------------

### openCypher Writing Clause Examples

Source: https://github.com/decisionnerd/graphforge/blob/main/README.md

Provides examples of common openCypher clauses for writing data, including CREATE, MERGE, SET, REMOVE, DELETE, and DETACH DELETE.

```cypher
-- Writing
CREATE (n:Person {name: 'Alice'})
MERGE (n:Person {name: 'Alice'})
SET n.age = 30
REMOVE n.temp
DELETE n
DETACH DELETE n
```

--------------------------------

### Generate a list of integers

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/opencypher-features/02-functions.md

The `range()` function generates a list of integers starting from `start`, up to and including `end`. An optional `step` parameter can be provided to increment by values other than 1.

```cypher
RETURN range(0, 10) AS result
// Returns: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
```

```cypher
RETURN range(0, 10, 2) AS result
// Returns: [0, 2, 4, 6, 8, 10]
```

```cypher
RETURN range(10, 0, -1) AS result
// Returns: [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
```

--------------------------------

### Start New Feature Branch

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/development/v0.2-plan-summary.md

Use this command to start working on a new feature, ensuring you pull the latest changes from main and create a descriptive branch name.

```bash
git checkout main
git pull origin main
git checkout -b feature/20-unwind-clause
```

--------------------------------

### Run All Tests

Source: https://github.com/decisionnerd/graphforge/blob/main/CONTRIBUTING.md

Execute all tests using the `make test` command. For full validation, use `make pre-push`.

```bash
make test
```

--------------------------------

### Initialize and Query GraphForge

Source: https://github.com/decisionnerd/graphforge/blob/main/docs/reference/feature-graph-queries.md

Opens the feature graph database and executes a basic query to list features. Ensure the graph database is built before running.

```python
from graphforge import GraphForge

# Open the feature graph
db = GraphForge('docs/feature-graph.db')

# Run queries
results = db.execute("""
    MATCH (f:Feature)
    RETURN f.name, f.category, f.subcategory
    LIMIT 10
""")

for row in results:
    print(f"{row['f.name'].value} ({row['f.category'].value})")
```