Embedding Operations

Learn how to generate and store embeddings for your documents. Choose between simple utility methods (recommended for beginners) or direct storage methods (for advanced control).

LLM API Integration

The CAIP Agents SDK uses the LLM API (/v1/embeddings endpoint) under the hood for embedding generation. The SDK simplifies the process by automatically handling authentication, batching, and retries.

Learn more: See the LLM API Reference for details on the underlying embedding generation API, supported models, and advanced configuration options.

---

Utility Methods (Recommended)

These high-level methods automatically handle configuration, batching, and error handling.

Process Files Automatically

Best for: Ingesting documentation from files/directories

from caip_agents_sdk import CAIPAgentsClient

client = CAIPAgentsClient()

# Process entire directory
result = await client.build_and_push_embeddings(
    document_path="your_docs_path",
    vector_store_id="your_vector_store_id",
    metadata={"your_metadata_key" : "your_metadata_value"}
)

print(f"✓ Processed {len(result['processed_files'])} files")
print(f"✓ Created {result['total_chunks']} chunks")

Supported File Formats:

• 📄 Text: .txt, .md
• 📑 PDF: .pdf
• 📝 Word: .docx, .doc
• 🌐 Web: .html, .htm
• 📋 Other: .rtf, .odt

What it does:

1. ✅ Extracts text from files automatically
2. ✅ Chunks text into optimal sizes
3. ✅ Generates embeddings in batches
4. ✅ Uploads to your vector store

Batch Text to Embeddings

Best for: Converting many texts to embeddings

texts = [
    "Authentication requires Bearer token",
    "Rate limits are 1000 requests per hour",
    "API keys are managed in the dashboard"
]

# Much faster than individual calls!
embeddings = await client.batch_text_to_embeddings(
    texts=texts,
    vector_store_id="your_vector_store_id"
)

print(f"Generated {len(embeddings)} embeddings")

Performance: ⚡ 10-100x faster than individual calls

Single Text to Embedding

Best for: Converting queries or single texts

# Convert a single text
embedding = await client.text_to_embedding(
    text="your_query_text",
    vector_store_id="your_vector_store_id"
)

print(f"Embedding dimension: {len(embedding)}")

Method Comparison

Method	Use When	Speed	Complexity
build_and_push_embeddings()	Processing files/directories	Fast	Easiest
batch_text_to_embeddings()	Converting many texts	Very Fast	Easy
text_to_embedding()	Single text conversion	Medium	Easy
create_embeddings()	Storing pre-computed embeddings	N/A	Advanced

---

Direct Storage Methods (Advanced)

Use these methods when you already have embeddings and just need to store them in your vector store.

Store Pre-Computed Embeddings

Best for: When you already have embeddings from an external source or pre-computed them

# If you already have embeddings (e.g., from another service or pre-computed)
pre_computed_embeddings = [
    [0.1, 0.2, 0.3, ...],  # 1536 dimensions for text-embedding-3-small
    [0.4, 0.5, 0.6, ...],  # Second embedding
    [0.7, 0.8, 0.9, ...]   # Third embedding
]

texts = [
    "Authentication requires Bearer token",
    "Rate limits are 1000 requests per hour",
    "API keys are managed in the dashboard"
]

# Store embeddings directly in vector store
await client.create_embeddings(
    vector_store_id="your-vector-store-id",
    embedding_data={
        "embeddings": pre_computed_embeddings,
        "chunks": texts,
        "documentIds": ["doc-1", "doc-2", "doc-3"],
        "sequences": [0, 0, 0],  # Each is a single chunk
        "metadata": [
            {"category": "api", "topic": "auth"},
            {"category": "api", "topic": "limits"},
            {"category": "api", "topic": "keys"}
        ]
    }
)

print(f"✅ Stored {len(pre_computed_embeddings)} embeddings")

Batch Storage with Document Chunking

Best for: Storing embeddings for multi-chunk documents

# Example: A document split into multiple chunks
document_chunks = [
    "Chapter 1: Introduction to the platform...",
    "Chapter 2: Authentication methods...",
    "Chapter 3: Advanced features..."
]

# Pre-computed embeddings for each chunk (from external source)
chunk_embeddings = [
    [0.1, 0.2, ...],  # Embedding for Chapter 1
    [0.3, 0.4, ...],  # Embedding for Chapter 2
    [0.5, 0.6, ...]   # Embedding for Chapter 3
]

# Store with proper sequencing
await client.create_embeddings(
    vector_store_id="your-vector-store-id",
    embedding_data={
        "embeddings": chunk_embeddings,
        "chunks": document_chunks,
        "documentIds": ["manual.pdf", "manual.pdf", "manual.pdf"],  # Same document
        "sequences": [0, 1, 2],  # Chunk order: first, second, third
        "metadata": [
            {"filename": "manual.pdf", "chapter": 1, "page": 1},
            {"filename": "manual.pdf", "chapter": 2, "page": 15},
            {"filename": "manual.pdf", "chapter": 3, "page": 30}
        ]
    }
)

print(f"✅ Stored {len(chunk_embeddings)} chunks from manual.pdf")

Understanding sequences

The sequences field tracks chunk order for multi-chunk documents:

# Example: Document split into 3 chunks
documentIds = ["manual.pdf", "manual.pdf", "manual.pdf"]
sequences = [0, 1, 2]  # First, second, third chunk

# Example: Three separate documents (1 chunk each)
documentIds = ["doc1.txt", "doc2.txt", "doc3.txt"]
sequences = [0, 0, 0]  # Each is the first (and only) chunk

tip

For simple cases where each text is a single document, use [0] * len(texts) - each text is the first (and only) chunk.

Managing Embeddings

List stored embeddings:

# List all embeddings in vector store
embeddings = await client.list_embeddings(
    vector_store_id="your-vector-store-id"
)

for emb in embeddings:
    print(f"- {emb.embeddingId}: {emb.chunk[:50]}...")

Delete embeddings:

# Delete specific embeddings by document ID
await client.delete_embeddings(
    vector_store_id="your-vector-store-id",
    delete_request={
        "documentIds": ["doc-1", "doc-2"]  # Remove specific documents
    }
)

# Delete all embeddings from vector store
await client.delete_embeddings(
    vector_store_id="your-vector-store-id",
    delete_request={
        "deleteAll": True
    }
)

Important

When using create_embeddings(), ensure:

• Embedding dimensions match your vector store configuration
• documentIds and sequences arrays have the same length as embeddings
• Embeddings are normalized (if required by your vector store)

---

Complete Example

import asyncio
from caip_agents_sdk import CAIPAgentsClient

async def ingest_documentation():
    """Complete example using utility methods."""
    client = CAIPAgentsClient()
    
    # 1. Create vector store
    vs = await client.create_vector_store({
        "name": "Documentation",
        "embeddingModel": "text-embedding-3-small", 
        "embeddingDimension": 1536
    })
    vs_id = vs.vectorStoreId
    
    # 2. Ingest documents (easiest method)
    result = await client.build_and_push_embeddings(
        document_path="your_document_path",
        vector_store_id=vs_id,
        metadata={"your_metadata_key":"your_metadata_value"}
    )
    
    print(f"✅ Processed {len(result['processed_files'])} files")
    print(f"✅ Created {result['total_chunks']} chunks")
    
    # 3. Convert query to embedding for search
    query_embedding = await client.text_to_embedding(
        text="How do I authenticate?",
        vector_store_id=vs_id
    )
    
    # 4. Search
    search_results = await client.vector_search(
        vector_store_id=vs_id,
        search_request={
            "queryEmbedding": query_embedding,
            "limit": 10,  # Change accordingly
            "scoreThreshold": 0, # Change accordingly
            "includeEmbeddings": False # Change True to False
        }
    )
    # Extract results from response (Pydantic model)
    results = search_results.results if hasattr(search_results, 'results') else []
    print(f"✅ Found {len(results)} results")

if __name__ == "__main__":
    asyncio.run(ingest_documentation())

---

Next Steps

• Search & Filtering - Learn search strategies
• Best Practices - Optimization tips
• Overview - Back to main guide