@allansantos-dev/smart-tool 0.0.0-stage → 0.9.1

package/web_adapters/node/package.json

@@ -0,0 +1,12 @@
+{
+  "private": true,
+  "name": "smart-tool-web-adapters",
+  "version": "0.9.0",
+  "description": "Adaptadores Node empacotados com a Smart Tool",
+  "dependencies": {
+    "@angular/compiler": "20.3.0",
+    "java-parser": "3.0.1",
+    "open-websearch": "2.1.11",
+    "typescript": "5.9.3"
+  }
+}

package/web_adapters/node/wikipedia-search.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Uso: node wikipedia-search.mjs "consulta" [--num 8] [--lang pt]
+// Saída: JSON no stdout — [{ title, url, snippet }, ...]
+// API oficial da Wikipedia (MediaWiki `action=query&list=search`), não scraping de SERP --
+// fonte de índice genuinamente diferente dos demais adaptadores (enciclopédica, sem
+// desafio anti-bot), mas só cobre conteúdo enciclopédico -- não serve pra cotação/notícia
+// do dia, por exemplo.
+import { parseArgs, stripTags } from './adapter-common.mjs';
+
+async function main() {
+  const { query, num, lang } = parseArgs(process.argv.slice(2),
+    'Usage: node wikipedia-search.mjs "query" [--num 8] [--lang pt]', { num: 8, lang: 'pt' });
+
+  const url = `https://${lang}.wikipedia.org/w/api.php?` + new URLSearchParams({
+    action: 'query', list: 'search', format: 'json', srlimit: String(num), srsearch: query,
+  });
+  const res = await fetch(url, {
+    headers: { 'user-agent': process.env.SMART_TOOL_USER_AGENT || 'SmartTool (local MCP search tool)' },
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!res.ok) {
+    throw new Error(`Wikipedia answered HTTP ${res.status}`);
+  }
+  const data = await res.json();
+  const hits = data?.query?.search ?? [];
+  if (hits.length === 0) {
+    throw new Error(`No Wikipedia (${lang}) result for this query.`);
+  }
+
+  const results = hits.slice(0, num).map((h) => ({
+    title: h.title,
+    url: `https://${lang}.wikipedia.org/wiki/${encodeURIComponent(h.title.replace(/ /g, '_'))}`,
+    snippet: stripTags(h.snippet || ''),
+  }));
+  process.stdout.write(JSON.stringify(results));
+}
+
+// Nunca process.exit() aqui: ver mesma nota em ddg-search.mjs (handle assíncrono do
+// AbortSignal.timeout ainda pendente na hora de um exit() imediato crasharia o libuv
+// no Windows) -- só marca o exit code e deixa o event loop drenar sozinho.
+main().catch((err) => {
+  console.error(String(err?.message ?? err));
+  process.exitCode = 1;
+});

package/web_document_graph.py

@@ -0,0 +1,71 @@
+"""Referências locais de HTML, CSS e Markdown; documentos textuais mantêm cobertura."""
+import posixpath
+import re
+from html.parser import HTMLParser
+from urllib.parse import unquote,urlsplit
+
+
+def analyze(sources,all_paths):
+    paths=set(all_paths);dependencies=[];diagnostics=[];parsed=[]
+    def reference(origin,value,line,kind):
+        if not value or value.startswith(('#','data:','javascript:','mailto:','tel:')):return
+        url=urlsplit(value)
+        if url.scheme or url.netloc:
+            dependencies.append({'source':origin,'target':None,'specifier':value[:300],'line':line,'kind':kind,'resolution':'external'});return
+        target=posixpath.normpath(posixpath.join(posixpath.dirname(origin),unquote(url.path))) if not url.path.startswith('/') else unquote(url.path).lstrip('/')
+        if target.startswith('../') or target==origin:return
+        found=target if target in paths else None
+        dependencies.append({'source':origin,'target':found,'specifier':value[:300],'line':line,'kind':kind,'resolution':'resolved' if found else 'unresolved'})
+    class Html(HTMLParser):
+        def handle_starttag(self,tag,attrs):
+            attrs=dict(attrs)
+            for attr in ('src','href','poster'):
+                if attr in attrs:reference(self.origin,attrs[attr],self.getpos()[0],'html_resource' if tag!='a' else 'document_link')
+            if attrs.get('srcset'):
+                for item in attrs['srcset'].split(','):
+                    value=item.strip().split(' ')[0]
+                    if value:reference(self.origin,value,self.getpos()[0],'html_resource')
+    def css_links(text):
+        # Scanner de tokens: ignora comentários e strings que apenas mencionam url().
+        i=0
+        def quoted(at):
+            quote=text[at];j=at+1;out=[]
+            while j<len(text):
+                if text[j]=='\\' and j+1<len(text):out.append(text[j+1]);j+=2;continue
+                if text[j]==quote:return ''.join(out),j+1
+                out.append(text[j]);j+=1
+            return ''.join(out),j
+        while i<len(text):
+            if text.startswith('/*',i):
+                end=text.find('*/',i+2);i=len(text) if end<0 else end+2;continue
+            if text[i] in ('"',"'"):
+                _,i=quoted(i);continue
+            match=re.match(r'(?i)(@import\s+|url\s*\()',text[i:])
+            if match and (i==0 or not (text[i-1].isalnum() or text[i-1] in '_-')):
+                start=i;i+=len(match[0])
+                while i<len(text) and text[i].isspace():i+=1
+                if i<len(text) and text[i] in ('"',"'"):value,i=quoted(i);yield value,text.count('\n',0,start)+1
+                elif match[0].lower().startswith('url'):
+                    end=text.find(')',i)
+                    if end<0:return
+                    value=text[i:end].strip();i=end+1;yield value,text.count('\n',0,start)+1
+                continue
+            i+=1
+    for path,text in sources.items():
+        extension=posixpath.splitext(path)[1].lower()
+        if extension in ('.html','.htm'):
+            parser=Html(convert_charrefs=True);parser.origin=path
+            try:parser.feed(text);parsed.append(path)
+            except (ValueError,AssertionError):diagnostics.append({'path':path,'reason':'HTML could not be fully parsed.'})
+        elif extension in ('.css','.scss','.sass','.less'):
+            for target,line in css_links(text):reference(path,target,line,'style_resource')
+            parsed.append(path)
+        elif extension in ('.md','.markdown'):
+            in_fence=False
+            for line_no,line in enumerate(text.splitlines(),1):
+                if re.match(r'^\s*(```|~~~)',line):in_fence=not in_fence;continue
+                if in_fence:continue
+                line=re.sub(r'`[^`]*`','',line)
+                for match in re.finditer(r'!?\[[^\]]*\]\(<?([^\s)>]+)>?(?:\s+[^)]*)?\)',line):reference(path,match[1],line_no,'document_link')
+            parsed.append(path)
+    return {'dependencies':dependencies,'diagnostics':diagnostics,'parsed':parsed}

package/web_fetch.py

@@ -0,0 +1,242 @@
+"""web_fetch: lê uma URL conhecida e devolve só a resposta ao pedido, feita pelo modelo mini do gateway.
+
+Desenho copiado do WebFetch do Claude Code (Markdown + pedido num modelo separado; code.claude.com/docs/en/tools-reference)
+e do OpenCode (`packages/opencode/src/tool/webfetch.ts`: limite de 5 MB, User-Agent de navegador). Medido em 2026-10-05
+(docs/spikes/web_fetch_rejudge.py), 37 pares (URL, pedido) reais do WebFetch nativo, juiz cego contra a página
+renderizada: melhor resposta 18 × 18 (1 empate), respondeu certo 22 × 16, caracteres devolvidos 35 mil × 72 mil;
+3,6 s de mediana, navegador em 7 de 37 (páginas montadas por JavaScript). Repetições da mesma URL nos transcripts:
+92 de 124 dentro de 24 h (PAGE_TTL_S).
+"""
+import codecs
+import http.client
+import ipaddress
+import json
+import socket
+import ssl
+import threading
+import time
+import urllib.parse
+
+import trafilatura
+
+import model_client
+import research_cache
+
+CACHE_NAMESPACE = "web_fetch"
+PAGE_TTL_S = 86400
+PAGE_MAX_CHARS = 60_000
+MAX_DOWNLOAD_BYTES = 5 * 1024 * 1024
+MAX_REDIRECTS = 5
+HTTP_TIMEOUT_S = 20
+READ_CHUNK = 64 * 1024
+THIN_CHARS = 1500
+PLACEHOLDER_SCAN_CHARS = 5000
+MIN_CHARS = 200
+ANSWER_MAX_TOKENS = 1500
+FAILED_TTL_S = 600
+PLACEHOLDERS = ("carregando", "loading...", "enable javascript", "habilite o javascript", "ative o javascript")
+TEXT_TYPES = ("text/plain", "text/markdown", "text/x-markdown", "application/json", "text/csv", "application/xml",
+              "text/xml")
+USER_AGENT = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) "
+              "Chrome/140.0 Safari/537.36")
+ANSWER_SYSTEM = (
+    "You answer a request about one web page using ONLY the page content provided. Cover every item the request "
+    "asks for. Keep exact names, versions, numbers, prices, flags, code and URLs; quote the exact lines when the "
+    "request asks for exact values or wording. Say explicitly which requested items the page does not contain. "
+    "No preamble. Answer in the language of the request."
+)
+_failed_lock = threading.Lock()
+_failed = {}
+
+
+class FetchError(RuntimeError):
+    pass
+
+
+def _ip_allowed(ip):
+    return ipaddress.ip_address(ip).is_global
+
+
+def _public_address(host, port):
+    """Resolves once; every address must be publicly routable (no private, loopback, link-local, CGNAT/Tailscale)."""
+    try:
+        infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
+    except (socket.gaierror, UnicodeError):
+        return None
+    addresses = [info[4][0] for info in infos]
+    try:
+        if not addresses or not all(_ip_allowed(address) for address in addresses):
+            return None
+    except ValueError:
+        return None
+    return addresses[0]
+
+
+def _target(url):
+    try:
+        parsed = urllib.parse.urlsplit(url)
+        port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    except ValueError:
+        return None
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        return None
+    address = _public_address(parsed.hostname, port)
+    return (parsed, port, address) if address else None
+
+
+def is_safe_target(url):
+    return _target(url) is not None
+
+
+class _PinnedHTTP(http.client.HTTPConnection):
+    """Connects to the address validated by _public_address, so a second DNS answer (rebinding) is never used."""
+
+    def __init__(self, host, port, address, timeout):
+        super().__init__(host, port, timeout=timeout)
+        self._address = address
+
+    def connect(self):
+        self.sock = socket.create_connection((self._address, self.port), self.timeout)
+
+
+class _PinnedHTTPS(http.client.HTTPSConnection):
+    def __init__(self, host, port, address, timeout):
+        super().__init__(host, port, timeout=timeout, context=ssl.create_default_context())
+        self._address = address
+
+    def connect(self):
+        sock = socket.create_connection((self._address, self.port), self.timeout)
+        self.sock = self._context.wrap_socket(sock, server_hostname=self.host)
+
+
+def normalize(url):
+    return urllib.parse.urldefrag(str(url or "").strip())[0]
+
+
+def mark_failed(key):
+    with _failed_lock:
+        now = time.monotonic()
+        for old in [k for k, at in _failed.items() if now - at >= FAILED_TTL_S]:
+            del _failed[old]
+        _failed[normalize(key)] = now
+
+
+def recently_failed(key):
+    with _failed_lock:
+        at = _failed.get(normalize(key))
+        return at is not None and time.monotonic() - at < FAILED_TTL_S
+
+
+def _left(deadline):
+    left = deadline - time.monotonic()
+    if left <= 1:
+        raise TimeoutError("Deadline expired before reading the page.")
+    return left
+
+
+def _get(url, deadline):
+    target = _target(url)
+    if target is None:
+        raise FetchError(f"URL rejected (internal, reserved or invalid network target): {url}")
+    parsed, port, address = target
+    cls = _PinnedHTTPS if parsed.scheme == "https" else _PinnedHTTP
+    conn = cls(parsed.hostname, port, address, min(HTTP_TIMEOUT_S, _left(deadline)))
+    path = urllib.parse.urlunsplit(("", "", parsed.path or "/", parsed.query, ""))
+    try:
+        conn.request("GET", path, headers={"User-Agent": USER_AGENT, "Accept-Language": "en,pt-BR;q=0.8",
+                                           "Accept": "text/markdown, text/html;q=0.9, text/plain;q=0.8, */*;q=0.5"})
+        sock = conn.sock
+        response = conn.getresponse()
+        if response.status in (301, 302, 303, 307, 308):
+            return response.status, response.getheader("Location"), None, None
+        if response.status >= 400:
+            raise FetchError(f"HTTP {response.status} at {url}")
+        body = bytearray()
+        while True:
+            if sock.fileno() != -1:
+                sock.settimeout(min(HTTP_TIMEOUT_S, _left(deadline)))
+            chunk = response.read(READ_CHUNK)
+            if not chunk:
+                break
+            body += chunk
+            if len(body) > MAX_DOWNLOAD_BYTES:
+                raise FetchError("Page larger than 5 MB.")
+        return response.status, None, response.headers, bytes(body)
+    except (OSError, http.client.HTTPException) as exc:
+        raise FetchError(f"Network failure at {url}: {exc}") from None
+    finally:
+        conn.close()
+
+
+def fetch_http(url, deadline):
+    """GET with redirects followed by hand (every hop re-validated). Returns (final_url, content_type, charset, body)."""
+    current = url
+    for _ in range(MAX_REDIRECTS + 1):
+        status, location, headers, body = _get(current, deadline)
+        if headers is None:
+            if not location:
+                raise FetchError(f"HTTP {status} without a target at {current}")
+            current = urllib.parse.urljoin(current, location)
+            continue
+        return current, headers.get_content_type(), headers.get_content_charset(), body
+    raise FetchError(f"More than {MAX_REDIRECTS} redirects from {url}.")
+
+
+def _decode(body, charset):
+    try:
+        codecs.lookup(charset or "utf-8")
+    except LookupError:
+        charset = None
+    return body.decode(charset or "utf-8", errors="replace")
+
+
+def thin(text):
+    stripped = text.strip()
+    if len(stripped) < THIN_CHARS:
+        return True
+    return len(stripped) < PLACEHOLDER_SCAN_CHARS and any(p in stripped[:600].lower() for p in PLACEHOLDERS)
+
+
+def read_page(url, deadline, render):
+    """Page text (Markdown) from the 24 h cache, HTTP + trafilatura, or `render(url, deadline)` when HTTP comes thin."""
+    url = normalize(url)
+    for entry in research_cache.candidates(CACHE_NAMESPACE, url, limit=1):
+        if entry.get("query") == url and time.time() - entry["saved_at"] < PAGE_TTL_S:
+            return {**entry["result"], "cached": True, "fetched_at": entry["saved_at"]}
+    final_url, kind, charset, body = fetch_http(url, deadline)
+    rendered, render_error = False, None
+    if "html" in kind:
+        # Bytes, not str: trafilatura detects the encoding declared in <meta charset> when the header has none.
+        text = trafilatura.extract(body, output_format="markdown", include_links=True, include_tables=True,
+                                   include_formatting=True, url=final_url) or ""
+        if thin(text):
+            try:
+                markdown = render(final_url, deadline)
+            except Exception as exc:
+                markdown, render_error = "", f"{type(exc).__name__}: {exc}"[:200]
+            if len(markdown.strip()) > len(text.strip()):
+                text, rendered = markdown, True
+    elif kind in TEXT_TYPES:
+        text = _decode(body, charset)
+    else:
+        raise FetchError(f"Content type {kind} is not read by web_fetch ({final_url}).")
+    if len(text.strip()) < MIN_CHARS:
+        detail = f"; browser failed: {render_error}" if render_error else ", not even when rendered in the browser"
+        raise FetchError(f"Page without readable text ({final_url}){detail}.")
+    page = {"url": url, "final_url": final_url, "text": text[:PAGE_MAX_CHARS], "truncated": len(text) > PAGE_MAX_CHARS,
+            "rendered": rendered}
+    saved_at = research_cache.put(CACHE_NAMESPACE, url, page, {})
+    return {**page, "cached": False, "fetched_at": saved_at or time.time(), "render_error": render_error}
+
+
+def answer(model, prompt, page, deadline):
+    response = model_client.fetch("/v1/chat/completions", model_client.get_token(), method="POST",
+                                  timeout=min(90, _left(deadline)), body={
+        "model": model, "temperature": 0, "max_tokens": ANSWER_MAX_TOKENS,
+        "messages": [{"role": "system", "content": ANSWER_SYSTEM},
+                     {"role": "user", "content": json.dumps({"request": prompt, "page": page["text"]},
+                                                            ensure_ascii=False)}]})
+    text = (response["choices"][0]["message"].get("content") or "").strip()
+    if not text:
+        raise RuntimeError("The model returned no answer for the page.")
+    return text

package/web_search_adapters.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""Registro único dos adaptadores de motor de busca do `web_search`. Cada adaptador é um
+subprocesso independente (executável + script) que recebe `[query, "--num", n, *extra_args]`
+e devolve `[{title, url, snippet}, ...]` em JSON no stdout — mesmo contrato pra todos, então
+`smart_tool_daemon._handle_web_search` itera a lista sem precisar saber o que cada um faz por
+dentro. Acrescentar/remover/reordenar um motor é só editar `ADAPTERS`; `router.py` monta o
+prompt/schema do modelo de roteamento a partir do campo `hint` de cada entrada, então também
+não precisa mudar por adaptador novo.
+
+Três etapas, marcadas por `fan_out` e `fallback_group` (ver ADR 0006):
+
+- `fan_out=True` ("duckduckgo", "open-websearch", "wikipedia", "yahoo", "exa", "parallel", "keenable",
+  "google"): baratos e rápidos — `_handle_web_search` dispara todos em paralelo (google pelo navegador
+  residente). exa/parallel/keenable seguem o padrão de Hermes e OpenCode: plano público sem chave, chave
+  opcional do usuário no mesmo endpoint. e combina os resultados
+  de quem responder a tempo, pra garantir diversidade de fonte em toda chamada em vez de
+  parar no primeiro que responder.
+- `fallback_group="http"` ("tavily", "firecrawl"): APIs com cota gratuita sem chave
+  e chave pessoal opcional; entram sob demanda se a cobertura ainda for insuficiente.
+- `fallback_group="browser"` ("camoufox", "startpage"): navegador real, mais lento;
+  entra só quando as fontes anteriores ainda forem insuficientes, em sequência.
+- `service_engine`: o tier roda no navegador Camoufox residente (browser_service.py), uma
+  instância com abas reaproveitadas para todos os consumidores, em vez de um script por chamada.
+
+Sem entrada pra Bing: por períodos ele devolve um SERP genérico da entidade (ou de outro
+assunto), sempre com 200 e sem erro. Em 2026-10-02 um cliente HTTP com TLS de navegador
+recebeu resultados reais (44 de 50); em 2026-10-03 o mesmo cliente, o Camoufox e o Chromium
+receberam a isca. Por não lançar erro, mascararia qualquer fallback depois dele; o índice do
+Bing entra pelo tier yahoo.
+"""
+import os
+import sys
+
+PACKAGE_DIR = os.path.dirname(os.path.abspath(__file__))
+NODE_ADAPTER_DIR = os.path.join(PACKAGE_DIR, "web_adapters", "node")
+BROWSER_ADAPTER_DIR = os.path.join(PACKAGE_DIR, "web_adapters", "browser")
+LOCAL_NODE_EXECUTABLE = os.path.join(NODE_ADAPTER_DIR, ".node-runtime", "node.exe")
+NODE_EXECUTABLE = LOCAL_NODE_EXECUTABLE if os.path.isfile(LOCAL_NODE_EXECUTABLE) else "node"
+CAMOUFOX_VENV_PYTHON = os.path.join(BROWSER_ADAPTER_DIR, ".venv", "Scripts", "python.exe")
+BROWSER_SERVICE_SCRIPT = os.path.join(BROWSER_ADAPTER_DIR, "browser_service.py")
+DDG_SEARCH_SCRIPT = os.path.join(NODE_ADAPTER_DIR, "ddg-search.mjs")
+OPEN_WEBSEARCH_ADAPTER_SCRIPT = os.path.join(NODE_ADAPTER_DIR, "open-websearch-adapter.mjs")
+WIKIPEDIA_SEARCH_SCRIPT = os.path.join(NODE_ADAPTER_DIR, "wikipedia-search.mjs")
+EXTERNAL_SEARCH_SCRIPT = os.path.join(PACKAGE_DIR, "web_search_external.py")
+DDGS_SEARCH_SCRIPT = os.path.join(PACKAGE_DIR, "web_search_ddgs.py")
+
+FETCH_TIMEOUT_S = 15
+OPEN_WEBSEARCH_TIMEOUT_S = 30
+WIKIPEDIA_TIMEOUT_S = 15
+EXTERNAL_TIMEOUT_S = 18
+DDGS_TIMEOUT_S = 15
+GOOGLE_TIMEOUT_S = 12
+BROWSER_TIMEOUT_S = 60
+# O desafio do Startpage continua caro: duas buscas reais isoladas em 2026-09-29
+# retornaram resultados em 101s e 154s, mesmo com o cookie curto da primeira ainda
+# válido na segunda. Nenhum cookie semanal do Anubis foi emitido; o pré-aquecimento
+# periódico foi removido porque não evitava o custo da busca seguinte. Este tier só
+# roda como último fallback quando as fontes anteriores não cobrem a consulta.
+STARTPAGE_TIMEOUT_S = 240
+
+ADAPTERS = [
+    {
+        "name": "duckduckgo",
+        "executable": NODE_EXECUTABLE,
+        "script": DDG_SEARCH_SCRIPT,
+        "extra_args": [],
+        "timeout_s": FETCH_TIMEOUT_S,
+        "fan_out": True,
+        # Em inglês (não PT-BR): entra literal no system prompt do router_model em
+        # router.py, que é contrato com o modelo — ver convenção de idioma do AGENTS.md.
+        "hint": "plain fetch against DuckDuckGo HTML — fastest and cheapest, but fails "
+                "when DDG serves its JS anti-bot challenge (fetch never executes JS)",
+    },
+    {
+        "name": "open-websearch",
+        "executable": NODE_EXECUTABLE,
+        "script": OPEN_WEBSEARCH_ADAPTER_SCRIPT,
+        "extra_args": ["--engine", "duckduckgo"],
+        "timeout_s": OPEN_WEBSEARCH_TIMEOUT_S,
+        "fan_out": True,
+        "hint": "same DuckDuckGo index, via the open-websearch npm package's own HTTP "
+                "client — no browser, cheaper than camoufox; different access "
+                "technique than the plain-fetch duckduckgo tier",
+    },
+    {
+        "name": "wikipedia",
+        "executable": NODE_EXECUTABLE,
+        "script": WIKIPEDIA_SEARCH_SCRIPT,
+        "extra_args": [],
+        "timeout_s": WIKIPEDIA_TIMEOUT_S,
+        "fan_out": True,
+        "hint": "official Wikipedia search API, not a search-engine scrape — genuinely "
+                "different index (encyclopedic), no anti-bot risk at all, but narrow: "
+                "useless for time-sensitive queries (prices, news, weather)",
+    },
+    {
+        "name": "yahoo",
+        "executable": sys.executable,
+        "script": DDGS_SEARCH_SCRIPT,
+        "extra_args": ["--backend", "yahoo"],
+        "timeout_s": DDGS_TIMEOUT_S,
+        "fan_out": True,
+        "hint": "Yahoo SERP (Bing index) via the ddgs library — a different index than the "
+                "DuckDuckGo tiers, ~1 s, keyless; intermittently returns nothing",
+    },
+    {
+        "name": "exa",
+        "executable": sys.executable,
+        "script": EXTERNAL_SEARCH_SCRIPT,
+        "extra_args": ["--provider", "exa"],
+        "timeout_s": EXTERNAL_TIMEOUT_S,
+        "fan_out": True,
+        "hint": "Exa neural index via its public MCP (keyless free tier, optional user key) — strong on official docs and primary sources",
+    },
+    {
+        "name": "parallel",
+        "executable": sys.executable,
+        "script": EXTERNAL_SEARCH_SCRIPT,
+        "extra_args": ["--provider", "parallel"],
+        "timeout_s": EXTERNAL_TIMEOUT_S,
+        "fan_out": True,
+        "hint": "Parallel index via its public search MCP (keyless free tier, optional user key) — ranked excerpts, ~1 s",
+    },
+    {
+        "name": "keenable",
+        "executable": sys.executable,
+        "script": EXTERNAL_SEARCH_SCRIPT,
+        "extra_args": ["--provider", "keenable"],
+        "timeout_s": EXTERNAL_TIMEOUT_S,
+        "fan_out": True,
+        "hint": "Keenable independent index (own crawler and ranking) via its public endpoint, optional user key — ~0.3 s",
+    },
+    {
+        "name": "google",
+        "service_engine": "google",
+        "timeout_s": GOOGLE_TIMEOUT_S,
+        "fan_out": True,
+        "hint": "Google SERP via the resident Camoufox browser — best index, ~1-2 s once the "
+                "browser is open; one search at a time, paused for an hour after a captcha",
+    },
+    {
+        "name": "tavily",
+        "executable": sys.executable,
+        "script": EXTERNAL_SEARCH_SCRIPT,
+        "extra_args": ["--provider", "tavily"],
+        "timeout_s": EXTERNAL_TIMEOUT_S,
+        "fan_out": False,
+        "fallback_group": "http",
+        "hint": "independent ranked web search via Tavily; keyless quota is rate-limited, "
+                "so use only when existing results are incomplete or irrelevant",
+    },
+    {
+        "name": "firecrawl",
+        "executable": sys.executable,
+        "script": EXTERNAL_SEARCH_SCRIPT,
+        "extra_args": ["--provider", "firecrawl"],
+        "timeout_s": EXTERNAL_TIMEOUT_S,
+        "fan_out": False,
+        "fallback_group": "http",
+        "hint": "independent Firecrawl search API with clean snippets; keyless quota is "
+                "rate-limited, so use only when cheaper results remain insufficient",
+    },
+    {
+        "name": "camoufox",
+        "service_engine": "duckduckgo",
+        "timeout_s": BROWSER_TIMEOUT_S,
+        "fan_out": False,
+        "fallback_group": "browser",
+        "hint": "same DuckDuckGo index, via the resident Camoufox browser — solves the "
+                "anti-bot challenge the duckduckgo and open-websearch tiers can't",
+    },
+    {
+        "name": "startpage",
+        "service_engine": "startpage",
+        "timeout_s": STARTPAGE_TIMEOUT_S,
+        "fan_out": False,
+        "fallback_group": "browser",
+        "hint": "different index (Startpage, via the resident Camoufox browser) — the only fallback "
+                "that survives DuckDuckGo itself being down, not just the access "
+                "technique; subject to burst rate-limiting",
+    },
+]
+
+# Merge order of the round-robin. Measured 2026-10-03 (docs/spikes/merge_order_spike.py, 40 real queries, same
+# collected results): this order beat the previous random order 16 x 5 (19 ties), SearXNG consensus scoring 14 x 13.
+MERGE_PRIORITY = ["exa", "parallel", "google", "tavily", "firecrawl", "camoufox", "startpage", "keenable", "yahoo",
+                  "duckduckgo", "open-websearch", "wikipedia", "memoria"]
+DEFAULT_TIER_ORDER = [a["name"] for a in ADAPTERS]
+SPECS = {a["name"]: a for a in ADAPTERS}
+FAN_OUT_TIERS = [a["name"] for a in ADAPTERS if a["fan_out"]]
+FALLBACK_TIERS = [a["name"] for a in ADAPTERS if not a["fan_out"]]
+HTTP_FALLBACK_TIERS = [a["name"] for a in ADAPTERS if a.get("fallback_group") == "http"]
+BROWSER_FALLBACK_TIERS = [a["name"] for a in ADAPTERS if a.get("fallback_group") == "browser"]

package/web_search_ddgs.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Adaptador da biblioteca ddgs: um backend por chamada, sem chave."""
+import json
+import sys
+
+from ddgs import DDGS
+from ddgs.exceptions import DDGSException
+
+sys.stdout.reconfigure(encoding="utf-8")
+sys.stderr.reconfigure(encoding="utf-8")
+
+
+def parse_args(argv):
+    # Manual parsing: the query is positional and may start with "-" (e.g. "-v flag in pytest").
+    options, query_parts, i = {"--num": "8", "--backend": None, "--timeout": "10"}, [], 0
+    while i < len(argv):
+        if argv[i] in options and i + 1 < len(argv):
+            options[argv[i]] = argv[i + 1]
+            i += 2
+        else:
+            query_parts.append(argv[i])
+            i += 1
+    if not query_parts or not options["--backend"]:
+        raise ValueError('Usage: python web_search_ddgs.py "query" --backend name [--num 8] [--timeout 10]')
+    return " ".join(query_parts), int(options["--num"]), options["--backend"], int(options["--timeout"])
+
+
+def main():
+    query, num, backend, timeout = parse_args(sys.argv[1:])
+    try:
+        rows = DDGS(timeout=timeout).text(query, max_results=num, backend=backend)
+    except DDGSException as exc:
+        print(f"{backend}: {exc}", file=sys.stderr)
+        return 1
+    results = [{"title": row.get("title", ""), "url": row.get("href", ""), "snippet": row.get("body", "")}
+               for row in rows if row.get("href")]
+    print(json.dumps(results[:num], ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())