find_similar_moments
Find historically similar audience moments across the screen network using embedding similarity search. Input a natural-language description of the target moment.
Moment embeddings are 768-D vectors generated from multi-modal observation data (visual, audio, environmental, social) via the MomentEmbeddingService. This tool embeds your query text and finds the closest real-world moments via approximate nearest-neighbour (ANN) cosine similarity over a Lance IVF_PQ index.
CONSISTENCY: results are APPROXIMATE and EVENTUALLY CONSISTENT.
Approximate: retrieval is ANN, not an exhaustive scan (measured recall ~0.96 against exact KNN), so an identical query may omit a borderline match.
Eventually consistent: the index is served from a replicated pool whose replicas refresh independently, so for up to 5 minutes after new moments are published, two identical calls may return slightly different result sets. The difference is confined to the VISIBILITY of newly-published moments; the relative ranking of already-visible ones does not change. Do not use this tool where a repeatable, exhaustive result set is required.
WHEN TO USE:
Searching for historical moments similar to a target scenario
Finding "moments like this one" across different venues/times
Discovering when similar audience compositions or behaviors occurred
Planning ad placements based on past similar contexts
RETURNS:
data: Array of matching observations with similarity scores
observation_id, observed_at, venue_type, device_id, screen_mongo_id
payload: full observation data
evidence_grade: quality of observation
similarity: cosine similarity score (0-1, higher = more similar)
metadata: { result_count, embedding_model, min_similarity_threshold }
suggested_next_queries: Follow-up queries
EXAMPLE: User: "Find moments with high engagement in evening restaurants with families" find_similar_moments({ query: "evening restaurant venue with families present, high emotional engagement and attention" })
User: "When did we see young adults highly engaged at transit screens?" find_similar_moments({ query: "transit venue morning commute young adults high attention" })
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return. Default: 10, max: 200. | |
| query | Yes | Natural-language description of the target moment. Be descriptive about venue, time, audience, behavior, and conditions. | |
| venue_type | No | Filter results to a specific venue type. Optional. | |
| min_similarity | No | Minimum cosine similarity threshold (0-1). Default: 0.7. Lower values return more but less relevant results. |