neo4j-helpers 0.1.0

Lightweight helpers for running local Neo4j instances and scripting bulk Cypher workloads.

neo4j-helpers

Utilities for scripting Neo4j workflows from Python. The package bundles a handful of small helpers you can mix and match:

• Neo4jDatabaseHelper – thin wrapper around the official driver for common admin tasks
• CypherDispatcher – thread-based worker pool for running a Cypher statement concurrently
• Neo4jLocalTools – utilities for working with a locally installed Neo4j distribution
• BvecReader / IvecReader – streaming readers for ANN vector datasets (Faiss .bvecs/.ivecs)

The project currently targets Python 3.10+ and the Neo4j Python driver >= 5.0.

Installation

pip install neo4j-helpers

Or, for local development inside this repository:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e '.[dev]'

Quickstart

from neo4j_helpers import (
    CypherDispatcher,
    Neo4jDatabaseHelper,
    Neo4jInfo,
    Neo4jLocalTools,
)

neo_info = Neo4jInfo.GetDefaultLocalHost()
helper = Neo4jDatabaseHelper(neo_info)

if not helper.is_db_exists():
    helper.create_db()

with CypherDispatcher(neo_info, "CREATE (:Person {name: $name})") as dispatcher:
    for name in ["Ada", "Grace", "Linus"]:
        dispatcher.submit({"name": name})

local = Neo4jLocalTools("~/neo4j/instances/local")
local.start_server(wait=True)
# ...
local.stop_server(wait=True)

Vector dataset helpers stream binary records without loading entire files:

from neo4j_helpers import BvecReader

reader = BvecReader("~/bigann/bigann_base.bvecs.gz")
for vector in reader.iter_vectors(limit=2):
    print(len(vector), vector[:8])

Development Workflow

• Run the test suite with python3 -m pytest
• Linting relies on the standard library venv + pip install -e '.[dev]'
• Temporary environment variables used in examples:

  export VECTOR_FILTER_BVECS_PATH='~/bigann/bigann_base.bvecs.gz'
  export VECTOR_FILTER_IMPORT_DIR='~/neo4j/import/sample-dbs/vector-filter-v2'
  export NEO4J_HOME='~/neo4j/instances/local/'
  

Releasing

1. Update pyproject.toml and src/neo4j_helpers/__init__.py with the next version.
2. Build the distribution artifacts:

   python -m build
   

3. Inspect the generated dist/ archives (optional but recommended).
4. Upload to PyPI (or TestPyPI first):

   twine upload dist/*
   

If you are publishing to TestPyPI, pass --repository testpypi to twine upload.

Internal Reference Notes

These notes remain from the original utilities project – feel free to move them elsewhere if they no longer belong in the public README.

• Authenticate with Google Cloud:

  gcloud auth application-default login --no-launch-browser
  gcloud compute config-ssh
  

• JVM tuning for vector imports (requires a JDK providing incubator vectors):

  export JVM_OPTS="--add-modules jdk.incubator.vector"
  

• Sample inline Neo4j admin import command:

  /opt/neo4j/bin/neo4j-admin database import full \
      --schema=/mnt/neo4j-import/sample-dbs/vector-filter-v2/vector-filter-schema.cypher \
      --nodes=CHUNK=/mnt/neo4j-import/sample-dbs/vector-filter-v2/chunks.csv \
      --nodes=DOCUMENT=/mnt/neo4j-import/sample-dbs/vector-filter-v2/documents.csv \
      --nodes=PROJECT=/mnt/neo4j-import/sample-dbs/vector-filter-v2/projects.csv \
      --nodes=AUTHOR=/mnt/neo4j-import/sample-dbs/vector-filter-v2/authors.csv \
      --relationships=PART_OF=/mnt/neo4j-import/sample-dbs/vector-filter-v2/chunk-doc.csv \
      --relationships=WRITTEN_FOR=/mnt/neo4j-import/sample-dbs/vector-filter-v2/doc-proj.csv \
      --relationships=WRITTEN_BY=/mnt/neo4j-import/sample-dbs/vector-filter-v2/doc-author.csv \
      --overwrite-destination=true \
      --report-file=/mnt/neo4j-import/sample-dbs/vector-filter-v2/report.txt \
      --verbose \
      vector.filter.v2