The problem

Property graphs can stay queryable while silently losing required properties, cardinalities, relationship direction, or the answers an application depends on. Those failures are difficult to review consistently because schema expectations, business questions, and drift thresholds usually live in separate tools and ad hoc queries. GraphCheck turns those expectations into version-controlled YAML and produces deterministic, evidence-backed JSON and offline HTML reports for local runs and CI.

Quickstart

For complete setup, credential, authoring, redaction, baseline, and configuration instructions, see the full user guide.

GraphCheck requires Python 3.12 or 3.13 and a supported Neo4j server. See the compatibility matrix for the tested Neo4j and Cypher versions.

Install the published CLI and scaffold a project:

pip install graphcheck

mkdir graph-health
cd graph-health
graphcheck init

Install either optional add-on separately if you need its commands:

pip install "graphcheck[generate]"
pip install "graphcheck[mcp]"

The generate add-on enables AI-assisted check authoring, while mcp enables the MCP server.

graphcheck init creates the following local project:

graphcheck.yml          Project paths and runtime settings
profiles.yml            Neo4j connection profiles; ignored by Git
checks/example.yml      Example check suite
.graphcheck/            Baselines, run history, JSON, and HTML reports

Edit profiles.yml with the URI, database, and credential for your Neo4j instance. Enterprise and Developer deployments must use a user assigned only Neo4j's built-in reader role plus the automatic PUBLIC role; GraphCheck rejects missing, additional, or custom roles. Community deployments cannot enforce read-only roles, so GraphCheck instead rejects every customer-authored query unless Neo4j plans it as read-only.

Verify the connection, replace the generated suite with the baseline-free example below, and run it:

graphcheck debug
graphcheck run

Each prepared run writes immutable history plus convenient latest copies:

.graphcheck/runs/<run-id>/results.json
.graphcheck/runs/<run-id>/report.html
.graphcheck/runs/latest/results.json
.graphcheck/runs/latest/report.html

The HTML report is self-contained and works offline. Exit codes are stable for CI: 0 means all executed checks passed, 1 means an error-severity finding or execution error, 2 means a warning or incomplete evaluation, and 3 means the run could not be prepared or completed.

For development, use the locked environment instead:

uv sync --group dev
uv run graphcheck --version

Example

Replace checks/example.yml with a suite that matches labels in your graph:

suite: customer-health
defaults:
  severity: error
  tags: [production]

conformance:
  - id: customer-name-present
    check: completeness
    with:
      label: Customer
      property: name
      threshold: 0.98

competency:
  - id: customers-can-be-counted
    question: Can customers be counted?
    query: MATCH (c:Customer) RETURN count(c) AS count
    expect:
      rows: { exactly: 1 }
      columns: [count]

Then select it directly or by tag:

graphcheck run --suite customer-health
graphcheck run --select tag:production

A suite can combine three kinds of checks:

• Conformance applies reusable rules for completeness, uniqueness, types, formats, cardinality, relationship direction, temporal sanity, outliers, and sampled PII signals.
• Competency runs authored read-only Cypher and asserts its rows, columns, uniqueness, emptiness, or returned values.
• Drift compares node counts, relationship counts, or property coverage with a stored baseline.

Suite YAML is strict: duplicate keys, unknown fields, invalid payloads, and inconsistent expectations fail before execution. Runtime evaluation is rule-based; generated check suggestions remain inert until a person reviews and activates them.

For the full contracts, see the check YAML specification, results.json specification, and engine and CLI specification. The agent guide, telemetry disclosure, and contributor guide cover integration and operational workflows.

Non-goals

• GraphCheck does not mutate, repair, or migrate the graph.
• GraphCheck does not decide which business rules are sufficient for a domain or claim complete schema coverage.
• GraphCheck does not use an LLM as the judge for check results; execution and evaluation are deterministic.
• Sampled PII checks are heuristics, not a guarantee of complete PII discovery.
• GraphCheck's read-query guard is defense in depth, not a replacement for Neo4j authorization where server-enforced read-only roles are available.

License

Apache-2.0. See LICENSE.