Skip to content

Releases

v0.14.0 - Vendor Modes, a CLI for Agents & Four New Search Backends

Choose a tag to compare

@ilchemla ilchemla released this 19 Nov 09:08
8a46ba7

Choose how each backend runs and know what it cost, and let coding agents use WebRouter from their terminal.

Upgrade with pip install -U "webrouter[all]". Then read Behaviour Change: some defaults changed.

🚀 What's New

Vendor modes (#315, #324, #327, #343, #347)

  • Get the speed or depth you need from one backend: pin one of its own tiers, such as Exa's instant search or Tavily's ultra-fast tier, by naming it in provider. Works on search, extract, answer and browse, and inside auto chains
  • Know what each call really cost: it is priced at its mode's published rate, in cost_usd and against any spending limit you set. A mode with no published price never runs under a spending limit
  • Let a router pick the mode for you: opt in with route_modes=True, and a mode the backend refuses falls through to the next one at no charge. Vendor modes lists every mode
from web_router import WebRouter

router = WebRouter()
router.search("...", provider="exa:exa-instant")        # Exa's instant search type
router.search("...", provider="exa:exa-instant+lite")   # the same, at the lite depth
router.search("...", provider="tavily:tavily-ultra-fast")

CLI for agents (#330)

  • Coding agents with a terminal, such as Claude Code, Codex and Cursor, can now search, read pages and get answers through WebRouter with one shell command, with no MCP server to set up
  • Agents can read every result and handle every failure: each method is a webrouter command that prints one JSON object, with exit codes to branch on: 1 the call failed, 2 refused before anything was sent, 3 a key or an extra is missing. Try it with no install and no key through uvx. See CLI
uvx --from "webrouter[search,extract]" webrouter search "rust async runtimes" -n 5 | jq -r '.results[].url'

More features

  • Four more search backends for auto to fall back on and for you to compare: Valyu, Seltz, Octen and Keirolabs. Call Valyu, Seltz and Octen with search(provider=...); call_vendor() no longer lists them (#257, #258, #259, #264)
  • Run one MCP server for your whole team: web-router-mcp --transport http serves it over HTTP, local by default and on other addresses only with WEB_ROUTER_MCP_TOKEN, and a Dockerfile ships with it (#348)
  • Find the right scraper faster: live data search ranks by site, kind of page and country, so "amazon product" finds product pages first. And extract() tells you which data API (YouTube, GitHub, Wikipedia and others) serves a page's site, so you can call it directly (#256, #280)

🐛 Fixes

  • timeout= now holds on the sync WebRouter: a slow response no longer runs past your deadline (#348)
  • When every URL in an extract fails, you get one error with each URL's reason, so you know which to retry (#348)
  • Docs: the MCP guide loads again, at /mcp-server, and several pages were corrected (#291, #338, #340)

🔄 Behaviour Change

  • Agent tools are safer by default (Claude, OpenAI, LangChain): a model can no longer point them at your internal network, a stuck call ends after 60 s, and a failed call comes back to the model as a message it can act on instead of crashing your agent. Pass url_policy=None or timeout=None to undo either (#348)
  • MCP load_env reads only .env files, so a prompt can't make it read another file on your machine. webrouter[mcp] now installs the browser tools too, so every MCP tool works out of the box (#348)
  • Keenable now works with spending limits: when you cap spend with Budget(max_cost_usd=...), WebRouter used to skip Keenable because it had no price. It now has one ($4 per 1,000 requests), so it runs, and its cost counts toward your limit (#349)
  • If you look up prices by mode, use the new names: ":ultra-fast" is now "tavily-ultra-fast". The old name still works this release, with a warning (#289)

🙌 New Contributors

  • @Manasbh made their first contribution in #264, adding Keirolabs as a search backend

Full Changelog: v0.13.0...v0.14.0

v0.13.0 - Vendor Data, Live Data & Cost on Every Call

Choose a tag to compare

@ilchemla ilchemla released this 16 Nov 09:58

Your agent can now pull data from 372 vendor APIs, from your own ad and log accounts to public data, run ready-made scrapers from four vendors without picking one, and see what every call cost. With Nimble among the keyless providers, you get more free usage before your first API key, and search can go through the LiteLLM proxy your team already runs.

Upgrade with pip install -U "webrouter[all]". If you use the MCP live data tools or plan() and run(), read Behaviour Change first.

🚀 What's New

Vendor data (#132, #133, #134, #249, #281)

  • call_vendor() calls a vendor's own API with your credentials (your Google Ads reports, your Datadog logs, public data such as FRED) and returns its answer untouched. The catalog lists 372 vendors and 2,708 endpoints in VENDORS.md
  • Every endpoint is listed as a read, and some reads spend your vendor credits. A write goes through vendor_request() and must be allowed explicitly. Your credentials go only to that vendor's own host
  • search() also lists the vendor APIs that match a query, from the local catalog at no cost (#250), and agents get the catalog as MCP tools
  • Every entry is written from the vendor's own API docs, so tell us on GitHub Issues if one doesn't match what the vendor returns
from web_router import WebRouter

router = WebRouter()

router.find_vendor_endpoints("google ads spend by campaign")  # matching endpoints, from the local catalog

response = router.call_vendor(
    "google-ads.query",
    {
        "customer_id": "1234567890",
        "query": "SELECT campaign.name, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS",
    },
)
response.data  # Google's JSON, untouched

Live data from Apify, Bright Data and Oxylabs (#113, #208, #255, #263)

  • Where vendor data calls an API you hold an account with, live data runs a vendor's ready-made scraper for one website (a product page, Google Maps places) and returns records. Apify, Bright Data and Oxylabs join Nimble
  • Ask once and every vendor you hold a key for is searched, then run the source you pick on its own vendor. Apify and Bright Data were tested against the live services
from web_router import WebRouter

router = WebRouter()

page = router.live_data_sources(query="amazon product")  # every vendor with a key, asked at once
source = router.live_data_source(page.sources[0])  # its schemas and samples, from its own vendor
result = router.live_data(source, source.samples[0].input)  # run it there; no provider named
result.records

Nimble joins the keyless providers (#279)

  • More free usage before your first API key: Nimble now serves search and extract with no key, within a free daily allowance, beside the free tiers WebRouter already had (Tavily, You.com, Exa, Parallel and Keenable for search; Tavily, Jina Reader, Firecrawl and Keenable for extract)
  • With no keys set, auto (the default when you name no provider) tries Nimble first, then falls back through the other free tiers when its allowance is spent, so a first run keeps working for longer

Search through your LiteLLM proxy (#262)

  • Teams that already run a LiteLLM gateway can send Exa, Tavily and Parallel searches through it: the vendor keys stay on the proxy, and every call is billed and tracked under your LiteLLM key
  • Each keeps the full set of options it has when called directly, and joins auto after the free tiers. Tested against a live proxy

Cost and time on every response (#275, #278)

  • Know what each call cost and how long it took: every search, extract, answer, research and browse response carries cost_usd and elapsed_s, the backend's own figure where it states one, an estimate otherwise, or None when neither is known
  • Budgets are no longer experimental. A new router tries free backends first, and a spend log sums what you spent by day, backend or method
from web_router import Budget, WebRouter

router = WebRouter(router="cheapest_first")  # free backends first, then the cheapest paid ones
log = router.log_spend("spend.jsonl")  # from here on, every answered call is logged
response = router.answer("...", budget=Budget(max_cost_usd=0.01, time_limit_s=10))
response.provider, response.cost_usd, response.cost_source, response.elapsed_s
log.report()  # what you spent, by day, backend and method

Ready for production (#273, #276, #284, #286)

  • Run WebRouter in a service without surprises: a timeout on search, extract and answer, a cap on calls in flight, a pause on a backend that answers with a rate limit or runs out of credit, and a log line for each fallback
  • Every error says what went wrong (a bad key, a rate limit, a bad request, the page itself, a timeout) and whether a retry may help. Fallback stops when the next backend would fail the same way, so a broken URL is no longer billed across every backend
  • A new Running in production page covers one shared router per process, threads, logging and warm-up

A lighter MCP server (#272, #277)

  • The tool list costs a model about 15% less context per turn, you can serve only the tools you name, and answer returns only the sources it cites
  • The server is listed in the official MCP Registry and on Glama

More routers (#241, #265)

  • With no router named, plan() and run() now route by built-in rules: a URL is read, a request for a report or a comparison runs research (billed per run), anything else is searched. Methods you call directly are unchanged
  • Point WebRouter at your own router service or any OpenAI-compatible model, try several routers in order, and register your own by name

🐛 Fixes

  • extract() reports a 404 page, a bot challenge or a login wall as a failure instead of a document, and under auto a batch retries each failed URL on the next backend (#270)
  • pip install "webrouter[all]" now includes the MCP server, which crashed on start without it, and a billed MCP tool is no longer marked read-only, so a client that auto-approves read-only tools asks first (#269)
  • A router shared across threads no longer leaks open connections (#268)
  • research(provider="auto") no longer starts a second paid run, and Nimble research at effort="max" runs again (#197, #242)
  • A variable set in a .env the library did not load is now named in the error (never its value), with how to load it (#271)

🔄 Behaviour Change

  • run_template(), templates() and template() are now live_data(), live_data_sources() and live_data_source(). The old names still work with a DeprecationWarning until a later release, but the MCP tools are renamed with no alias: live_data_sources, live_data_source and live_data, whose template argument is now source. Their results use records and sources keys, and MCP answer counts uncited sources in uncited_sources instead of citation_count (#113, #277)
  • With no router named, plan() and run() can now run research, billed per run, for a prompt that asks for a report or a comparison. Pass router=None to keep the old behaviour (#265)
  • A method call with an invalid argument raises InvalidParameterError (still a ValueError) instead of pydantic's ValidationError (#273)
  • answer(provider="you", recency="day") is refused before the call, since You.com cited pages several days old for it (#239)

Full Changelog: v0.12.0...v0.13.0

v0.12.0 - Nimble Research Citations & Python 3.11

Choose a tag to compare

@ilchemla ilchemla released this 10 Nov 11:25
e83894a

Research with Nimble now cites the sources it read, and WebRouter now needs Python 3.11 or newer.

🐛 Fixes

  • research(provider="nimble") left citations empty for a run without trust (Nimble's claim-by-claim citations, off by default), although the run returned its sources. Those sources are now the citations, and a run with trust also gains any source its claims leave out (#126)

🔄 Behaviour Change

  • WebRouter now needs Python 3.11 or newer. Python 3.10 reached end of life in October 2026, and the security fixes of some dependencies need 3.11. On Python 3.10, pip and uv keep installing 0.11.0; move to Python 3.11 or newer to get 0.12.0 (#127)

Also new: the package description and the README now say what WebRouter is in one line, "an open source standard that connects your agent to the web" (#125).

Full Changelog: v0.11.0...v0.12.0

v0.11.0 - On PyPI as webrouter & New Home

Choose a tag to compare

@yogev-nimble yogev-nimble released this 09 Nov 18:45
1c7e833

Install WebRouter from PyPI with one command: pip install "webrouter[all]".

🚀 What's New

On PyPI, as webrouter (#122)

  • pip install "webrouter[all]" or uv add "webrouter[all]", with the same extras as before
  • Each release is built from its tag and published through PyPI's trusted publishing, with no upload token

A new home: github.com/Nimbleway/webrouter (#121)

  • Old links redirect. Report security issues privately through GitHub's vulnerability reporting (see SECURITY.md)

🔄 Behaviour Change

  • The package is now named webrouter (it was web-router): change it in your requirements. import web_router, the web-router-mcp command and the MCP server's name are unchanged (#122)

Full Changelog: v0.10.0...v0.11.0

v0.10.0 - Smart Routing, Benchmark-Ranked Defaults & Search Options

Choose a tag to compare

@ilchemla ilchemla released this 09 Nov 12:44
fc1d906

Every prompt goes to the right tool and service, within your budget of time and money, and the default order is now the one that scored best on public benchmarks.

🚀 What's New

Smart routing (#102)

  • Send each prompt to the right tool and the best service for it, within the time and money you allow, instead of one fixed order for everything
  • Plug in any router that decides where a prompt goes. WebRouter gives it every service that could answer, with its estimated price and latency, runs its pick and falls back to the next one if it fails. Four examples to start from: plain rules (no model, no key), a scikit-learn classifier you train on your own prompts, any OpenAI-compatible LLM, and TypeSafe's Jev, which scores each candidate with a probability
  • plan() previews a prompt, run() runs it, and a Budget caps estimated cost and time. Agents get it through the MCP server's web_run
from web_router import Budget, RouteDecision, RouteRequest, WebRouter


def route(req: RouteRequest) -> RouteDecision:
    if req.urls:  # the http(s) URLs in the prompt
        return RouteDecision(tools=["extract"])
    return RouteDecision()  # no opinion: the default order runs


wr = WebRouter(router=route)
response = wr.run("read https://example.com/pricing", budget=Budget(max_cost_usd=0.05))

Defaults ranked by benchmark (#74)

  • With no router, auto now tries services in the order that answered best on public question sets: SealQA (hard) for search and SimpleQA for answers. When two services score within the noise, the cheaper one goes first
  • The order follows the results, not habit: with Brave and Exa keys, Exa now goes first, at a higher price. Set your own order in provider_config

Search: recency and effort (#108)

  • recency keeps results from the last day, week, month or year; effort picks a faster or more thorough tier, and higher costs more
  • search_depth now means a size: lite about 500 characters, fast a few thousand, deep the whole page

Logged-in pages without a browser (#98)

  • The login you save in a browser session (since v0.6.0) now also works for extract(): pass the same profile id with provider="browserbase" and read pages as that user, with no browser session to start or release

Also new: WebRouter is now licensed under the Apache License 2.0 (#111).

🐛 Fixes

  • The MCP server refuses unknown arguments and private URLs instead of dropping or sending them (#109)
  • extract() counts an error page with no text as a failure, so auto tries the next service (#109)

🔄 Behaviour Change

  • auto's default search and answer orders changed (see above), so with some keys a different service serves first (#74)
  • The decider proof of concept (decider=, classify(), execute()) is removed; routers replace it. Pin web-router==0.9.0 to keep it (#102)
  • Search refuses a value a service cannot serve before sending it, and Parallel moved to its v1 API, which refuses the beta processor and excerpts options (#108)
  • The mcp extra now needs mcp 2.2 or later (#109)

Full Changelog: v0.9.0...v0.10.0

v0.9.0 - answer() & Template Samples

Choose a tag to compare

@ilchemla ilchemla released this 04 Nov 10:38
c76f2d6

Ask a question and get a written answer with its source links, in one call. Also: sample runs for templates, and one fix.

🚀 What's New

answer(): a written answer with its sources (#53, #65, #66)

  • Six answer services, each with your own key: Perplexity, Exa, You.com, Linkup, Parallel and Brave (Brave reads BRAVE_ANSWER_API_KEY, not the search key). Install the answer extra and set one key; the README lists each one
  • By default, WebRouter tries the services you hold a key for, cheapest list price first, and moves on when one fails or has no answer. Each one it tries bills
  • Agents can call it too: the MCP server has an answer tool, and the Claude, OpenAI and LangChain tools offer it when you switch it on (#64)
from web_router import WebRouter

with WebRouter() as router:
    response = router.answer("who won the 2022 world cup final")

print(response.answer)
for citation in response.citations:
    print(citation.field or "-", citation.url)

For adapter authors: AnswerProvider, HttpAnswerProvider and register_answer_provider() add an answer service (#53).

Template samples (#38)

  • template.samples holds the runs the vendor recorded: an input the template took and the record it returned, so you can see what it needs before you pay for a run
  • On Nimble, a template listing now includes each template's inputs and samples, in Python and in the MCP server, so one call is enough

🐛 Fixes

  • Errors with no message, such as timeouts, now show their type: search failed: ReadTimeout (#53)

🔄 Behaviour Change

  • auto now also moves to the next service when one returns nothing (no results, or only blank pages), not only on an error. Each extra service it tries bills. To stop at the first result, set provider_config={"auto": {"fallback_on_empty": False}}; the MCP server has no such switch (#41)
  • Template samples moved from template.extra["samples"] to template.samples (#38)
  • The max_results description now suggests 5 to 10 results to an agent (#54)
  • The evals extra now allows openai 3 (#67)

Full Changelog: v0.8.0...v0.9.0

v0.8.0 - AWS AgentCore Web Search

Choose a tag to compare

@yogev-nimble yogev-nimble released this 28 Oct 09:05
0e944bb

Search through your own AWS AgentCore Gateway, plus PNG screenshots on Anchor.

🚀 What's New

AWS AgentCore Web Search as a search backend (agentcore) (#35)

  • Searches through your own AgentCore Gateway, set in AGENTCORE_GATEWAY_URL. Requests are SigV4-signed with botocore's usual credential chain, for the region in the gateway's hostname. Install the new aws extra (all includes it)
  • Maps max_results (at most 25), include_domains and exclude_domains (connector 1.2.0 or later; an older target raises rather than dropping them). Queries up to 200 characters. A date range goes through provider_options
  • AWS's terms apply: show each result's citation, and don't store results in bulk
  • Setup and teardown: docs/agentcore-setup.md
from web_router import Provider, WebRouter

response = WebRouter(Provider.AGENTCORE).search("python 3.13 release", max_results=5, include_domains=["python.org"])
print(response.provider, [result.url for result in response.results])

🐛 Fixes

  • Screenshots on Anchor are PNG. Anchor answered a PNG request with JPEG bytes, so Screenshot.png held a JPEG, width and height were wrong, and the MCP server labeled it image/png. A capture that is not PNG is now converted with Pillow, which the browser extra now installs (#36)
  • MCP-based search backends no longer treat a reply carried only in structuredContent as empty (#35)

Full Changelog: v0.7.0...v0.8.0

v0.7.0 - Smart Routing v0, Extract Templates & Max Extract

Choose a tag to compare

@yogev-nimble yogev-nimble released this 26 Oct 06:19
10cddcd

Route a query to a method with a swappable decision model (experimental), run a vendor's saved site extractors, and race every extract backend for the fastest page.

🚀 What's New

Smart routing v0 (experimental): classify() and execute() (#20)

  • Opt-in with decider=, and the API may change. classify(query) picks the method (search, extract, research or browse) and returns a Route on that method's default auto chain. execute(route) runs it
  • Pick the model that decides: "keywords" (built-in keyword rules, no key, offline; it picks search or extract, and research or browse fall back to search), "jev" (TypeSafe's Jev), "llm" (any OpenAI-compatible chat model, needs the evals extra), or plug in your own with register_decider()
  • A failed or low-confidence decision falls back to search, with Route.fallback saying why
from web_router import Provider, WebRouter

router = WebRouter(decider="jev")  # TypeSafe's Jev, reads TYPESAFE_API_KEY
route = router.classify("Summarize https://example.com/pricing")
route.method  # e.g. "extract"
response = router.execute(route)

Extract Templates: run_template() (#28)

  • run_template(name, inputs, provider=...) runs a vendor's saved, site-specific extraction and returns the parsed record. templates() lists them and template() describes one, with the schemas of its inputs and output
  • provider is required: a template name belongs to one vendor, so there is no auto. Nimble is the first backend. The MCP server adds templates, template and run_template
  • An unknown name raises TemplateNotFoundError. A failed run or a 4xx/5xx page raises ProviderError, never an empty record
router = WebRouter()
template = router.template("walmart_pdp", provider="nimble")
template.input_schema  # what `inputs` takes
response = router.run_template("walmart_pdp", {"product_id": "123456789"}, provider="nimble")
response.data  # {'title': ..., 'price': ..., ...}

max: every extract backend at once (#29)

  • WebRouter(Provider.MAX).extract(url) sends the request to every backend auto would try and returns the first document back. response.provider names the one that answered
  • Every fetch is billed, so it costs up to one extract per configured backend per URL. It is never the default
  • provider_config={"max": {"hedge": 0.8}} runs the first backend alone for 0.8 s and starts the rest only if it hasn't answered
response = WebRouter(Provider.MAX).extract("https://example.com", format="markdown")
response.provider  # whichever backend answered first

Also new: benchmark_extract() compares extract backends on the same URLs, with a scan script in benchmarks/providers/extract.py (#7).

🐛 Fixes

  • Nimble enrichments (research with records) work as documented, and combinations Nimble refuses now raise before a run starts (#32)
  • Browser Use steps carry a real detail, read from the step's memory, and the action it took (#24)
  • benchmarks/providers/run.py saves rows as it goes, so a scan that dies keeps what it paid for (#7)

🔄 Changed

Browser Use now maps output_schema, max_steps and allowed_domains (#24). A browse call through auto that sets any of them was refused before; it now starts a Browser Use task.

Full Changelog: v0.6.0...v0.7.0

v0.6.0 - Kernel Browsers & Logged-In Sessions

Choose a tag to compare

@ilchemla ilchemla released this 20 Oct 15:33
c06d7ce

Log in once and reuse the login across browser sessions, plus Kernel as a browser backend.

🚀 What's New

Log in once, reuse the login (#22)

  • control_url() returns a link where a person can drive the session, for example to log in. It's a secret, like cdp_url
  • With an existing vendor profile (an id; a name on Anchor) and persist_profile=True, the login is saved on release, and the next session on that profile starts logged in
  • Works on Browserbase, Steel, Hyperbrowser, Anchor and Kernel (Kernel needs headless=False). auto refuses profile and persist_profile: name the backend

Kernel for browser sessions (kernel) (#21)

  • Set KERNEL_API_KEY. Supports idle_timeout, stealth, headless and viewport. Without idle_timeout, Kernel ends a session after 60 s idle
  • timeout, solve_captchas and proxy_country raise an error: Kernel has no session lifetime, stealth already solves CAPTCHAs, and a proxy country needs a proxy created first
  • Tried after the other hosted browsers and before local, so existing calls keep their backend

🔄 Changed

Steel's, Hyperbrowser's and Anchor's interactive live-view links, before only in raw, are now also returned by control_url(). live_view_url is unchanged.

Full Changelog: v0.5.0...v0.6.0

v0.5.0 - DeepSeek Search & Extract, You.com Research

Choose a tag to compare

@ilchemla ilchemla released this 19 Oct 15:08
db4a628

Two new backends and three fixes.

🚀 What's New

DeepSeek for search and extract (deepseek) (#15)

  • Set DEEPSEEK_API_KEY. Domain and locale filters work as on every other backend
  • Queries over DeepSeek's 128-character limit are refused before sending, so auto falls through to the next backend

You.com for research (you) (#12)

  • Uses the same YOU_API_KEY as You.com search. Returns a markdown answer with citations
  • effort maps onto You.com's tiers. output_schema and cancel() are not supported yet

For adapter authors: ExtractProvider.min_start_interval spaces out fetch starts for backends with a per-second rate limit (#15).

Both backends are added last in auto, so existing calls keep their backend.

🐛 Fixes

  • A research or browse call that times out now raises ResearchTimeoutError / BrowseTimeoutError with the job id, so you can resume the run (#13)
  • Empty or padded API keys count as missing, which was breaking Jina (#10)
  • Bright Data reports an unreachable URL as a failure, not an empty page (#14)

🔄 Behaviour Change

If YOU_API_KEY is your only key, research() through auto now starts a paid You.com run instead of raising ConfigurationError.

Full Changelog: v0.4.0...v0.5.0