# Embeddings API

This page documents the conceptual API surface for embeddings and semantic similarity in Curiosity Workspace.

• Embedding index: an index built over a field to enable similarity retrieval.
• Similarity query: returns a set of nearest neighbors with similarity scores.
• Scores: typically normalized to ([0, 1]) for interpretability (implementation-dependent).

// Find items similar to a query phrase
return Q().StartAtSimilarText("Apple screen issue", nodeTypes: new[] { "SupportCase" })
          .EmitWithScores();

Common patterns:

• compute an embedding representation for a node’s field(s)
• retrieve nearest neighbors
• optionally constrain by context (graph or facets)

// Similarity constrained to a context set (e.g., related-to a manufacturer)
class SimilarRequest { public string Query { get; set; } public string Manufacturer { get; set; } }
var req = Body.FromJson<SimilarRequest>();

return Q().StartAtSimilarText(req.Query, nodeTypes: new[] { "SupportCase" }, count: 500)
          .IsRelatedTo(Node.GetUID("Manufacturer", req.Manufacturer))
          .EmitWithScores();

• Choose fields carefully: embeddings are most useful for long, descriptive fields.
• Chunk long content: improves recall and reduces truncation artifacts.
• Tune cutoffs: establish a minimum similarity threshold for “related”.
• Constrain by context: use graph relationships to keep semantic matches relevant.

• Embeddings concepts: NLP → Embeddings
• Vector retrieval: Search → Vector Search