world-model-optimizer 0.2.0__py3-none-any.whl

wmo/config/store.py

@@ -0,0 +1,177 @@
+"""Named world models on disk.
+
+The selected project root (`.wmo/` by default) holds named world models under `models/<name>/`.
+Each model directory is a self-contained artifact in the layout `ArtifactPaths` already understands
+(config.toml, prompts/, index/, metrics.json). The store turns names into directories, lists what
+is available, and reads a small summary for `wmo list`.
+
+    .wmo/                <- writable: where `wmo build` writes
+      models/
+        tau2-airline/    <- one artifact (config.toml, prompts/, index/, metrics.json)
+        retail-bench/    <- another
+
+"Filesystem as DB": loading a model is just reading its folder. The default root is the writable
+`.wmo/` directory used by `wmo build`; callers can pass another root such as `examples/<task>` to
+read intentional prebuilt example artifacts from that root's `models/` directory.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel, JsonValue
+
+from wmo.config.card import ModelCard, load_card
+from wmo.config.config import ARTIFACT_DIR, ArtifactPaths, HarnessConfig
+from wmo.providers.models import resolve_provider_model
+
+# The implicit model name used when the user does not pass `--name`.
+DEFAULT_MODEL_NAME = "default"
+
+# A safe, filesystem-friendly model name: no path separators, traversal, or leading dot.
+_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def validate_name(name: str) -> str:
+    """Return `name` if it is a safe single path segment, else raise a friendly ValueError."""
+    if not _NAME_RE.match(name) or name in {".", ".."} or "/" in name or "\\" in name:
+        raise ValueError(
+            f"invalid world model name {name!r}: use letters, digits, '.', '_', '-' "
+            "(must start with a letter or digit, no path separators)"
+        )
+    return name
+
+
+def normalize_name(name: str) -> str:
+    """Dash-join whitespace: 'tau bench' -> 'tau-bench'. Validity stays validate_name's call."""
+    return re.sub(r"\s+", "-", name.strip())
+
+
+class ModelInfo(BaseModel):
+    """A one-line summary of a built world model, for `wmo list`."""
+
+    name: str
+    serve_provider: str
+    serve_model: str
+    held_out_accuracy: float | None = None
+    rollouts_used: int | None = None
+    frontier_size: int | None = None
+
+
+class WorldModelStore:
+    """Resolves and enumerates named world models under a selected project root."""
+
+    def __init__(self, root: str | Path = ARTIFACT_DIR) -> None:
+        self.root = Path(root)
+
+    @property
+    def models_dir(self) -> Path:
+        """The selected root's models dir (`.wmo/models/` by default)."""
+        return self.root / "models"
+
+    def model_dir(self, name: str) -> Path:
+        """The artifact directory for `name` (where a build writes; may not exist)."""
+        return self.models_dir / validate_name(name)
+
+    def dir_for(self, name: str) -> Path | None:
+        """The artifact dir holding `name`'s config, or None."""
+        model_dir = self.model_dir(name)
+        if ArtifactPaths(model_dir).config.exists():
+            return model_dir
+        return None
+
+    def exists(self, name: str) -> bool:
+        return self.dir_for(name) is not None
+
+    def _names_in(self, models_dir: Path) -> set[str]:
+        """Names of every artifact (a dir containing config.toml) directly under `models_dir`."""
+        if not models_dir.exists():
+            return set()
+        return {d.name for d in models_dir.iterdir() if d.is_dir() and (d / "config.toml").exists()}
+
+    def list_names(self) -> list[str]:
+        """Sorted names of every locally built model."""
+        return sorted(self._names_in(self.models_dir))
+
+    def resolve(self, name: str | None) -> Path:
+        """Resolve `name` to a model's artifact dir for read commands (serve/demo/play).
+
+        With an explicit `name`, require it to exist. With `name=None`, fall back to the single
+        available model if there is exactly one; else raise, listing the choices.
+        """
+        if name is not None:
+            found = self.dir_for(name)
+            if found is None:
+                available = self.list_names()
+                hint = f" (have: {', '.join(available)})" if available else ""
+                raise FileNotFoundError(
+                    f"no world model named {name!r} under {self.models_dir}{hint}; "
+                    "run `wmo build --name <name>` first"
+                )
+            return found
+
+        names = self.list_names()
+        if not names:
+            raise FileNotFoundError(
+                f"no world models built under {self.models_dir}; "
+                "run `wmo build --name <name>` first"
+            )
+        if len(names) > 1:
+            raise ValueError(
+                f"multiple world models built ({', '.join(names)}); pass --name to choose one"
+            )
+        resolved = self.dir_for(names[0])
+        assert resolved is not None  # name came from list_names(), so it resolves
+        return resolved
+
+    def card(self, name: str) -> ModelCard | None:
+        """The model's `card.json` metadata, or None when the model carries no card."""
+        model_dir = self.dir_for(name)
+        if model_dir is None:
+            raise FileNotFoundError(f"no world model named {name!r} under {self.models_dir}")
+        return load_card(model_dir)
+
+    def info(self, name: str) -> ModelInfo:
+        """Read a model's config + metrics into a summary (for `wmo list`)."""
+        model_dir = self.dir_for(name)
+        if model_dir is None:
+            raise FileNotFoundError(f"no world model named {name!r}")
+        paths = ArtifactPaths(model_dir)
+        with paths.config.open("rb") as fh:
+            config = HarnessConfig.model_validate(tomllib.load(fh))
+        accuracy: float | None = None
+        rollouts: int | None = None
+        if paths.metrics.exists():
+            metrics = json.loads(paths.metrics.read_text(encoding="utf-8"))
+            accuracy = _as_float(metrics.get("held_out_accuracy"))
+            rollouts = _as_int(metrics.get("rollouts_used"))
+        frontier_size: int | None = None
+        if paths.frontier.exists():
+            frontier = json.loads(paths.frontier.read_text(encoding="utf-8"))
+            if isinstance(frontier, list):
+                frontier_size = len(frontier)
+        serve = config.serve_provider_config()
+        model_type = serve.model_type or resolve_provider_model(serve.kind, serve.model).model_type
+        return ModelInfo(
+            name=name,
+            serve_provider=serve.kind.value,
+            serve_model=model_type,
+            held_out_accuracy=accuracy,
+            rollouts_used=rollouts,
+            frontier_size=frontier_size,
+        )
+
+    def list_info(self) -> list[ModelInfo]:
+        return [self.info(name) for name in self.list_names()]
+
+
+def _as_float(value: JsonValue) -> float | None:
+    # bool is an int subclass; exclude it so a stray `true` doesn't read as 1.0.
+    return float(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+
+
+def _as_int(value: JsonValue) -> int | None:
+    return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else None

wmo/conftest.py

@@ -0,0 +1,19 @@
+"""Suite-wide fixtures.
+
+The default failover chain lives in a developer-local, gitignored `.wmo/fallback.toml`; tests must
+behave identically whether or not the developer running them has one, so the default lookup path is
+pointed at a nonexistent file for every test. Chain tests pass an explicit `path=`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _no_local_fallback_chain(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(
+        "wmo.providers.waterfall.FALLBACK_CONFIG_PATH", tmp_path / "no-fallback.toml"
+    )

wmo/connect/__init__.py

@@ -0,0 +1,88 @@
+"""Context connectors: fetch content from a service into normalized `ContextItem`s.
+
+This is a library, not a CLI. A host (the platform's connector tools) supplies a per-service
+access token and calls a connector's `pull`:
+
+    from wmo.connect import ConnectorAuth, PullQuery, get_connector
+
+    items = get_connector("github").pull(
+        ConnectorAuth(kind="token", access_token=token),
+        PullQuery(query="repo:me/proj is:open", limit=20),
+    )
+
+A `ContextConnector` owns one service: `pull` (normalized `ContextItem`s) plus `verify` (a cheap
+identity check) and `connect` (an interactive auth flow, for callers that want to acquire tokens
+themselves). Token/OAuth acquisition is the caller's responsibility. Connectors register
+themselves on import and are looked up by name (`get_connector`) or listed (`list_connectors`),
+mirroring `wmo.ingest`.
+"""
+
+# Import each built-in connector module for its registration side effect so `get_connector(...)`
+# works on package import, mirroring wmo/ingest/__init__.py. All are SDK-free at import
+# time: they talk httpx directly, and notion imports its optional `mcp` SDK (the `connectors`
+# extra) lazily inside the MCP code paths, so a bare install still imports this package.
+from wmo.connect import brave as brave  # noqa: F401
+from wmo.connect import github as github  # noqa: F401
+from wmo.connect import google as google  # noqa: F401
+from wmo.connect import notion as notion  # noqa: F401
+from wmo.connect import slack as slack  # noqa: F401
+from wmo.connect.apps import EMBEDDED_APPS, get_app
+from wmo.connect.connector import (
+    ConnectUI,
+    ContextConnector,
+    get_connector,
+    list_connectors,
+    register_connector,
+)
+from wmo.connect.credentials import (
+    connectors_path,
+    delete_connector_auth,
+    list_connected,
+    load_connector_auth,
+    resolve_env_token,
+    save_connector_auth,
+    token_env_var,
+    token_env_vars,
+)
+from wmo.connect.oauth import (
+    OAuthApp,
+    ensure_fresh,
+    pkce_challenge,
+    refresh_auth,
+    run_device_flow,
+    run_loopback_flow,
+)
+from wmo.connect.store import BundleManifest, ContextStore, render_markdown
+from wmo.connect.types import ConnectError, ConnectorAuth, ContextItem, ItemKind, PullQuery
+
+__all__ = [
+    "EMBEDDED_APPS",
+    "BundleManifest",
+    "ConnectError",
+    "ConnectUI",
+    "ConnectorAuth",
+    "ContextConnector",
+    "ContextItem",
+    "ContextStore",
+    "ItemKind",
+    "OAuthApp",
+    "PullQuery",
+    "connectors_path",
+    "delete_connector_auth",
+    "ensure_fresh",
+    "get_app",
+    "get_connector",
+    "list_connected",
+    "list_connectors",
+    "load_connector_auth",
+    "pkce_challenge",
+    "refresh_auth",
+    "register_connector",
+    "render_markdown",
+    "resolve_env_token",
+    "run_device_flow",
+    "run_loopback_flow",
+    "save_connector_auth",
+    "token_env_var",
+    "token_env_vars",
+]

wmo/connect/apps.py

@@ -0,0 +1,78 @@
+"""The shared OAuth app registry: embedded endpoint defaults, env-var client credentials.
+
+Endpoint configuration per provider is embedded here; client credentials never are. The repo
+policy is all-or-nothing: since some providers' credentials cannot ship (Google and Slack
+token exchanges demand a client secret), none do, and every OAuth connector requires its
+`WMO_<NAME>_CLIENT_ID` (plus `WMO_<NAME>_CLIENT_SECRET` where the provider demands one) when,
+and only when, that connector is used. `get_app` resolves the env credentials over the
+embedded endpoints. A planned hosted path will supply registered apps platform-side instead.
+"""
+
+from __future__ import annotations
+
+import os
+
+from wmo.connect.oauth import OAuthApp
+from wmo.connect.types import ConnectError
+
+# Full endpoint config per provider; client ids/secrets come from the env, never the repo.
+EMBEDDED_APPS: dict[str, OAuthApp] = {
+    "github": OAuthApp(
+        name="github",
+        # Expects a GitHub App client id ($WMO_GITHUB_CLIENT_ID): GitHub Apps carry their
+        # permissions in the app registration, repo-scoped at install time, so no scopes are
+        # sent in the flow, and the device grant needs no client secret.
+        client_id="",
+        auth_url="https://github.com/login/oauth/authorize",
+        token_url="https://github.com/login/oauth/access_token",
+        device_url="https://github.com/login/device/code",
+    ),
+    "google": OAuthApp(
+        name="google",
+        # Google's Desktop-client token exchange requires the client secret even with PKCE
+        # ($WMO_GOOGLE_CLIENT_ID + $WMO_GOOGLE_CLIENT_SECRET). The planned zero-setup path
+        # points token_url at a hosted stateless exchange holding a secret platform-side.
+        client_id="",
+        auth_url="https://accounts.google.com/o/oauth2/v2/auth",
+        token_url="https://oauth2.googleapis.com/token",
+        extra_auth_params={"access_type": "offline", "prompt": "consent"},
+    ),
+    "slack": OAuthApp(
+        name="slack",
+        client_id="",
+        auth_url="https://slack.com/oauth/v2/authorize",
+        token_url="https://slack.com/api/oauth.v2.access",
+    ),
+}
+
+
+def get_app(name: str) -> OAuthApp:
+    """Resolve the OAuth app for `name`, layering env overrides over the embedded defaults.
+
+    Env vars (name upper-cased, hyphens to underscores): `WMO_<NAME>_CLIENT_ID` and
+    `WMO_<NAME>_CLIENT_SECRET`. Set-but-empty values are treated as unset.
+
+    Raises:
+        ConnectError: When `name` is unknown, or when neither layer provides a client id.
+    """
+    if name not in EMBEDDED_APPS:
+        known = ", ".join(sorted(EMBEDDED_APPS))
+        raise ConnectError(f"no OAuth app configuration for {name!r}; known apps: {known}")
+    prefix = f"WMO_{name.upper().replace('-', '_')}"
+    app = EMBEDDED_APPS[name]
+    updates: dict[str, str] = {}
+    client_id = os.environ.get(f"{prefix}_CLIENT_ID")
+    if client_id:
+        updates["client_id"] = client_id
+    client_secret = os.environ.get(f"{prefix}_CLIENT_SECRET")
+    if client_secret:
+        updates["client_secret"] = client_secret
+    if updates:
+        app = app.model_copy(update=updates)
+    if not app.client_id:
+        raise ConnectError(
+            f"no OAuth client id available for {name!r}: set ${prefix}_CLIENT_ID (and "
+            f"${prefix}_CLIENT_SECRET if the provider requires one) to use your own OAuth "
+            "app; see docs/reference/connect-library.md"
+        )
+    return app

wmo/connect/brave.py

@@ -0,0 +1,284 @@
+"""Brave Search context connector: API-key auth, web search results pulled as PAGE items.
+
+`connect` prefers an env-injected key (the generic `WMO_BRAVE_TOKEN` override, then the
+`BRAVE_SEARCH_API_KEY` deployments already carry for the grounding engine) and falls back to a
+pasted key; `verify` runs one minimal search; `pull` queries the web search endpoint (`--query`
+required, `--target` becomes a `site:` filter) and fetches each result page through the
+grounding engine's SSRF-guarded fetcher, stripped to readable text. A failed or guarded-out
+page fetch degrades that item's body to the search snippet, never aborting the pull.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+
+import httpx
+
+from wmo.connect.connector import ConnectUI, register_connector
+from wmo.connect.credentials import resolve_env_token
+from wmo.connect.types import (
+    ConnectError,
+    ConnectorAuth,
+    ContextItem,
+    ItemKind,
+    PullQuery,
+    capped,
+    opt_str,
+    strip_html,
+    transport_errors,
+)
+from wmo.core.types import JsonObject
+from wmo.engine.grounding import FetchFn, http_get
+
+logger = logging.getLogger(__name__)
+
+_API_BASE = "https://api.search.brave.com"
+_API_HOST = "api.search.brave.com"
+_SEARCH_PATH = "/res/v1/web/search"
+_TIMEOUT_SECONDS = 30.0
+_SOURCE = "brave"
+
+_DASHBOARD_URL = "https://api-dashboard.search.brave.com/"
+
+# Brave's per-request page-size ceiling for the web search endpoint.
+_PAGE_MAX = 20
+
+# Hard cap on results per pull, below PullQuery's default limit of 100: Brave result relevance
+# degrades sharply at deep offsets (and the API caps `offset` at 9), so a pull stops at 50
+# results (3 pages of 20) no matter how large --limit is.
+MAX_RESULTS = 50
+
+
+def _raise_for_response(response: httpx.Response, *, doing: str) -> None:
+    """Turn Brave error statuses into ConnectErrors that say what to do next."""
+    status = response.status_code
+    if status < 400:
+        return
+    if status in (401, 403):
+        raise ConnectError(
+            f"brave search rejected the API key during {doing} (HTTP {status}); check "
+            f"$BRAVE_SEARCH_API_KEY (or the stored key) against your subscription at "
+            f"{_DASHBOARD_URL}; the key is invalid or expired and a valid key must be supplied"
+        )
+    if status == 429:
+        wait = response.headers.get("Retry-After", "1")
+        raise ConnectError(
+            f"brave search rate-limited {doing} (HTTP 429): wait {wait}s (Retry-After), then "
+            "re-run the command; the free tier allows 1 request/second"
+        )
+    raise ConnectError(
+        f"brave search {doing} failed (HTTP {status}): {response.text[:200]}; "
+        "check the query and retry"
+    )
+
+
+def _result_rows(response: httpx.Response) -> list[JsonObject]:
+    """The `web.results` rows of one search response ([] on any other shape)."""
+    try:
+        raw = response.json()
+    except ValueError:
+        return []
+    if not isinstance(raw, dict):
+        return []
+    web = raw.get("web")
+    results = web.get("results") if isinstance(web, dict) else None
+    if not isinstance(results, list):
+        return []
+    return [row for row in results if isinstance(row, dict)]
+
+
+def _iso_date(value: str, *, field: str) -> str:
+    """An ISO-8601 date or datetime as the YYYY-MM-DD form Brave's freshness range expects.
+
+    Raises:
+        ConnectError: When the value is not ISO-8601.
+    """
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        raise ConnectError(
+            f"could not parse {field}={value!r} as ISO-8601; use YYYY-MM-DD or a full timestamp"
+        ) from None
+    return parsed.date().isoformat()
+
+
+def _freshness(since: str | None, until: str | None) -> str | None:
+    """The Brave `freshness` range for the query bounds, or None when there is no clean mapping.
+
+    Both bounds map to `YYYY-MM-DDtoYYYY-MM-DD`; `since` alone ranges to today. `until` alone
+    is dropped (Brave has no until-only freshness form).
+    """
+    if not since:
+        if until:
+            logger.debug("brave freshness has no until-only form; ignoring until=%s", until)
+        return None
+    start = _iso_date(since, field="since")
+    end = _iso_date(until, field="until") if until else datetime.now(UTC).date().isoformat()
+    return f"{start}to{end}"
+
+
+def _created_at(row: JsonObject) -> str | None:
+    """`page_age` (usually ISO) or `age`, normalized to ISO-8601 when parseable, else None."""
+    for field in ("page_age", "age"):
+        value = opt_str(row.get(field))
+        if not value:
+            continue
+        try:
+            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            continue  # relative forms like "2 days ago" carry no usable timestamp
+        return parsed.isoformat()
+    return None
+
+
+class BraveConnector:
+    """Brave Search connector: keyed web searches with result pages fetched as bodies.
+
+    Args:
+        transport: Injected httpx transport for the search API calls (tests pass
+            `httpx.MockTransport`); None means the real network.
+        fetch: The page-body fetcher; defaults to the grounding engine's SSRF-guarded
+            `http_get` (http(s)-only, public addresses only, redirects re-checked). Tests
+            inject a plain function.
+    """
+
+    name = _SOURCE
+    label = "Brave Search"
+
+    def __init__(
+        self,
+        transport: httpx.BaseTransport | None = None,
+        fetch: FetchFn = http_get,
+    ) -> None:
+        self._transport = transport
+        self._fetch = fetch
+
+    def connect(self, ui: ConnectUI) -> ConnectorAuth:
+        """Use the env-injected key when set (never persisted), else prompt for a pasted key.
+
+        Raises:
+            ConnectError: When no key is entered or Brave rejects the key.
+        """
+        resolved = resolve_env_token(self.name)
+        if resolved is not None:
+            env_var, token = resolved
+            auth = ConnectorAuth(kind="token", access_token=token)
+            account = self.verify(auth)
+            ui.info(f"using the ${env_var} key ({account})")
+            return auth.model_copy(update={"account": account})
+        key = ui.prompt_secret(f"Brave Search API key (free at {_DASHBOARD_URL})").strip()
+        if not key:
+            raise ConnectError(
+                f"no Brave Search API key entered; create a free key at {_DASHBOARD_URL} "
+                "and supply it as the connection credential"
+            )
+        auth = ConnectorAuth(kind="token", access_token=key)
+        account = self.verify(auth)
+        ui.info(f"Brave Search key verified ({account})")
+        return auth.model_copy(update={"account": account})
+
+    def verify(self, auth: ConnectorAuth) -> str:
+        """Check the key with one minimal search (`q=wmo, count=1`).
+
+        Raises:
+            ConnectError: When Brave rejects the key (with dashboard guidance) or the call
+                fails at the transport level.
+        """
+        with self._client(auth) as client, transport_errors(_API_HOST):
+            response = client.get(_SEARCH_PATH, params={"q": "wmo", "count": "1"})
+        _raise_for_response(response, doing="the Brave Search key check")
+        return "Brave Search (key valid)"
+
+    def pull(self, auth: ConnectorAuth, query: PullQuery) -> list[ContextItem]:
+        """Search the web and normalize each result into a PAGE item with its fetched body.
+
+        `query.query` is required (it is the web search itself); `query.target` scopes results
+        to one site via a prepended `site:` filter; `query.since`/`query.until` map to Brave's
+        `freshness` range. Results paginate by offset in fixed pages (`count` stays constant
+        across pages because Brave skips `count * offset` results, so a varying count would
+        misalign them) up to `query.limit`, hard-capped at `MAX_RESULTS`.
+
+        Raises:
+            ConnectError: On a missing query, an unparseable since/until, a rejected key, or
+                a rate limit.
+        """
+        if not query.query:
+            raise ConnectError(
+                "brave pull needs search terms: pass --query '<terms>' "
+                "(add --target <domain> to scope results to one site)"
+            )
+        q = f"site:{query.target} {query.query}" if query.target else query.query
+        limit = min(query.limit, MAX_RESULTS)
+        if limit <= 0:
+            return []
+        freshness = _freshness(query.since, query.until)
+        count = min(_PAGE_MAX, limit)
+        rows: list[JsonObject] = []
+        with self._client(auth) as client, transport_errors(_API_HOST):
+            offset = 0
+            while len(rows) < limit:
+                params = {"q": q, "count": str(count), "offset": str(offset)}
+                if freshness:
+                    params["freshness"] = freshness
+                response = client.get(_SEARCH_PATH, params=params)
+                _raise_for_response(response, doing="the Brave web search")
+                page = _result_rows(response)
+                rows.extend(page)
+                if len(page) < count:
+                    break  # a short page means Brave has no further results
+                offset += 1
+        items = [self._page_item(row, rank) for rank, row in enumerate(rows[:limit], start=1)]
+        logger.debug("pulled %d brave results for %r", len(items), q)
+        return items
+
+    def _client(self, auth: ConnectorAuth) -> httpx.Client:
+        """A search API client carrying the subscription-token header."""
+        return httpx.Client(
+            base_url=_API_BASE,
+            headers={
+                "Accept": "application/json",
+                "X-Subscription-Token": auth.access_token,
+            },
+            timeout=_TIMEOUT_SECONDS,
+            transport=self._transport,
+        )
+
+    def _page_item(self, row: JsonObject, rank: int) -> ContextItem:
+        """Normalize one search result, fetching its page for the body."""
+        url = opt_str(row.get("url"))
+        snippet = opt_str(row.get("description")) or ""
+        body, fetch_error = self._page_body(url, snippet)
+        metadata: JsonObject = {"rank": rank, "snippet": snippet}
+        if fetch_error:
+            metadata["fetch_error"] = fetch_error
+        return ContextItem(
+            id=url or f"result-{rank}",
+            source=self.name,
+            kind=ItemKind.PAGE,
+            title=opt_str(row.get("title")) or url or "(untitled)",
+            body=body,
+            url=url,
+            created_at=_created_at(row),
+            metadata=metadata,
+        )
+
+    def _page_body(self, url: str | None, snippet: str) -> tuple[str, str | None]:
+        """(body, fetch_error) for one result: the page's readable text, else the snippet.
+
+        The fetch goes through the injected SSRF-guarded fetcher, so a result URL resolving
+        into private address space is refused there; any refusal or transport failure degrades
+        to the search snippet with the reason recorded, never aborting the pull.
+        """
+        if not url:
+            return snippet, "result has no url"
+        try:
+            raw = self._fetch(url, {"Accept": "text/html", "User-Agent": "wmo-connector"})
+        except Exception as exc:  # noqa: BLE001 - any failed/guarded fetch degrades to the snippet
+            reason = str(exc)[:200] or type(exc).__name__
+            logger.debug("brave page fetch failed for %s: %s", url, reason)
+            return snippet, reason
+        return capped(strip_html(raw)), None
+
+
+register_connector(BraveConnector())