[](https://github.com/graphistry/tck-gfql/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/graphistry/pygraphistry)
# GFQL Cypher TCK Conformance Harness
This repo hosts the Cypher TCK -> GFQL translation harness used by
PyGraphistry. It relies on an installed `pygraphistry` package to execute
GFQL queries and validate results.
## Layout
- [`tests/cypher_tck/`](tests/cypher_tck/): Scenario translations, runner, and gap analysis.
- [`docs/conformance-ownership-map.md`](docs/conformance-ownership-map.md): Ownership boundary with PyGraphistry and shared conformance artifact contracts.
- [`docs/capability-debt-manifest-schema.md`](docs/capability-debt-manifest-schema.md): Public schema for scenario-level capability/debt metadata and validation drift checks.
- [`docs/conformance-profile-handoff-template.md`](docs/conformance-profile-handoff-template.md): Coordinator-facing template for cross-repo conformance lanes.
- TCK clone (gitignored): `plans/cypher-tck-conformance/tck`.
- Cross-repo coordination guide: [SYNC.md](SYNC.md).
## Links
- PyGraphistry repo: [graphistry/pygraphistry](https://github.com/graphistry/pygraphistry)
- GFQL docs: [pygraphistry.readthedocs.io](https://pygraphistry.readthedocs.io/en/latest/gfql/index.html)
- openCypher TCK: [opencypher/openCypher](https://github.com/opencypher/openCypher/tree/main/tck)
- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
- Code of Conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- Security: [SECURITY.md](SECURITY.md)
## Setup
1. Install or editable-link `pygraphistry`:
```bash
uv pip install --python "$(command -v python)" networkx -e /path/to/pygraphistry
```
2. Clone the openCypher TCK locally (gitignored):
```bash
mkdir -p plans/cypher-tck-conformance
git clone https://github.com/opencypher/openCypher plans/cypher-tck-conformance/tck
```
## Run
```bash
./bin/ci.sh
python3 -m pytest tests/cypher_tck -xvs
TEST_CUDF=1 python3 -m pytest tests/cypher_tck -xvs
```
`./bin/ci.sh` checks that the imported `graphistry.compute` package exposes the
GFQL row-pipeline API and row expression parser backend required by this harness
before pytest collection starts.
## Local pygraphistry override
Use a sibling checkout and install its dependencies in editable mode:
```bash
PYGRAPHISTRY_INSTALL=1 PYGRAPHISTRY_PATH=../pygraphistry ./bin/ci.sh
```
`PYGRAPHISTRY_PATH` without `PYGRAPHISTRY_INSTALL=1` only prepends source to
`PYTHONPATH`; that is useful for quick import checks, but strict GFQL row
expression tests also need pygraphistry's parser dependency installed.
Install a specific ref from GitHub:
```bash
PYGRAPHISTRY_INSTALL=1 PYGRAPHISTRY_REF=master ./bin/ci.sh
```
Dependency freshness policy:
- Non-graphistry dependencies should use a 6-day cooldown (`UV_EXCLUDE_NEWER="6 days"`).
- `graphistry`/`pygraphistry` is first-party and may be installed same-day.
## License
This repository is licensed under the Apache License 2.0. See [LICENSE](LICENSE)
and [NOTICE](NOTICE) for details and upstream attribution.
## Per-route conformance ledger
`bin/routes-off.sh` replays the TCK once per pygraphistry hot path with that path declined
(`GFQL_ROUTES_OFF`, pygraphistry's test-side route switch) and diffs each run against the
baseline (`tests/cypher_tck/route_ledger.py`): scenarios the route was masking (pass at
baseline, fail with it off) and scenarios only the route answers (fail or expected-fail at
baseline, pass with it off). It is a ledger, not a gate: it always exits 0. Modes:
`MODES="native-fast cypher-fast" OUT=build/routes-off ./bin/routes-off.sh`.
### Native Polars candidate validation
Set `TEST_POLARS=1` to check native Polars results against the TCK expectations.
An unavailable or broken Polars installation fails validation when this flag is set.
```bash
python bin/polars_candidate.py --product /path/to/pygraphistry --mode normal
python bin/polars_candidate.py --product /path/to/pygraphistry --mode all-off
```
The runner requires installed product dependencies, verifies imports come from the selected
checkout, and sets `TEST_POLARS=1`. The second command disables every route in that
checkout's route registry; newly registered routes are included automatically.
Both commands must pass for the release candidate. The **Polars candidate conformance**
Actions workflow runs both for an explicitly selected published PyGraphistry ref.
Native operations that raise `NotImplementedError` remain reported declines; this does
not establish support for those operations. The ordinary pandas CI run does not replace
these Polars checks.
README の元ファイルを読む