Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
b4adba8
Rust: opt-in IVF approximate search and a faster exact scan
maheshvaikri-code Nov 16, 2026
75e7fbe
C#: opt-in IVF approximate search
maheshvaikri-code Nov 16, 2026
7c8297a
C++: opt-in IVF approximate search, and test the libcurl transport fo…
maheshvaikri-code Nov 16, 2026
a56e612
Add isongraph-vector-server: multi-tenant retrieval service (alpha)
maheshvaikri-code Nov 16, 2026
f99d325
TypeScript and JavaScript: opt-in IVF search and async encoders
maheshvaikri-code Nov 16, 2026
8c75bc1
Add real-data benchmarks: multi-hop retrieval quality and a cross-lib…
maheshvaikri-code Nov 16, 2026
01676c4
Add benchmark-only harnesses for the cross-library comparison
maheshvaikri-code Nov 16, 2026
65c17a4
Update the docs for the ports' IVF search, the server and the benchma…
maheshvaikri-code Nov 16, 2026
252ad66
Rust: concurrent and batch search, one copy of each vector, folds at …
maheshvaikri-code Nov 17, 2026
3bc2c53
Docs: record the Rust engine rework and what it did not improve
maheshvaikri-code Nov 17, 2026
c211947
Rust: opt-in int8 scan with exact f32 rerank
maheshvaikri-code Nov 17, 2026
61acb14
Rust: optional binary snapshot beside the JSON embeddings sidecar
maheshvaikri-code Nov 17, 2026
6f4bc2a
Add an opt-in HNSW approximate index beside IVF (AnnMode::Hnsw)
maheshvaikri-code Nov 17, 2026
66d7552
Rust: int8 IVF batch goes cell-major like the f32 batch
maheshvaikri-code Nov 17, 2026
2b9e07c
Add stage_b_bench: indicative snapshot and int8 measurements
maheshvaikri-code Nov 17, 2026
6b16854
Docs: DESIGN.md sections 10 (int8 scan) and 11 (binary snapshot)
maheshvaikri-code Nov 17, 2026
d3ac95c
HNSW: benchmark example, DESIGN section 10, README, size-based ef_sea…
maheshvaikri-code Nov 17, 2026
5767252
Merge stage-b-hnsw: opt-in HNSW index
maheshvaikri-code Nov 17, 2026
c44e3bd
Stage C: honest Rust re-benchmark; correct the exact-scan claim; docu…
maheshvaikri-code Nov 17, 2026
7138617
Fix CI: Rust 1.98 clippy lints; C++ score equality on GCC 15
maheshvaikri-code Nov 17, 2026
6577dc4
Rust examples: build the Windows memory probe struct only on Windows
maheshvaikri-code Nov 17, 2026
86e2436
Rust: build the AVX2-only int8 pieces for x86_64 only
maheshvaikri-code Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
51 changes: 51 additions & 0 deletions .github/workflows/cpp-curl.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
name: C++ libcurl transport

# Builds the optional libcurl transport for HttpEncoder against a real libcurl
# and runs its tests. ci.yml builds the C++ port without libcurl (the transport
# is behind -DISONGRAPH_VECTOR_CURL=ON and needs the library installed), so
# nothing there compiles or exercises include/isongraph_vector_http.hpp's
# CurlTransport. The tests talk to a small HTTP server started inside the test
# process on 127.0.0.1 - no internet is used.

on:
push:
paths:
- 'isongraph-vector-cpp/**'
- '.github/workflows/cpp-curl.yml'
pull_request:
paths:
- 'isongraph-vector-cpp/**'
- '.github/workflows/cpp-curl.yml'
workflow_dispatch:

permissions:
contents: read

jobs:
curl:
name: libcurl transport on ${{ matrix.os }}
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest]
steps:
- uses: actions/checkout@v4

# Ubuntu's runner image ships the curl command but not the development
# package (headers and libcurl.so for find_package(CURL)). macOS has
# libcurl and its headers in the SDK, so nothing to install there.
- name: Install libcurl headers (Linux)
if: runner.os == 'Linux'
run: |
sudo apt-get update
sudo apt-get install -y libcurl4-openssl-dev

- name: Configure
run: >
cmake -S isongraph-vector-cpp -B isongraph-vector-cpp/build-curl
-DISONGRAPH_VECTOR_CURL=ON -DCMAKE_BUILD_TYPE=Release
- name: Build
run: cmake --build isongraph-vector-cpp/build-curl --config Release
- name: Test
run: ctest --test-dir isongraph-vector-cpp/build-curl -C Release --output-on-failure
85 changes: 76 additions & 9 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,18 +173,84 @@ JavaScript, Rust and C++.
- A cross-port CI check (`scripts/cross_port/graph_files.py`) of graph files,
sidecars and the graph digest: every port writes, every port reads, and a
tampered file must raise each reader's mismatch error (72 checks).
- **Approximate search in every port (opt-in)** - the same lazily built,
never-persisted IVF-flat index (seeded k-means, nlist about 4*sqrt(N), nprobe
about 5%, minimum size 50,000, exact override, `recall_check`) in Rust
(`set_ann`), C++ (`enableAnn`), C# (`AnnMode.Ivf`) and TypeScript /
JavaScript (`ann: 'ivf'`). Graph files, sidecars and the digest are
unchanged. Seeds do not reproduce across ports (each uses its own generator),
so indexes differ while recall is comparable. The standalone SQLite stores
have no index. See `benchmarks/competitive/` for measured speed and recall.
- **Rust: HNSW, int8 scan, binary snapshot** (all opt-in; design in
`isongraph-vector-rs/DESIGN.md` sections 10-12, measured in
`benchmarks/rust-stage-c/`). `AnnConfig::hnsw()` adds an HNSW index that
holds links only (about 1.2x raw memory at 1M x 384); at recall@10 0.95 its
single-thread speed is level with faiss HNSW and hnswlib and ahead of
usearch. It builds about 8-20x slower than IVF (about 150 s at 1M) and is
not persisted. `ScanPrecision::Int8` adds an int8 first pass with exact
rerank: 3-3.6x faster single-query scans at 1M, recall 1.000 against the
f32 scan from rerank factor 2 on real embeddings, no gain for batches, +0.25x
memory, and not used by HNSW graph search. `save_with_snapshot` writes a
binary `.snap` beside the JSON sidecar: 3x smaller and about 6x faster to
load at 1M (JSON stays the portable default; graph file and digest bytes are
unchanged; a stale or corrupt snapshot falls back to JSON).
- **Rust engine rework** (design in `isongraph-vector-rs/DESIGN.md`, measured
in `benchmarks/rust-stage-a/`): exact search uses AVX2/FMA kernels and
threads; searches take `&self` on a persistent pool, with batch search
(`similarity_search_vector_batch` and friends) that returns bit-for-bit the
same answers as one query at a time; `SharedEmbeddingStore` for threads that
read and write together; each vector is held once in a chunked matrix
(1.12x raw at 1M x 384, was 2.41x); pending rows are folded into the index
in groups of 256 at write time, so the first query after 30k writes into 1M
takes about 8 ms (was about 600 ms). Equal scores are ordered by arrival.
**Breaking:** `EmbeddingStore::get` and `SemanticGraph::get_embedding` now
return an owned `Option<EmbeddingRecord>`; use `get_vector` to borrow.
Costs: single-thread exact scan is 0-13% slower, ingest is slower, and
updates at 1M are 2-3x slower because index upkeep moved from the first
search to the write.
- **Async encoders in TypeScript / JavaScript** - `AsyncEncoder` and
`...Async` methods (`addNodeAsync`, `updateNodeAsync`, `embedAllNodesAsync`,
`reembedStaleAsync`, `similaritySearchAsync`, `semanticMultiHopAsync`, ...)
let `HttpEncoder` auto-embed without a prefetch. Failures are atomic. The
synchronous interface and `prefetch` still work.
- **C++ libcurl transport is built and tested against real libcurl** (8.11.1,
loopback server, no internet). Two bugs fixed: `Expect: 100-continue`
stalling large bodies, and a misleading error for over-cap responses. A new
`cpp-curl.yml` workflow runs it on Linux and macOS.
- **`isongraph-vector-server` (alpha)** - a separate package that serves the
library over HTTP: per-tenant API keys (salted hashes), isolated graphs,
quotas and rate limits, search / multi-hop / path / subgraph / similar,
atomic checksummed snapshots with digest verification, a tenant-sharding
router and digest-verified read replicas. Not provided: TLS, failover,
resharding, a write-ahead log, cross-tenant queries.
- **Real-data benchmarks** - `benchmarks/multihop/` (HotpotQA, 2Wiki,
MuSiQue; two encoders; graphs built without the gold annotations; negative
controls; BM25, hybrid, cross-encoder and personalised-PageRank baselines)
and `benchmarks/competitive/` (faiss, hnswlib, usearch, chromadb, lancedb,
sqlite-vec, numpy on text, GloVe and SIFT vectors at 100k and 1M).

### Known limits

- `C#` copies: nodes and edges read from the C# read-only graph view are
copies, so editing one's `Properties` silently changes nothing.
- The JavaScript / TypeScript encoder interface is synchronous, so an
`HttpEncoder` only serves texts that were prefetched; auto-embedding in
`SemanticGraph` needs a `prefetch` first.
- The libcurl transport for the C++ `HttpEncoder` has not been built against a
real libcurl; it is off by default.
- Approximate search is Python-only, uses a numpy IVF index rather than HNSW,
and recall was measured on synthetic data, not real embeddings.
- The synchronous JavaScript / TypeScript encoder interface still only serves
prefetched texts; use the `...Async` methods to embed through a network
encoder. `loadGraph({onMismatch: 'reembed'})` has no async form.
- Approximate search is IVF-flat in every port; only Rust also has HNSW. Recall on real embeddings was
measured at 100k and 1M (`benchmarks/competitive/`); the index is not
persisted and is rebuilt after load. JavaScript builds are slow (about 8
minutes at 1M vectors).
- **Not a vector-database replacement.** Against faiss, hnswlib and usearch
the ports are 2-4x slower per query at 100k and about 14x slower at 1M text
vectors at equal recall; only Rust has batched and concurrent search (the other ports serialise on one lock); vectors
persist as JSON only; and memory is 2-4x higher (Rust is now 1.1x raw; the other ports still store vectors twice). Graph-aware retrieval
beating plain vector search on multi-hop questions is the supported claim,
and it depends on the graph carrying real structure
(`benchmarks/multihop/README.md`).
- Fast filtered search was only measured for node-type filters, and only Rust
is fast there (Python's filtered search is no faster than its unfiltered
scan). The C++ exact scan is scalar and about 6x slower than numpy; the C#
and JS exact scans are also slower than numpy.
- The digest cannot tell `1` from `1.0` in JavaScript / TypeScript, and
integers beyond 64 bits are not supported in C# / C++ / Rust. Where a graph
contains such values the loader warns instead of raising a false mismatch.
Expand Down Expand Up @@ -212,8 +278,9 @@ JavaScript, Rust and C++.
prerelease dependency (NU5104), so a stable 1.0.0 was not possible against
it. The redistribution carries the same upstream C at the version the Rust,
Node and C++ ports already use.
- Similarity search is brute force. There is no ANN index: this is built for an
application's own knowledge graph, not as a vector-database replacement.
- Similarity search is exact (brute force) by default, with an opt-in IVF
index; this is built for an application's own knowledge graph, not as a
vector-database replacement.
- Payload vectors are float32 in every port, but the JSON text differs: Rust
writes the shortest form that round-trips as f32 (`0.33590567`), Python
widens to float64 first (`0.33590567111968994`). Same number, and importing
Expand Down
20 changes: 14 additions & 6 deletions DESCRIBE.md
Original file line number Diff line number Diff line change
Expand Up @@ -272,10 +272,16 @@ the default `threshold` of 0.3, so she never seeds the search either.
linear in the number of nodes. In Python the numpy path is vectorised and
patches its cache on writes, which moved the point where a search passes
50 ms from roughly 90,000 vectors to (extrapolated) around a million;
see `benchmarks/`. Python has an opt-in IVF approximate index
(`ann="ivf"`) that pays off from about a million vectors; the other ports are
exact only. This stays an application's
own knowledge graph rather than a vector-database replacement.
see `benchmarks/`. Every in-memory store has an opt-in IVF approximate index
(`ann="ivf"` in Python; `set_ann`, `enableAnn`, `AnnMode.Ivf`, `ann: 'ivf'`
elsewhere) that pays off from roughly a million vectors; the standalone
SQLite stores have none. Measured against faiss, hnswlib and usearch
(`benchmarks/competitive/`), the ports are 2-4x slower per query at 100k and
about 14x slower at 1M vectors at equal recall, have no batched or
concurrent search, and persist vectors as JSON only. This stays an
application's own knowledge graph rather than a vector-database replacement;
its measured strength is graph-aware retrieval on multi-hop questions
(`benchmarks/multihop/`).
- One embedding per node, generated from a single text field/concat -
no multi-vector-per-node, no edge embeddings (that's RudraDB's domain,
not this package's).
Expand Down Expand Up @@ -304,8 +310,10 @@ the default `threshold` of 0.3, so she never seeds the search either.
(or errors). Use `stale_embeddings()` and `reembed_stale()` to refresh them.
An encoder `version` is recorded in the sidecar and warns on a change, but a
version-only change is not treated as stale.
- Distributed or multi-tenant retrieval, access control and any server layer
are out of scope for an embedded library.
- The library itself stays embedded. A separate package,
`isongraph-vector-server` (alpha), adds multi-tenant access control, quotas,
a router that shards tenants across nodes and snapshot-based read replicas;
it has no automatic failover, no resharding and no TLS.
- C++ remains the one port where the base graph library is vendored rather
than declared as a dependency, because there is no package registry to
declare it in.
Expand Down
24 changes: 19 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -342,11 +342,25 @@ every suite asserts that set.

## Honest limits

- **Search is brute force in every backend**, sqlite-vec included — all of them
linear in the number of nodes. This is built for an application's own
knowledge graph, not as a vector-database replacement. For vectors on both
nodes *and* edges, ANN indexing and link prediction, RudraDB is the right
tool; these are not really competitors despite the surface similarity.
- **Search is exact (brute force) by default**, sqlite-vec included — linear in
the number of nodes. Every in-memory store has an opt-in IVF index for large
stores. This is built for an application's own knowledge graph, not as a
vector-database replacement: measured against faiss, hnswlib and usearch
(`benchmarks/competitive/`) the ports are 2-4x slower per query at 100k and
about 14x slower at 1M vectors at equal recall, have no batched or concurrent
search, and persist vectors as JSON only. They do build indexes 8-25x faster
and take inserts and updates far faster than HNSW. For vectors on both
nodes *and* edges and link prediction, RudraDB is the right tool; these are
not really competitors despite the surface similarity.
- **Where it does help: multi-hop questions.** On HotpotQA, 2WikiMultihopQA and
MuSiQue, graph-aware retrieval found every supporting passage more often than
plain vector search (+9 to +51 points at k=10, paired p<0.001), but only when
the graph carries real structure: on a randomly relabelled graph the gain
disappears, and an independently written personalised-PageRank re-ranker
matches it. See `benchmarks/multihop/README.md`.
- **A separate server package exists** (`isongraph-vector-server`, alpha):
multi-tenant HTTP API, tenant-sharding router and read replicas. It has no
TLS, failover or write-ahead log.
- **One embedding per node**, from one text field or a concatenation. No
multi-vector nodes, no edge embeddings.
- **`MockEncoder` has no semantic structure.** It exists so tests and demos
Expand Down
39 changes: 24 additions & 15 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,39 @@ What is deliberately not done yet, in rough priority order. Items marked
## Next

1. **Cut 1.0.0.** Nothing is tagged or published. Follow `RELEASING.md`.
2. **Run the new CI step once on real runners.** `graph_files.py` passes
locally on Windows only; the Linux paths (g++, TS symlink, dotnet) are
unproven. Also build the C++ libcurl transport once against real libcurl.
3. **Retrieval-quality benchmark on real data.** `benchmarks/` uses a
synthetic graph and synthetic vectors. Run it against a real knowledge
graph and a real encoder, add answer-groundedness, and measure ANN recall on
real embeddings.
4. **Per-record encoder version.** Today a version-only change warns on
2. **Run the new CI jobs once on real runners.** The cross-port graph-file
check and `cpp-curl.yml` have run on Linux only through the first PR; the
server package's tests and its Dockerfile have only run on Windows (the
Dockerfile has never been built).
3. **Make Rust the reference engine.** Done and measured in Rust
(`isongraph-vector-rs/DESIGN.md`, `benchmarks/rust-stage-c/`): concurrent
and batch search, one copy of the vectors, no post-write stall, opt-in HNSW
(level with faiss HNSW / hnswlib single-thread), int8 scan, binary snapshot.
Still open: port the proven pieces to the other ports; persist the ANN
index; faster HNSW single-call inserts (1.4k/s at 1M); exact scan is at
parity with faiss Flat, not ahead.
5. **Fix the slow ports.** The C++ exact scan has no scan cache and is scalar
(6x slower than numpy); JavaScript k-means takes about 8 minutes at 1M.
6. **Per-record encoder version.** Today a version-only change warns on
load but cannot be fixed by `reembed_stale`.

## Later

- **Approximate search beyond Python**, and HNSW as an optional extra if IVF's
recall/latency trade-off proves too weak on real data.
- **Async encoders in TypeScript / JavaScript**, so an `HttpEncoder` works with
auto-embedding without a `prefetch`.
- **Binary persistence** for vectors and the index, as an addition to the
portable JSON sidecar (which stays the default and keeps the digest).
- **Approximate search for the standalone SQLite stores.**
- **Relationship-type weights** (per type rather than a per-edge property),
and richer node predicates than a callback.
- **Multi-vector and edge embeddings.**
- **C# loading Python's undirected graph files** - blocked on the IsonGraph
NuGet package accepting the `meta.graph` block.
- **Server package:** TLS, a write-ahead log, failover and resharding, only if
the service is to be run beyond a trusted network.

## Out of scope

- Distributed indexing and retrieval, replication, multi-node availability.
- Multi-tenant access control and a service layer. Put those in front of the
library.
- Distributed indexing and retrieval inside the library, and multi-node
availability. The server package offers per-tenant sharding and
bounded-staleness snapshot replicas only.
- Competing with dedicated vector databases on raw query throughput. The
supported claim is graph-aware retrieval over up to about a million vectors.
4 changes: 4 additions & 0 deletions benchmarks/competitive/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Large captured console output and the discarded first (unpinned) run stay local
results/raw/*.stdout.txt
results/archive_unpinned/
__pycache__/
Loading
Loading