semantic_search_observations

io.github.snehdhruv/trillboards-dooh · Verify this server

Search observations by semantic similarity. Find moments that match a description like "lunch rush at fast casual restaurants" using vector embeddings. Uses 768-dimensional Gemini embeddings on observation payloads to find promoted observations matching a natural language query via approximate nearest-neighbour (ANN) cosine similarity search 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 observations are published, two identical calls may return slightly different result sets. The difference is confined to the VISIBILITY of newly-published observations; the relative ranking of already-visible ones does not change. Do not use this tool where a repeatable, exhaustive result set is required. TIME BOUND: searches the last 30 days by default. Pass filters.time_range to widen or narrow it; the window actually applied is echoed in metadata.time_range. Observations are retained for 90 days. WHEN TO USE: - Finding observations that match a conceptual description - Discovering contextual moments across the screen network - Searching for audience situations ("families waiting in line", "professionals on coffee break") - Finding commerce patterns ("high purchase intent near checkout") RETURNS: - data: Array of matching observations ranked by semantic similarity, each with: - observation_id, device_id, venue_type, observation_family - observed_at, payload, confidence, evidence_grade - similarity: Cosine similarity score (0-1, higher = more relevant) - metadata: { result_count, query_embedding_model, search_scope, time_range } - suggested_next_queries: Related semantic queries to explore EXAMPLE: User: "Find lunch rush moments at fast casual restaurants" semantic_search_observations({ query: "lunch rush at fast casual restaurants with high foot traffic", filters: { venue_type: ["restaurant_qsr"] }, limit: 20 }) User: "Find moments with high emotional engagement" semantic_search_observations({ query: "audience showing strong positive emotional reactions", filters: { observation_family: ["audience"] }, limit: 10 })