Metadata-Version: 2.4
Name: embedsavior
Version: 1.0.0
Summary: Embedding Prefix and Template Management Library
Author: iamalreadynoob
Author-email: <sadikefe69@gmail.com>
Keywords: python,embedding,deep learning,deep,data science,data
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license-file
Dynamic: summary


# 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:

```bash
pip install embedsavior
```

No external dependencies are required.

---

## Quick Start

### IntFloat E5

```python
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

```python
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

```python
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

```python
EmbedPrefix(model_name: str)
```

---

### `add_prefix(...)`

Registers a new prefix strategy.

```python
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.

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

Returns a prefixed string.

---

### `list_strategies()`

Returns all registered strategy names.

```python
strategies = emb.list_strategies()
```

Example

```python
['query', 'input']
```

---

## Built-in Loaders

### IntFloat E5

```python
EmbedPrefixLoaders.load_intfloat_e5()
```

Registered strategies

| Strategy | Prefix |
|----------|--------|
| `query` | `query:` |
| `input` | `passage:` |

---

### Nomic Embed

```python
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.
