smbt 0.1.0__tar.gz

smbt-0.1.0/LICENSE

@@ -0,0 +1,72 @@
+MIT License
+
+Copyright (c) 2013-2026 Yasuo Tabei
+
+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.
+
+
+================================================================================
+THIRD-PARTY NOTICES
+================================================================================
+
+This distribution bundles third-party source code, licensed as follows.
+
+--------------------------------------------------------------------------------
+1. rsdic — rank/select dictionary (src/rsdic/)
+--------------------------------------------------------------------------------
+
+Copyright (c) 2012 Daisuke Okanohara
+Licensed under the BSD 3-Clause License.
+
+Vendored from https://code.google.com/p/rsdic (commit bf206fb, "fix bug in
+select", 2012-04-22), included unmodified.
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions
+   are met:
+
+   1. Redistributions of source code must retain the above Copyright
+      notice, this list of conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above Copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+   3. Neither the name of the authors nor the names of its contributors
+      may be used to endorse or promote products derived from this
+      software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+   IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+--------------------------------------------------------------------------------
+2. VarByte — variable-byte / delta coder (src/lib/var_byte.{hpp,cpp})
+--------------------------------------------------------------------------------
+
+Copyright (c) 2009 Daisuke Okanohara
+Licensed under the MIT License (same terms as above).

smbt-0.1.0/MANIFEST.in

@@ -0,0 +1,19 @@
+# Files needed to build and test the extension from an sdist.
+include LICENSE README.md pyproject.toml setup.py
+
+# C++ sources and headers (the extension compiles a fixed subset; ship all so
+# transitive includes resolve). The vendored rsdic lives under src/rsdic/.
+recursive-include src *.hpp *.cpp *.h
+recursive-include bindings *.cpp
+
+# Python package and test suite.
+graft python
+graft tests
+
+# Large sample data and the shell regression harness are kept in git only;
+# the golden pytest skips gracefully when they are absent.
+prune dat
+prune test
+prune prog
+
+global-exclude *.o *.so *~ __pycache__/* *.pyc

smbt-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: smbt
+Version: 0.1.0
+Summary: Succinct Multibit Tree: fast Jaccard/Tanimoto similarity search over chemical fingerprints
+Author-email: Yasuo Tabei <yasuo.tabei@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/tb-yasu/smbt
+Project-URL: Repository, https://github.com/tb-yasu/smbt
+Project-URL: Paper (WABI 2012), https://doi.org/10.1007/978-3-642-33122-0_16
+Keywords: cheminformatics,fingerprint,similarity-search,tanimoto,jaccard,succinct-data-structure
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# smbt — Succinct Multibit Tree
+
+Fast Jaccard/Tanimoto similarity search over chemical fingerprints, backed by
+succinct data structures. `smbt` indexes large fingerprint databases in little
+memory and, given a query fingerprint, returns every database entry whose
+Jaccard (Tanimoto) similarity is at or above a threshold.
+
+It is a Python binding around the original C++ implementation from
+[Tabei, WABI 2012](https://doi.org/10.1007/978-3-642-33122-0_16) (see
+[Citation](#citation)).
+
+## Installation
+
+```sh
+pip install smbt
+```
+
+Wheels are provided for macOS (x86_64/arm64) and Linux (x86_64/aarch64) on
+CPython 3.9+. Other platforms build from the source distribution and need a
+C++14 compiler. Windows is not supported yet.
+
+## Quick start
+
+```python
+import smbt
+
+# Each fingerprint is a set of uint32 item ids (e.g. "on" bits of a
+# structural fingerprint). Duplicate ids within a fingerprint are ignored.
+data = [
+    [1, 5, 9],
+    [2, 5, 8],
+    [1, 5, 9, 12],
+]
+
+idx = smbt.build(data, mode=1, minsup=10)
+
+# Every database fingerprint at similarity >= 0.5 to the query,
+# as (id, similarity) sorted by similarity descending then id ascending.
+idx.search([1, 5, 9], similarity=0.5)
+# -> [(0, 1.0), (2, 0.75)]
+
+idx.save("db.smbt")
+smbt.load("db.smbt").search([1, 5, 9], similarity=0.9)
+# -> [(0, 1.0)]
+```
+
+`id` is the 0-based position of the fingerprint in the input. `similarity` is
+the exact Jaccard/Tanimoto coefficient.
+
+Build straight from a file (one whitespace-separated fingerprint per line):
+
+```python
+idx = smbt.build_file("fingerprints.dat", mode=1, minsup=10)
+```
+
+## API
+
+| Call | Description |
+|------|-------------|
+| `smbt.build(data, mode=1, minsup=10, verbose=False)` | Build from a list of fingerprints (each a list of ints). |
+| `smbt.build_file(path, mode=1, minsup=10, verbose=False)` | Build from a fingerprint file. |
+| `smbt.load(path)` | Load an index written by `Index.save`. |
+| `Index.search(query, similarity=0.9)` | `[(id, similarity), ...]` above the threshold. |
+| `Index.save(path)` | Persist the index. |
+| `Index.mode` / `Index.size_in_bytes()` | Mode (1/2/3) and approximate index size. |
+
+`mode` selects the representation; **all three return identical results**:
+
+- **1** — succinct multibit tree + succinct trie (smallest index)
+- **2** — succinct multibit tree + variable-length array
+- **3** — pointer-based multibit tree (uncompressed baseline)
+
+`minsup` is the minimum number of fingerprints per leaf during construction; it
+affects index size and speed, not the result set.
+
+`search()` releases the GIL and is safe to call concurrently from multiple
+threads on the same index. `build`, `save`, and `load` are not thread-safe.
+
+Errors map to Python exceptions: invalid `mode`/`similarity`, an empty dataset,
+an empty fingerprint, or an empty query raise `ValueError`; an unreadable,
+truncated, or unrecognized index raises `smbt.Error`.
+
+## Command-line tools
+
+The original CLI is also available:
+
+```sh
+smbt-build  -mode 1 -minsup 10 fingerprints.dat db.smbt
+smbt-search -similarity 0.9 db.smbt queries.dat
+```
+
+Options must precede the positional arguments. Input format: one fingerprint
+per line, whitespace-separated uint32 item ids (treated as a set; blank lines
+are skipped).
+
+## Constraints
+
+- **64-bit only.** Wheels are built for 64-bit platforms (x86_64, arm64); 32-bit
+  is not supported (the format and the algorithm assume a 64-bit `size_t`).
+- **Index files are not portable across architectures.** They are a raw binary
+  dump assuming 64-bit, same-endianness, same `size_t` width. Build and read an
+  index on the same kind of machine (x86_64 and arm64 are both little-endian, so
+  this is rarely an issue in practice).
+- **Item ids are treated as a dense dimension.** Very large ids (e.g. 2^31)
+  inflate memory; map your fingerprint bits to a compact id range first.
+- Indexes written by pre-0.1 builds (format v1) are not readable; rebuild them.
+- In-memory `build` treats an empty fingerprint as an error, whereas the file
+  path skips blank lines. A blank-line-free file and the equivalent in-memory
+  data produce a byte-identical index.
+
+## How it works
+
+Fingerprints are grouped by cardinality; each group is indexed by one binary
+tree built by recursively splitting on the item that maximizes entropy. Internal
+nodes record the columns that are all-ones / all-zeros within their subtree;
+accumulating these gives an admissible Jaccard upper bound for branch-and-bound
+pruning, and leaves compute the exact Jaccard. Because pruning is admissible and
+leaves are exact, the result set is independent of the tree shape — which is why
+all three modes agree. Modes 1 and 2 encode the trees and the fingerprint store
+with succinct data structures (a vendored rank/select dictionary) to shrink the
+index; mode 3 is the uncompressed pointer-based baseline.
+
+## Citation
+
+If you use this software in academic work, please cite:
+
+> Yasuo Tabei. "Succinct Multibit Tree: Compact Representation of Multibit Trees
+> by Using Succinct Data Structures in Chemical Fingerprint Searches." In
+> *Algorithms in Bioinformatics — 12th International Workshop (WABI 2012)*,
+> Lecture Notes in Computer Science, vol. 7534, pp. 201–213. Springer, 2012.
+> [doi:10.1007/978-3-642-33122-0_16](https://doi.org/10.1007/978-3-642-33122-0_16)
+
+```bibtex
+@inproceedings{tabei2012succinct,
+  author    = {Yasuo Tabei},
+  title     = {Succinct Multibit Tree: Compact Representation of Multibit Trees
+               by Using Succinct Data Structures in Chemical Fingerprint
+               Searches},
+  booktitle = {Algorithms in Bioinformatics -- 12th International Workshop,
+               {WABI} 2012, Ljubljana, Slovenia},
+  series    = {Lecture Notes in Computer Science},
+  volume    = {7534},
+  pages     = {201--213},
+  publisher = {Springer},
+  year      = {2012},
+  doi       = {10.1007/978-3-642-33122-0_16}
+}
+```
+
+## License
+
+MIT (Yasuo Tabei). Bundles the vendored **rsdic** rank/select library
+(BSD-3-Clause, © 2012 Daisuke Okanohara) and a variable-byte coder (MIT, © 2009
+Daisuke Okanohara). See [LICENSE](LICENSE) for full third-party notices.

smbt-0.1.0/README.md

@@ -0,0 +1,154 @@
+# smbt — Succinct Multibit Tree
+
+Fast Jaccard/Tanimoto similarity search over chemical fingerprints, backed by
+succinct data structures. `smbt` indexes large fingerprint databases in little
+memory and, given a query fingerprint, returns every database entry whose
+Jaccard (Tanimoto) similarity is at or above a threshold.
+
+It is a Python binding around the original C++ implementation from
+[Tabei, WABI 2012](https://doi.org/10.1007/978-3-642-33122-0_16) (see
+[Citation](#citation)).
+
+## Installation
+
+```sh
+pip install smbt
+```
+
+Wheels are provided for macOS (x86_64/arm64) and Linux (x86_64/aarch64) on
+CPython 3.9+. Other platforms build from the source distribution and need a
+C++14 compiler. Windows is not supported yet.
+
+## Quick start
+
+```python
+import smbt
+
+# Each fingerprint is a set of uint32 item ids (e.g. "on" bits of a
+# structural fingerprint). Duplicate ids within a fingerprint are ignored.
+data = [
+    [1, 5, 9],
+    [2, 5, 8],
+    [1, 5, 9, 12],
+]
+
+idx = smbt.build(data, mode=1, minsup=10)
+
+# Every database fingerprint at similarity >= 0.5 to the query,
+# as (id, similarity) sorted by similarity descending then id ascending.
+idx.search([1, 5, 9], similarity=0.5)
+# -> [(0, 1.0), (2, 0.75)]
+
+idx.save("db.smbt")
+smbt.load("db.smbt").search([1, 5, 9], similarity=0.9)
+# -> [(0, 1.0)]
+```
+
+`id` is the 0-based position of the fingerprint in the input. `similarity` is
+the exact Jaccard/Tanimoto coefficient.
+
+Build straight from a file (one whitespace-separated fingerprint per line):
+
+```python
+idx = smbt.build_file("fingerprints.dat", mode=1, minsup=10)
+```
+
+## API
+
+| Call | Description |
+|------|-------------|
+| `smbt.build(data, mode=1, minsup=10, verbose=False)` | Build from a list of fingerprints (each a list of ints). |
+| `smbt.build_file(path, mode=1, minsup=10, verbose=False)` | Build from a fingerprint file. |
+| `smbt.load(path)` | Load an index written by `Index.save`. |
+| `Index.search(query, similarity=0.9)` | `[(id, similarity), ...]` above the threshold. |
+| `Index.save(path)` | Persist the index. |
+| `Index.mode` / `Index.size_in_bytes()` | Mode (1/2/3) and approximate index size. |
+
+`mode` selects the representation; **all three return identical results**:
+
+- **1** — succinct multibit tree + succinct trie (smallest index)
+- **2** — succinct multibit tree + variable-length array
+- **3** — pointer-based multibit tree (uncompressed baseline)
+
+`minsup` is the minimum number of fingerprints per leaf during construction; it
+affects index size and speed, not the result set.
+
+`search()` releases the GIL and is safe to call concurrently from multiple
+threads on the same index. `build`, `save`, and `load` are not thread-safe.
+
+Errors map to Python exceptions: invalid `mode`/`similarity`, an empty dataset,
+an empty fingerprint, or an empty query raise `ValueError`; an unreadable,
+truncated, or unrecognized index raises `smbt.Error`.
+
+## Command-line tools
+
+The original CLI is also available:
+
+```sh
+smbt-build  -mode 1 -minsup 10 fingerprints.dat db.smbt
+smbt-search -similarity 0.9 db.smbt queries.dat
+```
+
+Options must precede the positional arguments. Input format: one fingerprint
+per line, whitespace-separated uint32 item ids (treated as a set; blank lines
+are skipped).
+
+## Constraints
+
+- **64-bit only.** Wheels are built for 64-bit platforms (x86_64, arm64); 32-bit
+  is not supported (the format and the algorithm assume a 64-bit `size_t`).
+- **Index files are not portable across architectures.** They are a raw binary
+  dump assuming 64-bit, same-endianness, same `size_t` width. Build and read an
+  index on the same kind of machine (x86_64 and arm64 are both little-endian, so
+  this is rarely an issue in practice).
+- **Item ids are treated as a dense dimension.** Very large ids (e.g. 2^31)
+  inflate memory; map your fingerprint bits to a compact id range first.
+- Indexes written by pre-0.1 builds (format v1) are not readable; rebuild them.
+- In-memory `build` treats an empty fingerprint as an error, whereas the file
+  path skips blank lines. A blank-line-free file and the equivalent in-memory
+  data produce a byte-identical index.
+
+## How it works
+
+Fingerprints are grouped by cardinality; each group is indexed by one binary
+tree built by recursively splitting on the item that maximizes entropy. Internal
+nodes record the columns that are all-ones / all-zeros within their subtree;
+accumulating these gives an admissible Jaccard upper bound for branch-and-bound
+pruning, and leaves compute the exact Jaccard. Because pruning is admissible and
+leaves are exact, the result set is independent of the tree shape — which is why
+all three modes agree. Modes 1 and 2 encode the trees and the fingerprint store
+with succinct data structures (a vendored rank/select dictionary) to shrink the
+index; mode 3 is the uncompressed pointer-based baseline.
+
+## Citation
+
+If you use this software in academic work, please cite:
+
+> Yasuo Tabei. "Succinct Multibit Tree: Compact Representation of Multibit Trees
+> by Using Succinct Data Structures in Chemical Fingerprint Searches." In
+> *Algorithms in Bioinformatics — 12th International Workshop (WABI 2012)*,
+> Lecture Notes in Computer Science, vol. 7534, pp. 201–213. Springer, 2012.
+> [doi:10.1007/978-3-642-33122-0_16](https://doi.org/10.1007/978-3-642-33122-0_16)
+
+```bibtex
+@inproceedings{tabei2012succinct,
+  author    = {Yasuo Tabei},
+  title     = {Succinct Multibit Tree: Compact Representation of Multibit Trees
+               by Using Succinct Data Structures in Chemical Fingerprint
+               Searches},
+  booktitle = {Algorithms in Bioinformatics -- 12th International Workshop,
+               {WABI} 2012, Ljubljana, Slovenia},
+  series    = {Lecture Notes in Computer Science},
+  volume    = {7534},
+  pages     = {201--213},
+  publisher = {Springer},
+  year      = {2012},
+  doi       = {10.1007/978-3-642-33122-0_16}
+}
+```
+
+## License
+
+MIT (Yasuo Tabei). Bundles the vendored **rsdic** rank/select library
+(BSD-3-Clause, © 2012 Daisuke Okanohara) and a variable-byte coder (MIT, © 2009
+Daisuke Okanohara). See [LICENSE](LICENSE) for full third-party notices.

smbt-0.1.0/bindings/smbt_core.cpp

@@ -0,0 +1,235 @@
+/*
+ * smbt_core.cpp — pybind11 bindings for the Succinct Multibit Tree.
+ * Copyright (c) 2013-2026 Yasuo Tabei. MIT License (see LICENSE).
+ *
+ * Exposes a single Python type, smbt._core.Index, that wraps the three C++
+ * implementations (mode 1 = trie, 2 = vla, 3 = mbt) behind one interface.
+ * The 8-byte format tag (mode + 10) that the CLI writes/reads outside the
+ * classes is handled here in save()/load(), mirroring build.cpp/search.cpp.
+ */
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+#include <algorithm>
+#include <fstream>
+#include <memory>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "lib/error.hpp"
+#include "smbt_trie/succinct_multibit_tree_trie.hpp"
+#include "smbt_vla/succinct_multibit_tree_vla.hpp"
+#include "mbt/multibit_tree.hpp"
+
+namespace py = pybind11;
+
+namespace {
+
+typedef std::vector<std::vector<uint32_t> > FpData;
+typedef std::vector<std::pair<uint64_t, double> > Hits;  // (db id, similarity)
+
+void validate_mode(int mode) {
+  if (mode != 1 && mode != 2 && mode != 3)
+    throw std::invalid_argument("mode must be 1, 2 or 3");
+}
+
+void validate_similarity(double similarity) {
+  if (similarity < 0.0 || similarity > 1.0)
+    throw std::invalid_argument("similarity must be in [0, 1]");
+}
+
+// Coerce any path-like (str, os.PathLike, pathlib.Path) to a std::string.
+// Must be called with the GIL held (it invokes os.fspath).
+std::string to_path(const py::object &pathobj) {
+  py::object s = py::module_::import("os").attr("fspath")(pathobj);
+  return s.cast<std::string>();
+}
+
+// Sort hits into a deterministic order: similarity descending, ties by id
+// ascending. Jaccard here is a ratio of integer counts, so it is bit-stable
+// across the three modes and the resulting order is identical for all.
+void sort_hits(Hits &hits) {
+  struct Cmp {
+    bool operator()(const std::pair<uint64_t, double> &a,
+                    const std::pair<uint64_t, double> &b) const {
+      if (a.second != b.second) return a.second > b.second;
+      return a.first < b.first;
+    }
+  };
+  std::sort(hits.begin(), hits.end(), Cmp());
+}
+
+class Index {
+ public:
+  // --- factories -----------------------------------------------------------
+  static Index *build(const FpData &data, int mode, uint64_t minsup, bool verbose) {
+    validate_mode(mode);
+    std::unique_ptr<Index> self(new Index(mode));
+    if (mode == 1) { self->trie_->set_verbose(verbose); self->trie_->build_from_data(data, minsup); }
+    else if (mode == 2) { self->vla_->set_verbose(verbose); self->vla_->build_from_data(data, minsup); }
+    else { self->mbt_->set_verbose(verbose); self->mbt_->build_from_data(data, minsup); }
+    return self.release();
+  }
+
+  static Index *build_file(const py::object &pathobj, int mode, uint64_t minsup, bool verbose) {
+    validate_mode(mode);
+    const std::string path = to_path(pathobj);
+    py::gil_scoped_release nogil;
+    std::unique_ptr<Index> self(new Index(mode));
+    if (mode == 1) { self->trie_->set_verbose(verbose); self->trie_->build(path.c_str(), minsup); }
+    else if (mode == 2) { self->vla_->set_verbose(verbose); self->vla_->build(path.c_str(), minsup); }
+    else { self->mbt_->set_verbose(verbose); self->mbt_->build(path.c_str(), minsup); }
+    return self.release();
+  }
+
+  static Index *load(const py::object &pathobj) {
+    const std::string path = to_path(pathobj);
+    py::gil_scoped_release nogil;
+    std::ifstream ifs(path.c_str(), std::ios::in | std::ios::binary);
+    if (!ifs)
+      throw smbt::Error("cannot open: " + path);
+    uint64_t tag = 0;
+    ifs.read((char *)&tag, sizeof(tag));
+    if (!ifs)
+      throw smbt::Error("error: corrupt or truncated index file: " + path);
+
+    int mode;
+    if (tag == 11) mode = 1;
+    else if (tag == 12) mode = 2;
+    else if (tag == 13) mode = 3;
+    else if (tag == 1 || tag == 2 || tag == 3)
+      throw smbt::Error("error: " + path +
+                        " is an old index format (v1) — rebuild the index with smbt-build.");
+    else {
+      std::ostringstream oss;
+      oss << "error: " << path << " is not a smbt index file (unknown format tag " << tag << ").";
+      throw smbt::Error(oss.str());
+    }
+
+    std::unique_ptr<Index> self(new Index(mode));
+    if (mode == 1) self->trie_->load(ifs);
+    else if (mode == 2) self->vla_->load(ifs);
+    else self->mbt_->load(ifs);
+    return self.release();
+  }
+
+  // --- persistence ---------------------------------------------------------
+  void save(const py::object &pathobj) const {
+    const std::string path = to_path(pathobj);
+    py::gil_scoped_release nogil;
+    std::ofstream ofs(path.c_str(), std::ios::out | std::ios::binary | std::ios::trunc);
+    if (!ofs)
+      throw smbt::Error("cannot open: " + path);
+    const uint64_t tag = (uint64_t)mode_ + 10;
+    ofs.write((const char *)&tag, sizeof(tag));
+    if (mode_ == 1) trie_->save(ofs);
+    else if (mode_ == 2) vla_->save(ofs);
+    else mbt_->save(ofs);
+    ofs.flush();
+    if (!ofs)
+      throw smbt::Error("error writing index file: " + path);
+  }
+
+  // --- query ---------------------------------------------------------------
+  // Not const: the underlying search_fv/search_query are not marked const,
+  // but they only read the succinct structures, so releasing the GIL and
+  // running searches concurrently is data-race-free.
+  Hits search(const std::vector<uint32_t> &query, double similarity) {
+    validate_similarity(similarity);
+    Hits hits;
+    if (mode_ == 1) {
+      std::vector<std::pair<float, uint32_t> > res;
+      trie_->search_fv(query, (float)similarity, res);
+      for (size_t i = 0; i < res.size(); ++i)
+        hits.push_back(std::make_pair((uint64_t)res[i].second, (double)res[i].first));
+    } else if (mode_ == 2) {
+      std::vector<std::pair<float, uint32_t> > res;
+      vla_->search_fv(query, (float)similarity, res);
+      for (size_t i = 0; i < res.size(); ++i)
+        hits.push_back(std::make_pair((uint64_t)res[i].second, (double)res[i].first));
+    } else {
+      std::vector<std::pair<float, uint64_t> > res;
+      mbt_->search_fv(query, (float)similarity, res);
+      for (size_t i = 0; i < res.size(); ++i)
+        hits.push_back(std::make_pair(res[i].second, (double)res[i].first));
+    }
+    sort_hits(hits);
+    return hits;
+  }
+
+  int mode() const { return mode_; }
+
+  uint64_t size_in_bytes() {
+    if (mode_ == 1) return trie_->size_in_bytes();
+    if (mode_ == 2) return vla_->size_in_bytes();
+    return mbt_->size_in_bytes();
+  }
+
+ private:
+  explicit Index(int mode) : mode_(mode) {
+    if (mode_ == 1) trie_.reset(new smbt::trie::SuccinctMultibitTreeTRIE());
+    else if (mode_ == 2) vla_.reset(new smbt::vla::SuccinctMultibitTreeVLA());
+    else mbt_.reset(new smbt::mbt::MultibitTree());
+  }
+
+  int mode_;
+  std::unique_ptr<smbt::trie::SuccinctMultibitTreeTRIE> trie_;
+  std::unique_ptr<smbt::vla::SuccinctMultibitTreeVLA>   vla_;
+  std::unique_ptr<smbt::mbt::MultibitTree>              mbt_;
+};
+
+}  // namespace
+
+PYBIND11_MODULE(_core, m) {
+  m.doc() = "Succinct Multibit Tree: Jaccard/Tanimoto similarity search over fingerprints.";
+
+  py::register_exception<smbt::Error>(m, "Error", PyExc_RuntimeError);
+
+  py::class_<Index>(m, "Index",
+                    "A built (or loaded) similarity-search index. Build with "
+                    "Index(fingerprints, mode=..., minsup=...), Index.from_file(path, ...), "
+                    "or Index.load(path). Not thread-safe for build/save/load, but "
+                    "search() releases the GIL and is safe to call concurrently.")
+      .def(py::init(&Index::build),
+           py::arg("fingerprints"),
+           py::arg("mode") = 1,
+           py::arg("minsup") = 10,
+           py::arg("verbose") = false,
+           py::call_guard<py::gil_scoped_release>(),
+           "Build an index from a list of fingerprints (each a list of uint32 "
+           "item ids). An empty fingerprint raises ValueError.")
+      .def_static("from_file", &Index::build_file,
+                  py::arg("path"),
+                  py::arg("mode") = 1,
+                  py::arg("minsup") = 10,
+                  py::arg("verbose") = false,
+                  "Build an index from a fingerprint file (one whitespace-separated "
+                  "line per fingerprint; blank lines are skipped).")
+      .def_static("load", &Index::load,
+                  py::arg("path"),
+                  "Load an index previously written by save(). Raises smbt.Error for "
+                  "a v1 index (rebuild required) or an unrecognized file.")
+      .def("save", &Index::save,
+           py::arg("path"),
+           "Write the index to a file, tagged with its mode.")
+      .def("search", &Index::search,
+           py::arg("query"),
+           py::arg("similarity") = 0.9,
+           py::call_guard<py::gil_scoped_release>(),
+           "Return [(db_id, similarity), ...] for every database fingerprint whose "
+           "Jaccard/Tanimoto similarity to the query is >= similarity, sorted by "
+           "similarity descending then id ascending. db_id is the 0-based input "
+           "index of the fingerprint. An empty query raises ValueError.")
+      .def_property_readonly("mode", &Index::mode, "The index mode (1, 2 or 3).")
+      .def("size_in_bytes", &Index::size_in_bytes,
+           "Approximate size of the succinct multibit tree(s), in bytes.")
+      .def("__repr__", [](Index &self) {
+        std::ostringstream oss;
+        oss << "<smbt.Index mode=" << self.mode() << ">";
+        return oss.str();
+      });
+}