Web search¶
One setting connects Caravel to a web-search backend, and three features use it: the assistant researching a place, the image picker finding a photo of it, and the assistant's second opinion on where a place is. It is optional — everything works without it, with less to go on.
There is no default provider. The right choice depends on what you are willing to run and pay for, and the providers do not all offer the same features.
Turning it on¶
| Variable | Purpose |
|---|---|
CARAVEL_SEARCH_PROVIDER |
ollama, serper, brave, ddgs or stub. Empty — the default — means no web search |
CARAVEL_SEARCH_KEY |
The API key, for the hosted providers |
CARAVEL_SEARCH_URL |
The service root for ddgs, which you run yourself, so it has no address to default to. For the hosted providers it is an optional override of their endpoint, for pointing at a proxy |
A provider missing its key or URL is refused at startup rather than at first
use. The search provider is independent of CARAVEL_LLM_URL: a provider on its
own is a working configuration, and gives you web image search with no LLM
anywhere near it.
What each provider can do¶
ollama |
serper |
brave |
ddgs |
|
|---|---|---|---|---|
| Web search for the assistant | ✅ | ✅ | ✅ | ✅ |
| Image search in the image picker | — | ✅ | ✅ | ✅ |
| Place lookup for the assistant's pins | — | ✅ | ✅ | — |
| Needs | key | key | key | URL |
| Runs where | hosted | hosted | hosted | your own host |
| Costs | free tier | per query | monthly credit, then per query | nothing |
A feature a provider lacks is not an error. Each one falls back to what works without it, described below.
The startup log says what the web half of the image picker ended up with, as
image_search_web=serper, image_search_web=ollama (no image search) or
image_search_web=none.
The providers¶
ollama — Ollama Cloud¶
Ollama Cloud's web search API. Hosted, with a free tier, and if you already use Ollama for the model, one account and one key cover both. It is a web search and nothing else: no images, no places.
serper — Google, through an API¶
Serper returns real Google results through an API. Like Brave it offers all three features, and its place lookup is Google Maps data.
The trade is money: every query is paid for, and place lookup adds one per place on top of the searches, up to six for one trip-level suggestion run.
brave — Brave Search API¶
The Brave Search API searches Brave's own index, through an API rather than by scraping. Like Serper it needs only a key and offers all three features. Its image thumbnails come through Brave's own proxy, so they load even from sites that block other sites from embedding their pictures.
Its place lookup agreed with Serper's to the metre for most places tested. It is given the postal address as the area to search in, so a place the assistant names without a town tends to be found near that address, though in one later test its first answer was a place of that name in a town 40 km away. Serper does not use the address, and found nothing for such a name in testing. Brave was also wrong once where Serper was right, picking a different café of the same chain 4.6 km away. Pins from it carry a "Brave Search" badge.
What sets it apart is the price for a small instance. Brave adds $5 of credit to the account every month, which covers roughly a thousand requests at $5 per thousand. A personal or family instance is unlikely to use that up, so in practice it costs nothing. Serper, by contrast, sells packs of credit that expire after six months. Past the monthly credit Brave is the more expensive of the two per query, so for heavy use Serper wins.
The account needs a credit card, and requests past the monthly credit are billed to it.
ddgs — self-hosted metasearch¶
DDGS is a metasearch library with a built-in API server, which you run yourself. No key, no account:
Two honest caveats, since it is the keyless option and therefore tempting. It works by scraping search engines — Bing, Brave, DuckDuckGo, Google and others — so one can break when someone changes their markup. It aggregates several and falls back between them, which softens this a lot. And scraped engines rate-limit datacenter addresses, so it suits a home server better than a VPS. Scraping Google and Bing is also against their terms of service.
stub¶
A built-in fake used by the test suite. It answers from a small fixed table that points at addresses which cannot resolve. Never a real answer.
What uses it¶
The assistant's research. The assistant searches the web to find out about a place before it reads any pages. Without a provider it has only what the model already knows and the pages it can name itself — a worse assistant, but a working one. See The assistant.
Image search. The image picker always searches Wikipedia, which needs no
configuration. With serper, brave or ddgs it also runs a web image
search, which is far better for hotels and restaurants but cannot tell you the
licence of what it finds. See Finding an image.
Place lookup. The assistant never takes coordinates from the model; it looks
the place up instead. The address search is always asked. With serper or
brave, a places search is asked as well, which is much better than
OpenStreetMap for restaurants, cafés, bars, shops and hotels. With any other
provider, only the address search is asked. See Coordinates are never taken from the
model.
Address search when you type into a location is a separate thing and does not use this setting at all — see Address search.