# Overview

The Embedding Service (`EmbeddingService`) provides comprehensive text embedding functionality for the Kamiwaza AI Platform. Located in `kamiwaza_sdk/services/embedding.py`, this service handles text chunking, embedding generation, and provider management.

## Key Features

- Provider-Based Architecture
- Text Chunking with Metadata
- Embedding Generation
- Batch Processing
- Multiple Provider Support
- Stateless Design

## Getting Started

The embedding service requires initializing a provider before use:

```python
from kamiwaza_sdk import KamiwazaClient

client = KamiwazaClient(api_key="your-key")

# Get an embedder instance (required first step)

embedder = client.embedding.get_embedder(

model="nomic-ai/nomic-embed-text-v1.5",  # optional, this is default

provider_type="sentencetransformers",     # optional, this is default

device="cuda"                             # optional, auto-detect if None
)
```

## Text Processing

### Available Methods

- `chunk_text(text: str, max_length: int = 1024, overlap: int = 102, preamble_text: str = "", return_metadata: bool = False) -> Union[List[str], ChunkResponse]`: Split text into chunks
- `embed_chunks(text_chunks: List[str], batch_size: int = 64) -> List[List[float]]`: Generate embeddings for chunks
- `create_embedding(text: str, max_length: int = 1024, overlap: int = 102, preamble_text: str = "") -> EmbeddingOutput`: Create embedding for text
- `get_embedding(text: str, return_offset: bool = False) -> EmbeddingOutput`: Generate embedding for text

```python
# Initialize embedder first

embedder = client.embedding.get_embedder()

# Split text into chunks

chunks = embedder.chunk_text(

text="Long document text...",

max_length=1024,

overlap=102
)

# Or get chunks with metadata

chunk_response = embedder.chunk_text(

text="Long document text...",

max_length=1024,

overlap=102,

return_metadata=True
)

# Access: chunk_response.chunks, chunk_response.offsets, chunk_response.token_counts

# Generate embeddings for chunks

embeddings = embedder.embed_chunks(chunks, batch_size=64)

# Create single embedding

result = embedder.create_embedding("Sample text")

embedding_vector = result.embedding  # List[float]

# Generate embedding (alternative method)

result = embedder.get_embedding("Sample text")

embedding_vector = result.embedding
```

## Provider Management

### Getting an Embedder

The primary method for working with embeddings is through `get_embedder()`:

```python
# Get embedder with default settings

embedder = client.embedding.get_embedder()

# Get embedder with custom model

embedder = client.embedding.get_embedder(

model="sentence-transformers/all-mpnet-base-v2",

provider_type="sentencetransformers",

device="cuda"  # or "cpu", "mps", None for auto-detect
)

# List available providers

providers = client.embedding.get_providers()
```

### Default Configuration

- **Default Model**: `nomic-ai/nomic-embed-text-v1.5`
- **Default Provider**: `sentencetransformers`
- **Default Device**: Auto-detected based on availability

## Return Types

The service returns Pydantic models for structured data:

### EmbeddingOutput

```python
class EmbeddingOutput:

embedding: List[float]  # The embedding vector

offset: Optional[int]   # Offset in original text (if requested)
```

### ChunkResponse

```python
class ChunkResponse:

chunks: List[str]                    # Text chunks

offsets: Optional[List[int]]         # Start positions in original text

token_counts: Optional[List[int]]    # Token count per chunk

metadata: Optional[List[dict]]       # Additional metadata per chunk
```

## Error Handling

The service uses a unified error handling approach:

```python
from kamiwaza_sdk.exceptions import APIError

try:

embedder = client.embedding.get_embedder()

result = embedder.create_embedding("text")

except APIError as e:

print(f"Operation failed: {e}")
```

## Deprecated Methods

The following methods are deprecated and should not be used:

### HuggingFaceEmbedding()
- **Status**: Deprecated
- **Replacement**: Use `get_embedder()` instead
- **Warning**: Logs deprecation warning when called

### reset_model()
- **Status**: Deprecated (no-op in stateless design)
- **Returns**: `{"status": "no-op"}`
- **Note**: Model state is now handled per request

### call()
- **Status**: Deprecated
- **Replacement**: Use `get_embedder()` then call methods on the provider
- **Raises**: `DeprecationWarning`

## Best Practices

1. **Always initialize an embedder first** using `get_embedder()`
2. **Choose appropriate chunk sizes** based on your model's context window
3. **Use batch processing** for multiple texts to improve performance
4. **Handle overlaps properly** to maintain context between chunks
5. **Consider memory usage** when processing large batches
6. **Cache embeddings** when possible to avoid recomputation
7. **Use return_metadata=True** when you need chunk offsets or token counts

## Complete Example

```python
from kamiwaza_sdk import KamiwazaClient

from kamiwaza_sdk.exceptions import APIError

# Initialize client

client = KamiwazaClient(api_key="your-key")

# Get embedder

embedder = client.embedding.get_embedder(

model="nomic-ai/nomic-embed-text-v1.5",

provider_type="sentencetransformers"
)

try:

# Process a document

document = "Your long document text here..."

# Chunk with metadata

chunk_response = embedder.chunk_text(

text=document,

max_length=512,

overlap=50,

return_metadata=True
    )

# Generate embeddings

embeddings = embedder.embed_chunks(

chunk_response.chunks,

batch_size=32
    )

# Process results

for i, (chunk, embedding) in enumerate(zip(chunk_response.chunks, embeddings)):

print(f"Chunk {i}: {len(embedding)} dimensions")

if chunk_response.offsets:

print(f"  Offset: {chunk_response.offsets[i]}")

if chunk_response.token_counts:

print(f"  Tokens: {chunk_response.token_counts[i]}")

except APIError as e:

print(f"Embedding operation failed: {e}")
```