ZerdaZerda

Quickstart

On this page

Fully local, zero API keys

The simplest path uses HuggingFaceEmbedder, which downloads and runs a sentence-transformers model on your machine:

Python · 8 lines
from zerda.embeddings import HuggingFaceEmbedder

embedder = HuggingFaceEmbedder()  # defaults to paraphrase-multilingual-MiniLM-L12-v2
vector = embedder.encode("Hello, world")
print(vector.shape)  # (384,)

vectors = embedder.encode(["first text", "second text"])
print(vectors.shape)  # (2, 384)

Arabic-optimized local embedding

ArabicEmbedder wraps the same local pipeline but adds Arabic-specific text normalization (diacritic removal, hamza normalization, etc.) before encoding:

Python · 5 lines
from zerda.embeddings import ArabicEmbedder

embedder = ArabicEmbedder(normalization_level="standard")
vector = embedder.encode("مرحباً بكم في عالم الذكاء الاصطناعي")
print(embedder.embedding_dim)

Hosted APIs

All three hosted embedders follow the same shape — pass (or export) an API key, then call .encode():

Python · 6 lines
import os
from zerda.embeddings import OpenAIEmbedder

os.environ["OPENAI_API_KEY"] = "sk-..."
embedder = OpenAIEmbedder(model_name="text-embedding-3-small")
vectors = embedder.encode(["first document", "second document"])
Python · 4 lines
from zerda.embeddings import GeminiEmbedder

embedder = GeminiEmbedder(api_key="your-google-api-key", task_type="RETRIEVAL_DOCUMENT")
vectors = embedder.encode(["first document", "second document"])
Python · 4 lines
from zerda.embeddings import MistralEmbedder

embedder = MistralEmbedder(api_key="your-mistral-api-key")
vectors = embedder.encode(["first document", "second document"])

Local server via Ollama

Python · 4 lines
from zerda.embeddings import OllamaEmbedder

embedder = OllamaEmbedder(model_name="nomic-embed-text")  # auto-starts `ollama serve` if needed
vector = embedder.encode("مرحباً Hello")

Computing similarity

Every embedder inherits similarity() and batch_similarity() from BaseEmbedder:

Python · 7 lines
score = embedder.similarity("cats are great", "dogs are great", metric="cosine")

top = embedder.batch_similarity(
    query="machine learning",
    texts=["deep learning", "cooking recipes", "neural networks"],
    top_k=2,
)  # -> [(index, score), (index, score)]

ArabicEmbedder additionally provides its own compute_similarity() and find_most_similar() helpers — see ArabicEmbedder.

Context managers

Every embedder implements __enter__/__exit__ (and BaseEmbedder also implements the async equivalents __aenter__/__aexit__), which log a usage summary and call cleanup() on exit:

Python · 3 lines
with OpenAIEmbedder() as embedder:
    vectors = embedder.encode(texts)
# usage/cost summary logged here

Async usage

BaseEmbedder provides aencode(), aencode_with_cache(), and abatch_similarity(), all of which run the corresponding synchronous method in a thread via asyncio.to_thread — no embedder overrides these, so async support is uniform across the whole package:

Python · 6 lines
import asyncio

async def main():
    vectors = await embedder.aencode(["a", "b", "c"])

asyncio.run(main())

Related pages