kodachi 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- kodachi/__init__.py +6 -0
- kodachi/main.py +288 -0
- kodachi/py.typed +0 -0
- kodachi-0.1.0.dist-info/METADATA +201 -0
- kodachi-0.1.0.dist-info/RECORD +7 -0
- kodachi-0.1.0.dist-info/WHEEL +4 -0
- kodachi-0.1.0.dist-info/licenses/LICENSE +21 -0
kodachi/__init__.py
ADDED
kodachi/main.py
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
"""Approximate nearest neighbor search with random projection trees.
|
|
2
|
+
|
|
3
|
+
This module provides an Annoy-style index that builds a forest of random
|
|
4
|
+
hyperplane trees and searches it for the vectors with the highest cosine
|
|
5
|
+
similarity to a query.
|
|
6
|
+
|
|
7
|
+
Example:
|
|
8
|
+
>>> import numpy as np
|
|
9
|
+
>>> data = np.random.default_rng(0).normal(size=(1000, 16))
|
|
10
|
+
>>> index = Index(dim=16, n_trees=10, seed=42)
|
|
11
|
+
>>> index.build_index(data)
|
|
12
|
+
>>> index.search(data[0], k=5)
|
|
13
|
+
array([...])
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
from dataclasses import dataclass
|
|
18
|
+
import numpy as np
|
|
19
|
+
import heapq
|
|
20
|
+
import itertools
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(slots=True)
|
|
24
|
+
class _Node:
|
|
25
|
+
"""A node of a random projection tree.
|
|
26
|
+
|
|
27
|
+
An internal node splits space by the hyperplane ``normal · x + offset = 0``.
|
|
28
|
+
A leaf node stores the indices of the data points that fall into it.
|
|
29
|
+
|
|
30
|
+
Attributes:
|
|
31
|
+
normal: Unit normal vector of the splitting hyperplane. ``None`` for leaves.
|
|
32
|
+
offset: Bias term of the splitting hyperplane.
|
|
33
|
+
left: Child containing points with ``normal · x + offset < 0``.
|
|
34
|
+
right: Child containing points with ``normal · x + offset > 0``.
|
|
35
|
+
indices: Indices of the data points in this leaf. ``None`` for internal nodes.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
normal: np.ndarray | None = None
|
|
39
|
+
offset: float = 0.0
|
|
40
|
+
left: _Node | None = None
|
|
41
|
+
right: _Node | None = None
|
|
42
|
+
indices: np.ndarray | None = None
|
|
43
|
+
|
|
44
|
+
@property
|
|
45
|
+
def is_leaf(self) -> bool:
|
|
46
|
+
"""bool: Whether this node is a leaf."""
|
|
47
|
+
return self.indices is not None
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class _Helper:
|
|
51
|
+
"""Stateless numerical helpers used by :class:`Index`."""
|
|
52
|
+
|
|
53
|
+
@staticmethod
|
|
54
|
+
def make_offset_and_normal(point_1: np.ndarray, point_2: np.ndarray) -> tuple[np.ndarray, float]:
|
|
55
|
+
"""Computes the hyperplane that equidistantly separates two points.
|
|
56
|
+
|
|
57
|
+
Args:
|
|
58
|
+
point_1: First point, shape ``(dim,)``.
|
|
59
|
+
point_2: Second point, shape ``(dim,)``.
|
|
60
|
+
|
|
61
|
+
Returns:
|
|
62
|
+
A tuple ``(normal, offset)`` where ``normal`` is the unit vector
|
|
63
|
+
pointing from ``point_2`` to ``point_1`` and ``offset`` places the
|
|
64
|
+
hyperplane at their midpoint. If the points are identical,
|
|
65
|
+
``normal`` is the zero vector.
|
|
66
|
+
"""
|
|
67
|
+
normal = point_1 - point_2
|
|
68
|
+
norm = np.linalg.norm(normal)
|
|
69
|
+
if norm > 0:
|
|
70
|
+
normal = normal / norm
|
|
71
|
+
offset = float(np.dot(-normal, (point_1 + point_2) / 2))
|
|
72
|
+
return normal, offset
|
|
73
|
+
|
|
74
|
+
@staticmethod
|
|
75
|
+
def normalize_rows(a: np.ndarray) -> np.ndarray:
|
|
76
|
+
"""L2-normalizes each row of a 2-D array.
|
|
77
|
+
|
|
78
|
+
Rows with zero norm are left unchanged.
|
|
79
|
+
|
|
80
|
+
Args:
|
|
81
|
+
a: Array of shape ``(n, dim)``.
|
|
82
|
+
|
|
83
|
+
Returns:
|
|
84
|
+
A new array of shape ``(n, dim)`` whose non-zero rows have unit length.
|
|
85
|
+
"""
|
|
86
|
+
norms = np.linalg.norm(a, axis=1, keepdims=True)
|
|
87
|
+
norms[norms == 0] = 1
|
|
88
|
+
return a / norms
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
class Index:
|
|
92
|
+
"""Approximate nearest neighbor index based on cosine similarity.
|
|
93
|
+
|
|
94
|
+
The index builds ``n_trees`` random projection trees over L2-normalized
|
|
95
|
+
data. Searching descends every tree toward the query and then explores
|
|
96
|
+
the most promising unvisited branches until enough candidates are
|
|
97
|
+
collected, finally ranking the candidates by exact cosine similarity.
|
|
98
|
+
|
|
99
|
+
Attributes:
|
|
100
|
+
dim: Dimensionality of the vectors.
|
|
101
|
+
n_trees: Number of trees in the forest.
|
|
102
|
+
max_leaf_size: Maximum number of points stored in a single leaf.
|
|
103
|
+
"""
|
|
104
|
+
|
|
105
|
+
def __init__(self, dim: int, n_trees: int = 10, max_leaf_size: int = 32, seed: int | None = None):
|
|
106
|
+
"""Initializes an empty index.
|
|
107
|
+
|
|
108
|
+
Args:
|
|
109
|
+
dim: Dimensionality of the vectors to be indexed.
|
|
110
|
+
n_trees: Number of trees to build. More trees improve recall at
|
|
111
|
+
the cost of memory and build time.
|
|
112
|
+
max_leaf_size: Maximum number of points in a leaf node.
|
|
113
|
+
seed: Seed for the random number generator. Use a fixed value
|
|
114
|
+
for reproducible trees.
|
|
115
|
+
"""
|
|
116
|
+
self.dim = dim
|
|
117
|
+
self.n_trees = n_trees
|
|
118
|
+
self.max_leaf_size = max_leaf_size
|
|
119
|
+
self._rng = np.random.default_rng(seed)
|
|
120
|
+
self._roots: list[_Node] = []
|
|
121
|
+
self._data: np.ndarray | None = None
|
|
122
|
+
|
|
123
|
+
def build_index(self, data: np.ndarray) -> None:
|
|
124
|
+
"""Builds the forest from the given data.
|
|
125
|
+
|
|
126
|
+
Any previously built trees are discarded. The data is copied, cast to
|
|
127
|
+
``float32`` and L2-normalized before indexing.
|
|
128
|
+
|
|
129
|
+
Args:
|
|
130
|
+
data: Array-like of shape ``(n_points, dim)``.
|
|
131
|
+
|
|
132
|
+
Raises:
|
|
133
|
+
ValueError: If ``data`` is not 2-D or its second dimension does
|
|
134
|
+
not equal ``dim``.
|
|
135
|
+
"""
|
|
136
|
+
data = np.asarray(data, dtype=np.float32)
|
|
137
|
+
if data.ndim != 2 or data.shape[1] != self.dim:
|
|
138
|
+
raise ValueError(f"Expected data of shape (n_points, {self.dim}), but got {data.shape}.")
|
|
139
|
+
self._data = _Helper.normalize_rows(data)
|
|
140
|
+
self._roots = []
|
|
141
|
+
all_idx = np.arange(data.shape[0])
|
|
142
|
+
for _ in range(self.n_trees):
|
|
143
|
+
self._roots.append(self._make_tree(all_idx))
|
|
144
|
+
|
|
145
|
+
def _make_tree(self, idx: np.ndarray) -> _Node:
|
|
146
|
+
"""Recursively builds a tree over a subset of the data.
|
|
147
|
+
|
|
148
|
+
Args:
|
|
149
|
+
idx: Indices of the data points to place in this subtree.
|
|
150
|
+
|
|
151
|
+
Returns:
|
|
152
|
+
The root node of the built subtree.
|
|
153
|
+
"""
|
|
154
|
+
node = _Node()
|
|
155
|
+
if len(idx) <= self.max_leaf_size:
|
|
156
|
+
node.indices = idx
|
|
157
|
+
return node
|
|
158
|
+
|
|
159
|
+
point_1, point_2 = self._rng.choice(idx, size=2, replace=False)
|
|
160
|
+
normal, offset = _Helper.make_offset_and_normal(self._data[point_1], self._data[point_2])
|
|
161
|
+
node.normal = normal
|
|
162
|
+
node.offset = offset
|
|
163
|
+
s = self._data[idx] @ normal + offset
|
|
164
|
+
left_mask = 0 > s
|
|
165
|
+
on_mask = 0 == s
|
|
166
|
+
right_mask = 0 < s
|
|
167
|
+
|
|
168
|
+
on = self._rng.permutation(idx[on_mask])
|
|
169
|
+
half = len(on) // 2
|
|
170
|
+
left = np.concatenate((idx[left_mask], on[half:]))
|
|
171
|
+
right = np.concatenate((idx[right_mask], on[:half]))
|
|
172
|
+
|
|
173
|
+
node.left = self._make_tree(left)
|
|
174
|
+
node.right = self._make_tree(right)
|
|
175
|
+
return node
|
|
176
|
+
|
|
177
|
+
def search(self, query: np.ndarray, k: int = 10, search_k: int | None = None) -> np.ndarray:
|
|
178
|
+
"""Finds the approximate ``k`` nearest neighbors of a query.
|
|
179
|
+
|
|
180
|
+
Args:
|
|
181
|
+
query: Query vector of shape ``(dim,)``.
|
|
182
|
+
k: Number of neighbors to return.
|
|
183
|
+
search_k: Number of candidate points to collect before ranking.
|
|
184
|
+
Larger values improve recall at the cost of speed. Defaults
|
|
185
|
+
to ``k * n_trees * 10``. If it is at least the number of
|
|
186
|
+
indexed points, an exact brute-force search is performed
|
|
187
|
+
instead of traversing the trees.
|
|
188
|
+
|
|
189
|
+
Returns:
|
|
190
|
+
Array of up to ``k`` data indices, sorted by descending cosine
|
|
191
|
+
similarity to ``query``.
|
|
192
|
+
|
|
193
|
+
Raises:
|
|
194
|
+
RuntimeError: If :meth:`build_index` has not been called.
|
|
195
|
+
ValueError: If ``query`` does not have shape ``(dim,)``.
|
|
196
|
+
"""
|
|
197
|
+
if self._data is None:
|
|
198
|
+
raise RuntimeError("Index has not been built. Call build_index() first.")
|
|
199
|
+
query = np.asarray(query, dtype=np.float32)
|
|
200
|
+
if query.shape != (self.dim,):
|
|
201
|
+
raise ValueError(f"Expected query of shape ({self.dim},), but got {query.shape}.")
|
|
202
|
+
query = _Helper.normalize_rows(query[None, :])[0]
|
|
203
|
+
if search_k is None:
|
|
204
|
+
search_k = k * self.n_trees * 10
|
|
205
|
+
|
|
206
|
+
if search_k >= len(self._data):
|
|
207
|
+
cand = np.arange(len(self._data))
|
|
208
|
+
else:
|
|
209
|
+
cand = self._collect_candidates(query, search_k)
|
|
210
|
+
|
|
211
|
+
scores = self._data[cand] @ query
|
|
212
|
+
order = np.argsort(-scores)[:k]
|
|
213
|
+
return cand[order]
|
|
214
|
+
|
|
215
|
+
def _collect_candidates(self, query: np.ndarray, search_k: int) -> np.ndarray:
|
|
216
|
+
"""Collects candidate points by best-first traversal of the forest.
|
|
217
|
+
|
|
218
|
+
Args:
|
|
219
|
+
query: Normalized query vector of shape ``(dim,)``.
|
|
220
|
+
search_k: Number of candidates to collect before stopping.
|
|
221
|
+
|
|
222
|
+
Returns:
|
|
223
|
+
Array of unique data indices of the collected candidates.
|
|
224
|
+
"""
|
|
225
|
+
heap: list[tuple[float, int, _Node]] = []
|
|
226
|
+
counter = itertools.count()
|
|
227
|
+
candidates: set[int] = set()
|
|
228
|
+
|
|
229
|
+
for node in self._roots:
|
|
230
|
+
leaf = self.down_node(heap, counter, node, query, np.inf)
|
|
231
|
+
candidates.update(leaf.indices.tolist())
|
|
232
|
+
|
|
233
|
+
while heap and len(candidates) < search_k:
|
|
234
|
+
neg_priority, _, node = heapq.heappop(heap)
|
|
235
|
+
leaf = self.down_node(heap, counter, node, query, -neg_priority)
|
|
236
|
+
candidates.update(leaf.indices.tolist())
|
|
237
|
+
|
|
238
|
+
return np.fromiter(candidates, dtype=np.int64)
|
|
239
|
+
|
|
240
|
+
def down_node(self, heap: list[tuple[float, int, _Node]], counter: itertools.count,
|
|
241
|
+
node: _Node, query: np.ndarray, space: float) -> _Node:
|
|
242
|
+
"""Descends from a node to a leaf, deferring the other branches.
|
|
243
|
+
|
|
244
|
+
At each internal node the query follows the side of the hyperplane it
|
|
245
|
+
lies on, and the opposite branch is pushed onto ``heap`` with a
|
|
246
|
+
priority based on the query's margin to the hyperplane.
|
|
247
|
+
|
|
248
|
+
Args:
|
|
249
|
+
heap: Priority queue of deferred branches, stored as
|
|
250
|
+
``(negated_priority, tie_breaker, node)`` tuples. Modified in place.
|
|
251
|
+
counter: Monotonic counter used as a tie-breaker in ``heap``.
|
|
252
|
+
node: Node to start descending from.
|
|
253
|
+
query: Normalized query vector of shape ``(dim,)``.
|
|
254
|
+
space: Smallest margin accumulated along the path to ``node``.
|
|
255
|
+
|
|
256
|
+
Returns:
|
|
257
|
+
The leaf node reached by the descent.
|
|
258
|
+
"""
|
|
259
|
+
while not node.is_leaf:
|
|
260
|
+
s = float(query @ node.normal + node.offset)
|
|
261
|
+
if s <= 0:
|
|
262
|
+
near, far = node.left, node.right
|
|
263
|
+
else:
|
|
264
|
+
near, far = node.right, node.left
|
|
265
|
+
heapq.heappush(heap, (-min(space, -abs(s)), next(counter), far))
|
|
266
|
+
space = min(space, abs(s))
|
|
267
|
+
node = near
|
|
268
|
+
return node
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
if __name__ == "__main__":
|
|
272
|
+
rng = np.random.default_rng(0)
|
|
273
|
+
n, dim, k = 20000, 32, 10
|
|
274
|
+
data = rng.normal(size=(n, dim))
|
|
275
|
+
queries = rng.normal(size=(100, dim))
|
|
276
|
+
|
|
277
|
+
index = Index(dim=dim, n_trees=10, seed=42)
|
|
278
|
+
index.build_index(data)
|
|
279
|
+
|
|
280
|
+
data_n = _Helper.normalize_rows(data)
|
|
281
|
+
queries_n = _Helper.normalize_rows(queries)
|
|
282
|
+
for search_k in (None, 1000, 5000):
|
|
283
|
+
hits = 0
|
|
284
|
+
for q, qn in zip(queries, queries_n):
|
|
285
|
+
truth = set(np.argsort(-(data_n @ qn))[:k].tolist())
|
|
286
|
+
got = set(index.search(q, k=k, search_k=search_k).tolist())
|
|
287
|
+
hits += len(truth & got)
|
|
288
|
+
print(f"search_k={search_k}: recall@{k} = {hits / (len(queries) * k):.3f}")
|
kodachi/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: kodachi
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Approximate nearest neighbor search with random projection trees.
|
|
5
|
+
Project-URL: Homepage, https://github.com/yuzujelly2222/kodachi
|
|
6
|
+
Project-URL: Documentation, https://yuzujelly2222.github.io/kodachi/
|
|
7
|
+
Project-URL: Repository, https://github.com/yuzujelly2222/kodachi
|
|
8
|
+
Project-URL: Issues, https://github.com/yuzujelly2222/kodachi/issues
|
|
9
|
+
Author: yuzujelly2222
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: ann,cosine-similarity,nearest-neighbor,random-projection,vector-search
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.10
|
|
26
|
+
Requires-Dist: numpy>=1.23
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: build; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
30
|
+
Requires-Dist: twine; extra == 'dev'
|
|
31
|
+
Provides-Extra: docs
|
|
32
|
+
Requires-Dist: furo; extra == 'docs'
|
|
33
|
+
Requires-Dist: myst-parser; extra == 'docs'
|
|
34
|
+
Requires-Dist: sphinx>=7; extra == 'docs'
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
[English](https://github.com/yuzujelly2222/kodachi/blob/main/README.md) | [日本語](https://github.com/yuzujelly2222/kodachi/blob/main/README.ja.md)
|
|
38
|
+
|
|
39
|
+
# kodachi
|
|
40
|
+
|
|
41
|
+
A modern, pure-Python ANN library built on a forest of random projection trees.
|
|
42
|
+
|
|
43
|
+
[](https://pypi.org/project/kodachi/)
|
|
44
|
+
[](https://github.com/yuzujelly2222/kodachi/blob/main/LICENSE)
|
|
45
|
+
[](https://www.python.org/)
|
|
46
|
+
[](https://github.com/yuzujelly2222/kodachi/actions/workflows/tests.yml)
|
|
47
|
+
|
|
48
|
+
> 詳しい日本語の解説は [README.ja.md](https://github.com/yuzujelly2222/kodachi/blob/main/README.ja.md) にあります。
|
|
49
|
+
|
|
50
|
+
## What is this
|
|
51
|
+
|
|
52
|
+
kodachi is an approximate nearest neighbor (ANN) search library built on a forest of
|
|
53
|
+
random projection trees, written in pure Python with NumPy as its only dependency.
|
|
54
|
+
|
|
55
|
+
Graph-based methods such as HNSW (Hierarchical Navigable Small World) dominate modern
|
|
56
|
+
ANN and are faster. Random projection forests, on the other hand, generally use less
|
|
57
|
+
memory and are simpler to understand. kodachi favors ease of installation (no C
|
|
58
|
+
extensions, works anywhere) and readable code over raw speed.
|
|
59
|
+
|
|
60
|
+
Input is a plain numeric array of shape `(n_points, dim)`, so the vectors can come from
|
|
61
|
+
anywhere: text or image embeddings, feature vectors, user/item vectors for
|
|
62
|
+
recommendation — anything you want to search by cosine similarity.
|
|
63
|
+
|
|
64
|
+
The whole implementation fits in a single file, `kodachi/main.py` (about 300 lines),
|
|
65
|
+
so it also works as a readable reference for the algorithm.
|
|
66
|
+
|
|
67
|
+
## Install
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
pip install kodachi
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Depends only on `numpy`. Requires Python 3.10+.
|
|
74
|
+
|
|
75
|
+
## Usage
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
import numpy as np
|
|
79
|
+
from kodachi import Index
|
|
80
|
+
|
|
81
|
+
# Vectors to index (e.g. 10,000 vectors with 64 dimensions)
|
|
82
|
+
data = np.random.default_rng(0).normal(size=(10000, 64))
|
|
83
|
+
|
|
84
|
+
index = Index(dim=64, n_trees=20, seed=42)
|
|
85
|
+
index.build_index(data)
|
|
86
|
+
|
|
87
|
+
# Indices of the top 10 neighbors, sorted by cosine similarity
|
|
88
|
+
neighbors = index.search(data[0], k=10)
|
|
89
|
+
print(neighbors) # -> [0 ...] (the query itself ranks first)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Similarity search over embeddings
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
texts = ["I like apples", "I like oranges", "I commute by train", ...]
|
|
96
|
+
|
|
97
|
+
embeddings = embed(texts) # any embedding model, shape (len(texts), dim)
|
|
98
|
+
|
|
99
|
+
index = Index(dim=embeddings.shape[1], n_trees=30, seed=0)
|
|
100
|
+
index.build_index(embeddings)
|
|
101
|
+
|
|
102
|
+
ids = index.search(embed(["I like fruit"])[0], k=3)
|
|
103
|
+
print([texts[i] for i in ids])
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Trading accuracy for speed
|
|
107
|
+
|
|
108
|
+
Raising `search_k` (the number of candidates collected before ranking) improves recall
|
|
109
|
+
at the cost of speed.
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
index.search(query, k=10) # default: search_k = k * n_trees * 10
|
|
113
|
+
index.search(query, k=10, search_k=5000) # more candidates, higher recall
|
|
114
|
+
index.search(query, k=10, search_k=len(data)) # >= n_points: exact brute-force search
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## How it works
|
|
118
|
+
|
|
119
|
+
**Building** (`build_index` -> `_make_tree`)
|
|
120
|
+
|
|
121
|
+
1. **Normalize** all data to unit length, so splitting by Euclidean distance gives the
|
|
122
|
+
same ranking as cosine similarity.
|
|
123
|
+
2. **Split** by picking two random points and cutting the space with the hyperplane
|
|
124
|
+
equidistant from them. Points exactly on the hyperplane are split evenly.
|
|
125
|
+
3. **Recurse** on each side until it holds at most `max_leaf_size` (default 32) points.
|
|
126
|
+
4. Repeat `n_trees` times to get a forest of trees that each split the space differently.
|
|
127
|
+
|
|
128
|
+
**Searching** (`search` -> `_collect_candidates` -> `down_node`)
|
|
129
|
+
|
|
130
|
+
1. In each tree, descend straight to the leaf on the query's side. Branches not taken
|
|
131
|
+
are pushed onto a priority queue.
|
|
132
|
+
2. Until `search_k` candidates are collected, explore deferred branches in order of how
|
|
133
|
+
close the query was to their hyperplane.
|
|
134
|
+
3. Rank all candidates by exact cosine similarity and return the top `k`.
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
data -> normalize -> recursively split by random bisecting hyperplanes -> n_trees trees
|
|
138
|
+
|
|
139
|
+
query -> normalize -> descend each tree to a leaf (stage 1)
|
|
140
|
+
-> explore branches closest to their hyperplane first (stage 2, up to search_k)
|
|
141
|
+
-> return the top k candidates by cosine similarity
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Let `n` be the number of points, `d` the dimensionality, and `T` the number of trees.
|
|
145
|
+
Building takes roughly `O(T · n · d · log n)`; searching takes `O(T · d · log n)` plus
|
|
146
|
+
`O(search_k · d)` to rank candidates.
|
|
147
|
+
|
|
148
|
+
On 20,000 random 32-dimensional points, `n_trees=20, search_k=4000` reaches recall@10 of
|
|
149
|
+
0.95 at 3.5 ms/query — but NumPy brute force takes only 0.6 ms at this scale. Trees pay
|
|
150
|
+
off with hundreds of thousands of points or more and with structured data such as real
|
|
151
|
+
embeddings. Start with `n_trees` around 20–50 and tune `search_k` on your own data. See
|
|
152
|
+
[README.ja.md](https://github.com/yuzujelly2222/kodachi/blob/main/README.ja.md) for the
|
|
153
|
+
full benchmark table.
|
|
154
|
+
|
|
155
|
+
## API
|
|
156
|
+
|
|
157
|
+
Only the members below are part of the public API; `_Node`, `_Helper`, `_make_tree`,
|
|
158
|
+
and `_collect_candidates` are internal.
|
|
159
|
+
|
|
160
|
+
| Member | Description |
|
|
161
|
+
|---|---|
|
|
162
|
+
| `Index(dim, n_trees=10, max_leaf_size=32, seed=None)` | Create an empty index. Fix `seed` for reproducible trees |
|
|
163
|
+
| `build_index(data)` | Build the forest from an array of shape `(n_points, dim)`. Calling it again rebuilds from scratch |
|
|
164
|
+
| `search(query, k=10, search_k=None)` | Return up to `k` data indices for a `(dim,)` query, sorted by descending cosine similarity |
|
|
165
|
+
| `down_node(heap, counter, node, query, space)` | Low-level helper that descends one branch to a leaf (rarely needed directly) |
|
|
166
|
+
|
|
167
|
+
Invalid input raises:
|
|
168
|
+
|
|
169
|
+
- `ValueError` if `build_index` gets an array that is not 2-D or whose width is not `dim`
|
|
170
|
+
- `ValueError` if `search` gets a query whose shape is not `(dim,)`
|
|
171
|
+
- `RuntimeError` if `search` is called before `build_index`
|
|
172
|
+
|
|
173
|
+
If `k` exceeds the number of points, all points are returned in similarity order.
|
|
174
|
+
|
|
175
|
+
## Documentation & tests
|
|
176
|
+
|
|
177
|
+
The API reference is published at <https://yuzujelly2222.github.io/kodachi/>.
|
|
178
|
+
Its Sphinx source lives in `docs/` and is deployed to GitHub Pages on every push to
|
|
179
|
+
`main`. To build it locally:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
pip install -e ".[docs]"
|
|
183
|
+
sphinx-build docs docs/_build/html
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
A pytest suite lives in `tests/` and runs on GitHub Actions across Windows / macOS /
|
|
187
|
+
Linux and Python 3.10–3.13:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
pip install -e ".[dev]"
|
|
191
|
+
pytest
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## License & credits
|
|
195
|
+
|
|
196
|
+
Distributed under the **MIT License** — see
|
|
197
|
+
[LICENSE](https://github.com/yuzujelly2222/kodachi/blob/main/LICENSE).
|
|
198
|
+
|
|
199
|
+
The algorithm is an independent Python implementation inspired by Spotify's
|
|
200
|
+
[Annoy](https://github.com/spotify/annoy) by Erik Bernhardsson: a forest of trees split
|
|
201
|
+
by random bisecting hyperplanes, searched with a priority queue. No Annoy code is included.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
kodachi/__init__.py,sha256=xBh0YF8_rNic4XXVWSnh_5bRcKjezI3bYFxvj_3okek,149
|
|
2
|
+
kodachi/main.py,sha256=ebXDNVKdVylUXwfMe6mIHTJDBWfyqT86wYBrDA3lqOo,10845
|
|
3
|
+
kodachi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
4
|
+
kodachi-0.1.0.dist-info/METADATA,sha256=QLXiq8lz76-mosNT9vp5PBDfsfXVoO2jHUbFzAx9ZJo,8287
|
|
5
|
+
kodachi-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
6
|
+
kodachi-0.1.0.dist-info/licenses/LICENSE,sha256=ex7DC4yv6V1nZzIIcnfBQ19YRD3Rmaazjww74YONzq0,1070
|
|
7
|
+
kodachi-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 yuzujelly2222
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|