EmbedPrefix

A lightweight Python utility for managing embedding prefixes across different embedding models.

Many embedding models require specific prefixes (e.g. query:, passage:, search_document:) depending on the task being performed. EmbedPrefix provides a simple interface for registering those prefixes and applying them consistently.

Features

• Simple API
• Multiple prefix strategies per model
• Configurable prefix position (start or end)
• Optional separators
• Built-in loaders for common embedding models
• Easy to extend for custom models

---

Installation

Clone the repository:

pip install embedsavior

No external dependencies are required.

---

Quick Start

IntFloat E5

from embedprefix import EmbedPrefixLoaders

emb = EmbedPrefixLoaders.load_intfloat_e5()

query = emb.capsule(
    "What is artificial intelligence?",
    strategy="query"
)

document = emb.capsule(
    "Artificial intelligence is a branch of computer science.",
    strategy="input"
)

print(query)
# query: What is artificial intelligence?

print(document)
# passage: Artificial intelligence is a branch of computer science.

---

Nomic Embed

from embedprefix import EmbedPrefixLoaders

emb = EmbedPrefixLoaders.load_nomic()

query = emb.capsule(
    "What is machine learning?",
    strategy="query"
)

document = emb.capsule(
    "Machine learning is a field of AI.",
    strategy="input"
)

print(query)
# search_query: What is machine learning?

print(document)
# search_document: Machine learning is a field of AI.

---

Creating Your Own Configuration

from embedprefix import EmbedPrefix

emb = EmbedPrefix("my-model")

emb.add_prefix(
    prefix="[QUERY]",
    name="query",
    position="start",
    sep=" "
)

emb.add_prefix(
    prefix="[DOC]",
    name="document",
    position="start",
    sep=" "
)

text = emb.capsule(
    "Hello world",
    strategy="query"
)

print(text)
# [QUERY] Hello world

---

API

EmbedPrefix

Represents a collection of prefix strategies for a single embedding model.

Constructor

EmbedPrefix(model_name: str)

---

add_prefix(...)

Registers a new prefix strategy.

add_prefix(
    prefix: str,
    name: str,
    position: Literal["start", "end"],
    sep: str = "",
    set_default: bool = False,
    force: bool = False
)

Parameters

Parameter	Description
prefix	Prefix string.
name	Strategy name.
position	Prefix placement (start or end).
sep	Separator between prefix and text.
set_default	Marks this strategy as the default.
force	Overwrites an existing strategy with the same name.

---

capsule(...)

Applies a prefix strategy to a text.

capsule(
    text: str,
    strategy: str | None = None
)

Returns a prefixed string.

---

list_strategies()

Returns all registered strategy names.

strategies = emb.list_strategies()

Example

['query', 'input']

---

Built-in Loaders

IntFloat E5

EmbedPrefixLoaders.load_intfloat_e5()

Registered strategies

Strategy	Prefix
query	query:
input	passage:

---

Nomic Embed

EmbedPrefixLoaders.load_nomic()

Registered strategies

Strategy	Prefix
query	search_query:
input	search_document:
cluster	clustering:
clf	classification:

---

Supported Models

Currently included:

• IntFloat E5
• Nomic Embed

Additional loaders can easily be implemented for other embedding models.

---

License

This project is released under the Apache License.