sqlite-hybrid-search 0.1.0__tar.gz

sqlite_hybrid_search-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,95 @@
+name: Release
+
+# Builds platform wheels + an sdist and, on a published GitHub Release,
+# uploads them to PyPI via Trusted Publishing (OIDC -- no API token).
+#
+# PyPI setup (one time): project -> Publishing -> add a pending publisher
+#   Owner:            ashray-00
+#   Repository:       sqlite-hybrid-search
+#   Workflow name:    release.yml
+#   Environment name: pypi
+# Then create the `pypi` environment under repo Settings -> Environments.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}   # manual runs build artifacts but do not publish
+
+permissions:
+  contents: read
+
+jobs:
+  wheels:
+    name: wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # x86_64 Linux + Apple-Silicon macOS. GitHub retired the macos-13
+        # (Intel) hosted runners; Intel-Mac users build from the sdist.
+        os: [ubuntu-latest, macos-14]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21.3   # bump to the latest tag periodically
+        env:
+          # cp39..cp313, 64-bit only; skip PyPy and musl for a first release.
+          CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-*"
+          CIBW_SKIP: "*-musllinux_* *_i686 *-win32 pp*"
+          CIBW_ARCHS_MACOS: "arm64"
+          # The built-in ONNX Runtime backend is a source-build opt-in; PyPI
+          # wheels ship the dependency-free mock backend only.
+          CIBW_ENVIRONMENT_LINUX: 'CMAKE_ARGS="-DRETRIEVAL_ENGINE_WITH_ONNX=OFF"'
+          # Link the macOS SDK's system SQLite (present on every Mac, part of
+          # the OS) instead of a Homebrew build: delocate keeps system libs
+          # as plain dynamic deps, so the wheel stays clean and its
+          # deployment target is not dragged up to the runner's macOS.
+          CIBW_ENVIRONMENT_MACOS: >-
+            CMAKE_ARGS="-DRETRIEVAL_ENGINE_WITH_ONNX=OFF
+            -DSQLite3_INCLUDE_DIR=$(xcrun --show-sdk-path)/usr/include
+            -DSQLite3_LIBRARY=$(xcrun --show-sdk-path)/usr/lib/libsqlite3.tbd"
+          CIBW_BEFORE_ALL_LINUX: "yum install -y sqlite-devel || dnf install -y sqlite-devel"
+          # Smoke-test every wheel after auditwheel/delocate repairs it.
+          CIBW_TEST_COMMAND: >-
+            python -c "import sqlite_hybrid_search, tempfile, os;
+            e = sqlite_hybrid_search.Engine(os.path.join(tempfile.mkdtemp(), 'x.sqlite3'), dim=3);
+            e.add(documents=[{'id': 'a', 'text': 'hi'}], embeddings=[[1, 0, 0]]);
+            assert e.search([1, 0, 0], 1)[0]['document_id'] == 'a'"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install SQLite headers + library
+        run: sudo apt-get update && sudo apt-get install -y libsqlite3-dev
+      - run: pipx run build --sdist
+      - name: Verify the sdist builds from source
+        run: pip install dist/*.tar.gz
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: publish to PyPI
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    environment: pypi            # must match the PyPI trusted-publisher config
+    permissions:
+      id-token: write            # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        # with:
+        #   repository-url: https://test.pypi.org/legacy/   # uncomment for TestPyPI

sqlite_hybrid_search-0.1.0/BENCHMARKS.md

@@ -0,0 +1,263 @@
+# Benchmarks
+
+Reproducible measurement of the four retrieval paths this engine exposes,
+across dataset sizes, on one machine. Generated by `benchmarks/run_eval.py`;
+raw numbers in [`benchmarks/results.json`](benchmarks/results.json).
+
+## What was measured
+
+| Approach | Call | What it is |
+|---|---|---|
+| `dense` | `search_dense()` | usearch HNSW cosine ANN only |
+| `sparse` | `search_sparse()` | SQLite FTS5 BM25 only |
+| `hybrid` | `search_hybrid()` | Reciprocal Rank Fusion (k=60) of dense + sparse |
+| `hybrid_decay` | `search_memory()` | `hybrid` re-scored by exponential recency decay (λ = 0.1) |
+
+- **Retrieval quality:** Recall@10, nDCG@10, MRR@10 over 100 labelled queries.
+- **Latency:** warm-cache p50 / p95 / p99 and throughput; cold-cache first-query
+  latency; index **load**-on-open time (from the `.usearch` sidecar).
+- **Footprint:** SQLite + sidecar size on disk, process peak RSS, RSS growth
+  during indexing, ingestion throughput.
+
+### Environment
+
+Numbers below were measured on `macOS 26.6 arm64` (Apple Silicon), Python 3.12,
+engine dim 64, single thread. Full C++/Python test suites green (`ctest`: 41,
+`pytest`: 32). The harness is OS-independent; absolute timings will differ on
+other hardware.
+
+### Reproduce
+
+```
+cmake -B build && cmake --build build            # Linux
+# macOS: cmake -B build -DCMAKE_PREFIX_PATH=/opt/homebrew && cmake --build build
+.venv/bin/python benchmarks/run_eval.py           # 1k / 10k / 100k, ~1.5 min
+```
+
+### Honest caveat on the corpus
+
+The corpus is **synthetic** (`benchmarks/corpus.py`): every relevant document
+carries a unique rare entity token, and embeddings are a 64-dim hashed
+bag-of-words, not a trained model. So:
+
+- **Sparse/BM25 numbers are a best case** — the rare entity token is a perfect
+  exact-match signal, which is exactly the situation BM25 is built for.
+- **Dense numbers are a worst case** — a 64-dim hashing-trick vector collides
+  badly as the corpus grows; a real embedding model (nomic, BGE-M3, MiniLM via
+  the built-in ONNX path) would not degrade like the `dense` column does here.
+- **Latency and memory are model-independent** and transfer directly.
+
+Read the quality section as *"how the fusion behaves when the two signals
+disagree"*, not as an absolute quality score for dense retrieval.
+
+---
+
+## Retrieval quality
+
+**Recall@10** — fraction of relevant docs found in the top 10:
+
+| Approach | 1k | 10k | 100k |
+|---|---|---|---|
+| dense | 0.987 | 0.783 | 0.493 |
+| sparse | 1.000 | 1.000 | 1.000 |
+| **hybrid** | **1.000** | **1.000** | **1.000** |
+| hybrid_decay | 1.000 | 1.000 | 1.000 |
+
+**nDCG@10** — ranking quality:
+
+| Approach | 1k | 10k | 100k |
+|---|---|---|---|
+| dense | 0.944 | 0.752 | 0.507 |
+| sparse | 1.000 | 1.000 | 1.000 |
+| hybrid | 0.992 | 0.969 | 0.951 |
+| **hybrid_decay** | **0.998** | **0.998** | **0.997** |
+
+**MRR@10:**
+
+| Approach | 1k | 10k | 100k |
+|---|---|---|---|
+| dense | 0.978 | 0.870 | 0.673 |
+| sparse | 1.000 | 1.000 | 1.000 |
+| hybrid | 1.000 | 0.995 | 0.990 |
+| hybrid_decay | 1.000 | 1.000 | 0.995 |
+
+**Reading it:**
+
+- **Hybrid recovers everything dense loses.** As the toy dense vectors collapse
+  (Recall 0.99 → 0.49), `hybrid` stays at **1.000** recall — RRF lets the sparse
+  side carry the query. This is the headline result: *fusion is strictly safer
+  than dense-only.*
+- **When one signal is already perfect, fusing in a noisy one costs a little
+  ranking quality.** `sparse` nDCG is 1.000; `hybrid` nDCG is 0.951 at 100k,
+  because RRF interleaves dense's mistaken candidates. Fusion trades a few
+  points of top-rank precision for robustness.
+- **Recency decay buys most of that back.** `hybrid_decay` nDCG is ~0.997 across
+  all sizes: the decay term breaks ties in favour of the (correctly recent)
+  relevant docs, pushing them back above dense's false positives. This is the
+  agent-memory case working as intended.
+
+---
+
+## Latency
+
+**Warm-cache latency (ms), 100 queries × repeated passes:**
+
+| Approach | 1k p50 | 1k p95 | 1k p99 | 10k p50 | 10k p95 | 10k p99 | 100k p50 | 100k p95 | 100k p99 |
+|---|---|---|---|---|---|---|---|---|---|
+| dense | 0.090 | 0.094 | 0.097 | 0.103 | 0.112 | 0.115 | 0.173 | 0.199 | 0.211 |
+| sparse | 0.436 | 0.457 | 0.478 | 4.605 | 5.013 | 5.159 | 49.34 | 49.77 | 49.89 |
+| hybrid | 0.524 | 0.541 | 0.558 | 4.765 | 5.059 | 5.297 | 49.44 | 50.13 | 50.50 |
+| hybrid_decay | 0.729 | 0.790 | 0.818 | 6.517 | 7.350 | 7.630 | 70.06 | 83.28 | 85.93 |
+
+**Throughput (queries/sec, single thread):**
+
+| Approach | 1k | 10k | 100k |
+|---|---|---|---|
+| dense | 11048 | 9625 | 5705 |
+| sparse | 2286 | 215 | 20 |
+| hybrid | 1905 | 208 | 20 |
+| hybrid_decay | 1371 | 155 | 14 |
+
+- **Dense is sub-millisecond and near flat with scale** (0.09 → 0.17 ms p50 from
+  1k to 100k) — usearch HNSW is doing its job.
+- **Sparse/hybrid latency is dominated by FTS5** and grows roughly linearly with
+  corpus size: ~0.4 ms → ~49 ms p50. The OR-of-terms BM25 query scans large
+  posting lists for common tokens. This is the main query-time bottleneck.
+  Fusion now feeds BM25's top `min(k, 200)` rows into RRF — a ceiling that
+  bounds pathologically large `k` without touching ordinary retrieval, so at
+  the benchmark's `k = 10` sparse/hybrid latency is unchanged.
+- **`hybrid_decay` adds a re-scoring pass** over the fused candidate set:
+  +40% p50 over `hybrid` at 100k (49.4 → 70.1 ms), and a wider p95/p99 tail.
+
+**Index load on open.** The usearch graph is persisted to a `<db>.usearch`
+sidecar and memory-loaded on the next open instead of being rebuilt from
+SQLite. Startup is now effectively instant at every size:
+
+| Dataset | Load from sidecar | (was: rebuild from SQLite) |
+|---|---|---|
+| 1k | 0.7 ms | 40 ms |
+| 10k | 3.2 ms | 721 ms |
+| 100k | **24.5 ms** | **14.6 s** |
+
+The first open of a brand-new database still rebuilds (there is no sidecar
+yet) and writes the sidecar; every open after that takes the load path. A
+sidecar that is missing, truncated, or out of sync with the chunk table is
+rejected in microseconds and the engine falls back to a rebuild.
+
+**Cold vs warm query.** With the graph loaded from the sidecar, the first
+query after an open is no slower than a warm one (100k `hybrid`: 49.3 ms cold
+vs 49.4 ms warm p50; `dense`: 0.32 ms cold vs 0.17 ms warm).
+
+---
+
+## Memory & storage footprint
+
+| Dataset | SQLite | `.usearch` sidecar | Ingest throughput | RSS growth during indexing | Process peak RSS |
+|---|---|---|---|---|---|
+| 1k | 0.57 MB | ~0.5 MB | 21695 docs/s | 3.5 MB | 35 MB |
+| 10k | 5.21 MB | ~4 MB | 12826 docs/s | 11.1 MB | 79 MB |
+| 100k | 51.98 MB | 40.5 MB | 6505 docs/s | 52.5 MB | 430 MB |
+
+- **On-disk scales linearly.** SQLite is ~520 bytes/doc (chunk text + metadata +
+  FTS5 index + the vector blob kept for a rebuild); the sidecar adds the
+  serialised HNSW graph (~400 bytes/doc at dim 64). At 100k that is ~92 MB
+  total.
+- **Ingestion throughput falls ~3.3× from 1k to 100k** — dual-writing SQLite,
+  FTS5, and usearch, with HNSW insertion getting more expensive as the graph
+  grows. The harness ingests in 5k-row batches and the sidecar is reserialised
+  after each one (20 writes at 100k); measured throughput (6505 docs/s) is
+  within run-to-run noise of the pre-persistence number (6482), but a workload
+  of many tiny batches would pay more, since each save rewrites the whole graph.
+- **Peak RSS at 100k (430 MB) is inflated by the Python driver** holding the
+  whole synthetic corpus (100k × 64 floats as Python lists) in memory at once.
+  The native cross-check below is the honest engine-only number.
+
+### Native cross-check (`benchmarks/run_benchmarks.cpp`, no Python in the loop)
+
+20 000 random unit vectors, 200 queries:
+
+| | value |
+|---|---|
+| SQLite on disk | 8.58 MB |
+| Peak RSS (engine only) | 37.7 MB |
+| Ingest throughput | 783 docs/s |
+| dense p50 / p95 / p99 | 0.671 / 0.736 / 0.793 ms |
+| hybrid p50 / p95 / p99 | 0.938 / 0.999 / 1.048 ms |
+
+The engine's own peak RSS for 20k docs is **~38 MB**, versus the 79–430 MB the
+Python-driven run reports — most of that difference is the driver, not the
+engine. Ingest throughput here (783 docs/s) is a *worst case*: uniformly random
+64-dim vectors are the hardest input for HNSW (every candidate is roughly
+equidistant), whereas the structured corpus in the Python run indexes 8–28×
+faster. Real embeddings sit between the two.
+
+---
+
+## Honest tradeoffs & writeup
+
+### Where this engine wins
+
+- **Exact entity / keyword matches.** The FTS5 BM25 side nails rare tokens
+  (names, IDs, error codes) — 1.000 recall at every size here — and RRF makes
+  `hybrid` inherit that for free. A pure vector store cannot do this without a
+  separate keyword index bolted on.
+- **Fusion is strictly safer than dense-only.** `hybrid` never lost recall
+  relative to `dense` in any configuration; when the dense signal degraded, RRF
+  fell back on sparse automatically. You do not have to tune which retriever to
+  trust per query.
+- **Recency-biased agent memory is built in.** `hybrid_decay` held nDCG ≈ 0.997
+  across all sizes by preferring recent relevant memories — the Mem0/Zep-style
+  capability, in-process, no service, one `decay_lambda` parameter.
+- **Zero-dependency deployment.** One process, one SQLite file plus a
+  `.usearch` sidecar, an in-memory usearch index. No server to run, no
+  container, nothing listening on a port. Engine-only peak RSS is ~38 MB for
+  20k docs.
+- **Instant startup via the disk-backed index sidecar.** The HNSW graph is
+  serialised to `<db>.usearch` on write and memory-loaded on the next open:
+  **24.5 ms at 100k**, versus 14.6 s to rebuild it from SQLite. Cold start is
+  no longer a function of corpus size.
+- **Dense retrieval is fast and scale-stable.** Sub-0.2 ms p50 at 100k, ~5700
+  q/s single-threaded.
+- **SQLite stays authoritative.** The sidecar is a cache: if it is missing,
+  truncated, or its vector count disagrees with the chunk table, the engine
+  discards it and rebuilds — a corrupt index is never data loss.
+
+### Where it loses or bottlenecks
+
+- **Sparse/hybrid query latency grows with corpus size** — ~49 ms p50 at 100k,
+  ~20 q/s. FTS5's BM25 over an OR of common terms is the cost. Dense stays
+  sub-millisecond; the fusion is only as fast as its slower half.
+- **`hybrid_decay` has a fat tail.** The extra recency re-scoring pass pushes
+  100k p99 to ~87 ms and throughput to ~14 q/s.
+- **Dual-write ingestion overhead, plus sidecar reserialisation.** Every
+  document hits SQLite, FTS5, and usearch; throughput drops ~3.3× from 1k to
+  100k, and HNSW insertion cost is sensitive to how clustered the embeddings
+  are (783 → 22k docs/s depending on input). Each `add_documents` call also
+  rewrites the whole `.usearch` sidecar — negligible for bulk ingest,
+  meaningful for a stream of one-document writes.
+- **Single-threaded, not concurrency-safe.** `RetrievalEngine` must be confined
+  to one thread or externally locked; there is no query parallelism yet.
+- **Small embedding dimensions collide.** dim 64 is fine for a demo; production
+  needs 384–1024, which raises the memory and index-build numbers accordingly.
+
+### DX comparison
+
+| | This engine | sqlite-vec + glue | ChromaDB | Qdrant / Weaviate / Milvus |
+|---|---|---|---|---|
+| Deployment | in-process library, 1 file | in-process (SQLite ext) | embedded lib **or** server | separate server / cluster |
+| Process to run | none | none | none (embedded) / one (server) | one+ (plus its deps) |
+| Hybrid dense+sparse | built in (RRF) | DIY: wire up FTS5 + your own fusion | dense only (some keyword filtering) | built in (server-side) |
+| Recency / memory semantics | built in (`search_memory`) | DIY | DIY | DIY (metadata + custom scoring) |
+| Rerank / score trail | `search_explained()` | DIY | limited | varies |
+| Persistence model | SQLite authoritative + `.usearch` sidecar | SQLite table | DuckDB/parquet | own storage engine |
+| Index persistence | ✅ sidecar file, auto-managed | ✅ (rows in SQLite) | ✅ | ✅ |
+| Ops surface | none | none | small | real (scaling, backups, upgrades) |
+| Language | C++ core + Python | C + your language | Python-first | any (client libs) |
+| Best fit | desktop / CLI / edge agent, local-first, privacy | you already live in SQLite and want vectors | Python RAG prototypes | multi-tenant, large-scale, networked |
+
+**When to reach for something else:** if you need horizontal scale, multi-writer
+concurrency, or sub-10 ms keyword search over millions of docs, a dedicated
+vector DB is the right tool. If you want dense + BM25 + RRF + recency-aware
+memory in one embeddable library with nothing to operate and instant startup,
+that gap is what this engine fills — and the `hybrid` column above (1.000
+recall, no server) is the argument for it.

sqlite_hybrid_search-0.1.0/CMakeLists.txt

@@ -0,0 +1,146 @@
+cmake_minimum_required(VERSION 3.24)
+project(sqlite_hybrid_search LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# The static core library gets linked into the nanobind Python extension (a
+# shared object), so all of its objects must be position-independent. ELF
+# linkers reject non-PIC objects in a shared library; Mach-O does not, which
+# is why this was invisible on macOS.
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+option(RETRIEVAL_ENGINE_BUILD_TESTS "Build the C++ unit tests" ON)
+# OFF by default so the plain C++ dev/test build (`cmake -B build &&
+# cmake --build build`) is completely unaffected; turned ON by
+# pyproject.toml's scikit-build-core config when building the Python
+# extension (`pip install -e .`).
+option(RETRIEVAL_ENGINE_BUILD_PYTHON_BINDINGS "Build the nanobind Python extension module" OFF)
+
+include(FetchContent)
+
+# --- SQLite3 --------------------------------------------------------------
+# Homebrew's sqlite formula is keg-only (macOS ships its own, older sqlite),
+# so it is NOT linked into /opt/homebrew/include or /opt/homebrew/lib by
+# default. Help CMake find the Homebrew ARM64 build explicitly, per
+# CLAUDE.md's M1 Architecture Compatibility directive.
+find_program(HOMEBREW_EXECUTABLE brew)
+if(HOMEBREW_EXECUTABLE)
+    execute_process(
+        COMMAND ${HOMEBREW_EXECUTABLE} --prefix sqlite
+        OUTPUT_VARIABLE HOMEBREW_SQLITE_PREFIX
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        ERROR_QUIET
+    )
+    # `brew --prefix sqlite` prints a path even when the formula is not
+    # installed, so only trust it if the library is actually there.
+    if(HOMEBREW_SQLITE_PREFIX AND EXISTS "${HOMEBREW_SQLITE_PREFIX}/lib")
+        list(APPEND CMAKE_PREFIX_PATH "${HOMEBREW_SQLITE_PREFIX}")
+    endif()
+endif()
+
+find_package(SQLite3 REQUIRED)
+
+# --- usearch (header-only ANN index) ---------------------------------------
+# Fetched via FetchContent rather than assuming a system/Homebrew install
+# (usearch is not packaged in Homebrew).
+FetchContent_Declare(
+    usearch
+    GIT_REPOSITORY https://github.com/unum-cloud/usearch.git
+    GIT_TAG v2.9.2
+    GIT_SHALLOW TRUE
+    # Only the `fp16` submodule: usearch's headers include <fp16/fp16.h> on
+    # targets without native _Float16 (x86_64 without AVX512 -- ARM and
+    # AVX512 use the compiler's own half type). `simsimd`/`stringzilla` are
+    # not referenced by the header subset this project uses.
+    GIT_SUBMODULES "fp16"
+)
+FetchContent_GetProperties(usearch)
+if(NOT usearch_POPULATED)
+    # usearch's own CMakeLists.txt builds C/Python/etc. bindings we don't
+    # need -- we only want its header-only C++ API, so populate the sources
+    # without add_subdirectory()'ing it. CMP0169=OLD keeps the classic
+    # Populate() signature usable for that (superseded by MakeAvailable(),
+    # which always add_subdirectory()s when a CMakeLists.txt is present).
+    cmake_policy(SET CMP0169 OLD)
+    FetchContent_Populate(usearch)
+
+    # v2.9.2 has a genuine upstream bug that fails to compile under
+    # AppleClang: see cmake/patch_usearch_candidates_iterator_bug.cmake.
+    set(USEARCH_SOURCE_DIR "${usearch_SOURCE_DIR}")
+    include(cmake/patch_usearch_candidates_iterator_bug.cmake)
+endif()
+
+add_library(usearch INTERFACE)
+add_library(usearch::usearch ALIAS usearch)
+target_include_directories(usearch SYSTEM INTERFACE "${usearch_SOURCE_DIR}/include")
+if(EXISTS "${usearch_SOURCE_DIR}/fp16/include")
+    target_include_directories(usearch SYSTEM INTERFACE "${usearch_SOURCE_DIR}/fp16/include")
+endif()
+
+# --- ONNX Runtime (built-in embedding backend) ---------------------------
+# The real embed()/add_text()/search_text() backend runs a local ONNX
+# sentence-embedding model (all-MiniLM-L6-v2 by default). ONNX Runtime is
+# NOT header-only and NOT fetchable -- it must be installed
+# (`brew install onnxruntime` on this macOS/ARM64 setup). The option
+# defaults ON but degrades gracefully: if the library isn't found the
+# engine still builds with only the dependency-free mock backend, and any
+# attempt to load a .onnx model reports that clearly at runtime.
+option(RETRIEVAL_ENGINE_WITH_ONNX "Build the ONNX Runtime embedding backend" ON)
+
+if(RETRIEVAL_ENGINE_WITH_ONNX)
+    find_path(ONNXRUNTIME_INCLUDE_DIR onnxruntime_cxx_api.h
+        PATHS /opt/homebrew/include /opt/homebrew/include/onnxruntime /usr/local/include
+              /usr/local/include/onnxruntime /usr/include /usr/include/onnxruntime)
+    find_library(ONNXRUNTIME_LIBRARY NAMES onnxruntime
+        PATHS /opt/homebrew/lib /usr/local/lib /usr/lib)
+
+    if(ONNXRUNTIME_INCLUDE_DIR AND ONNXRUNTIME_LIBRARY)
+        add_library(onnxruntime::onnxruntime UNKNOWN IMPORTED)
+        set_target_properties(onnxruntime::onnxruntime PROPERTIES
+            IMPORTED_LOCATION "${ONNXRUNTIME_LIBRARY}"
+            INTERFACE_INCLUDE_DIRECTORIES "${ONNXRUNTIME_INCLUDE_DIR}")
+        message(STATUS "ONNX Runtime embedding backend: ON (${ONNXRUNTIME_LIBRARY})")
+    else()
+        message(WARNING
+            "ONNX Runtime not found (looked for onnxruntime_cxx_api.h and libonnxruntime); "
+            "building with the mock embedding backend only. To enable the real backend, install "
+            "it (macOS: `brew install onnxruntime`; Linux: extract an onnxruntime-linux-* release "
+            "into /usr/local, or pass -DONNXRUNTIME_INCLUDE_DIR= and -DONNXRUNTIME_LIBRARY=) and "
+            "reconfigure. See README.md.")
+        set(RETRIEVAL_ENGINE_WITH_ONNX OFF)
+    endif()
+endif()
+
+# --- GoogleTest (test framework) -------------------------------------------
+if(RETRIEVAL_ENGINE_BUILD_TESTS)
+    FetchContent_Declare(
+        googletest
+        GIT_REPOSITORY https://github.com/google/googletest.git
+        GIT_TAG v1.18.0
+        GIT_SHALLOW TRUE
+    )
+    # Match the parent project's runtime library on Windows; irrelevant on
+    # macOS but harmless to set.
+    set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+    FetchContent_MakeAvailable(googletest)
+
+    enable_testing()
+    include(GoogleTest)
+endif()
+
+add_subdirectory(core)
+
+# Native benchmark harness (benchmarks/). ON alongside the C++ tests by
+# default; the Python packaging build turns both OFF (see pyproject.toml).
+option(RETRIEVAL_ENGINE_BUILD_BENCHMARKS
+    "Build the native retrieval micro-benchmark (benchmarks/run_benchmarks)"
+    ${RETRIEVAL_ENGINE_BUILD_TESTS})
+if(RETRIEVAL_ENGINE_BUILD_BENCHMARKS)
+    add_subdirectory(benchmarks)
+endif()
+
+if(RETRIEVAL_ENGINE_BUILD_PYTHON_BINDINGS)
+    add_subdirectory(bindings)
+endif()

sqlite_hybrid_search-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashray Adhikari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.