perf(graph): search shortest paths from both ends

.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.2.0"
+current_version = "0.3.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(-(?P<pre_label>alpha|beta|rc)\\.(?P<pre_n>\\d+))?"
 serialize = [
     "{major}.{minor}.{patch}-{pre_label}.{pre_n}",
@@ -29,22 +29,22 @@ first_value = "0"
 
 # Rust Cargo.toml files
 [[tool.bumpversion.files]]
-filename = "crates/lance-graph/Cargo.toml"
+filename = "crates/lance-csr/Cargo.toml"
 search = 'version = "{current_version}"'
 replace = 'version = "{new_version}"'
 
 [[tool.bumpversion.files]]
-filename = "crates/lance-graph-catalog/Cargo.toml"
+filename = "crates/lance-csr-catalog/Cargo.toml"
 search = 'version = "{current_version}"'
 replace = 'version = "{new_version}"'
 
 [[tool.bumpversion.files]]
-filename = "crates/lance-graph-benches/Cargo.toml"
+filename = "crates/lance-csr-benches/Cargo.toml"
 search = 'version = "{current_version}"'
 replace = 'version = "{new_version}"'
 
 [[tool.bumpversion.files]]
-filename = "crates/lance-graph-python/Cargo.toml"
+filename = "crates/lance-csr-python/Cargo.toml"
 search = 'version = "{current_version}"'
 replace = 'version = "{new_version}"'
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: Report incorrect results, errors, or a performance regression.
+---
+
+## What happened?
+
+Describe the expected and actual behaviour. Include the error message or incorrect result.
+
+## Minimal reproducer
+
+Include a small script or query and enough synthetic data to reproduce the problem.
+Remove credentials and private data.
+
+## Environment
+
+- lance-csr version (or commit):
+- Python version:
+- Operating system and architecture:
+- For performance issues: data size, hardware, and timings:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Suggest an improvement to single-machine graph queries.
+---
+
+## Problem or use case
+
+What are you trying to do, and what gets in the way?
+
+## Proposed improvement
+
+Describe the behaviour you would like and any alternatives you have tried.
+Include an example query or API call if helpful.
+
+<!-- Distributed execution is outside this project's scope. See the README goals. -->

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Problem and change
+
+Explain the problem, why the change is needed, and how it helps users. Link related issues.
+
+## Validation
+
+List the checks run and their results. For bug fixes, include a regression test.
+For code changes, include correctness checks and before-and-after results for both benchmark
+suites, with hardware and settings. Documentation-only changes do not need benchmarks.
+
+## User impact
+
+Note any API or behaviour changes and the documentation or examples updated, or write “None”.
+
+See [contribution guidelines](https://github.com/hyperdimensionalcomputingai/lance-csr/blob/main/CONTRIBUTING.md).

.github/workflows/docs.yml

@@ -7,6 +7,8 @@ on:
     paths:
       - docs/**
       - zensical.toml
+      # Pages include this example with --8<--.
+      - crates/lance-csr/examples/**
       - .github/workflows/docs.yml
 
 concurrency:

.github/workflows/python-test.yml

@@ -35,7 +35,7 @@ jobs:
         with:
           shared-key: "lance-csr-python"
           # maturin builds the bindings crate, which sits outside the workspace.
-          workspaces: crates/lance-graph-python
+          workspaces: crates/lance-csr-python
       - name: Install dependencies
         run: |
           sudo apt update

.github/workflows/rust-test.yml

@@ -38,5 +38,8 @@ jobs:
         run: cargo test --workspace --no-run
       - name: Run tests
         run: cargo test --workspace
+      # The Rust guide includes this example; run it so the documented code works.
+      - name: Run embedded example
+        run: cargo run -p lance-csr --example embedded_query
       - name: Check benchmarks
-        run: cargo check -p lance-graph-benches --benches
+        run: cargo check -p lance-csr-benches --benches

AGENTS.md

@@ -1,18 +1,18 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- `crates/lance-graph/` hosts the Rust Cypher engine; keep new modules under `src/` and co-locate helpers inside `query/` or feature-specific submodules.
-- `crates/lance-graph-catalog/` provides the graph source catalog and `DirNamespace` (Unity Catalog and Delta Lake support were removed).
-- `crates/lance-graph-benches/` contains performance benchmarks in a dedicated unpublished crate; add new benchmarks here rather than in the main crate.
-- `crates/lance-graph-python/src/` contains the PyO3 bridge; `python/python/lance_csr/` holds the pure-Python facade and packaging metadata.
+- `crates/lance-csr/` hosts the Rust Cypher engine; keep new modules under `src/` and co-locate helpers inside `query/` or feature-specific submodules.
+- `crates/lance-csr-catalog/` provides the graph source catalog and `DirNamespace` (Unity Catalog and Delta Lake support were removed).
+- `crates/lance-csr-benches/` contains performance benchmarks in a dedicated unpublished crate; add new benchmarks here rather than in the main crate.
+- `crates/lance-csr-python/src/` contains the PyO3 bridge; `python/python/lance_csr/` holds the pure-Python facade and packaging metadata.
 - `python/python/tests/` stores functional tests; mirror new features with targeted cases here and in the corresponding Rust module.
 - `examples/` demonstrates Cypher usage; update or add examples when introducing new public APIs.
 - `docs/` is the Zensical documentation site (configured by `zensical.toml`); follow `docs/AGENTS.md`.
-- Keep the docs in step with the code. Any substantial code change (a new or changed Python method, parameter, return type, exception or Cypher feature, or a change in behaviour users can observe) updates the affected guide pages in the same pull request, and `docs/api-reference.md` whenever the Python API changes. That page is written by hand from `crates/lance-graph-python/src/`, so check every signature and statement against the code. Then run `uv run --project docs --locked zensical build --strict` and `uvx typos@1.26.0 .` (the spell check CI runs).
+- Keep the docs in step with the code. Any substantial code change (a new or changed Python method, parameter, return type, exception or Cypher feature, or a change in behaviour users can observe) updates the affected guide pages in the same pull request, and `docs/api-reference.md` whenever the Python API changes. That page is written by hand from `crates/lance-csr-python/src/`, so check every signature and statement against the code. Then run `uv run --project docs --locked zensical build --strict` and `uvx typos@1.26.0 .` (the spell check CI runs).
 
 ## Build, Test, and Development Commands
 - `cargo test --workspace` (from the repository root) runs the Rust tests; building needs `protoc`.
-- `cargo bench --bench graph_execution -p lance-graph-benches` measures performance-critical changes; include shortened runs with `--warm-up-time 1`.
+- `cargo bench --bench graph_execution -p lance-csr-benches` measures performance-critical changes; include shortened runs with `--warm-up-time 1`.
 - Never use `pip`. In `python/`, `make install` runs `uv sync --locked --no-install-project` (locked dependencies and the `dev` group) and then a debug build with `uv run --no-sync maturin develop`; re-run it after Rust edits. Change dependencies with `uv add`/`uv remove` and commit `uv.lock`.
 - `make test` runs the Python tests; `make lint` runs `ruff`, formatting checks, and `pyright`.
 

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing to lance-csr
+
+Start with the [project goals](README.md#goals) and [contribution guidelines](README.md#contributing).
+This project focuses on single-machine graph queries; distributed execution is out of scope.
+For a larger change, open an issue to explain the problem and proposed approach before starting work.
+
+## Report a bug or suggest an improvement
+
+Search the [existing issues](https://github.com/hyperdimensionalcomputingai/lance-csr/issues) first.
+For bugs, include a small reproducer, expected and actual results, your lance-csr and Python versions,
+and your operating system. Use synthetic data when possible; remove credentials and private data.
+For improvements, describe the use case and how the change would help users.
+
+## Prepare a pull request
+
+Follow the [build instructions](README.md#build-from-source) and
+[Python development guide](python/DEVELOPMENT.md) to set up and run the relevant checks.
+Keep changes focused, add a regression test for bug fixes, and update affected documentation for
+user-visible changes. Python API changes also need an update to `docs/api-reference.md`.
+
+Explain the problem, why the change is needed, and how you validated it. Code changes need correctness
+checks and before-and-after results from both benchmark suites listed in the
+[contribution guidelines](README.md#contributing), using the same hardware and settings.
+Documentation-only changes do not need benchmarks. Agent-assisted contributions follow the same
+requirements: review the generated code and validate it before submitting.

Cargo.toml

@@ -1,9 +1,9 @@
 [workspace]
 members = [
-    "crates/lance-graph",
-    "crates/lance-graph-catalog",
-    "crates/lance-graph-benches",
+    "crates/lance-csr",
+    "crates/lance-csr-catalog",
+    "crates/lance-csr-benches",
 ]
 # Python package needs to be built by maturin.
-exclude = ["crates/lance-graph-python"]
+exclude = ["crates/lance-csr-python"]
 resolver = "2"

README.md

@@ -1,4 +1,20 @@
-# lance-csr: Fast graph queries on Lance
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/desktop-dark-1016.png">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/brand/desktop-light-1016.png">
+    <img src="docs/assets/brand/desktop-light-1016.png" alt="lance-csr" width="340">
+  </picture>
+</h1>
+
+**Fast graph queries on Lance**
+
+[![Rust tests](https://github.com/hyperdimensionalcomputingai/lance-csr/actions/workflows/rust-test.yml/badge.svg?branch=main)](https://github.com/hyperdimensionalcomputingai/lance-csr/actions/workflows/rust-test.yml)
+[![Python tests](https://github.com/hyperdimensionalcomputingai/lance-csr/actions/workflows/python-test.yml/badge.svg?branch=main)](https://github.com/hyperdimensionalcomputingai/lance-csr/actions/workflows/python-test.yml)
+[![PyPI version](https://img.shields.io/pypi/v/lance-csr?color=555)](https://pypi.org/project/lance-csr/)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-555)](LICENSE)
+
+[Documentation](https://lance-csr.pages.dev/) · [Examples](examples/README.md) ·
+[Releases](https://github.com/hyperdimensionalcomputingai/lance-csr/releases) · [Contributing](CONTRIBUTING.md)
 
 lance-csr is a fast graph query engine over [Lance](https://lancedb.github.io/lance/) datasets, built in Rust on
 Apache DataFusion, with Python bindings. It is a fork of [lance-graph](https://github.com/lance-format/lance-graph)
@@ -60,7 +76,7 @@ DataFusion as extension operators, falling back to a join for any hop the CSR ca
 
 ## Repository layout
 
-- `crates/lance-graph` – the Cypher-capable query engine implemented in Rust
+- `crates/lance-csr` – the Cypher-capable query engine implemented in Rust
 - `python/` – PyO3 bindings and Python packages:
   - `lance_csr` – thin wrapper around the Rust query engine
 
@@ -75,6 +91,10 @@ uv add lance-csr
 Prebuilt wheels cover Linux x86-64 and native Apple Silicon (CPython 3.12+); no Rust toolchain is needed.
 See [`python/README.md`](python/README.md) for details and usage.
 
+To use the engine from Rust, add the crate with `cargo add lance-csr` and see
+[`crates/lance-csr/README.md`](crates/lance-csr/README.md) and the
+[Rust guide](https://lance-csr.pages.dev/rust/).
+
 ## Build from source
 
 You need:

crates/lance-graph-benches/Cargo.toml → crates/lance-csr-benches/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
-name = "lance-graph-benches"
-version = "0.2.0"
+name = "lance-csr-benches"
+version = "0.3.0"
 edition = "2021"
 publish = false
-description = "Benchmarks for lance-graph (not published)"
+description = "Benchmarks for lance-csr (not published)"
 
 [dependencies]
-lance-graph = { path = "../lance-graph", version = "0.2.0" }
+lance-csr = { path = "../lance-csr", version = "0.3.0" }
 lance = "13.0.0"
 arrow-array = "58"
 arrow-schema = "58"

crates/lance-graph-benches/README.md → crates/lance-csr-benches/README.md

@@ -1,17 +1,17 @@
 # Lance Graph Benchmarks
 
-Performance benchmarks for the `lance-graph` crate.
+Performance benchmarks for the `lance-csr` crate.
 
 ## Running Benchmarks
 
 From the repository root:
 
 ```bash
 # Run all benchmarks
-cargo bench -p lance-graph-benches
+cargo bench -p lance-csr-benches
 
 # Run specific benchmark
-cargo bench -p lance-graph-benches --bench graph_execution
+cargo bench -p lance-csr-benches --bench graph_execution
 ```
 
 ## Benchmarks

crates/lance-graph-benches/benches/graph_execution.rs → crates/lance-csr-benches/benches/graph_execution.rs

@@ -22,7 +22,7 @@ use arrow_schema::{DataType, Field, Schema as ArrowSchema};
 use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
 use futures::TryStreamExt;
 use lance::dataset::{Dataset, WriteMode, WriteParams};
-use lance_graph::{CypherQuery, GraphConfig};
+use lance_csr::{CypherQuery, GraphConfig};
 use tempfile::TempDir;
 
 fn create_people_batch() -> RecordBatch {