Filters (all optional, combine freely): ``bbox`` as
``[min_lon, min_lat, max_lon, max_lat]`` in WGS84 degrees; ``intersects`` as
a GeoJSON polygon object (a ``Polygon`` / ``MultiPolygon`` geometry, or a
``Feature`` / ``FeatureCollection`` wrapping one) to keep only footprints
intersecting it -- a tighter spatial filter than the rectangular ``bbox``,
and mutually exclusive with ``bbox`` / ``place``; ``place`` as a
free-text name geocoded to a bbox; ``area`` as a substring of the Umbra
task (site) name (set ``fuzzy`` to match it loosely -- word-order- and
punctuation-independent and typo-tolerant, resolved deterministically with
no model call, so ``"beet piler"`` still reaches ``"Beet Piler - ND"`` and
``"utah centerfield"`` still reaches ``"Centerfield,
Utah"``; set ``semantic`` instead to treat ``area`` as a plain-language
*description* of a site whose name you don't know and resolve it to the
closest task names by *meaning* via the prebuilt embedding index, so
``"grain storage north dakota"`` reaches ``"Beet Piler - ND"`` -- a query
that shares no word with the label, which ``fuzzy`` cannot and should not
fake; ``semantic`` and ``fuzzy`` are mutually exclusive, and the resolved
task name is returned as ``resolved_area`` with the ranked candidates in
``semantic_matches`` so you can audit and retry with a different one, and
``min_score`` -- a cosine threshold in ``[0, 1]`` -- drops weak aliases, so
a description that matches nothing confidently returns an empty result
rather than an arbitrary top pick); ``start``/``end`` as acquisition-date
bounds -- an ISO
``YYYY-MM-DD`` date, a bare year/month (``2024``, ``2024-03``), or a
relative expression (``today``, ``yesterday``, ``3 months ago``,
``last month``), resolved deterministically with no model call;
``products`` to restrict to product types
(any of GEC, SICD, SIDD, CPHD); the SAR acquisition-property filters
``polarizations`` (keep items exposing any of these, e.g. ``["VV"]`` -- the
filter that keeps a change comparison like-with-like), ``min_incidence`` /
``max_incidence`` (view incidence-angle bounds in degrees) and
``max_resolution`` (keep items at least this fine, in metres) -- each a hard
predicate that excludes items missing that metadata; ``canonical`` to keep
the preferred copy of a collect Umbra republished under another prefix
(``True``), only the other copies (``False``), or every item when omitted;
``limit`` to cap
results; ``max_per_task`` to cap items per site (use 1 for a one-pin-per-site
overview).

``local`` selects the backend: leave it unset to use the on-disk index when
present (instant) and fall back to a live S3 walk otherwise. When the server
is configured with a Canopy token (``$UMBRA_CANOPY_TOKEN``), the search runs
against Umbra's authenticated commercial archive instead and ``source`` is
reported as ``"canopy-archive"``. Returns the per-item context cards, not
full STAC JSON, to protect the context window; call ``get_item`` for one
item's full metadata.

Prefer ``fuzzy=True`` (or :func:`find_repeat_sites`) when ``area`` shares
words with a task name; that path is deterministic and needs no key.
``semantic=True`` is only for a description that shares **no** tokens with
the label. It requires a task-embedding index built ahead of time with
``umbra semantic build`` and a user-supplied embedding key (``OPENAI_API_KEY``,
optionally ``OPENAI_BASE_URL`` / ``UMBRA_EMBED_MODEL``); it raises a helpful
setup error otherwise, so it never runs implicitly. The only model call is
turning ``area`` into a vector -- the resolved search over the chosen backend
stays fully deterministic.