​
Overview

Vector search in Julep enables semantic search capabilities across your document store. This allows you to find relevant documents based on meaning rather than just keyword matches. This guide covers how to effectively use vector search in your applications.

Perform simple semantic searches:

Python
# Basic semantic search
results = client.agents.docs.search(
    agent_id=agent.id,
    text="How to configure SSL certificates"
)

# Search with limit
results = client.agents.docs.search(
    agent_id=agent.id,
    text="deployment best practices",
    limit=5
)
JavaScript
// Basic semantic search
const results = await client.agents.docs.search({
    agentId: agent.id,
    text: "How to configure SSL certificates"
});

// Search with limit
const results = await client.agents.docs.search({
    agentId: agent.id,
    text: "deployment best practices",
    limit: 5
});

​
Advanced Search Options

​
Metadata Filtering

Combine semantic search with metadata filters:

Python
# Search with metadata filters
results = client.agents.docs.search(
    agent_id=agent.id,
    text="error handling",
    metadata_filter={
        "type": "documentation",
        "version": "2.0",
        "status": "published"
    }
)

# Complex metadata filters
results = client.agents.docs.search(
    agent_id=agent.id,
    text="security configuration",
    metadata_filter={
        "type": {"$in": ["guide", "tutorial"]},
        "tags": {"$contains": "security"},
        "published_at": {"$gt": "2024-01-01"}
    }
)

​
Search Configuration

Customize search behavior:

Python
# Configure search parameters
results = client.agents.docs.search(
    agent_id=agent.id,
    text="API authentication",
    config={
        "similarity_threshold": 0.8,  # Minimum similarity score
        "rerank": True,  # Enable reranking
        "model": "multilingual",  # Use multilingual model
        "chunk_level": True  # Search at chunk level
    }
)

Combine semantic and keyword search:

Python
# Hybrid search
results = client.agents.docs.hybrid_search(
    agent_id=agent.id,
    text="python error handling",
    keywords=["try", "except", "finally"],
    weights={
        "semantic": 0.7,
        "keyword": 0.3
    }
)

​
Search Contexts

Search within specific contexts:

Python
# Search agent documents
agent_results = client.agents.docs.search(
    agent_id=agent.id,
    text="configuration options"
)

# Search user documents
user_results = client.users.docs.search(
    user_id=user.id,
    text="preferences"
)

# Search shared documents
shared_results = client.docs.search(
    text="common guidelines",
    scope="shared"
)

Search across multiple contexts:

Python
# Search across contexts
results = client.docs.search(
    text="security protocols",
    contexts=[
        {"type": "agent", "id": agent.id},
        {"type": "user", "id": user.id},
        {"type": "shared"}
    ]
)

​
Search Processing

​
Result Processing

Process and format search results:

Python
# Get search results with content
results = client.agents.docs.search(
    agent_id=agent.id,
    text="deployment steps",
    include_content=True
)

# Process results
for result in results:
    print(f"Document: {result.title}")
    print(f"Similarity: {result.similarity}")
    print(f"Content: {result.content}")
    print(f"Metadata: {result.metadata}")

​
Result Aggregation

Aggregate results from multiple searches:

Python
# Perform multiple searches
def multi_search(query, contexts):
    all_results = []
    
    for context in contexts:
        results = client.docs.search(
            text=query,
            context=context,
            include_content=True
        )
        all_results.extend(results)
    
    # Sort by similarity
    all_results.sort(key=lambda x: x.similarity, reverse=True)
    
    return all_results[:10]  # Return top 10 results

​
Vector Operations

​
Document Embedding

Work with document embeddings:

Python
# Get document embedding
embedding = client.agents.docs.get_embedding(
    agent_id=agent.id,
    document_id=document.id
)

# Create document with custom embedding
document = client.agents.docs.create(
    agent_id=agent.id,
    title="Custom Embedded Document",
    content="Document content...",
    embedding=custom_embedding
)

​
Embedding Management

Manage document embeddings:

Python
# Update document embedding
client.agents.docs.update_embedding(
    agent_id=agent.id,
    document_id=document.id,
    embedding=new_embedding
)

# Recompute embeddings
client.agents.docs.recompute_embeddings(
    agent_id=agent.id,
    filter={
        "type": "documentation",
        "updated_at": {"$gt": "2024-01-01"}
    }
)

​
Best Practices

  1. Search Optimization

    • Use appropriate similarity thresholds
    • Balance semantic and keyword search
    • Optimize metadata filters

  2. Performance

    • Cache frequent search results
    • Use chunk-level search for large documents
    • Implement pagination for large result sets

  3. Result Quality

    • Validate search results
    • Implement feedback mechanisms
    • Monitor search performance

​
Example: Advanced Search Implementation

Here’s an example of a comprehensive search implementation:

Python
class DocumentSearcher:
    def __init__(self, client, agent_id):
        self.client = client
        self.agent_id = agent_id
        
    def search(self, query, **options):
        # Default search configuration
        config = {
            "similarity_threshold": 0.7,
            "rerank": True,
            "chunk_level": True,
            "limit": 10
        }
        
        # Update with user options
        config.update(options.get("config", {}))
        
        # Perform semantic search
        semantic_results = self.client.agents.docs.search(
            agent_id=self.agent_id,
            text=query,
            config=config,
            metadata_filter=options.get("metadata_filter"),
            include_content=True
        )
        
        # Perform keyword search if specified
        if options.get("keywords"):
            keyword_results = self.client.agents.docs.keyword_search(
                agent_id=self.agent_id,
                keywords=options["keywords"],
                metadata_filter=options.get("metadata_filter")
            )
            
            # Combine results
            results = self._combine_results(
                semantic_results,
                keyword_results,
                weights=options.get("weights", {"semantic": 0.7, "keyword": 0.3})
            )
        else:
            results = semantic_results
        
        # Process results
        processed_results = self._process_results(results)
        
        return processed_results
    
    def _combine_results(self, semantic_results, keyword_results, weights):
        # Combine and score results
        combined = {}
        
        for result in semantic_results:
            combined[result.id] = {
                "score": result.similarity * weights["semantic"],
                "data": result
            }
        
        for result in keyword_results:
            if result.id in combined:
                combined[result.id]["score"] += result.score * weights["keyword"]
            else:
                combined[result.id] = {
                    "score": result.score * weights["keyword"],
                    "data": result
                }
        
        # Sort by combined score
        sorted_results = sorted(
            combined.values(),
            key=lambda x: x["score"],
            reverse=True
        )
        
        return [item["data"] for item in sorted_results]
    
    def _process_results(self, results):
        # Process and format results
        processed = []
        
        for result in results:
            processed.append({
                "id": result.id,
                "title": result.title,
                "content": result.content,
                "similarity": result.similarity,
                "metadata": result.metadata,
                "highlights": self._get_highlights(result)
            })
        
        return processed
    
    def _get_highlights(self, result):
        # Extract relevant highlights from content
        # Implementation depends on your highlighting needs
        pass

# Use the searcher
searcher = DocumentSearcher(client, agent.id)

results = searcher.search(
    "security best practices",
    config={
        "similarity_threshold": 0.8,
        "limit": 5
    },
    metadata_filter={
        "type": "documentation",
        "status": "published"
    },
    keywords=["security", "authentication", "encryption"],
    weights={
        "semantic": 0.6,
        "keyword": 0.4
    }
)

for result in results:
    print(f"Title: {result['title']}")
    print(f"Similarity: {result['similarity']}")
    print(f"Highlights: {result['highlights']}")
    print("---")

​
Next Steps

  1. Explore document integration
  2. Learn about document management
  3. Understand agent memory