find_similar
Find archived scenes that look like the acquisition at url.
This is the one search that lives in the pixels, not the metadata: where
``search_catalog`` filters by date/bbox/task-name, this renders the query
item's quicklook, embeds it, and ranks the pre-embedded scene index by visual
(cosine) similarity — "find scenes that look like this flooded field / crowded
berth / runway". The query item is excluded from its own results.
Requires a scene-embedding index built ahead of time with ``umbra embed
build`` (a sidecar ``catalog.embed.db`` beside the catalog index) and a
user-supplied multimodal embedding key (``OPENAI_API_KEY``, optionally
``OPENAI_BASE_URL`` / ``UMBRA_SCENE_EMBED_MODEL``) — the only model call is
turning the query image into a vector; ranking is deterministic. ``asset``
picks which product's quicklook to embed (default ``GEC``; match how the index
was built); ``model`` must match the index's embedding model. Returns the
ranked matches as compact records (each with the acquisition's ``href``, so
hand it to ``get_item`` / ``quicklook`` / ``change_composite`` next) plus the
attribution line.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"url": "<url>"
},
"name": "find_similar"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | STAC JSON URL or index item id of the scene to match. The public host also accepts a filename or stem in the index. | |
| asset | No | Product whose quicklook is embedded. Default GEC. Match how the scene index was built. | GEC |
| model | No | Embedding model id. Must match the scene index. Omit for the server default. | |
| top_k | No | Maximum matches to return. Default 10. | |
| min_score | No | Minimum cosine similarity. Default 0. Matches below it are dropped. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||