symrank 0.1.2

High-performance cosine similarity ranking for Retrieval-Augmented Generation (RAG) pipelines, vector search, and information retrieval, with a Python interface powered by a Rust backend.

Similarity ranking for Retrieval-Augmented Generation

Meta

✨ What is SymRank?

SymRank is a blazing-fast Python library for top-k cosine similarity ranking, designed for vector search, retrieval-augmented generation (RAG), and embedding-based matching.

Built with a Rust + SIMD backend, it offers the speed of native code with the ease of Python.

🚀 Why SymRank?

⚡ Fast: SIMD-accelerated cosine scoring with adaptive parallelism

🧠 Smart: Automatically selects serial or parallel mode based on workload

🔢 Top-K optimized: Efficient inlined heap selection (no full sort overhead)

🐍 Pythonic: Easy-to-use Python API

🦀 Powered by Rust: Safe, high-performance core engine

📦 Installation

You can install SymRank with 'uv' or alternatively using 'pip'.

Recommended (with uv):

uv pip install symrank

Alternatively (using pip):

pip install symrank

🧪 Usage

Basic Example

import symrank as sr

query = [0.1, 0.2, 0.3, 0.4]  # or np.array([...], dtype=np.float32)
candidates = [
    ("doc_1", [0.1, 0.2, 0.3, 0.5]),
    ("doc_2", [0.9, 0.1, 0.2, 0.1]),
    ("doc_3", [0.0, 0.0, 0.0, 1.0]),
]

results = sr.cosine_similarity(query, candidates, k=2)
print(results)

Output

[{'id': 'doc_1', 'score': 0.9987}, {'id': 'doc_3', 'score': 0.8912}]

🧩 API: cosine_similarity(...)

cosine_similarity(
    query_vector,              # List[float] or np.ndarray
    candidate_vectors,         # List[Tuple[str, List[float] or np.ndarray]]
    k=5,                       # Number of top results to return
    batch_size=None,           # Optional: split into batches for large sets
)

'cosine_similarity(...)' Parameters

Parameter	Type	Default	Description
query_vector	List[float] or np.ndarray	required	Vector to search with
candidate_vectors	List[Tuple[str, List[float] or np.ndarray]]	required	(id, vector) pairs to compare against
k	int	5	Number of results to return
batch_size	int or None	None	Optional batch size to reduce memory use

Returns

List of dictionaries with id and score (cosine similarity):

[{"id": "doc_42", "score": 0.8763}, {"id": "doc_17", "score": 0.8451}, ...]

📄 License

This project is licensed under the Apache License 2.0.