simmetry 1.0.1__tar.gz

simmetry-1.0.1/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/

simmetry-1.0.1/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to **simmetry** will be documented in this file.
+
+The format is based on **Keep a Changelog**, and this project adheres to **Semantic Versioning**.
+
+## [1.0.1] - 2026-02-21
+### Added
+- Optional Numba acceleration for `pairwise(..., metric="euclidean_sim" | "manhattan_sim")` when installed via `simmetry[fast]`.
+
+### Changed
+- Improved validation and error messages for vector dimension mismatches.
+- Fixed `similarity([], [], metric="auto")` to route to string similarity batch behavior.
+- Project cleanup for public/PyPI release packaging.
+
+## [1.0.0] - 2026-02-21
+### Added
+- Auto similarity (`metric="auto"`) across strings/vectors/points/sets.
+- Batch string APIs (`pairwise_strings`, `topk_strings`).
+- Optional ANN module (`hnswlib` / `faiss-cpu`) via extras.
+- Unified `SimIndex` with `exact` / `hnsw` / `faiss` backends.
+- Composite similarity for dict records (field metrics + weights).

simmetry-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

simmetry-1.0.1/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: simmetry
+Version: 1.0.1
+Summary: Blazing-fast similarity scores for strings, vectors, points, and sets.
+Project-URL: Homepage, https://pypi.org/project/simmetry/
+Project-URL: Repository, https://github.com/algumusrende/simmetry
+Author-email: Ali Can Gumusrende <algumusrende@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cosine,distance,haversine,jaccard,levenshtein,similarity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Provides-Extra: ann
+Requires-Dist: hnswlib>=0.8.0; extra == 'ann'
+Provides-Extra: ann-faiss
+Requires-Dist: faiss-cpu>=1.7.4; extra == 'ann-faiss'
+Provides-Extra: ann-hnsw
+Requires-Dist: hnswlib>=0.8.0; extra == 'ann-hnsw'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: fast
+Requires-Dist: numba>=0.58; extra == 'fast'
+Description-Content-Type: text/markdown
+
+# simmetry
+
+Blazing-fast similarity scores for **strings**, **vectors**, **points**, and **sets** — with a simple API.
+
+## Install
+
+```bash
+pip install simmetry
+pip install "simmetry[fast]"
+```
+
+`simmetry[fast]` enables optional Numba acceleration for `pairwise(..., metric="euclidean_sim")` and `pairwise(..., metric="manhattan_sim")`.
+
+## Quickstart
+
+### One function
+```python
+from simmetry import similarity
+
+similarity("kitten", "sitting", metric="levenshtein")     
+similarity([1,2,3], [1,2,4], metric="cosine")             
+similarity((41.1, 29.0), (41.2, 29.1), metric="haversine_km")
+similarity({1,2,3}, {2,3,4}, metric="jaccard")
+```
+
+### Pairwise matrices (fast for vectors)
+```python
+import numpy as np
+from simmetry import pairwise
+
+X = np.random.randn(1000, 128)
+S = pairwise(X, metric="cosine")          
+```
+
+### Top-k search
+```python
+import numpy as np
+from simmetry import topk
+
+X = np.random.randn(5000, 64)
+q = np.random.randn(64)
+idx, scores = topk(q, X, k=10, metric="cosine")
+```
+
+## Available metrics
+
+```python
+from simmetry import available
+available()             
+available("vector")     
+available("string")     
+available("point")      
+available("set")        
+```
+
+### Vectors
+- `cosine`, `dot`, `euclidean_sim`, `manhattan_sim`, `pearson`
+
+### Strings
+- `levenshtein` (normalized similarity)
+- `jaro_winkler`
+- `ngram_jaccard` (character n-gram set Jaccard)
+- `token_jaccard` (whitespace token set Jaccard)
+
+### Points / Geo
+- `euclidean_2d`
+- `haversine_km`
+
+### Sets
+- `jaccard`, `dice`, `overlap`
+
+## License
+MIT
+## Batch string APIs
+
+If you need many string-to-string similarities (e.g., deduping names), use:
+
+```python
+from simmetry.strings import pairwise_strings, topk_strings
+
+S = pairwise_strings(["item_one", "item_two"], ["item_one", "item_alt"], metric="jaro_winkler")
+idx, scores = topk_strings("samplecorp", ["samplecorp", "examplefinance", "testgroup"], k=2, metric="levenshtein")
+```
+
+## ANN top-k (optional, does NOT bloat core)
+
+For very large vector corpora (100k+), exact `topk()` can be slow. ANN gives fast approximate results.
+
+### hnswlib (recommended)
+```bash
+pip install "simmetry[ann-hnsw]"
+```
+
+```python
+import numpy as np
+from simmetry.ann import build_hnsw
+
+X = np.random.randn(200_000, 128).astype("float32")
+X /= np.linalg.norm(X, axis=1, keepdims=True)  
+
+index = build_hnsw(X, space="cosine")
+labels, distances = index.query(X[0], k=10)
+```
+
+### faiss
+```bash
+pip install "simmetry[ann-faiss]"
+```
+
+```python
+import numpy as np
+from simmetry.ann import build_faiss
+
+X = np.random.randn(200_000, 128).astype("float32")
+X /= np.linalg.norm(X, axis=1, keepdims=True)  
+
+index = build_faiss(X, metric="ip")
+labels, scores = index.query(X[0], k=10)
+```
+
+
+## SimIndex (exact or ANN)
+
+Exact search (no extras):
+
+```python
+import numpy as np
+from simmetry import SimIndex
+
+X = np.random.randn(50_000, 128).astype("float32")
+index = SimIndex(metric="cosine", backend="exact").add(X)
+
+idx, scores = index.query(X[0], k=10)
+```
+
+ANN (optional):
+
+```bash
+pip install "simmetry[ann-hnsw]"
+```
+
+```python
+import numpy as np
+from simmetry import SimIndex
+
+X = np.random.randn(200_000, 128).astype("float32")
+X /= np.linalg.norm(X, axis=1, keepdims=True)
+
+index = SimIndex(metric="cosine", backend="hnsw").add(X)
+labels, distances = index.query(X[0], k=10)
+```
+
+## Auto similarity and composite records
+
+Auto metric selection:
+
+```python
+from simmetry import similarity
+
+similarity("samplecorp", "sample corp")
+similarity((41.0, 29.0), (41.1, 29.1)) 
+similarity({1,2,3}, {2,3,4})         
+```
+
+Composite similarity over dict fields:
+
+```python
+a = {"name": "Entity One", "city": "CityAlpha", "loc": (41.0, 29.0)}
+b = {"name": "Entity One Extended", "city": "CityAlpha", "loc": (41.01, 28.99)}
+
+score = similarity(
+    a, b,
+    metric={"name": "jaro_winkler", "loc": "haversine_km"},
+    weights={"name": 0.7, "loc": 0.3},
+)
+```

simmetry-1.0.1/README.md

@@ -0,0 +1,176 @@
+# simmetry
+
+Blazing-fast similarity scores for **strings**, **vectors**, **points**, and **sets** — with a simple API.
+
+## Install
+
+```bash
+pip install simmetry
+pip install "simmetry[fast]"
+```
+
+`simmetry[fast]` enables optional Numba acceleration for `pairwise(..., metric="euclidean_sim")` and `pairwise(..., metric="manhattan_sim")`.
+
+## Quickstart
+
+### One function
+```python
+from simmetry import similarity
+
+similarity("kitten", "sitting", metric="levenshtein")     
+similarity([1,2,3], [1,2,4], metric="cosine")             
+similarity((41.1, 29.0), (41.2, 29.1), metric="haversine_km")
+similarity({1,2,3}, {2,3,4}, metric="jaccard")
+```
+
+### Pairwise matrices (fast for vectors)
+```python
+import numpy as np
+from simmetry import pairwise
+
+X = np.random.randn(1000, 128)
+S = pairwise(X, metric="cosine")          
+```
+
+### Top-k search
+```python
+import numpy as np
+from simmetry import topk
+
+X = np.random.randn(5000, 64)
+q = np.random.randn(64)
+idx, scores = topk(q, X, k=10, metric="cosine")
+```
+
+## Available metrics
+
+```python
+from simmetry import available
+available()             
+available("vector")     
+available("string")     
+available("point")      
+available("set")        
+```
+
+### Vectors
+- `cosine`, `dot`, `euclidean_sim`, `manhattan_sim`, `pearson`
+
+### Strings
+- `levenshtein` (normalized similarity)
+- `jaro_winkler`
+- `ngram_jaccard` (character n-gram set Jaccard)
+- `token_jaccard` (whitespace token set Jaccard)
+
+### Points / Geo
+- `euclidean_2d`
+- `haversine_km`
+
+### Sets
+- `jaccard`, `dice`, `overlap`
+
+## License
+MIT
+## Batch string APIs
+
+If you need many string-to-string similarities (e.g., deduping names), use:
+
+```python
+from simmetry.strings import pairwise_strings, topk_strings
+
+S = pairwise_strings(["item_one", "item_two"], ["item_one", "item_alt"], metric="jaro_winkler")
+idx, scores = topk_strings("samplecorp", ["samplecorp", "examplefinance", "testgroup"], k=2, metric="levenshtein")
+```
+
+## ANN top-k (optional, does NOT bloat core)
+
+For very large vector corpora (100k+), exact `topk()` can be slow. ANN gives fast approximate results.
+
+### hnswlib (recommended)
+```bash
+pip install "simmetry[ann-hnsw]"
+```
+
+```python
+import numpy as np
+from simmetry.ann import build_hnsw
+
+X = np.random.randn(200_000, 128).astype("float32")
+X /= np.linalg.norm(X, axis=1, keepdims=True)  
+
+index = build_hnsw(X, space="cosine")
+labels, distances = index.query(X[0], k=10)
+```
+
+### faiss
+```bash
+pip install "simmetry[ann-faiss]"
+```
+
+```python
+import numpy as np
+from simmetry.ann import build_faiss
+
+X = np.random.randn(200_000, 128).astype("float32")
+X /= np.linalg.norm(X, axis=1, keepdims=True)  
+
+index = build_faiss(X, metric="ip")
+labels, scores = index.query(X[0], k=10)
+```
+
+
+## SimIndex (exact or ANN)
+
+Exact search (no extras):
+
+```python
+import numpy as np
+from simmetry import SimIndex
+
+X = np.random.randn(50_000, 128).astype("float32")
+index = SimIndex(metric="cosine", backend="exact").add(X)
+
+idx, scores = index.query(X[0], k=10)
+```
+
+ANN (optional):
+
+```bash
+pip install "simmetry[ann-hnsw]"
+```
+
+```python
+import numpy as np
+from simmetry import SimIndex
+
+X = np.random.randn(200_000, 128).astype("float32")
+X /= np.linalg.norm(X, axis=1, keepdims=True)
+
+index = SimIndex(metric="cosine", backend="hnsw").add(X)
+labels, distances = index.query(X[0], k=10)
+```
+
+## Auto similarity and composite records
+
+Auto metric selection:
+
+```python
+from simmetry import similarity
+
+similarity("samplecorp", "sample corp")
+similarity((41.0, 29.0), (41.1, 29.1)) 
+similarity({1,2,3}, {2,3,4})         
+```
+
+Composite similarity over dict fields:
+
+```python
+a = {"name": "Entity One", "city": "CityAlpha", "loc": (41.0, 29.0)}
+b = {"name": "Entity One Extended", "city": "CityAlpha", "loc": (41.01, 28.99)}
+
+score = similarity(
+    a, b,
+    metric={"name": "jaro_winkler", "loc": "haversine_km"},
+    weights={"name": 0.7, "loc": 0.3},
+)
+```

simmetry-1.0.1/bench/run.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import time
+
+import numpy as np
+
+from simmetry import pairwise, topk
+
+
+def main():
+    X = np.random.randn(5000, 128)
+    t0 = time.time()
+    S = pairwise(X[:1000], X[:1000], metric="cosine")
+    t1 = time.time()
+    print("pairwise cosine (1000x1000) seconds:", round(t1 - t0, 4), "shape:", S.shape)
+
+    q = np.random.randn(128)
+    t0 = time.time()
+    idx, scores = topk(q, X, k=10, metric="cosine")
+    t1 = time.time()
+    print("topk cosine seconds:", round(t1 - t0, 6), "idx:", idx[:3], "scores:", scores[:3])
+
+if __name__ == "__main__":
+    main()

simmetry-1.0.1/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "simmetry"
+version = "1.0.1"
+description = "Blazing-fast similarity scores for strings, vectors, points, and sets."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Ali Can Gumusrende", email = "algumusrende@gmail.com" }]
+keywords = ["similarity", "distance", "cosine", "levenshtein", "jaccard", "haversine"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+  "numpy>=1.23",
+]
+
+[project.optional-dependencies]
+fast = [
+  "numba>=0.58",
+]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.4",
+]
+
+ann-hnsw = [
+  "hnswlib>=0.8.0",
+]
+ann-faiss = [
+  "faiss-cpu>=1.7.4",
+]
+ann = [
+  "hnswlib>=0.8.0",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/simmetry/"
+Repository = "https://github.com/algumusrende/simmetry"
+
+[tool.hatch.build.targets.wheel]
+packages = ["simmetry"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

simmetry-1.0.1/simmetry/__init__.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from .api import pairwise, similarity, topk
+from .index import SimIndex
+from .points.core import euclidean_2d, haversine_km
+from .registry import available, get, register
+from .sets.core import dice, jaccard, overlap
+from .strings.jaro import jaro_winkler
+from .strings.levenshtein import levenshtein
+from .strings.ngrams import ngram_jaccard, token_jaccard
+from .vectors.core import cosine, dot, euclidean_sim, manhattan_sim, pearson
+
+register("cosine", cosine, kind="vector")
+register("dot", dot, kind="vector")
+register("euclidean_sim", euclidean_sim, kind="vector")
+register("manhattan_sim", manhattan_sim, kind="vector")
+register("pearson", pearson, kind="vector")
+
+register("levenshtein", levenshtein, kind="string")
+register("jaro_winkler", jaro_winkler, kind="string")
+register("ngram_jaccard", ngram_jaccard, kind="string")
+register("token_jaccard", token_jaccard, kind="string")
+
+register("euclidean_2d", euclidean_2d, kind="point")
+register("haversine_km", haversine_km, kind="point")
+
+register("jaccard", jaccard, kind="set")
+register("dice", dice, kind="set")
+register("overlap", overlap, kind="set")
+
+__all__ = [
+    "similarity",
+    "SimIndex",
+    "pairwise",
+    "topk",
+    "register",
+    "get",
+    "available",
+]

simmetry-1.0.1/simmetry/ann/__init__.py

@@ -0,0 +1,4 @@
+from .faiss_ import FaissIndex, build_faiss
+from .hnsw import HNSWIndex, build_hnsw
+
+__all__ = ["HNSWIndex", "build_hnsw", "FaissIndex", "build_faiss"]

simmetry-1.0.1/simmetry/ann/faiss_.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+
+
+def _require_faiss():
+    try:
+        import faiss
+    except Exception as e:
+        raise ImportError(
+            'faiss is not installed. Install with: pip install "simmetry[ann-faiss]"'
+        ) from e
+    return faiss
+
+
+@dataclass
+class FaissIndex:
+    dim: int
+    metric: Literal["l2", "ip"]
+    index: object
+    n_items: int
+
+    def query(self, q, k: int = 10) -> tuple[np.ndarray, np.ndarray]:
+        q = np.asarray(q, dtype=np.float32)
+        if q.ndim == 1:
+            q = q.reshape(1, -1)
+        distances, labels = self.index.search(q, k)
+        return labels[0], distances[0]
+
+
+def build_faiss(X, metric: Literal["l2", "ip"] = "ip") -> FaissIndex:
+    faiss = _require_faiss()
+    X = np.asarray(X, dtype=np.float32)
+    if X.ndim != 2:
+        raise ValueError("X must be a 2D array of shape (n, dim).")
+    n, dim = X.shape
+
+    if metric == "l2":
+        index = faiss.IndexFlatL2(dim)
+    elif metric == "ip":
+        index = faiss.IndexFlatIP(dim)
+    else:
+        raise ValueError("metric must be 'l2' or 'ip'.")
+
+    index.add(X)
+    return FaissIndex(dim=dim, metric=metric, index=index, n_items=n)

simmetry-1.0.1/simmetry/ann/hnsw.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+
+
+def _require_hnswlib():
+    try:
+        import hnswlib
+    except Exception as e:
+        raise ImportError(
+            'hnswlib is not installed. Install with: pip install "simmetry[ann-hnsw]"'
+        ) from e
+    return hnswlib
+
+
+@dataclass
+class HNSWIndex:
+    dim: int
+    space: Literal["cosine", "l2", "ip"]
+    index: object
+    n_items: int
+
+    def query(self, q, k: int = 10) -> tuple[np.ndarray, np.ndarray]:
+        q = np.asarray(q, dtype=np.float32)
+        if q.ndim == 1:
+            q = q.reshape(1, -1)
+        labels, distances = self.index.knn_query(q, k=k)
+        return labels[0], distances[0]
+
+
+def build_hnsw(
+    X,
+    space: Literal["cosine", "l2", "ip"] = "cosine",
+    ef_construction: int = 200,
+    M: int = 16,
+    ef: int = 50,
+) -> HNSWIndex:
+    hnswlib = _require_hnswlib()
+    X = np.asarray(X, dtype=np.float32)
+    if X.ndim != 2:
+        raise ValueError("X must be a 2D array of shape (n, dim).")
+
+    n, dim = X.shape
+    idx = hnswlib.Index(space=space, dim=dim)
+    idx.init_index(max_elements=n, ef_construction=int(ef_construction), M=int(M))
+    idx.add_items(X, np.arange(n, dtype=np.int32))
+    idx.set_ef(int(ef))
+    return HNSWIndex(dim=dim, space=space, index=idx, n_items=n)