### Install embetter via pip

Source: https://github.com/koaning/embetter/blob/main/README.md

Standard installation command for the core library.

```bash
python -m pip install embetter
```

--------------------------------

### Installing Required Dependencies

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Commands to install optional dependencies for various embetter components.

```bash
pip install embetter[text]  # For sentence-transformers
pip install embetter[vision]  # For timm
pip install embetter[openai]  # For OpenAI
pip install embetter[all]  # For everything
```

--------------------------------

### Install Embetter

Source: https://github.com/koaning/embetter/blob/main/_autodocs/INDEX.md

Install the core library or specific optional dependencies for text, vision, or external API support.

```bash
# Core only
pip install embetter

# With text encoders
pip install "embetter[text]"

# With vision encoders
pip install "embetter[vision]"

# With external API support
pip install "embetter[openai]"
pip install "embetter[cohere]"

# All optional dependencies
pip install "embetter[all]"
```

--------------------------------

### Install Optional Dependencies

Source: https://github.com/koaning/embetter/blob/main/_autodocs/configuration.md

Install specific extras via pip to enable text, vision, or external service support.

```bash
# Text encoders (Sentence-Transformers)
pip install "embetter[text]"

# Vision encoders (timm)
pip install "embetter[vision]"

# PyTorch (required for most encoders)
pip install "embetter[pytorch]"

# External services
pip install "embetter[openai]"
pip install "embetter[cohere]"
pip install "embetter[ollama]"

# All optional dependencies
pip install "embetter[all]"

# Development and documentation
pip install "embetter[dev]"
pip install "embetter[docs]"
```

--------------------------------

### Install optional embetter dependencies

Source: https://github.com/koaning/embetter/blob/main/README.md

Commands to install specific feature sets or all available embeddings.

```bash
python -m pip install "embetter[text]"
python -m pip install "embetter[vision]"
python -m pip install "embetter[all]"
```

--------------------------------

### ContrastiveTuner Usage Example

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/finetune.md

Demonstrates initializing the tuner, training on embeddings, and performing incremental learning with partial_fit.

```python
import numpy as np
from embetter.finetune import ContrastiveTuner
from embetter.text import SentenceEncoder

# Generate embeddings
encoder = SentenceEncoder('all-MiniLM-L6-v2')
texts = ["cat1", "cat2", "dog1", "dog2", "bird1"]
embeddings = encoder.transform(texts)

# Labels indicating class membership
labels = np.array([0, 0, 1, 1, 2])

# Create and train
tuner = ContrastiveTuner(hidden_dim=50, n_neg=3, epochs=20)
tuner.fit(embeddings, labels)

# Transform to get learned embeddings
new_embeddings = tuner.transform(embeddings)

# Incremental learning
tuner = ContrastiveTuner(hidden_dim=50)
batch1_emb = embeddings[:3]
batch1_labels = labels[:3]
tuner.fit(batch1_emb, batch1_labels)

# Add more data
batch2_emb = embeddings[3:]
batch2_labels = labels[3:]
tuner.partial_fit(batch2_emb, batch2_labels, classes=np.unique(batch2_labels))
```

--------------------------------

### Ollama Service Setup

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/external.md

Commands to prepare the local Ollama environment for use with the encoder.

```bash
# Install Ollama from https://ollama.ai
# Then pull an embedding model
ollama pull nomic-embed-text:latest

# Start Ollama service
ollama serve
```

--------------------------------

### FeedForwardTuner Usage Example

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/finetune.md

Demonstrates training the tuner with batch data and incremental updates using partial_fit.

```python
import numpy as np
from embetter.finetune import FeedForwardTuner
from embetter.text import SentenceEncoder

# Generate embeddings using a pretrained encoder
encoder = SentenceEncoder('all-MiniLM-L6-v2')
texts = ["positive example", "negative example", "neutral text"]
embeddings = encoder.transform(texts)

# Labels for each embedding
labels = np.array([1, 0, 1])

# Create and train the tuner
tuner = FeedForwardTuner(hidden_dim=50, n_epochs=500, learning_rate=0.01)
tuner.fit(embeddings, labels)

# Transform to get task-specific embeddings
new_embeddings = tuner.transform(embeddings)

# With partial_fit for streaming data
tuner = FeedForwardTuner(hidden_dim=50, n_epochs=100)
batch1_embeddings = encoder.transform(["text1", "text2"])
batch1_labels = np.array([1, 0])
tuner.partial_fit(batch1_embeddings, batch1_labels, classes=np.array([0, 1]))

batch2_embeddings = encoder.transform(["text3", "text4"])
batch2_labels = np.array([0, 1])
tuner.partial_fit(batch2_embeddings, batch2_labels)

# Continue training with more batches
transformed = tuner.transform(batch1_embeddings)
```

--------------------------------

### SbertLearner Usage Example

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/finetune.md

Demonstrates initializing the learner, fitting on text pairs, transforming data, predicting similarities, and saving the model.

```python
from sentence_transformers import SentenceTransformer
from embetter.finetune import SbertLearner

# Load base model
base_model = SentenceTransformer('all-MiniLM-L6-v2')

# Create learner
learner = SbertLearner(
    sent_tfm=base_model,
    batch_size=16,
    epochs=1,
    warmup_steps=100
)

# Prepare pair data
texts1 = ["cat", "dog", "bird"]
texts2 = ["feline", "canine", "eagle"]
similarities = [1.0, 1.0, 1.0]  # All similar

# Finetune
learner.fit(texts1, texts2, similarities)

# Encode with finetuned model
embeddings = learner.transform(["new text"])

# Predict similarity
sims = learner.predict(["cat"], ["feline"])

# Save finetuned model
learner.to_disk("models/finetuned_sbert")
```

--------------------------------

### SentenceEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/text.md

Examples demonstrating basic usage, quantization, and integration into scikit-learn pipelines.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline
from sklearn.linear_model import LogisticRegression

from embetter.grab import ColumnGrabber
from embetter.text import SentenceEncoder

# Simple usage
encoder = SentenceEncoder('all-MiniLM-L6-v2')
embeddings = encoder.transform(['hello', 'world', 'test'])

# With quantization and custom device
import torch
encoder = SentenceEncoder(
    name='all-MiniLM-L6-v2',
    device=torch.device('cpu'),
    quantize=True
)

# In a pipeline
df = pd.DataFrame({
    "text": ["positive sentiment", "super negative"],
    "label": ["pos", "neg"]
})

pipeline = make_pipeline(
    ColumnGrabber("text"),
    SentenceEncoder('all-MiniLM-L6-v2')
)
embeddings = pipeline.fit_transform(df)

# Classification pipeline
clf_pipeline = make_pipeline(
    ColumnGrabber("text"),
    SentenceEncoder('all-MiniLM-L6-v2'),
    LogisticRegression()
)
clf_pipeline.fit(df, df['label']).predict(df)
```

--------------------------------

### OllamaEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/external.md

Demonstrates initializing the encoder, using it within a scikit-learn pipeline, and configuring batch sizes.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline

from embetter.grab import ColumnGrabber
from embetter.external import OllamaEncoder

# Ensure Ollama is running: ollama serve

df = pd.DataFrame({
    "text": ["positive sentiment", "super negative"],
    "label": ["pos", "neg"]
})

# Simple usage with default localhost
encoder = OllamaEncoder(model="nomic-embed-text:latest")
embeddings = encoder.transform(df['text'].values)

# Custom host
encoder = OllamaEncoder(
    model="nomic-embed-text:latest",
    host="http://ollama-server:11434"
)

# In a pipeline
pipeline = make_pipeline(
    ColumnGrabber("text"),
    OllamaEncoder(model="nomic-embed-text:latest")
)
embeddings = pipeline.fit_transform(df)

# With batch optimization
encoder_large_batch = OllamaEncoder(
    model="nomic-embed-text:latest",
    batch_size=100
)
```

--------------------------------

### LiteTextEncoder Usage

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/text.md

Example demonstrating training, saving, and loading a text encoder pipeline.

```python
from embetter.text import learn_lite_text_embeddings, LiteTextEncoder

# Train and save a model
def text_generator():
    texts = [
        "positive sentiment",
        "super negative",
        "neutral statement",
        # ... more texts
    ]
    for text in texts:
        yield text

# Train the encoder
learn_lite_text_embeddings(
    text_generator(),
    dim=300,
    lite=True,
    path="models/text_encoder.skops"
)

# Load and use
encoder = LiteTextEncoder(path="models/text_encoder.skops")
embeddings = encoder.transform([
    "encode this example",
    "and this one"
])
```

--------------------------------

### AzureOpenAIEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/external.md

Demonstrates initializing the encoder with environment variables, explicit credentials, and integration into a scikit-learn pipeline.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline
from dotenv import load_dotenv

from embetter.grab import ColumnGrabber
from embetter.external import AzureOpenAIEncoder

load_dotenv()  # Load Azure credentials from .env

df = pd.DataFrame({
    "text": ["positive sentiment", "super negative"],
    "label": ["pos", "neg"]
})

# Simple usage with environment variables
encoder = AzureOpenAIEncoder()
embeddings = encoder.transform(df['text'].values)

# Or pass credentials explicitly
encoder = AzureOpenAIEncoder(
    model="text-embedding-ada-002",
    api_key="your-api-key",
    azure_endpoint="https://your-resource.openai.azure.com/",
    api_version="2024-02-15-preview"
)

# In a pipeline
pipeline = make_pipeline(
    ColumnGrabber("text"),
    AzureOpenAIEncoder()
)
embeddings = pipeline.fit_transform(df)
```

--------------------------------

### TextEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/text.md

Demonstrates initialization, transformation, and integration into scikit-learn pipelines.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline
from sklearn.linear_model import LogisticRegression

from embetter.grab import ColumnGrabber
from embetter.text import TextEncoder
from model2vec import StaticModel

# Simple usage with default model
encoder = TextEncoder()
embeddings = encoder.transform(['hello', 'world'])

# With specific model
encoder = TextEncoder('minishlab/potion-base-4M')
embeddings = encoder.transform(['hello', 'world'])

# With pre-loaded model
model = StaticModel.from_pretrained('minishlab/potion-base-8M')
encoder = TextEncoder(model)

# In a pipeline
df = pd.DataFrame({
    "text": ["positive sentiment", "super negative"],
    "label": ["pos", "neg"]
})

pipeline = make_pipeline(
    ColumnGrabber("text"),
    TextEncoder('minishlab/potion-base-8M'),
    LogisticRegression()
)
pipeline.fit(df, df['label']).predict(df)
```

--------------------------------

### OpenAIEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/external.md

Demonstrates initializing the encoder, using it within a scikit-learn pipeline, and configuring batch sizes.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline
from sklearn.linear_model import LogisticRegression
from dotenv import load_dotenv

from embetter.grab import ColumnGrabber
from embetter.external import OpenAIEncoder

load_dotenv()  # Load OPENAI_API_KEY from .env file

df = pd.DataFrame({
    "text": ["positive sentiment", "super negative"],
    "label": ["pos", "neg"]
})

# Simple usage
encoder = OpenAIEncoder(model="text-embedding-ada-002")
embeddings = encoder.transform(df['text'].values)

# In a pipeline
pipeline = make_pipeline(
    ColumnGrabber("text"),
    OpenAIEncoder(model="text-embedding-ada-002")
)
embeddings = pipeline.fit_transform(df)

# Classification pipeline
clf_pipeline = make_pipeline(
    ColumnGrabber("text"),
    OpenAIEncoder(),
    LogisticRegression()
)
clf_pipeline.fit(df, df['label']).predict(df)

# With custom batch size
encoder_large = OpenAIEncoder(batch_size=100)  # Larger batches for efficiency
```

--------------------------------

### TimmEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/vision.md

Demonstrates initializing the encoder, processing images, and integrating it into a scikit-learn pipeline.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline

from embetter.grab import ColumnGrabber
from embetter.vision import ImageLoader, TimmEncoder

df = pd.DataFrame({
    "filepaths": ["image1.jpg", "image2.jpg"]
})

# Simple usage with default MobileNetV3
encoder = TimmEncoder(name="mobilenetv3_large_100")
images = ImageLoader(convert="RGB").fit_transform(df['filepaths'].values)
embeddings = encoder.fit_transform(images)

# Using ResNet50 for more powerful features
encoder = TimmEncoder(name="resnet50")

# Get predictions instead of embeddings
encoder_pred = TimmEncoder(name="resnet50", encode_predictions=True)
predictions = encoder_pred.fit_transform(images)

# In a full pipeline
pipe = make_pipeline(
    ColumnGrabber("filepaths"),
    ImageLoader(convert="RGB"),
    TimmEncoder(name="efficientnet_b0")
)

embeddings = pipe.fit_transform(df)

# With ViT for transformer-based features
encoder_vit = TimmEncoder(name="vit_base_patch16_224")
```

--------------------------------

### Build image embedding pipeline

Source: https://github.com/koaning/embetter/blob/main/README.md

Example showing how to load images from paths and process them using CLIP embeddings.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline 
from sklearn.linear_model import LogisticRegression

from embetter.grab import ColumnGrabber
from embetter.vision import ImageLoader
from embetter.multi import ClipEncoder

# This pipeline grabs the `img_path` column from a dataframe
# then it grabs the image paths and turns them into `PIL.Image` objects
# which then get fed into CLIP which can also handle images.
image_emb_pipeline = make_pipeline(
  ColumnGrabber("img_path"),
  ImageLoader(convert="RGB"),
  ClipEncoder()
)

dataf = pd.DataFrame({
  "img_path": ["tests/data/thiscatdoesnotexist.jpeg"]
})
image_emb_pipeline.fit_transform(dataf)
```

--------------------------------

### ContrastiveLearner Usage Example

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/finetune.md

Demonstrates training a ContrastiveLearner with sentence embeddings and performing inference.

```python
import numpy as np
from embetter.finetune import ContrastiveLearner
from embetter.text import SentenceEncoder

encoder = SentenceEncoder('all-MiniLM-L6-v2')

# Create pairs with similarity labels
texts1 = ["cat", "dog", "cat", "bird"]
texts2 = ["feline", "canine", "kitten", "eagle"]
X1 = encoder.transform(texts1)
X2 = encoder.transform(texts2)

# 1 = similar pairs, 0 = dissimilar pairs
y = np.array([1.0, 1.0, 1.0, 1.0])

# Train
learner = ContrastiveLearner(shape_out=300, batch_size=16, epochs=10)
learner.fit(X1, X2, y)

# Transform new embeddings
new_embeddings = learner.transform(X1)

# Predict similarity on new pairs
new_X1 = encoder.transform(["cat", "dog"])
new_X2 = encoder.transform(["feline", "canine"])
similarities = learner.predict(new_X1, new_X2)
```

--------------------------------

### Cross-Modal Search Example

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/multi.md

Shows how to perform similarity search between text queries and image embeddings.

```python
from embetter.multi import ClipEncoder
from PIL import Image
import numpy as np

encoder = ClipEncoder("clip-ViT-B-32")

# Create embeddings for a set of images
images = [Image.open(f"image_{i}.jpg") for i in range(10)]
image_embeddings = encoder.transform(images)

# Create embeddings for search queries
queries = ["red car", "blue sky", "tree"]
query_embeddings = encoder.transform(queries)

# Find most similar images for each query
from sklearn.metrics.pairwise import cosine_similarity
similarities = cosine_similarity(query_embeddings, image_embeddings)
top_matches = np.argsort(similarities, axis=1)[:, -3:]  # Top 3 for each query
```

--------------------------------

### Triggering ModuleNotFoundError

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Examples of how missing optional dependencies trigger errors during component initialization.

```python
# Missing sentence-transformers
from embetter.text import SentenceEncoder
encoder = SentenceEncoder()
# ModuleNotFoundError: In order to use SentenceEncoder you'll need to install via;
# pip install embetter[text]

# Missing OpenAI library
from embetter.external import OpenAIEncoder
encoder = OpenAIEncoder()
# ModuleNotFoundError: In order to use OpenAIEncoder you'll need to install via;
# pip install embetter[openai]
```

--------------------------------

### CohereEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/external.md

Demonstrates initializing the encoder, transforming text data, and using it within a scikit-learn pipeline.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline
from dotenv import load_dotenv

from embetter.grab import ColumnGrabber
from embetter.external import CohereEncoder

load_dotenv()  # Load COHERE_KEY from .env file

df = pd.DataFrame({
    "text": ["positive sentiment", "super negative"],
    "label": ["pos", "neg"]
})

# Simple usage
encoder = CohereEncoder(model="large")
embeddings = encoder.transform(df['text'].values)

# Using smaller model
encoder_small = CohereEncoder(model="small")

# In a pipeline
pipeline = make_pipeline(
    ColumnGrabber("text"),
    CohereEncoder(model="large")
)
embeddings = pipeline.fit_transform(df)
```

--------------------------------

### learn_lite_text_embeddings Usage

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/text.md

Example showing how to train an encoder using a generator and perform inference.

```python
from embetter.text import learn_lite_text_embeddings, LiteTextEncoder

# Create a text generator
def text_generator():
    texts = [
        "positive sentiment",
        "super negative",
        "neutral statement",
        # ... large dataset
    ]
    for text in texts:
        yield text

# Train the encoder
encoder = learn_lite_text_embeddings(
    text_generator(),
    dim=300,
    lite=True,
    path="models/embeddings.skops",
    max_features=5000
)

# Use directly
embeddings = encoder.transform(["new text", "another text"])

# Or load later
loaded_encoder = LiteTextEncoder(path="models/embeddings.skops")
embeddings = loaded_encoder.transform(["text to encode"])
```

--------------------------------

### ImageLoader Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/vision.md

Demonstrates loading images as PIL objects or numpy arrays, using ImageLoader within a scikit-learn pipeline, and performing grayscale conversion.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline

from embetter.grab import ColumnGrabber
from embetter.vision import ImageLoader, ColorHistogramEncoder

# Simple usage - load images as PIL objects
loader = ImageLoader(convert="RGB", out="pil")
images = loader.transform(["image1.jpg", "image2.jpg"])

# Load as numpy arrays
loader = ImageLoader(convert="RGB", out="numpy")
arrays = loader.transform(["image1.jpg", "image2.jpg"])

# In a pipeline
df = pd.DataFrame({
    "filepaths": ["image1.jpg", "image2.jpg"]
})

pipe = make_pipeline(
    ColumnGrabber("filepaths"),
    ImageLoader(convert="RGB"),
    ColorHistogramEncoder()
)

embeddings = pipe.fit_transform(df)

# Grayscale conversion
loader = ImageLoader(convert="L", out="numpy")
gray_images = loader.transform(["image1.jpg"])
```

--------------------------------

### ClipEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/multi.md

Demonstrates encoding text and images, using pipelines, quantization, and multilingual models.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline
from sklearn.linear_model import LogisticRegression
from PIL import Image

from embetter.grab import ColumnGrabber
from embetter.vision import ImageLoader
from embetter.multi import ClipEncoder

# Encoding text
encoder = ClipEncoder(name="clip-ViT-B-32")
text_embeddings = encoder.transform(["a cat", "a dog", "a bird"])

# Encoding images
images = [Image.open("cat.jpg"), Image.open("dog.jpg")]
image_embeddings = encoder.transform(images)

# Note: embeddings are comparable across text and images in the same space

# In a pipeline for images
df = pd.DataFrame({
    "img_path": ["image1.jpg", "image2.jpg"]
})

pipe = make_pipeline(
    ColumnGrabber("img_path"),
    ImageLoader(convert="RGB"),
    ClipEncoder()
)
embeddings = pipe.fit_transform(df)

# With quantization for smaller memory footprint
encoder_q = ClipEncoder(name="clip-ViT-B-32", quantize=True)

# Using multilingual variant
encoder_multi = ClipEncoder(name="clip-ViT-B-32-multilingual-v1")
embeddings = encoder_multi.transform(["bonjour", "hola", "hello"])

# Text and image similarity
text_emb = encoder.transform(["a red car"])
image_emb = encoder.transform([Image.open("car.jpg")])
# Can compute cosine similarity to compare concepts across modalities

# Classification with embeddings
df_train = pd.DataFrame({
    "img_path": ["cat1.jpg", "dog1.jpg", "cat2.jpg"],
    "label": ["cat", "dog", "cat"]
})

clf_pipeline = make_pipeline(
    ColumnGrabber("img_path"),
    ImageLoader(convert="RGB"),
    ClipEncoder("clip-ViT-B-32"),
    LogisticRegression()
)
clf_pipeline.fit(df_train, df_train['label']).predict(df_train)
```

--------------------------------

### Triggering AuthenticationError

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Examples of how missing or invalid API keys trigger authentication errors.

```python
from embetter.external import OpenAIEncoder

# Missing API key
encoder = OpenAIEncoder()
embeddings = encoder.transform(["hello"])
# AuthenticationError: Incorrect API key provided...

# Invalid API key
import os
os.environ['OPENAI_API_KEY'] = 'invalid-key'
encoder = OpenAIEncoder()
embeddings = encoder.transform(["hello"])
# AuthenticationError: Incorrect API key provided...
```

--------------------------------

### MatryoshkaEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/text.md

Demonstrates basic usage, integration into a scikit-learn pipeline, and configuration with a custom device.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline
from sklearn.linear_model import LogisticRegression

from embetter.grab import ColumnGrabber
from embetter.text import MatryoshkaEncoder

df = pd.DataFrame({
    "text": ["positive sentiment", "super negative"],
    "label": ["pos", "neg"]
})

# Simple usage
encoder = MatryoshkaEncoder()
embeddings = encoder.fit_transform(df['text'].values)

# In a classification pipeline
pipeline = make_pipeline(
    ColumnGrabber("text"),
    MatryoshkaEncoder(),
    LogisticRegression()
)
pipeline.fit(df, df['label']).predict(df)

# With custom device
import torch
encoder = MatryoshkaEncoder(device=torch.device('cuda'))
```

--------------------------------

### Compare distance metrics

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/utils.md

Examples of using different distance metrics for various embedding types.

```python
# Cosine is best for normalized embeddings
distances = calc_distances(inputs, anchors, pipeline, metric="cosine")

# Euclidean for raw vectors
distances = calc_distances(inputs, anchors, pipeline, metric="euclidean")

# Manhattan for sparse vectors
distances = calc_distances(inputs, anchors, pipeline, metric="manhattan")
```

--------------------------------

### ColorHistogramEncoder Usage Examples

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/vision.md

Demonstrates direct usage of the encoder, integration into a scikit-learn pipeline, and configuration with custom bucket counts.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline

from embetter.grab import ColumnGrabber
from embetter.vision import ImageLoader, ColorHistogramEncoder

# Simple usage
df = pd.DataFrame({
    "filepaths": ["image1.jpg", "image2.jpg"]
})

# Direct usage
loader = ImageLoader(convert="RGB")
encoder = ColorHistogramEncoder(n_buckets=256)

images = loader.fit_transform(df['filepaths'].values)
histograms = encoder.fit_transform(images)

# In a full pipeline
pipe = make_pipeline(
    ColumnGrabber("filepaths"),
    ImageLoader(convert="RGB"),
    ColorHistogramEncoder(n_buckets=256)
)

embeddings = pipe.fit_transform(df)

# With fewer buckets for lower-dimensional representation
encoder_64 = ColorHistogramEncoder(n_buckets=64)
histograms = encoder_64.fit_transform(images)  # Output shape: (n_samples, 192)
```

--------------------------------

### Compare lite embeddings with Sentence Transformers

Source: https://github.com/koaning/embetter/blob/main/docs/applications.md

Example of generating embeddings using Sentence Transformers for comparison with lightweight methods.

```python
from embetter.text import SentenceEncoder

sent_enc = SentenceEncoder()
X_orig = sent_enc.transform(texts) # this takes ~13.5s 
X = UMAP().fit_transform(X_orig)
plot_text(X, texts)
```

--------------------------------

### Build text embedding and classification pipelines

Source: https://github.com/koaning/embetter/blob/main/README.md

Example demonstrating how to use ColumnGrabber and SentenceEncoder within scikit-learn pipelines for text data.

```python
import pandas as pd
from sklearn.pipeline import make_pipeline 
from sklearn.linear_model import LogisticRegression

from embetter.grab import ColumnGrabber
from embetter.text import SentenceEncoder

# This pipeline grabs the `text` column from a dataframe
# which then get fed into Sentence-Transformers' all-MiniLM-L6-v2.
text_emb_pipeline = make_pipeline(
  ColumnGrabber("text"),
  SentenceEncoder('all-MiniLM-L6-v2')
)

dataf = pd.DataFrame({
  "text": ["positive sentiment", "super negative"],
  "label_col": ["pos", "neg"]
})
X = text_emb_pipeline.fit_transform(dataf, dataf['label_col'])

# This pipeline can also be trained to make predictions, using
# the embedded features.
text_clf_pipeline = make_pipeline(
  ColumnGrabber("text"),
  SentenceEncoder('all-MiniLM-L6-v2'),
  LogisticRegression()
)
text_clf_pipeline.fit(dataf, dataf['label_col']).predict(dataf)
```

--------------------------------

### Batching iterables with batched

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/utils.md

Examples of using batched to process lists and generators in chunks. Note that the function returns tuples and handles the final batch size dynamically.

```python
from embetter.utils import batched

# Batch a list
items = list(range(100))
for batch in batched(items, n=10):
    print(f"Processing batch of {len(batch)} items")
    # Output: 10 batches of (0,1,2,...,9), (10,11,...,19), etc.

# Batch a generator (memory efficient)
def text_generator():
    for i in range(10000):
        yield f"text {i}"

for batch in batched(text_generator(), n=64):
    print(f"Batch size: {len(batch)}")
    # Process batch

# Convert to list for random access
from embetter.utils import batched
batch_list = list(batched(range(100), n=25))
first_batch = batch_list[0]  # (0, 1, 2, ..., 24)
```

--------------------------------

### ContrastiveTuner.__init__

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/finetune.md

Initializes the ContrastiveTuner with hyperparameters for the training process.

```APIDOC
## ContrastiveTuner.__init__

### Description
Initializes the tuner with configuration for the contrastive learning process.

### Parameters
- **hidden_dim** (int) - Optional - Output dimensionality of the learned representation (default: 50)
- **n_neg** (int) - Optional - Number of negative examples per positive example (default: 3)
- **epochs** (int) - Optional - Number of training epochs (default: 20)
- **learning_rate** (float) - Optional - Learning rate for Adam optimizer (default: 0.001)
```

--------------------------------

### Triggering ValueError

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Examples of invalid parameter usage that result in ValueError exceptions.

```python
# Invalid output format
from embetter.vision import ImageLoader
loader = ImageLoader(out="invalid")
loader.fit(["image.jpg"])  # ValueError: Output format parameter out=invalid...

# Invalid batch size
from embetter.utils import batched
list(batched(range(10), n=0))  # ValueError: n must be at least one

# Missing classes on first partial_fit
from embetter.finetune import FeedForwardTuner
import numpy as np
tuner = FeedForwardTuner()
X = np.random.rand(10, 100)
y = np.array([0, 1, 0, 1, 0, 1, 0, 1, 0, 1])
tuner.partial_fit(X, y, classes=None)  # ValueError: `classes` must be provided...
```

--------------------------------

### Troubleshoot Dependencies and Errors

Source: https://github.com/koaning/embetter/blob/main/_autodocs/INDEX.md

Commands to resolve missing dependencies, authentication issues, GPU availability, and service connectivity.

```bash
# Fix missing dependencies
pip install "embetter[text]"

# Fix API authentication
export OPENAI_API_KEY="sk-..."

# Fix GPU availability
pip install torch --index-url https://download.pytorch.org/whl/cu118

# Fix Ollama connection
ollama serve
```

--------------------------------

### ContrastiveLearner.__init__

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/finetune.md

Initializes the ContrastiveLearner with specified hyperparameters for training.

```APIDOC
## ContrastiveLearner.__init__

### Description
Initializes the ContrastiveLearner instance with configuration for the training process.

### Parameters
- **shape_out** (int) - Optional - Output dimensionality of embeddings (default: 300)
- **batch_size** (int) - Optional - Batch size during training (default: 16)
- **epochs** (int) - Optional - Number of training epochs (default: 1)
- **learning_rate** (float) - Optional - Learning rate for Adam optimizer (default: 2e-05)
```

--------------------------------

### ImageLoader.__init__

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/vision.md

Initializes the ImageLoader with specified color conversion and output format.

```APIDOC
## ImageLoader.__init__(convert: str = "RGB", out: str = "pil")

### Description
Initializes the loader. The `convert` parameter defines the PIL color mode, and `out` defines the return type.

### Parameters
- **convert** (str) - Optional - PIL Image color conversion mode (e.g., "RGB", "RGBA", "L", "HSV"). Default: "RGB".
- **out** (str) - Optional - Output format: "pil" for PIL Image objects, "numpy" for numpy arrays. Default: "pil".
```

--------------------------------

### Import embetter API components

Source: https://github.com/koaning/embetter/blob/main/README.md

Overview of available modules for text, vision, multi-modal, finetuning, and external embedding providers.

```python
# Helpers to grab text or image from pandas column.
from embetter.grab import ColumnGrabber

# Representations/Helpers for computer vision
from embetter.vision import ImageLoader, TimmEncoder, ColorHistogramEncoder

# Representations for text
from embetter.text import SentenceEncoder, MatryoshkaEncoder, TextEncoder

# Representations from multi-modal models
from embetter.multi import ClipEncoder

# Finetuning components 
from embetter.finetune import FeedForwardTuner, ContrastiveTuner, ContrastiveLearner, SbertLearner

# External embedding providers, typically needs an API key
from embetter.external import CohereEncoder, OpenAIEncoder
```

--------------------------------

### OllamaEncoder.__init__

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/external.md

Initializes the OllamaEncoder with the specified model and connection settings.

```APIDOC
## OllamaEncoder(model, host='http://localhost:11434', batch_size=25)

### Description
Initializes the encoder to communicate with a local Ollama service.

### Parameters
- **model** (str) - Required - Ollama model name (e.g., "nomic-embed-text:latest")
- **host** (str) - Optional - URL of Ollama service (default: "http://localhost:11434")
- **batch_size** (int) - Optional - Number of texts to encode per request (default: 25)
```

--------------------------------

### Configure ContrastiveTuner

Source: https://github.com/koaning/embetter/blob/main/_autodocs/configuration.md

Initializes a ContrastiveTuner with output dimensions, negative samples, epochs, and learning rate.

```python
from embetter.finetune import ContrastiveTuner

tuner = ContrastiveTuner(
    hidden_dim=50,        # Output dimension
    n_neg=3,              # Negative samples per positive
    epochs=20,            # Training epochs
    learning_rate=0.001   # Learning rate
)
```

--------------------------------

### Configure ContrastiveLearner

Source: https://github.com/koaning/embetter/blob/main/_autodocs/configuration.md

Initializes a ContrastiveLearner with output shape, batch size, epochs, and learning rate.

```python
from embetter.finetune import ContrastiveLearner

learner = ContrastiveLearner(
    shape_out=300,        # Output dimension
    batch_size=16,        # Training batch size
    epochs=1,             # Training epochs
    learning_rate=2e-05   # Learning rate
)
```

--------------------------------

### SbertLearner.to_disk

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/finetune.md

Saves the finetuned model to a specified directory.

```APIDOC
## SbertLearner.to_disk(path)

### Description
Saves the finetuned SentenceTransformer to disk.

### Parameters
- **path** (str) - Required - Directory path to save the model
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/koaning/embetter/blob/main/_autodocs/INDEX.md

Set required API keys for external providers or configure them via a .env file.

```bash
# OpenAI
export OPENAI_API_KEY="sk-..."

# Azure OpenAI
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://..."
export OPENAI_API_VERSION="2024-02-15-preview"

# Cohere
export COHERE_KEY="..."

# Or use .env file with python-dotenv
# .env
# OPENAI_API_KEY=sk-...
# COHERE_KEY=...
```

--------------------------------

### Configure SbertLearner

Source: https://github.com/koaning/embetter/blob/main/_autodocs/configuration.md

Initializes an SbertLearner using a base SentenceTransformer model with specified training parameters.

```python
from embetter.finetune import SbertLearner
from sentence_transformers import SentenceTransformer

base_model = SentenceTransformer('all-MiniLM-L6-v2')
learner = SbertLearner(
    sent_tfm=base_model,   # Base model (required)
    batch_size=16,         # Training batch size
    epochs=1,              # Training epochs
    warmup_steps=100       # Warmup steps
)
```

--------------------------------

### Initialize ImageLoader

Source: https://github.com/koaning/embetter/blob/main/_autodocs/configuration.md

Configures image loading settings including color space conversion and output format.

```python
from embetter.vision import ImageLoader

loader = ImageLoader(
    convert="RGB",     # Color conversion
    out="pil"          # Output format
)
```

--------------------------------

### Catching NotInstalled ModuleNotFoundError

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Demonstrates how to handle missing optional dependencies when initializing an encoder.

```python
from embetter.text import SentenceEncoder
import sys

try:
    encoder = SentenceEncoder()
    embeddings = encoder.transform(["hello"])
except ModuleNotFoundError as e:
    print(f"Missing dependency: {e}")
    sys.exit(1)
```

--------------------------------

### Verify Environment Configuration

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Check for required environment variables at application startup to prevent runtime failures for external services.

```python
import os
from dotenv import load_dotenv

# Load environment at startup
load_dotenv()

# Verify required variables
required_vars = {
    'OpenAI': ['OPENAI_API_KEY'],
    'Azure': ['AZURE_OPENAI_API_KEY', 'AZURE_OPENAI_ENDPOINT'],
    'Cohere': ['COHERE_KEY'],
}

for service, vars in required_vars.items():
    for var in vars:
        if not os.getenv(var):
            print(f"Warning: {var} not set ({service} features unavailable)")
```

--------------------------------

### Handling FileNotFoundError in embetter

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Shows how to identify missing file paths and verify their existence before processing.

```python
from embetter.vision import ImageLoader

loader = ImageLoader()
images = loader.transform(["nonexistent.jpg"])
# FileNotFoundError: [Errno 2] No such file or directory: 'nonexistent.jpg'

from embetter.text import LiteTextEncoder

encoder = LiteTextEncoder(path="nonexistent_model.skops")
# FileNotFoundError: [Errno 2] No such file or directory: 'nonexistent_model.skops'
```

```python
import os
from embetter.vision import ImageLoader

image_path = "image.jpg"
if not os.path.exists(image_path):
    print(f"Error: {image_path} not found")
else:
    loader = ImageLoader()
    images = loader.transform([image_path])
```

--------------------------------

### ClipEncoder.__init__

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/multi.md

Initializes the ClipEncoder with a specific CLIP model and configuration settings.

```APIDOC
## ClipEncoder.__init__

### Description
Initializes the CLIP encoder instance.

### Parameters
- **name** (str) - Optional - Name of the CLIP model to use (default: "clip-ViT-B-32")
- **device** (torch.device) - Optional - Device to run model on (cpu, cuda, or mps); auto-detects GPU/MPS if available
- **quantize** (bool) - Optional - Enable dynamic quantization to reduce model size (default: False)
- **num_threads** (int) - Optional - Number of threads for PyTorch to use (CPU only)
```

--------------------------------

### Project File Structure

Source: https://github.com/koaning/embetter/blob/main/_autodocs/MANIFEST.md

Visual representation of the documentation directory layout.

```text
/workspace/home/output/
├── README.md                    # Guide to documentation
├── INDEX.md                     # Main navigation and quick-start
├── types.md                     # Type reference
├── configuration.md             # All configuration options
├── errors.md                    # Error handling reference
└── api-reference/
    ├── grab.md                  # Column/key extraction
    ├── text.md                  # Text encoders
    ├── vision.md                # Vision encoders
    ├── multi.md                 # Multi-modal encoder
    ├── external.md              # External API providers
    ├── finetune.md              # Finetuning components
    ├── model.md                 # Model utilities
    └── utils.md                 # Utility functions
```

--------------------------------

### AzureOpenAIEncoder.__init__

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/external.md

Initializes the AzureOpenAIEncoder with model configuration and authentication parameters.

```APIDOC
## AzureOpenAIEncoder.__init__

### Description
Initializes the encoder instance. Requires Azure credentials provided either via environment variables or constructor arguments.

### Parameters
- **model** (str) - Optional - Azure OpenAI embedding deployment name (default: "text-embedding-ada-002")
- **batch_size** (int) - Optional - Number of texts to encode per API call (default: 25)
- **kwargs** (dict) - Optional - Additional arguments for AzureOpenAI client (api_key, azure_ad_token, azure_endpoint, api_version)
```

--------------------------------

### TimmEncoder.__init__

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/vision.md

Initializes the TimmEncoder with a specific model name and configuration for output type.

```APIDOC
## TimmEncoder.__init__(name="mobilenetv3_large_100", encode_predictions=False)

### Description
Initializes the encoder with a pre-trained model from the timm library.

### Parameters
- **name** (str) - Optional - Name of the timm model to use. Defaults to "mobilenetv3_large_100".
- **encode_predictions** (bool) - Optional - If True, output classification predictions instead of pooled embeddings. Defaults to False.
```

--------------------------------

### Load Environment Variables

Source: https://github.com/koaning/embetter/blob/main/_autodocs/configuration.md

Use python-dotenv to load configuration from a .env file before initializing encoders.

```python
from dotenv import load_dotenv

# Load from .env file
load_dotenv()

# Then use encoders normally
from embetter.external import OpenAIEncoder
encoder = OpenAIEncoder()  # Uses OPENAI_API_KEY from .env
```

--------------------------------

### Build a scikit-learn pipeline with Embetter

Source: https://github.com/koaning/embetter/blob/main/_autodocs/INDEX.md

Demonstrates the standard scikit-learn transformer protocol using ColumnGrabber and SentenceEncoder.

```python
# Import components
from embetter.grab import ColumnGrabber
from embetter.text import SentenceEncoder
from sklearn.pipeline import make_pipeline
from sklearn.linear_model import LogisticRegression

# Build pipeline
pipe = make_pipeline(
    ColumnGrabber("text_column"),
    SentenceEncoder('all-MiniLM-L6-v2'),
    LogisticRegression()
)

# Fit and predict
pipe.fit(dataframe, labels)
predictions = pipe.predict(dataframe)
```

--------------------------------

### Setting Authentication Credentials

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Methods for configuring API credentials via environment variables or Python loaders.

```bash
export OPENAI_API_KEY="sk-..."
```

```python
import os
from dotenv import load_dotenv

load_dotenv()  # Loads from .env file
encoder = OpenAIEncoder()
```

--------------------------------

### SbertLearner

Source: https://github.com/koaning/embetter/blob/main/_autodocs/configuration.md

Initializes an SbertLearner using a SentenceTransformer base model.

```APIDOC
## SbertLearner

### Constructor
`embetter.finetune.SbertLearner(sent_tfm, batch_size=16, epochs=1, warmup_steps=100)`

### Parameters
- **sent_tfm** (SentenceTransformer) - Required - Base SentenceTransformer model
- **batch_size** (int) - Optional - Default: 16 - Training batch size
- **epochs** (int) - Optional - Default: 1 - Training epochs
- **warmup_steps** (int) - Optional - Default: 100 - Learning rate warmup steps
```

--------------------------------

### Initialize ClipEncoder

Source: https://github.com/koaning/embetter/blob/main/_autodocs/configuration.md

Configures a multi-modal CLIP encoder for processing text and images.

```python
from embetter.multi import ClipEncoder

encoder = ClipEncoder(
    name="clip-ViT-B-32",  # Model name
    device=None,            # Device
    quantize=False,         # Quantization
    num_threads=None        # CPU threads
)
```

--------------------------------

### Handling ConnectionError in embetter

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Demonstrates how to handle service connectivity issues, specifically for Ollama.

```python
from embetter.external import OllamaEncoder

# Ollama not running
encoder = OllamaEncoder(model="nomic-embed-text:latest")
embeddings = encoder.transform(["hello"])
# ConnectionError: Failed to connect to http://localhost:11434
```

```bash
# For Ollama
ollama serve

# Then in Python
from embetter.external import OllamaEncoder
encoder = OllamaEncoder(model="nomic-embed-text:latest")
embeddings = encoder.transform(["hello"])
```

--------------------------------

### CohereEncoder.__init__

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/external.md

Initializes the CohereEncoder instance with a specific model and batch size.

```APIDOC
## CohereEncoder(model="large", batch_size=10)

### Description
Initializes the encoder. Requires the COHERE_KEY environment variable to be set.

### Parameters
- **model** (str) - Optional - Cohere model size: "small" or "large". Defaults to "large".
- **batch_size** (int) - Optional - Number of texts to encode per API call. Defaults to 10.
```

--------------------------------

### Configure parallel processing

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/utils.md

Demonstrates how to use the n_jobs parameter to control parallel execution.

```python
from embetter.utils import calc_distances
import numpy as np

# Use all CPU cores
distances = calc_distances(
    inputs=large_input_set,
    anchors=anchors,
    pipeline=encoder,
    n_jobs=-1  # -1 uses all available cores
)

# Or specify number of cores
distances = calc_distances(
    inputs=large_input_set,
    anchors=anchors,
    pipeline=encoder,
    n_jobs=4
)
```

--------------------------------

### ContrastiveTuner

Source: https://github.com/koaning/embetter/blob/main/_autodocs/configuration.md

Initializes a ContrastiveTuner for contrastive learning tasks.

```APIDOC
## ContrastiveTuner

### Constructor
`embetter.finetune.ContrastiveTuner(hidden_dim=50, n_neg=3, epochs=20, learning_rate=0.001)`

### Parameters
- **hidden_dim** (int) - Default: 50 - Output embedding dimension
- **n_neg** (int) - Default: 3 - Negative pairs per positive
- **epochs** (int) - Default: 20 - Training epochs
- **learning_rate** (float) - Default: 0.001 - Learning rate
```

--------------------------------

### Handling RuntimeError in embetter

Source: https://github.com/koaning/embetter/blob/main/_autodocs/errors.md

Shows how to resolve device mismatch errors by correctly configuring the device for encoders.

```python
import torch
from embetter.text import SentenceEncoder

# CUDA not available but requested
encoder = SentenceEncoder(device=torch.device("cuda"))
embeddings = encoder.transform(["hello"])
# RuntimeError: CUDA is not available
```

```python
from embetter.text import SentenceEncoder

# Auto-detect (recommended)
encoder = SentenceEncoder(device=None)

# Or explicitly check
import torch
if torch.cuda.is_available():
    device = torch.device("cuda")
else:
    device = torch.device("cpu")
encoder = SentenceEncoder(device=device)
```

--------------------------------

### FeedForwardTuner.__init__

Source: https://github.com/koaning/embetter/blob/main/_autodocs/api-reference/finetune.md

Initializes the FeedForwardTuner with specified hyperparameters for the neural network.

```APIDOC
## FeedForwardTuner.__init__(hidden_dim=50, n_epochs=500, learning_rate=0.01, batch_size=32)

### Description
Initializes the tuner with configuration for the hidden layer size, training epochs, learning rate, and batch size.

### Parameters
- **hidden_dim** (int) - Optional - Size of the hidden layer in the feed-forward network (default: 50)
- **n_epochs** (int) - Optional - Number of training epochs (default: 500)
- **learning_rate** (float) - Optional - Learning rate for Adam optimizer (default: 0.01)
- **batch_size** (int) - Optional - Batch size during training (default: 32)
```

--------------------------------

### View Embetter Project Directory Structure

Source: https://github.com/koaning/embetter/blob/main/_autodocs/README.md

Displays the hierarchical organization of the Embetter source code modules.

```text
embetter/
├── grab.py           → ColumnGrabber, KeyGrabber
├── text/             → Sentence, Text, Matryoshka, LiteText encoders
├── vision/           → Image, ColorHistogram, Timm encoders
├── multi/            → ClipEncoder
├── external/         → OpenAI, Azure, Cohere, Ollama encoders
├── finetune/         → FeedForward, Contrastive, Sbert learners
├── model/            → DifferenceClassifier
├── utils.py          → cached, batched, calc_distances
└── base.py           → EmbetterBase (inherited by all transformers)
```