Semantic Search

Semantic search uses vector embeddings to find entities, decisions, and patterns based on meaning rather than exact keyword matches. The Context Graph generates embeddings for entity descriptions, decision rationale, agent trajectories, and query patterns, then uses approximate nearest neighbor (ANN) search to find similar items.

How It Works

The user query is converted into an embedding vector using the configured embedding model
The vector is compared against stored embeddings in the appropriate Pinecone namespace
Results are ranked by cosine similarity score
Optional graph context expansion adds structural relationships around each result

Search API

from context_graph.services.semantic_search_service import (
    SemanticSearchService,
    SearchQuery,
    SearchMode,
    SearchScope,
    SearchFilters,
)
 
results = await service.search(SearchQuery(
    query="customer churn prediction models",
    tenant_id="acme",
    mode=SearchMode.SEMANTIC,
    scope=SearchScope.ENTITIES,
    top_k=10,
    min_score=0.5,
    filters=SearchFilters(
        entity_types=["model", "feature"],
    ),
))

Embedding Namespaces

Different types of searches use different embedding namespaces:

Search Target	Namespace	Dimensions
Entity descriptions	`ENTITY_SEMANTIC`	1536
Entity graph structure	`ENTITY_STRUCTURAL`	128
Decision rationale	`DECISION_RATIONALE`	1536
Agent trajectories	`TRAJECTORY`	256
Query patterns	`QUERY_PATTERN`	1536

Scoring

Results are scored using cosine similarity between the query vector and stored vectors:

score = dot(query_vector, stored_vector) / (norm(query) * norm(stored))

Scores range from 0 (no similarity) to 1 (identical). Results below min_score are filtered out.

Natural Language Query Support

The semantic search service accepts natural language queries and automatically:

Extracts intent and entities from the query text
Generates an embedding vector from the query
Selects the appropriate embedding namespace based on the detected intent
Returns results with explanations of why each result matched

Example Queries

Query	What It Finds
"Find datasets similar to sales_data"	Datasets with similar descriptions to sales_data
"Show me models trained on customer features"	Models whose descriptions mention customer features
"What decisions were made about fraud detection?"	Decisions with rationale related to fraud detection
"Find all entities related to the recommendation pipeline"	Entities semantically similar to recommendation pipelines

Performance Considerations

Pinecone ANN search typically completes in under 50ms for up to 10 million vectors
Query vector generation adds 100-200ms depending on the embedding model
Graph context expansion adds 50-100ms per result when enabled
For latency-sensitive paths, disable graph expansion with include_graph_context=False

Search Capabilities Overview Structural Search