Skip to content

Getting Started

Farnsworth is a Cargo workspace.

git clone git@github.com:manz/farnsworth.git
cd farnsworth
cargo build

Requirements

  • Rust, edition 2024 (toolchain 1.85+)

Workspace layout

crates/
  farnsworth-core/         # autocomplete, details, geocode, reverse geocode - the real capabilities
  farnsworth-importer/     # native Rust Parquet reader for the real dataset - no duckdb needed
  farnsworth-text-spike/   # tantivy prototype - prefix, typo tolerance, synonyms, multi-language field
  farnsworth-geo-spike/    # rstar radius search + geo point-in-polygon (two binaries: main, polygon)
  farnsworth-wire-spike/   # JSON vs bincode serialization benchmark
  farnsworth-milli-spike/  # milli embedding spike (not a workspace member - see below)

Running the tests

cargo test

All tests are self-contained (small synthetic fixtures, no dependency on the external ~/.cache/farnsworth-data sample), so they run anywhere.

farnsworth-milli-spike is deliberately excluded from the workspace (Cargo.toml exclude): milli only compiles under rustc 1.98.1 (meilisearch's pinned toolchain), not this workspace's default. Build it standalone from inside that directory:

cd crates/farnsworth-milli-spike
cargo +1.98.1 build

The spike concluded milli isn't viable to embed directly - see architecture.

Running the tantivy spike

cargo run -p farnsworth-text-spike --release

Reads sample data from ~/.cache/farnsworth-data/pois_sample.json by default (real exported POI data, kept outside this repo - see architecture for why). Pass a path as the first argument to use different data.

Running the integration demo

cargo run -p farnsworth-core --bin demo --release

Combines text search and geo filtering into one query - see architecture for what it proves.

Importing the real world dataset

cargo run -p farnsworth-importer --release -- ~/path/to/localities-export

Reads every *.parquet file directly (POIs + every country's address files) via the parquet crate - no duckdb, no JSON intermediate step. Defaults to ~/Downloads/localites_data/export if no path is given. Builds a combined POI search index and geocode index across every country, then runs real queries to prove actual world coverage. See architecture for results.

More crates land as the spikes resolve - see architecture.