[prrao87]

Why

The README described what lance-csr adds but not what it is for, or what it will not do. Contributors need both before they open an issue or a pull request. It also still carried material from lance-graph: benchmark numbers from an old Criterion run nobody can reproduce, a link to lance-graph's DeepWiki page, and a project-structure proposal for crates that don't exist. This change states the project's goals and scope, shows the LDBC benchmark lance-csr is measured on, removes the stale upstream material, and credits the two projects lance-csr builds on.

What changed

• A Goals section after the introduction. lance-csr targets single-machine execution, and aims to:
  • provide a fast, lightweight and portable openCypher-compatible engine on top of the Lance format;
  • enable multimodal knowledge graphs, where media and vectors live alongside the graph and path traversals run over a single copy of the data;
  • push DataFusion's execution engine for multi-hop graph traversal.
• An out of scope note: graph queries across multiple machines are explicitly out of scope, and issues and pull requests that target distributed execution will be closed as out of scope. It points people with distributed graph workloads to HDC Labs' contact page.
• Credits move to the end of the README and now also credit the contributors of Apache DataFusion, alongside lance-graph's maintainers and contributors.
• Benchmarks now show the 30-query LDBC SNB SF1 suite from graph-benchmark-ldbc: lance-csr 0.1.0 in memory and lazy, next to Neo4j, Kuzu, Ladybug and lance-graph. The other engines' numbers are copied from that repository's 2026-10-16 run. lance-csr was measured on the same machine with the same settings on 2026-10-23, and the README notes that its runner is not yet in that repository. The Criterion table and its instructions are gone.
• The DeepWiki link to lance-graph's documentation is removed.
• The project structure document describes the actual workspace and the query pipeline, instead of lance-graph's proposal for lance-graph-core and lance-graph-planner crates.
• The examples say lance-csr, install lance-csr from PyPI, list the snapshot and refresh example, and build with maturin develop from python/. The old maturin develop -m crates/lance-graph-python/Cargo.toml skipped the package metadata and produced a module without the lance_csr package.
• Dependencies are managed with uv, never pip. Development tools (maturin, pytest, pandas, ruff, pyright) move from published extras into a uv dev dependency group, and uv.lock is regenerated for the 3.12 floor. Every documented setup installs with uv sync --locked --no-install-project, then makes a debug build with uv run --no-sync maturin develop. The READMEs explain both flags: uv would otherwise build the package in release mode, and a re-sync would remove the debug build. Users install with uv add lance-csr, and the examples run with uv run --with lance-csr. Building from source now lists protoc, and Rust commands run workspace-wide from the repository root.
• The Makefile's targets work. make install, test, lint, format, wheel and clean wrap the uv commands. The old test target ran a single file through an invalid uv run --with tests, and the documented doctest target didn't exist. DEVELOPMENT.md now describes this project rather than Lance's tracing, S3 tests, vector benchmarks and manylinux2014 wheels. The contributor notes for agents follow the same commands.
• The package metadata names the lance-csr authors instead of lance-graph's.
• CI
  • Python Tests installs with uv sync --locked. Its doctest step is removed: it ran python -m doctest on the package's __init__.py, which can't import the package that way, and swallowed the error, so it never tested anything.
  • The publish workflow gets zig and twine through uv instead of pip, and keeps maturin-action and its sccache cache.
  • Each built wheel is now tested by its file path. Before, --find-links dist lance-csr could resolve to PyPI's copy of the same version. ci/check_wheel.py now checks that the extension loads from site-packages, because uv's environments can place packages outside sys.prefix.
  • Wheels now build on pull requests only when the wheel build changes (the publish workflow, the wheel check, python/.cargo/), not on every pyproject.toml or bindings Cargo change. Other changes rely on a manual dry_run before a release.
• The repository layout gets its own heading. A leftover reference to an upstream lance-graph issue, and a stray fragment from an earlier edit, are removed.

Validation

• No library code or tests change. The package metadata, the Makefile and the CI workflows do.
• In python/, make install (uv sync --locked --no-install-project --inexact, then maturin develop), make test (280 passed) and make lint (clean) all run, and uv lock --check passes. The same commands also work in a fresh environment.
• The publish workflow's new wheel-test step was run locally against a macOS release wheel: check_wheel.py passes, and the full suite (280 tests) passes without Rust on PATH. A manylinux_2_28 x86-64 wheel built on macOS with zig supplied only through uv (uv run --with 'maturin[zig]'). CI will run the edited publish workflow on this PR, since the workflow file changed.
• Both workflows pass GitHub's workflow schema check.
• The three examples run with uv run --with lance-csr against the published release.
• The benchmark table was generated from the result files (graph-benchmark-ldbc's README table for the other engines, the two pytest-benchmark passes for lance-csr), not typed by hand.
• Checked the section order and Markdown by reading the files; the links were not fetched.
• This branch and feat(cypher): run the official ldbc ic queries as opencypher text #2 both edit the README, in different sections. feat(cypher): run the official ldbc ic queries as opencypher text #2 rewrites the "Much wider Cypher" bullet, which this change leaves alone, so whichever merges second needs at most a small rebase.

🤖 Generated with Claude Code