webrouter 0.11.0__tar.gz

webrouter-0.11.0/.gitignore

@@ -0,0 +1,74 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+sdist/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+junit.xml
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Environments
+.env
+.env.*
+!.env.example
+.venv
+venv/
+ENV/
+env/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints
+
+# Local scratch
+.scratch/
+scratch/
+.claude/
+
+# Agent benchmark runs (benchmarks/agent/run.py)
+benchmarks/agent/results/
+benchmarks/agent/.managed-agents.json
+benchmarks/providers/results/

webrouter-0.11.0/CHANGELOG.md

@@ -0,0 +1,212 @@
+# Changelog
+
+All notable changes to `web-router` are recorded here, newest first. Versions
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html); while on
+`0.x`, a breaking change bumps the minor version.
+
+## [Unreleased]
+
+### Added
+
+### Fixed
+
+## [0.11.0] - 2026-11-09
+
+### Changed
+
+- The repository moved to [github.com/Nimbleway/webrouter](https://github.com/Nimbleway/webrouter). Links to the old location redirect, and the package metadata now points to the new one. Security reports go through GitHub's private vulnerability reporting (see SECURITY.md).
+- **Breaking (install name):** the package is now named `webrouter` and is published to [PyPI](https://pypi.org/project/webrouter/): install it with `pip install "webrouter[all]"` or `uv add "webrouter[all]"`. Earlier releases were named `web-router` and published only to a private index. The import is unchanged (`import web_router`), as are the `web-router-mcp` command and the MCP server's name.
+
+## [0.10.0] - 2026-11-09
+
+### Added
+
+- `extract(profile=...)`: a saved identity on the backend whose cookies are sent with each fetch, the same `profile` a browser session starts from, so a login made in a session serves the fetches that follow. `browserbase` is the first extract backend to map it, through a new `BrowserbaseExtractProvider` over the Fetch API (`POST /v1/fetch`, a plain fetch that never renders the page; `markdown` and `html`, the latter Fetch's `raw`), with `profile` sent as `contextId`; it joins extract `auto` and `max` last, after DeepSeek, so no call that was already being served moves. Verified live by hand on 2026-10-29, and by the automated live tests on 2026-11-08: a cookie set in a persisting session came back from a fetch naming the same Context, and from none without it. A backend without saved profiles refuses `profile` rather than fetching anonymously, and extract `auto` and `max` now pass over a member that does not map an option the request sets, as search `auto` does, raising `UnsupportedParameterError` when none is left. The MCP `extract` tool never offers `profile`, as `browser_open` never has.
+- web-router is open source under the Apache License 2.0: `LICENSE` at the root, and `license = "Apache-2.0"` in the package metadata.
+- Routers (experimental): `router=` on `WebRouter` and `AsyncWebRouter` attaches your own router, `RouteRequest -> RouteDecision`: a function, method, partial or coroutine function, or an object with `route` or `aroute` (one that is only callable is refused) (typed as `RouterLike`, exported from `web_router`). It is shown the prompt and its priced, timed candidates, and answers the method and the order of `auto`'s backends. `route_tools=` limits the methods it orders; a router that fails leaves the static order, or with `fail_on_router_error=True` raises `RouterError`. An extract you did not pin, left with no URL to read, searches instead when a search backend is offered, and otherwise `plan()` raises `MissingParameterError`. With no router nothing changes. See the README's [Smart routing](README.md#smart-routing-experimental).
+- `plan(prompt, budget=, tool=)` and `run(plan_or_prompt, budget=, tool=)`, sync and async (experimental): `plan` works out a prompt's method, options and backends without running anything and returns a `Plan`; `run` runs it and returns that method's own response. A `Plan`'s `repr` shows neither its prompt nor a whole URL. `run` on a plan left with no backend calls nothing and raises. See [`plan()` and `run()`](README.md#plan-and-run).
+- Budgets (experimental): `budget=Budget(max_cost_usd=, time_limit_s=, strict=)` on `search`, `extract`, `answer`, `research`, `browse`, `plan` and `run`, and `with wr.budget(Budget(...)) as b:` for that router's calls to share one (another router's calls inside the block are untouched), with `plan()`, `run()`, `submit_research()` and `submit_browse()` on `BudgetScope` and `AsyncBudgetScope` too, and `status()` returning a `BudgetStatus` (exported from `web_router`) of what is spent, reserved and left; a cap that is not a finite number of 0 or more raises `ValueError`. Costs are list-price estimates, and under a cost cap an unknown price never runs, a price marked as a floor, a request with `provider_options` or a search asking for more results than its price assumes (`results_assumed`) included; the cap holds estimates, not the bill. A router's options are priced on the request the call runs -- `effort`, `search_depth`, `max_results` past `results_assumed`, extract's URLs per page -- and one that does not fit is set aside in `ignored`. A budgeted research call runs at one effort, chosen once before the router is asked and only from efforts each backend takes for the request (a Nimble enrichment under a $0.10 cap runs at `medium`, not `low`), on `auto`, a named backend, `plan`/`run` and `submit_research` alike. A call inside a shared budget is capped at what is left, and the router is shown that; a call spends from every scope of its router in force, so a scope made earlier cannot escape an outer block's cap. A call a backend makes inside a budgeted call, on its own router or another, is reserved once, by the call it is made in, and still settles in the shared budget when it runs in another thread or task or after its parent ended. A call where nothing fits raises `BudgetExceededError`; a time cap stops search, extract and answer with `DeadlineExceededError`. See [Budgets](README.md#budgets).
+- `url_policy="public_only"` on `WebRouter` and `AsyncWebRouter` (experimental): a plan or a router does not send a loopback, private or cloud-metadata URL to a backend as a URL (it stays in the prompt text). It reads the host as written, in the spellings a browser reads, NAT64 and IPv4-compatible IPv6 included; a numeric host resolvers read differently (`010.0.0.1`) is refused outright. It resolves no DNS and follows no redirect. Off by default; a URL with no host is refused even then. See [`url_policy`](README.md#url_policy). A bare `0x` part of an IPv4 host reads as 0, as a browser reads it, so `http://127.0x.0x.1/` is refused as loopback; the MCP browser tools' navigation guard reads hosts the same way. A 6to4 host (`2002::/16`) is judged by the IPv4 it carries when that address is not public, the same on every Python.
+- The decision record (experimental): a `DecisionRecord` in a new `decision` field on every routed or budgeted call's response and on every `Plan` -- what was offered, ranked, tried and skipped, and the estimated spend. It holds no prompt text: `prompt_sha256` is an unsalted SHA-256 of what the router reads (the query or task, an extract's whole URLs, a plan's whole prompt), a pseudonymous id, not anonymisation: a prompt or URL that can be guessed can be confirmed from it. Elsewhere a URL, scheme-relative ones included, shows only its scheme and host, a non-ASCII host as IDNA. A research or browse job started inside a budget keeps one in `Job.decision`, with the effort the budget chose and what it charged the start (`estimated_cost_usd`, `attempts`), and the answer `result()` returns carries it. `DecisionHop` and `DecisionAttempt` import from `web_router` and `web_router.types`. See [The decision record](README.md#the-decision-record).
+- The MCP server's `web_run`, `budget_start` and `budget_status` tools (experimental): `web_run` plans and runs a prompt, through the built-in keyless rules router (`web_router.routing.rules`) unless `WEB_ROUTER_MCP_ROUTER`, operator code set only in the server's process environment, names another; set empty, it stops the server. Every billed tool spends from one budget per connection, under the operator's ceiling (`WEB_ROUTER_MCP_MAX_COST_USD`, `WEB_ROUTER_MCP_TIME_LIMIT_S`, read once from the process environment; a value it cannot read, empty included, stops the server) and the task `budget_start` opens; `budget_status` reports the task, the connection's totals and the ceiling. A browser session is priced per whole minute of its `timeout`, a browser option that can bill an extra makes a paid backend's price unknown, Anchor's browser price is a floor, and extract's `max` is refused under a cost cap. `web_run`'s own caps must be finite and positive, and its time cap covers planning too; `url_policy` holds for its plans only, which the capabilities' `url_policy_note` says. When it picks research or browse, it waits 25 seconds, or less if its time cap or the budget has less left, then hands back a handle as those tools do, its note giving the wait it used. The capabilities resource gains a `routing` section, which names an operator's router `operator`, and the browser tools' navigation guard reads NAT64 and IPv4-compatible addresses as the IPv4 they carry. See [docs/mcp.md](docs/mcp.md#routing-and-budgets-web_run-budget_start-budget_status). An operator's router shows as `operator`, in the capabilities resource and in `web_run`'s `decision.router`, never by its import path or name.
+- Four example routers in `examples/` (experimental): `router_rules.py`, rules on the prompt; `router_classifier.py`, a scikit-learn classifier (`uv run --with scikit-learn`); `router_llm.py`, any OpenAI-compatible model; and `router_jev.py`, TypeSafe's Jev. The rules router takes the 50 ms default; the other three declare `timeout_s` of 0.05, 3.0 and 1.0. The model routers send the prompt to their server, and the Jev router refuses a probability outside 0 to 1. All four are tested offline.
+- `web_router.prices` (experimental): the estimated list price of every (provider, method, mode) web-router calls, from `web_router/data/prices.json`, with `estimate()`, `price()` and `prices()`, and the measured p50 and p90 latency of search and answer rows (`estimate_latency()`). `make prices` writes `PRICING.md`'s tables from it, and `make latency` the latency from the frozen results.
+- `benchmarks/providers/frozen/`: the per-question results route-eval and the latency figures rest on, committed with no question or answer text; `frozen.py join` puts them back from the public sets. Experimental until 1.0.
+- `benchmarks/providers/tools_effort.py` (experimental): the tool and effort set, 60 questions each run through search then read, extract, `answer()` and `research()` at each effort, under a hard `--budget`. Its first run is frozen as `tools-effort-60`.
+- route-eval, `benchmarks/providers/route_eval.py` (experimental): replays a router -- `static`, `oracle`, `always:<backend>` or your own `RouteRequest` → `RouteDecision` callable -- over the frozen results, offline, through the library's merge rule, and scores accuracy, cost, latency and regret against the static order, held out and in-sample, against each method's noise floor. It covers search and answer backend order and, on `tools-effort-60`, the method and research effort.
+- Search options: `recency` (`day` | `week` | `month` | `year`) and `effort` (`low` | `medium` | `high` | `max`) on `search()` and `asearch()`, `SearchRequest`, the benchmark, the MCP `search` tool and the Claude, OpenAI and LangChain tools. `effort` is how hard the backend looks, anchored on its own tiers: `medium` is what it does unset, `low` its fastest tier, `max` its most thorough; a backend with fewer tiers serves several levels with one setting. Higher effort costs more and takes longer, by a vendor-specific amount. Each `search_depth` level is now a size: `lite` a snippet of up to about 500 characters, `fast` a truncated body of a few thousand, `deep` the whole page. A backend that maps an option but cannot serve a value of it (a depth level it lacks, a country off its list) refuses it before anything is sent, `auto` passes it over, and a router's default option is dropped when a backend in the order would refuse it. The MCP `search` tool offers `search_depth` only at the levels a reachable backend serves. `recency` now reads "sources the backend dates within the window" on `answer()` too. `Recency` and the depth and effort levels live in `web_router.types_options`; `web_router.types` and `web_router` still export them. See the README's [Search options](README.md#search-options).
+- Internals (experimental, for router authors and contributors): `web_router.routing.candidates.build_candidates()` (a research backend that refuses the effort the budget maps for the request, such as Nimble's enrichment at `low`, is left out with its reason), `web_router.routing.merge.merge()`, `web_router.routing.params.map_effort()` (from `data/efforts.json`, `make efforts`), `web_router.routing.pricing`, and the per-call deadline under every method, which clamps each request to the time left. Their docstrings hold the rules.
+- Every MCP tool now carries a `title` and MCP behaviour hints (read-only, destructive, idempotent, open-world), so a client can let free lookups through and ask before a billed run or a page action.
+- MCP tool results now carry `structuredContent`, the same object as their JSON text, and reading an unknown resource returns MCP's resource-not-found error (-32002) instead of an internal error.
+
+### Changed
+
+- Search backends map the shared options their APIs document, each refusing before the call a value it cannot serve (README's [Search options](README.md#search-options) has the tables; each `contracts/search/<name>.json` the fields sent):
+  - Exa and Exa MCP: every option but `locale`. Exa MCP now calls Exa's keyless `web_search_advanced_exa` tool (named in `?tools=` on the server URL) instead of `web_search_exa`, and no longer sends `objective`, which that tool refuses. Unset depth still asks Exa for the whole text and Exa MCP for highlights. Exa's highlights cap is soft, so `lite` is cut to a snippet of about 500 characters by web-router.
+  - Perplexity: every option; `search_depth` at `lite` (cut to about 500 characters by web-router) and `fast` only, one domain list of at most 20, and `locale` as a bare two-letter language.
+  - Tavily: every option but `effort`. `country` becomes the country name Tavily takes (a ranking boost, general topic only); `locale` and `recency` are filters, and `recency` drops pages Tavily cannot date. `lite` is `basic` cut to about 500 characters by web-router, since `basic` returns up to three chunks of about 500.
+  - You.com and You.com MCP: every option but `effort`, `country` from its 36 codes and `locale` from its 51-language list (`pt` or `zh` alone refused), one domain list at a time. You.com MCP sends `site:`, `lang:` and `loc:` in the query, which its tool applies. `lite` is its snippets cut to about 500 characters by web-router.
+  - Brave: every option but `effort`, `search_depth` at `lite` alone, its description and extra snippets cut to about 500 characters by web-router, since Brave has no size setting; domains as `site:` operators (Brave marks them experimental), `country` and `locale` from its lists, and a query past 600 characters or 75 words with the operators refused.
+  - Parallel: every option but `locale`; `search_depth` at `lite` and `fast`, one domain list of at most 200, `country` from the 37 it geo-targets, and `effort` picking the mode (`low` `turbo`, `high` and `max` `advanced`). `lite` is cut to about 500 characters by web-router, since Parallel's excerpt cap returned about 1,400 live.
+  - WebIQ: every option but `recency` and `effort`; domains as `site:` operators, `country` as a two-letter region code and `locale` as an ISO 639-1 language (an unlisted one such as `zz` is refused), `deep` as each page's whole text.
+  - Keenable: `search_depth` at `lite` and `fast`, one `include_domains` entry, `recency` and `effort`.
+  - Linkup: `recency` and `effort` (as its `depth`: `low` `flash`, `medium` `fast`, still sent when unset, `high` `standard`, `max` `deep`, which Linkup bills at ten times the others).
+  - DeepSeek: `recency` as `after:` in the query, and `search_depth` at `lite` (its summary cut to about 500 characters by web-router) and `deep` (the page body).
+  - A domain filter that goes into the query as `site:` (Brave, WebIQ and DeepSeek, and You.com MCP's `include_domains`) must be a host name, optionally with a path; anything else is refused before the call with `UnsupportedParameterError` (and `auto` passes the backend over), so a value cannot add its own operators.
+  - AgentCore Web Search: `recency`, on connector 1.2.0 or later.
+  - Nimble: `recency` as its `time_range`; it refuses `effort`, and no longer takes a new shared option unmapped.
+- Parallel search moves from `/v1beta/search` to `/v1/search`, with `mode=fast` pinned (unset, `/v1` runs `advanced`, the old `agentic`, at five times the price). `max_results` now goes under `advanced_settings`, and an `advanced_settings` object in `provider_options` is merged with it rather than replacing it. The beta-only `processor`, `excerpts` and top-level `max_chars_per_result` are rejected by `/v1`.
+- `PageState`, `PageSnapshot`, `Screenshot`, `PageLoadState` and `PageFormat` move from `web_router.types` to `web_router.types_page`. `from web_router import ...` and `from web_router.types import ...` work as before.
+- `BenchmarkRun`, `BenchmarkReport`, `ExtractBenchmarkRun` and `ExtractBenchmarkReport` move from `web_router.types` to `web_router.types_benchmark`. `from web_router import ...` and `from web_router.types import ...` work as before.
+- `auto`'s default `search` (keyed) and `answer()` orders are now generated by `make chains`, ranked by accuracy on the frozen `sealqa-hard-254` and `answer-simpleqa-300` sets (method in `benchmarks/providers/README.md`). Search: perplexity, nimble, webiq, linkup, tavily, exa, parallel, brave, you (was perplexity, nimble, linkup, tavily, brave, webiq, parallel, exa, you). Answer: perplexity, you, linkup, parallel, exa, brave (was perplexity, exa, you, linkup, parallel, brave). The previous search order came from a SimpleQA scan; search is now ranked on SealQA hard because on SimpleQA every keyed backend scores 81-95%, too close to tell them apart, while on SealQA hard they differ. With every key, Perplexity still serves first; with some, another may, and some cost more: with Brave and Exa keys, a search now goes to Exa ($0.017) before Brave ($0.005). Keep the old order with `provider_config={"auto": {"chain": {...}}}`.
+- The provider scan's recommended order now uses route-eval's ranking: within the noise floor the cheaper backend goes first (a row's stated cost, else its list price), and the keyless tier last. A search that failed on a rate-limit or quota error is left out, not counted a miss, and shown in the *Rate limit or quota* column.
+- Contributors: `make check` now limits size. Ruff holds a function to 50 statements (`PLR0915`) and a complexity of 10 (`C901`); the few over either today carry a `noqa`. `tests/test_shape.py` holds a file to 400 lines, test files included; files already longer are listed in `tests/shape_baseline.json` and may only shrink, and `make shape-baseline` records a shrink and refuses a new or grown entry. `CHANGELOG.md` merges with git's union driver, so parallel pull requests that each add a line no longer conflict.
+
+### Fixed
+
+- Tavily: a `session` (`requests.Session`) or `client` (`httpx.AsyncClient`) passed to the Tavily search or extract provider goes only to the SDK client that takes it. Before, either one raised `TypeError` in the other client.
+- The MCP server now loads `BRAVE_ANSWER_API_KEY` and `JINA_API_KEY` from a `.env` file, at startup and through `load_env`. Before, both were ignored, so a Brave Answers key could not turn on `answer` the way the server's own hints said.
+
+- The MCP server reads every `.env` it finds at startup, not just the first one that sets a key: `WEB_ROUTER_ENV_FILE`, then your user config directory's `.env`, then a path `load_env(remember=true)` recorded, then the working directory's `.env`. An earlier file wins per variable and a later one only fills what is still unset, so a project's `.env` or a remembered file can add keys but never replace yours. Before, a project `.env` with any one key hid your user config `.env` entirely. The capabilities resource's `env.loaded` now maps each variable to the file it came from (it replaces `env.file`), and a file whose keys were all set already reports `nothing new`. `load_env` now tells the model to use only a path you gave and to set `remember` only when you ask.
+
+- An MCP tool call with an argument the tool does not declare, such as a typo or a guessed `recency`, is now refused with the names the tool takes, instead of running with the argument silently dropped.
+
+- An MCP result that is over its size budget now cuts every result's text further before it drops any result, so `max_results=3` returns three results; before, it dropped whole results first.
+
+- The `mcp` extra now requires `mcp>=2.2,<3`. It allowed 1.x, which cannot import the server.
+
+- The MCP tool list is about a sixth smaller (31 KB to 26 KB with no keys): each rule is said once, in the server instructions or the one tool it belongs to, and `browser_open`'s description is cut from 1,769 to 623 characters. The no-key hint is in the instructions, not repeated on `search`.
+
+- The MCP server refuses, before sending anything, a URL passed to `extract`, `browse` (`start_url`) or `run_template` (a URL among its `inputs`) that is not a public `http(s)` URL: `file:`, loopback, private and cloud-metadata hosts are named with the reason, by scheme and host only. Before, they went to every backend in the chain. The server instructions now also say that results are untrusted web content.
+
+- `extract()` counts a page that came back with a 4xx or 5xx status and no content as a failure, named in `failures` with its status, instead of a successful empty document. A call with nothing else raises, so `auto` tries its next backend. A page with text, such as a site's own "not found" page, is still returned.
+
+- MCP errors for a missing key no longer tell the model to pass `provider_config`, which a conversation cannot do; they say to put the key in the user's `.env` and call `load_env`. With no template backend configured, `templates`, `template` and `run_template` say which key would add one, instead of asking for a `provider` argument their schema does not offer.
+
+### Removed
+
+- The decider spike: `WebRouter(decider=, decider_config=)`, `WebRouter.classify()`, `WebRouter.execute()`, `Route` and the `web_router.decisions` package (`DecisionProvider`, `register_decider()` and the `keywords`, `jev` and `llm` deciders). It was a proof of concept for routing; `router=`, `plan()` and `run()` replace it. To keep using it, pin `web-router==0.9.0`, the last version that has it.
+
+
+
+## [0.9.0] - 2026-11-04
+
+### Added
+
+- `Template.samples`: the runs a backend recorded for a template, each a `TemplateSample` (importable from `web_router`) with the `input` it accepted and the `output` record it returned -- the shortest route to a first run of a template you have not run before. Nimble publishes one per template, and its catalogue rows carry the published version whole, so a `templates()` page describes each template as fully as `template()` does, schemas and samples included. The MCP `template` tool returns `samples` beside the schemas, whole or not at all, as the schemas go; a listing row from `templates` now carries `required_inputs`, the schema's own `required` list, and `sample_inputs`, the first recorded input that names any, left out whole when it is too large for the listing, so a URL-keyed template is told from an id-keyed one without a second call. `run_template`'s description says what a run bills: one template run on the vendor's account, on Nimble at one flat rate for every template, with the dated figure in `benchmarks/providers/PRICING.md` and never in code.
+- `answer()`, a seventh method, and its async twin: `WebRouter.answer(query, provider=...)` asks one question and returns the backend's own written answer with the sources it rests on, in one call -- between `search()`, which returns pages, and `research()`, a job of minutes. `AnswerResponse` carries `answer`, `citations` (the shared `Citation`; an inline marker in the answer goes in `field`), `outcome` (`partial` only when the backend says it stopped early), `request_id` and `raw`, one payload per call. An empty answer is returned as `""`, never raised. The options are `include_domains`, `exclude_domains`, `country`, `locale` and `recency` (`day`, `week`, `month` or `year`); a backend refuses each one it does not map with `UnsupportedParameterError`, before anything is sent. With `provider` unset the router's default serves the call when it is an answer backend, else the one configured answer backend, and a key passed in `provider_config` counts, and otherwise it raises `NoAnswerProviderError`, a `ProviderNotFoundError`, naming the configured backends when there are several and the variables to set when there are none. On the usual default, `auto`, that is answer()'s own `auto`: every answer backend you hold a key for, cheapest first at list price (Perplexity, Exa, You.com, Linkup, Parallel, then Brave). A backend that does not map an option the request sets is passed over without being built, one that refuses a value before sending or fails or answers with nothing is passed over for the next, each one tried bills, and with no key it raises `NoAnswerProviderError` naming the variables to set. `provider_config={"auto": {"chain": {"answer": [...]}}}` sets the order, and `fallback_on_empty=False` returns the first answer, empty or not. `AnswerProvider` and `HttpAnswerProvider` to add a backend, `register_answer_provider()`, `available_answer_providers()` and `configured_answer_providers()` beside the other registries, and an `answer` extra, which `mcp` and `all` include.
+- `benchmarks/providers/answer.py`, the answer scan: every configured answer backend on the same questions as the search scan, each backend's own answer graded by the same judge, with `--baseline` setting a finished search scan of the same questions and judge beside it. A row whose sources include one of SealQA's own pages, cited or only read, is marked leaked and left out of accuracy; cost is shown only where a backend states it. The latencies quoted for each answer backend are the medians from its run on 300 SimpleQA questions on 2026-11-01, graded by `openai:gpt-4o`. `PRICING.md` gains an Answer section.
+- `answer()` as a tool for an agent framework. The Claude and OpenAI `WebRouterTools` take `"answer"` in `methods` and serve `web_router_answer`, sent to `answer_provider`, else to `provider` when it answers, else to the router's default answer backend; with none to use, building the tools raises `NoAnswerProviderError`. LangChain gains `WebRouterAnswer` (`web_answer`). The model sends only the question and reads the answer whole with its citations, each snippet cut to `result_chars`; `routing_guide()` gains a paragraph for it when it is exposed. It is never exposed by default, since every answer backend needs a key and bills each call, so the default tools, the guide and the agent benchmark are unchanged.
+- The MCP server's `answer` tool, its twenty-first: the same call as `answer()`, shaped to fit a context window with the answer first, each citation's `field` marker kept, and a handle for `fetch_raw`. `provider` is optional, and only the configured answer backends are offered; unnamed, the router's `auto` tries them cheapest first. The capabilities resource keys its backends as `answer`, and `unlock` lists the ones a key would add.
+- Perplexity as an answer backend (`perplexity`): its Agent API at the `fast` effort, one call to `/v1/responses` answering in about two seconds. Maps `include_domains` or `exclude_domains` (its `search_domain_filter`, an excluded domain prefixed `-`; both together are refused before the call), `recency` and `country` (`user_location`) through the `web_search` tool, set only when a filter is; `locale` is refused. The answer cites inline as `[N]`, and each source it cites carries its marker in `Citation.field`. An `incomplete` response is `partial`. Verified live.
+- You.com as an answer backend (`you`): its Answer API on `api.you.com`, answering in about two seconds. Maps `include_domains`, `exclude_domains` and `country` to its own fields and `recency` to `freshness`; it takes one domain list, so asking for both raises before the call, and `locale` is refused. Its citations are only the sources the answer cites, marked `[[1, 2]]`; each carries its marker in `Citation.field` and its title from the pages considered. Verified live.
+- Parallel as an answer backend (`parallel`): its Chat API (beta) with the `lite` model, answering in about six seconds, the fastest model whose `basis` ties its sources to the answer. Each citation carries the basis's `confidence` in `extra`; a `finish_reason` of `length` is `partial`. The Chat API takes no source filter, so every option is refused. Verified live.
+- Exa as an answer backend (`exa`): its Answer API, answering in about 1.3 seconds with its stated cost in `raw`. The answer cites inline as `[N]`, numbering its citations from 1, and each cited source carries its marker in `Citation.field`. No option is mapped: the API has no source filter, and `userLocation` showed no clear effect, so `country` is refused. Verified live.
+- Linkup as an answer backend (`linkup`): its Search API with `outputType: sourcedAnswer`, answering in about a second. Maps `include_domains`, `exclude_domains` and `recency`, sent as `fromDate` that far back from today; `country` and `locale` have no Linkup field and are refused. Its sources are every page read; `includeInlineCitations` is always sent, so the answer marks the ones it rests on as `[N]`, and each carries its marker in `Citation.field`. Verified live.
+- Brave as an answer backend (`brave`): its Answers API, `POST /res/v1/chat/completions` with `model: brave`, answering in two to three seconds. It returns its sources only on a streamed call with `enable_citations`, so the router streams it and reads the whole stream; the answer is the text with Brave's `<citation>` and `<usage>` tags taken out, and each citation tag becomes a `Citation`, in order, its `number` and its span in the answer in `extra`. `raw` keeps the stream's events, the `<usage>` tag with the call's stated cost among them. It reads `BRAVE_ANSWER_API_KEY`, a key on Brave's Answers plan, separate from `BRAVE_SEARCH_API_KEY`. No option is mapped: the API has no source filter, and `language` showed no effect, so `locale` is refused. Verified live.
+
+### Changed
+
+- The `evals` extra now allows openai 3 (`openai>=1.0,<4`), and the lock moves to openai 3.45.0 and pyarrow 26.0.1 (25.0.1 stays for Python 3.10, which pyarrow 26 no longer supports). openai 3 uses HTTPX2 and no longer installs `httpx`; web-router still declares `httpx` itself, so nothing else changes. The Parallel answer backend's docs link points at its Chat Completions reference, since the old Chat API guide is gone.
+- The `max_results` description, in `SearchRequest`'s JSON schema and the MCP `search` tool, now steers an agent to 5 to 10 results instead of one. The README's "Wrapping `search` for your own agent" shows how to pin the number instead.
+- `auto` now moves to the next backend when one answers with nothing usable, as it does on an error: a search with no results and no `answer`, or an extract whose every document is blank. A document's page status is not read, since only some backends report one. When every member answers empty, the first empty answer comes back, naming its backend, rather than an error. A call that ends empty has tried every backend that can serve it, one after another, and each one you hold a key for bills for it. `provider_config={"auto": {"fallback_on_empty": False}}` returns the first answer, empty or not; the MCP server has no such switch. `max` is unchanged.
+- Nimble's `samples` moved out of `Template.extra` into the typed `Template.samples`; a caller reading `template.extra["samples"]` reads `template.samples` now.
+
+### Fixed
+
+- An error whose exception has no text -- httpx's read and connect timeouts -- now names its type instead of ending blank: a timed-out answer read `answer failed: ` and now reads `answer failed: ReadTimeout`. The same for every method's wrapped failure and the judge's.
+
+## [0.8.0] - 2026-10-28
+
+### Added
+
+- AWS AgentCore Web Search as a search backend (`agentcore`), through the caller's 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; botocore comes with a new `aws` extra, which `all` includes. Maps `max_results` (at most 25), `include_domains` and `exclude_domains`; on a target older than connector 1.2.0, which takes no filters, the domain options raise rather than being dropped. A date range goes through `provider_options["filters"]["publishedDateFilter"]` and merges with the mapped domains. `auto` tries it last, after DeepSeek, so no existing call changes backend. Setup and teardown: `docs/agentcore-setup.md`.
+
+### Fixed
+
+- Screenshots on Anchor are PNG, as on every other backend. Anchor's browser answers a PNG request with JPEG, even over raw CDP, so `Screenshot.png` held JPEG bytes, `width` and `height` were read from the wrong header (65536 by 4293001688), and the MCP server sent them as `image/png`. A capture that is not PNG is now converted, with Pillow, which the `browser` extra now installs. Checked live on Anchor.
+
+## [0.7.0] - 2026-10-26
+
+### Added
+
+- Templates, a sixth method: `WebRouter.run_template(name, inputs, provider=...)` runs one of a vendor's saved, site-specific extractions (Nimble's Extract Templates today) on one page and returns the record it parsed in `TemplateResponse.data`, `templates(provider=...)` lists one page of the vendor's catalogue as a `TemplatePage`, and `template(name, provider=...)` describes one as a `Template` with the JSON Schema of the inputs a run takes and the record it returns; each has its async twin. A template's inputs are its own -- a URL for some, an id, a slug or a search term for others -- which is why this is a method rather than an option on `extract`, and its name belongs to one vendor, which is why `provider` is required and there is no template `auto`. `format` asks for the page beside the record as `markdown` or `html`; unset, no page comes back. A run the backend could not complete, a page the site answered with 4xx or 5xx, or a parse that failed raises `ProviderError` with the reason, never an empty record; an unknown name raises the new `TemplateNotFoundError`. Nimble is the first backend (`NimbleTemplateProvider`, installed by `[extract]`, verified live), with `TemplateProvider` to add another and `register_template_provider()`, `available_template_providers()` and `configured_template_providers()` beside the other registries. The MCP server adds `templates`, `template` and `run_template`, which alone require `provider`, carry handles for `fetch_raw`, and are keyed as `template` in the capabilities resource.
+- `contracts/<method>/<provider>.json`: for every provider, the wire fields each option value sends, read from the provider's own code by `make contracts`, beside the vendor's reference pages, where each mapping was verified (live or in the docs) and the vendor's options no mapping sends. CI fails when a contract no longer matches its provider or leaves a hand-written field empty, so a mapping cannot change without its contract. Extract Template backends have one too. [AGENTS.md](AGENTS.md#provider-contracts) says how to start one.
+- `max`, an extract provider that sends the request to every backend `auto` would try, all at once, and returns the first document back -- `WebRouter(Provider.MAX).extract(url)`, with `response.provider` naming the backend that answered. Every fetch it starts is billed by its backend, so it costs up to one extract per configured backend per URL -- most backends take one URL per request, and a loser keeps fetching after the winner returns -- and is never the default. Only a document wins: a backend that refused, could not be built or returned nothing is its own loss, and when every one loses the error names each reason. `provider_config={"max": {"hedge": 0.8}}` runs the first member alone for that long and starts the rest only if it has not answered, so most one-URL calls stay at one fetch; a first member that fails early, or answers only part of the list, starts the rest at once. The hedge covers the first member's whole call, so it does not cap the cost of a multi-URL request. The members are `auto`'s: a `chain` or `members_config` set under `"auto"` in `provider_config` applies to `max` too, unless its own `"max"` entry sets one. `format` routes the same way, and the sync router's `close()` waits for a race's losers before shutting their clients while the async router cancels them. `max` joins `auto` in `BENCHMARK_EXCLUDED`, and the MCP `extract` tool offers it under `provider` with its cost in the description.
+- `WebRouter.benchmark_extract()` and its async twin: the same URLs fanned out across several extract backends at once, through the public `extract` path, one `ExtractBenchmarkRun` per provider in an `ExtractBenchmarkReport` -- measured facts only, as `benchmark()` reports for search. A backend that fails, cannot return the format, has no credentials or runs out of the comparison's `timeout` (`BENCHMARK_EXTRACT_TIMEOUT`, 120 seconds) is its own row's error, and a call that fetched some URLs and not others is an answered row whose response says which. `BenchmarkRun` and `BenchmarkReport` now share a base with the extract pair; their fields and behaviour are unchanged, except that a row for a backend that could not be built reports a latency of exactly zero on the async router too.
+- `benchmarks/providers/extract.py`: every configured extract backend on the same URLs, tabulated per backend (pages returned with text, empty, failed, timed out, refused, latency, median length) and per category, with a suggested `auto` extract order. Two URL sets ship under `benchmarks/providers/urls/` -- `general` (455 URLs) and `social-pdf` (908 URLs), URL lists sampled from public pages -- and `--urls` takes a CSV of your own. The scan writes `run.json` before its first call and each URL's rows as it finishes, so one that dies keeps what it paid for, and `--combine` on that folder alone reports the rows it fetched against the URLs asked. `examples/compare_extract_providers.py` shows the method on one URL.
+- `WebRouter.classify()` and `WebRouter.execute()`, an opt-in spike (unchanged unless you pass `decider=`). `classify(query)` asks a decider one set of questions (tool, recent, coverage, well_scoped) and turns the labels into a `Route`: the method and the auto chain to run it on, searching nothing. `execute(route)` runs it. Passing `urls` routes to extract and `output_schema` to research without asking; a decider that fails, or answers below 0.5 confidence, gives today's default, search on the default chain, with `Route.fallback` saying why (`decider_error`, `low_confidence`, `no_url`, `no_backend_for_method`). The decider is swappable: `WebRouter(decider=...)` takes `"keywords"` (simple keyword rules, keyless, with fixed confidences that are not measured; a research or browse pick sits below the threshold, so it falls back to search), `"jev"` (TypeSafe's Jev, reading `TYPESAFE_API_KEY`), `"llm"` (a chat model with structured outputs over any OpenAI-compatible API, with the `evals` extra, taking `api_key=` or reading `OPENAI_API_KEY`; its version carries a hash of its prompt and schema, `gpt-4.1-mini+p<8 hex>`), a name given to `register_decider()`, or any object with `decide()` and `close()`. `decider_config=` passes constructor kwargs to a decider given by name, as `provider_config=` does for backends. Every built-in decider reports confidence on Jev's normalized scale, `(p - 1/n)/(1 - 1/n)` (`normalized_confidence()`), and the llm decider scales its probabilities to sum to 1 before they are checked; an answer it cannot read takes the `decider_error` fallback. A decider that raises anything, not only `ProviderError`, takes the `decider_error` fallback. Exception types a decider names in its `passthrough` attribute propagate instead of becoming a default route.
+- Browser Use now maps `output_schema`, `max_steps` and `allowed_domains`, each checked against a live task on 2026-10-21; they were refused before. The schema is sent as Browser Use's `structuredOutput` and the answer comes back as `structured`; an answer that is not JSON stays in `answer`. `auto` can now serve a browse call that sets any of the three, through Browser Use.
+
+### Fixed
+
+- `benchmarks/providers/run.py` writes `run.json` before its first search and each depth's rows to `rows.jsonl` as that depth finishes, so a scan that dies keeps what it paid for; it wrote everything at the end, so a dropped connection or a Ctrl-C an hour in lost every row. `--combine` on that folder alone reports it, naming the backends whose depth never finished.
+- Nimble enrichments (`research` with `records`) work as documented. Nimble takes a table schema for one, so the row schema you pass as `output_schema` is now sent as an array of rows; it was sent as is and refused with a 422. `records` without an `output_schema`, or at `effort="low"`, which Nimble also refuses, now raise before a run starts. Checked live.
+- Browser Use steps now carry a `detail` and an `action`. `detail` came from `nextGoal`, which live tasks always return empty, so it was always `None`; it now reads the step's `memory`. A step that took a single action, which every step in four live tasks did, now has it as `action`. `nextGoal` moves to `extra`.
+
+## [0.6.0] - 2026-10-20
+
+### Added
+
+- Logging in once and reusing the login on vendor browser sessions. `profile` and `persist_profile` are now mapped on Browserbase (a context), Steel, Hyperbrowser and Anchor (a profile name), as they already were on Kernel, so a session opened on a profile with `persist_profile=True` saves its cookies and storage when released, and the next session on that profile starts logged in. The handle's new `control_url()` returns a page where a person can see and drive the session to log in: Browserbase's live view, fetched on first call, and the interactive live view each other vendor returns on open. It is a credential like `cdp_url`, kept as a `SecretStr` on the new `BrowserSession.control_url` and out of `repr` and serialization; `live_view_url` stays for pages that grant no control. All of it was checked live on 2026-10-20 on all five vendors. `persist_profile` without a `profile` raises. `auto` refuses `profile` and `persist_profile`, since a profile is saved on one backend; name that backend. The MCP server's `browser_open` still takes no profile, and never shows a control URL.
+- Kernel as a browser session backend (`kernel`), over its Browsers API, reading `KERNEL_API_KEY`. It maps `idle_timeout`, `stealth`, `headless`, `viewport`, `profile` and `persist_profile`, each checked against a live session. Kernel has an idle limit and no lifetime, so `timeout` raises and no default lifetime is sent; Kernel's own 60-second idle limit applies unless you set `idle_timeout`. `stealth` also brings Kernel's CAPTCHA solver and stealth proxy, so `solve_captchas` raises, and `proxy_country` raises because Kernel needs a proxy created first; pass an existing one through `provider_options`. `auto` tries Kernel after the other vendors and before `local`, so no existing call changes backend.
+
+### Changed
+
+- Steel's `debugUrl`, Hyperbrowser's `liveUrl` and Anchor's `live_view_url`, which were only in `raw`, are now returned by `control_url()`. Each grants control of the browser, so none of them becomes `live_view_url`, which is unchanged.
+
+## [0.5.0] - 2026-10-19
+
+### Added
+
+- DeepSeek as a search and an extract backend (`deepseek`), reading `DEEPSEEK_API_KEY`. Search maps `max_results`, `include_domains`, `exclude_domains` and `locale`; the filters go inside the query, and a query over DeepSeek's 128-character limit is refused, not cut. `search_depth` and `country` raise. A result's content is DeepSeek's summary unless `need_content` is sent through `provider_options`. Extract returns `markdown`, starting at most 5 fetches a second, DeepSeek's account limit; `ExtractProvider.min_start_interval` lets any backend space its fetches this way. `auto` tries DeepSeek last in both chains, so no existing call changes backend.
+- You.com as a research backend (`you`), over its Research API on `api.you.com`, reading the same `YOU_API_KEY` as search. A run is a background task, polled until it finishes; the answer is You.com's markdown and its sources become citations. `effort` maps `low`, `medium`, `high` and `max` onto `lite`, `standard`, `deep` and `exhaustive`; `frontier` is reachable through `provider_options`. `output_schema` is not mapped yet, and You.com offers no cancel. `auto` tries You.com last in the research chain when you hold its key, so no call that was already being served moves. If `YOU_API_KEY` was the only key you held, `research()` through `auto` now starts a billed You.com run instead of raising `ConfigurationError`.
+
+### Fixed
+
+- Jina: an empty `JINA_API_KEY` is treated as no key. It was sent as a bare `Bearer ` header, which httpx rejects, so every Jina call failed and `auto` quietly moved on to the next extract backend. Every provider now strips its API keys and settings, so a whitespace-only value counts as missing, a padded one such as a key with a trailing newline is sent without the padding, and `configured_*_providers()` no longer lists a provider whose only key is blank.
+- A research run or browse task whose status request stalled until the caller's `timeout` ran out raised `ProviderError`, which carries no job id, instead of `ResearchTimeoutError` / `BrowseTimeoutError`, so a run that was still going, and billing, could not be come back to. A poll whose request timed out once the deadline has passed now raises the method's timeout error with the job id, the failure as its cause. Any other poll failure -- one with time left, or an auth error or unrecognized status after the deadline -- still raises `ProviderError`.
+- Bright Data treats a URL its unlocker could not fetch, such as an unresolvable host, as a failure with Bright Data's reason and error code, instead of returning it as an empty document with status 502. A single-URL `extract()` raises `ProviderError`, and `auto` moves on to the next extract backend; in a multi-URL call the URL is listed in `ExtractResponse.failures` beside the pages that were fetched. A page the target site served, an error page included, is still a document.
+
+## [0.4.0] - 2026-10-14
+
+### Added
+
+- Keenable as a search and an extract backend (`keenable`), over its Search and Fetch APIs, reading `KEENABLE_API_KEY`. Search maps `max_results`; extract returns `markdown` and asks for up to 500,000 characters, where Keenable's own default cuts a page at 50,000. With `allow_keyless=True` both run on Keenable's keyless `/public` endpoints, rate-limited per IP. `auto` tries Keenable after the keyless tier when you hold its key, and its keyless tier last of all, so no call that was already being served moves.
+
+## [0.3.0] - 2026-10-12
+
+### Added
+
+- `NimbleProvider`, `NimbleExtractProvider` and `NimbleResearchProvider` accept the caller's own `AsyncNimble` as `async_client`, directly or through `provider_config={"nimble": {"async_client": client}}`. Such a provider needs no key, builds no sync client (a sync call raises `ConfigurationError`, and so does a synchronous `WebRouter` handed a client in `provider_config`), and leaves the client open on `aclose()`. An `api_key` passed beside the client raises `ConfigurationError` rather than replace its credential. Other options passed beside it apply to a copy that shares its connection pool, and research keeps the client's own timeouts, clamping only the read limit to the run's budget. `auto` counts Nimble as configured when it is handed a client, as it does for an `api_key`.
+
+### Changed
+
+- A missing extra's error now tells you to run `uv sync --extra <name>` in your clone, or `make setup` for every extra, instead of a `pip install` line.
+- The MCP server's `web-router://capabilities` resource adds `unlock`: for each method, the backends no key has reached yet, and the environment variables that would add each (names only).
+- Project links point at this repository, and the README opens with the alpha notice. The package carries no license metadata during the alpha; the code is shared under your agreement.
+
+## Alpha snapshot - 2026-10-08
+
+The first alpha snapshot, shared with alpha users. Not a published release:
+the next published version will be above it.
+
+- **Five methods behind one interface:** `search`, `extract`, `research`
+  (agentic, minutes rather than seconds), `open_browser` (a browser session you
+  drive, with page actions built in) and `browse` (a hosted browser agent's
+  task). Each call behaves the same whichever backend serves it.
+- **Many backends,** from Nimble, Tavily, Exa, Brave, Perplexity, Parallel,
+  Linkup, You.com, WebIQ, Firecrawl, Oxylabs, Bright Data and Jina Reader to
+  Steel, Browserbase, Hyperbrowser, Anchor, Browser Use, Skyvern and a local
+  Chromium. Several need no key at all.
+- **`auto`,** the default for every method: it tries the backends you hold keys
+  for, then the keyless ones, and routes each request to a backend that can
+  serve it. Pass a `chain` to choose your own order, per method.
+- **An MCP server** (`web-router-mcp`) exposing every method as tools, including
+  `browser_*` tools that drive a session, for Claude Code, Claude Desktop,
+  Cursor and other MCP clients.
+- **Agent integrations:** tools for the Claude and OpenAI APIs, and for
+  LangChain, with a routing guide that tells a model which tool fits which need.
+- **Benchmarking and evaluation:** `benchmark()` compares backends on the same
+  query, `evaluate()` scores their accuracy on a question set with an LLM judge,
+  and `benchmarks/` holds the scripts to run both at scale.

webrouter-0.11.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Nimble
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.