ultimate-pi 0.18.1 → 0.19.1

package/.pi/scripts/harness_web/evidence_bundle.py

@@ -0,0 +1,47 @@
+"""Build evidence-bundle.json from search-deep + optional highlight fetches."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def build_evidence_bundle(
+    search_deep_path: Path,
+    *,
+    highlight_files: dict[str, Path] | None = None,
+    query: str = "",
+) -> dict[str, Any]:
+    data = json.loads(search_deep_path.read_text(encoding="utf-8"))
+    intent = data.get("query") or query
+    hits = data.get("data", {}).get("web", [])
+    sources: list[dict[str, Any]] = []
+    for hit in hits:
+        url = hit.get("url", "")
+        entry: dict[str, Any] = {
+            "url": url,
+            "title": hit.get("title", ""),
+            "description": hit.get("description", ""),
+            "score": hit.get("score"),
+            "angle_ids": hit.get("angle_ids", []),
+        }
+        if highlight_files and url in highlight_files:
+            hp = highlight_files[url]
+            if hp.exists():
+                try:
+                    entry["highlights"] = json.loads(hp.read_text(encoding="utf-8"))
+                except json.JSONDecodeError:
+                    pass
+        sources.append(entry)
+    return {
+        "intent": intent,
+        "mode": data.get("mode", "deep"),
+        "engine": data.get("engine", ""),
+        "sources": sources,
+    }
+
+
+def write_evidence_bundle(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")

package/.pi/scripts/harness_web/find_similar.py

@@ -0,0 +1,88 @@
+"""Seed-URL discovery (Exa findSimilar analog)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .config import HarnessWebConfig
+from .deep_search import run_deep_search
+from .query_angles import AnglesPlan, SearchAngle
+from .rank import RankedHit, fuse_angle_results, normalize_url, tokenize
+from .scrape import fetch_page
+
+
+def _extract_seed_phrases(url: str, *, config: HarnessWebConfig, fast: bool) -> list[str]:
+    page = fetch_page(url, config=config, fast=fast, wait_ms=None)
+    title = ""
+    if hasattr(page, "css"):
+        for sel in ("title", "h1"):
+            nodes = page.css(sel)
+            if nodes:
+                title = (nodes[0].get_all_text(strip=True) or "").strip()
+                if title:
+                    break
+    if not title and hasattr(page, "get_all_text"):
+        title = (page.get_all_text(strip=True) or "")[:200].strip()
+    title = re.sub(r"\s+", " ", title).strip()
+    phrases: list[str] = []
+    if title:
+        phrases.append(title[:120])
+    # Key tokens from title
+    tokens = sorted(tokenize(title), key=len, reverse=True)[:6]
+    if tokens:
+        phrases.append(" ".join(tokens[:5]))
+    phrases.append(f"similar to {title[:80]}" if title else f"related pages {url}")
+    return [p for p in phrases if p.strip()][:3]
+
+
+def run_find_similar(
+    seed_url: str,
+    *,
+    config: HarnessWebConfig,
+    final_limit: int = 10,
+    per_angle_limit: int = 6,
+    fast_fetch: bool = True,
+) -> tuple[AnglesPlan, list[dict]]:
+    phrases = _extract_seed_phrases(seed_url, config=config, fast=fast_fetch)
+    angles = tuple(
+        SearchAngle(f"similar_{i + 1}", q, f"Derived from seed {seed_url}")
+        for i, q in enumerate(phrases)
+    )
+    plan = AnglesPlan(intent=f"pages similar to {seed_url}", angles=angles)
+    from .multi_search import multi_search
+
+    per_angle = multi_search(plan, per_angle_limit=per_angle_limit, config=config)
+    clean: dict[str, list[dict[str, str]]] = {}
+    for aid, rows in per_angle.items():
+        clean[aid] = [
+            {
+                "url": r.get("url", ""),
+                "title": r.get("title", ""),
+                "description": r.get("description", ""),
+            }
+            for r in rows
+        ]
+    ranked = fuse_angle_results(clean, final_limit=final_limit * 2, intent=plan.intent)
+
+    # Boost overlap with seed text
+    seed_norm = normalize_url(seed_url)
+    seed_tokens = tokenize(" ".join(phrases))
+    rescored: list[RankedHit] = []
+    for h in ranked:
+        if normalize_url(h.url) == seed_norm:
+            continue
+        blob = f"{h.title} {h.description}".lower()
+        overlap = len(seed_tokens & tokenize(blob)) / max(len(seed_tokens), 1)
+        rescored.append(
+            RankedHit(
+                url=h.url,
+                title=h.title,
+                description=h.description,
+                score=h.score + 0.2 * overlap,
+                angle_ids=h.angle_ids,
+                ranks=h.ranks,
+            )
+        )
+    rescored.sort(key=lambda x: -x.score)
+    return plan, [h.to_web_dict() for h in rescored[:final_limit]]

package/.pi/scripts/harness_web/heuristic_angles_shipped.py

@@ -0,0 +1,85 @@
+"""Shipped WRS heuristic angles (stdlib-only). Keep in sync with web-heuristic-angles.yaml."""
+
+from __future__ import annotations
+
+from typing import Any
+
+# fmt: off
+SHIPPED_HEURISTIC_ANGLES: dict[str, Any] = {
+    "version": 1,
+    "max_angles": 8,
+    "base": [
+        {"id": "definitional", "query": "{query}", "rationale": "Core intent phrasing"},
+        {
+            "id": "authoritative",
+            "query": "{query} official documentation OR specification OR RFC",
+            "rationale": "Primary specs and vendor docs",
+        },
+    ],
+    "categories": {
+        "code": [
+            {"id": "github", "query": "{query} site:github.com", "rationale": "Source, issues, discussions"},
+            {"id": "stackoverflow", "query": "{query} site:stackoverflow.com", "rationale": "Debugging and API usage Q&A"},
+            {"id": "stackexchange", "query": "{query} site:stackexchange.com", "rationale": "Broader SE network (Super User, Server Fault, etc.)"},
+            {"id": "readthedocs", "query": "{query} site:readthedocs.io", "rationale": "OSS library documentation"},
+            {"id": "mdn", "query": "{query} site:developer.mozilla.org", "rationale": "Web platform and browser APIs"},
+            {"id": "package_registries", "query": "{query} site:npmjs.com OR site:pypi.org OR site:pkg.go.dev OR site:crates.io", "rationale": "Package metadata across major ecosystems"},
+            {"id": "microsoft_learn", "query": "{query} site:learn.microsoft.com", "rationale": ".NET, Azure, Windows, and enterprise stacks"},
+            {"id": "hacker_news", "query": "{query} site:news.ycombinator.com", "rationale": "High-signal practitioner discussion"},
+            {"id": "gitlab", "query": "{query} site:gitlab.com", "rationale": "Alternate host and CI-visible code"},
+            {"id": "devto", "query": "{query} site:dev.to OR site:medium.com", "rationale": "Tutorials and implementation writeups"},
+        ],
+        "paper": [
+            {"id": "arxiv", "query": "{query} site:arxiv.org", "rationale": "Preprints and latest ML/CS uploads"},
+            {"id": "semantic_scholar", "query": "{query} site:semanticscholar.org", "rationale": "Citations, influences, and PDF links"},
+            {"id": "google_scholar", "query": "{query} site:scholar.google.com", "rationale": "Broad academic discovery"},
+            {"id": "papers_with_code", "query": "{query} site:paperswithcode.com", "rationale": "Benchmarks tied to implementations"},
+            {"id": "openreview", "query": "{query} site:openreview.net", "rationale": "Peer reviews and ML conference submissions"},
+            {"id": "acl_anthology", "query": "{query} site:aclanthology.org", "rationale": "NLP and computational linguistics"},
+            {"id": "acm_dl", "query": "{query} site:dl.acm.org", "rationale": "ACM proceedings and journals"},
+            {"id": "pubmed", "query": "{query} site:pubmed.ncbi.nlm.nih.gov", "rationale": "Biomedical and life-sciences literature"},
+        ],
+        "news": [
+            {"id": "recent", "query": "{query} news 2025 2026", "rationale": "Recency-biased open web"},
+            {"id": "wire_reuters", "query": "{query} site:reuters.com", "rationale": "Wire-service reporting"},
+            {"id": "wire_ap", "query": "{query} site:apnews.com", "rationale": "Associated Press coverage"},
+            {"id": "tech_press", "query": "{query} site:techcrunch.com OR site:theverge.com OR site:arstechnica.com", "rationale": "Technology industry news"},
+            {"id": "business_press", "query": "{query} site:bloomberg.com OR site:ft.com OR site:wsj.com", "rationale": "Markets and business context"},
+            {"id": "analysis", "query": "{query} in-depth analysis explainer", "rationale": "Long-form journalism and explainers"},
+            {"id": "bbc", "query": "{query} site:bbc.com/news", "rationale": "International general news desk"},
+        ],
+        "company": [
+            {"id": "official_site", "query": "{query} official website", "rationale": "Company-controlled messaging"},
+            {"id": "crunchbase", "query": "{query} site:crunchbase.com", "rationale": "Funding, investors, and competitors"},
+            {"id": "linkedin_company", "query": "{query} site:linkedin.com/company", "rationale": "Headcount, hiring, and positioning"},
+            {"id": "sec_filings", "query": "{query} site:sec.gov 10-K OR 10-Q OR S-1", "rationale": "US public-company disclosures"},
+            {"id": "g2_reviews", "query": "{query} site:g2.com OR site:capterra.com", "rationale": "B2B software reviews and comparisons"},
+            {"id": "company_news", "query": "{query} company announcement press release", "rationale": "Launches, partnerships, and earnings"},
+            {"id": "glassdoor", "query": "{query} site:glassdoor.com", "rationale": "Employee sentiment and culture signals"},
+        ],
+        "people": [
+            {"id": "linkedin", "query": "{query} site:linkedin.com/in", "rationale": "Professional profiles"},
+            {"id": "github_person", "query": "{query} site:github.com", "rationale": "Open-source footprint for builders"},
+            {"id": "wikipedia", "query": "{query} site:en.wikipedia.org", "rationale": "Neutral biographical baseline"},
+            {"id": "scholar_person", "query": "{query} site:scholar.google.com", "rationale": "Publication record for researchers"},
+            {"id": "interviews", "query": "{query} interview podcast keynote", "rationale": "First-person statements and talks"},
+            {"id": "twitter_x", "query": "{query} site:x.com OR site:twitter.com", "rationale": "Public statements and discourse"},
+        ],
+        "security": [
+            {"id": "cve_nvd", "query": "{query} CVE site:nvd.nist.gov", "rationale": "National Vulnerability Database"},
+            {"id": "owasp", "query": "{query} site:owasp.org", "rationale": "AppSec standards and cheat sheets"},
+            {"id": "cwe", "query": "{query} site:cwe.mitre.org", "rationale": "Weakness taxonomy"},
+            {"id": "github_advisories", "query": "{query} site:github.com/advisories OR dependabot", "rationale": "Ecosystem security advisories"},
+            {"id": "snyk_blog", "query": "{query} site:snyk.io/blog OR vulnerability", "rationale": "Practitioner security writeups"},
+        ],
+        "default": [
+            {"id": "technical", "query": "{query} how it works architecture internals", "rationale": "Mechanism and design"},
+            {"id": "criticism", "query": "{query} limitations criticism drawbacks", "rationale": "Counterpoints and failure modes"},
+            {"id": "wikipedia", "query": "{query} site:en.wikipedia.org", "rationale": "Structured overview"},
+            {"id": "comparison", "query": "{query} vs alternatives comparison benchmark", "rationale": "Competitive landscape"},
+            {"id": "reddit", "query": "{query} site:reddit.com", "rationale": "Community experience reports"},
+            {"id": "hn_default", "query": "{query} site:news.ycombinator.com", "rationale": "Practitioner threads when category unknown"},
+        ],
+    },
+}
+# fmt: on

package/.pi/scripts/harness_web/heuristic_config.py

@@ -0,0 +1,251 @@
+"""Load and merge WRS heuristic angle templates from YAML."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from .query_angles import SearchAngle
+
+try:
+    import yaml  # type: ignore[import-untyped]
+except ImportError:
+    yaml = None  # type: ignore[assignment]
+
+CONFIG_BASENAME = "web-heuristic-angles.yaml"
+CONFIG_JSON_BASENAME = "web-heuristic-angles.json"
+ENV_CONFIG_FILE = "HARNESS_WEB_HEURISTIC_ANGLES_FILE"
+
+
+@dataclass(frozen=True)
+class HeuristicAnglesConfig:
+    max_angles: int
+    base: tuple[SearchAngle, ...]
+    categories: dict[str, tuple[SearchAngle, ...]]
+
+
+def _project_root() -> Path:
+    env = os.environ.get("HARNESS_PROJECT_ROOT", "").strip()
+    if env:
+        return Path(env).resolve()
+    return Path.cwd().resolve()
+
+
+def _package_root() -> Path | None:
+    env = os.environ.get("HARNESS_PKG_ROOT", "").strip()
+    if env:
+        return Path(env).resolve()
+    here = Path(__file__).resolve()
+    for anc in here.parents:
+        if (anc / ".pi" / "harness" / CONFIG_BASENAME).is_file():
+            return anc
+    return None
+
+
+def discover_heuristic_config_paths() -> list[Path]:
+    """Package defaults first, then project override, then env file last (wins on id)."""
+    paths: list[Path] = []
+    pkg = _package_root()
+    if pkg is not None:
+        pkg_yaml = pkg / ".pi" / "harness" / CONFIG_BASENAME
+        pkg_json = pkg / ".pi" / "harness" / CONFIG_JSON_BASENAME
+        if pkg_yaml.is_file():
+            paths.append(pkg_yaml)
+        if pkg_json.is_file() and pkg_json not in paths:
+            paths.append(pkg_json)
+    proj_file = _project_root() / ".pi" / "harness" / CONFIG_BASENAME
+    if proj_file.is_file() and proj_file not in paths:
+        paths.append(proj_file)
+    env_path = os.environ.get(ENV_CONFIG_FILE, "").strip()
+    if env_path:
+        p = Path(env_path).expanduser().resolve()
+        if p.is_file() and p not in paths:
+            paths.append(p)
+    return paths
+
+
+def _format_query(template: str, query: str) -> str:
+    return template.replace("{query}", query.strip())
+
+
+def _parse_angle_list(raw: Any, *, source: str) -> list[SearchAngle]:
+    if raw is None:
+        return []
+    if not isinstance(raw, list):
+        raise ValueError(f"{source}: expected list of angle objects")
+    out: list[SearchAngle] = []
+    for i, item in enumerate(raw):
+        if not isinstance(item, dict):
+            raise ValueError(f"{source}[{i}]: expected object")
+        aid = str(item.get("id") or item.get("name") or f"angle_{i + 1}").strip()
+        qtpl = str(item.get("query") or "").strip()
+        if not aid or not qtpl:
+            raise ValueError(f"{source}[{i}]: id and query required")
+        rationale = str(item.get("rationale") or item.get("reason") or "").strip()
+        out.append(
+            SearchAngle(
+                id=aid,
+                query=qtpl,
+                rationale=rationale,
+            )
+        )
+    return out
+
+
+def _merge_config_dict(accum: dict[str, Any], layer: dict[str, Any]) -> dict[str, Any]:
+    out = dict(accum)
+    if "max_angles" in layer:
+        out["max_angles"] = layer["max_angles"]
+    if "version" in layer:
+        out["version"] = layer["version"]
+    base_acc = list(out.get("base") or [])
+    base_acc.extend(layer.get("base") or [])
+    out["base"] = base_acc
+    cats: dict[str, list[Any]] = dict(out.get("categories") or {})
+    layer_cats = layer.get("categories")
+    if isinstance(layer_cats, dict):
+        for key, angles in layer_cats.items():
+            cat = str(key).strip().lower()
+            if not cat:
+                continue
+            existing = list(cats.get(cat) or [])
+            if isinstance(angles, list):
+                existing.extend(angles)
+            cats[cat] = existing
+    out["categories"] = cats
+    return out
+
+
+def _load_config_file(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    if path.suffix.lower() == ".json":
+        data = json.loads(text)
+    elif yaml is not None:
+        data = yaml.safe_load(text)
+    else:
+        raise ValueError(f"PyYAML required to load {path} (or use .json)")
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: root must be a mapping")
+    return data
+
+
+def _embedded_builtin_dict() -> dict[str, Any]:
+    """Fallback when no config files load (stdlib shipped defaults)."""
+    pkg = _package_root()
+    if pkg is not None:
+        for name in (CONFIG_JSON_BASENAME, CONFIG_BASENAME):
+            pkg_file = pkg / ".pi" / "harness" / name
+            if not pkg_file.is_file():
+                continue
+            try:
+                return _load_config_file(pkg_file)
+            except (ValueError, json.JSONDecodeError, OSError):
+                continue
+    from .heuristic_angles_shipped import SHIPPED_HEURISTIC_ANGLES
+
+    return dict(SHIPPED_HEURISTIC_ANGLES)
+
+
+def heuristic_config_from_merged(merged: dict[str, Any]) -> HeuristicAnglesConfig:
+    max_angles = int(merged.get("max_angles") or 5)
+    max_angles = max(2, min(max_angles, 8))
+
+    base_templates = _parse_angle_list(merged.get("base"), source="base")
+    raw_cats = merged.get("categories")
+    categories: dict[str, tuple[SearchAngle, ...]] = {}
+    if isinstance(raw_cats, dict):
+        for key, raw_list in raw_cats.items():
+            cat = str(key).strip().lower()
+            if not cat:
+                continue
+            categories[cat] = tuple(
+                _parse_angle_list(raw_list, source=f"categories.{cat}")
+            )
+
+    if "default" not in categories:
+        categories["default"] = (
+            SearchAngle("technical", "{query} how it works architecture", "Technical"),
+            SearchAngle("criticism", "{query} limitations criticism", "Counterpoints"),
+        )
+
+    return HeuristicAnglesConfig(
+        max_angles=max_angles,
+        base=tuple(base_templates),
+        categories=categories,
+    )
+
+
+@lru_cache(maxsize=8)
+def load_heuristic_angles_config_cached(paths_key: tuple[str, ...]) -> HeuristicAnglesConfig:
+    paths = [Path(p) for p in paths_key] if paths_key else discover_heuristic_config_paths()
+    layers: list[dict[str, Any]] = []
+    for p in paths:
+        try:
+            layers.append(_load_config_file(p))
+        except (ValueError, json.JSONDecodeError, OSError):
+            continue
+    if layers:
+        merged: dict[str, Any] = {}
+        for layer in layers:
+            merged = _merge_config_dict(merged, layer)
+    else:
+        merged = _embedded_builtin_dict()
+    return heuristic_config_from_merged(merged)
+
+
+def load_heuristic_angles_config() -> HeuristicAnglesConfig:
+    paths = discover_heuristic_config_paths()
+    return load_heuristic_angles_config_cached(tuple(str(p) for p in paths))
+
+
+def clear_heuristic_config_cache() -> None:
+    load_heuristic_angles_config_cached.cache_clear()
+
+
+def build_heuristic_angles(
+    query: str,
+    *,
+    category: str | None = None,
+    config: HeuristicAnglesConfig | None = None,
+) -> tuple[SearchAngle, ...]:
+    cfg = config or load_heuristic_angles_config()
+    q = query.strip()
+    cat = (category or "").strip().lower()
+
+    angles: list[SearchAngle] = []
+    for tmpl in cfg.base:
+        angles.append(
+            SearchAngle(
+                id=tmpl.id,
+                query=_format_query(tmpl.query, q),
+                rationale=tmpl.rationale,
+            )
+        )
+
+    cat_angles = cfg.categories.get(cat) if cat else None
+    if not cat_angles:
+        cat_angles = cfg.categories.get("default", ())
+
+    for tmpl in cat_angles:
+        angles.append(
+            SearchAngle(
+                id=tmpl.id,
+                query=_format_query(tmpl.query, q),
+                rationale=tmpl.rationale,
+            )
+        )
+
+    # Stable dedupe by id (first wins — base before category)
+    seen: set[str] = set()
+    unique: list[SearchAngle] = []
+    for a in angles:
+        if a.id in seen:
+            continue
+        seen.add(a.id)
+        unique.append(a)
+
+    return tuple(unique[: cfg.max_angles])

package/.pi/scripts/harness_web/highlights.py

@@ -0,0 +1,47 @@
+"""Query-aligned excerpt extraction from page markdown."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+def _tokenize(text: str) -> set[str]:
+    return {t for t in re.findall(r"[a-z0-9]{3,}", text.lower()) if len(t) >= 3}
+
+
+def extract_highlights(
+    markdown: str,
+    query: str,
+    *,
+    max_spans: int = 5,
+    max_chars_per_span: int = 400,
+) -> list[dict[str, Any]]:
+    q_tokens = _tokenize(query)
+    if not q_tokens:
+        return []
+
+    paragraphs = [p.strip() for p in re.split(r"\n\s*\n", markdown) if p.strip()]
+    if not paragraphs:
+        paragraphs = [line.strip() for line in markdown.splitlines() if line.strip()]
+
+    scored: list[tuple[float, int, str]] = []
+    for idx, para in enumerate(paragraphs):
+        if len(para) < 40:
+            continue
+        tokens = _tokenize(para)
+        if not tokens:
+            continue
+        overlap = len(q_tokens & tokens) / max(len(q_tokens), 1)
+        scored.append((overlap, idx, para))
+
+    scored.sort(key=lambda x: (-x[0], x[1]))
+    out: list[dict[str, Any]] = []
+    for score, idx, para in scored[:max_spans]:
+        if score <= 0:
+            continue
+        text = para[:max_chars_per_span]
+        if len(para) > max_chars_per_span:
+            text += "…"
+        out.append({"score": round(score, 4), "paragraph_index": idx, "text": text})
+    return out

package/.pi/scripts/harness_web/multi_search.py

@@ -0,0 +1,59 @@
+"""Parallel SERP queries per search angle."""
+
+from __future__ import annotations
+
+import os
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from .config import HarnessWebConfig
+from .query_angles import AnglesPlan, SearchAngle
+from .search import search
+
+
+def _concurrency() -> int:
+    raw = os.environ.get("HARNESS_WEB_DEEP_CONCURRENCY", "4").strip()
+    try:
+        return max(1, min(8, int(raw)))
+    except ValueError:
+        return 4
+
+
+def multi_search(
+    plan: AnglesPlan,
+    *,
+    per_angle_limit: int,
+    config: HarnessWebConfig,
+    rate_limit_ms: int | None = None,
+) -> dict[str, list[dict[str, str]]]:
+    """Run search() for each angle; return angle_id -> hits."""
+    sleep_sec = (rate_limit_ms if rate_limit_ms is not None else config.rate_limit_ms) / 1000.0
+    results: dict[str, list[dict[str, str]]] = {}
+    angles = list(plan.angles)
+
+    def run_one(angle: SearchAngle) -> tuple[str, list[dict[str, str]]]:
+        hits = search(angle.query, limit=per_angle_limit, config=config)
+        tagged = []
+        for i, h in enumerate(hits):
+            row = dict(h)
+            row["_angle_id"] = angle.id
+            row["_angle_rank"] = str(i + 1)
+            tagged.append(row)
+        return angle.id, tagged
+
+    if len(angles) == 1:
+        aid, hits = run_one(angles[0])
+        results[aid] = hits
+        return results
+
+    with ThreadPoolExecutor(max_workers=min(_concurrency(), len(angles))) as pool:
+        futures = {pool.submit(run_one, a): a for a in angles}
+        done = 0
+        for fut in as_completed(futures):
+            aid, hits = fut.result()
+            results[aid] = hits
+            done += 1
+            if done < len(angles) and sleep_sec > 0:
+                time.sleep(sleep_sec)
+
+    return results

package/.pi/scripts/harness_web/output.py

@@ -24,6 +24,7 @@ def write_search_results(
     query: str,
     *,
     engine: str,
+    tier: str = "standard",
 ) -> None:
     """Firecrawl-compatible envelope: data.web[].url|title|description."""
     write_json(
@@ -31,6 +32,7 @@ def write_search_results(
         {
             "query": query,
             "engine": engine,
+            "tier": tier,
             "data": {
                 "web": [
                     {
@@ -45,6 +47,28 @@ def write_search_results(
     )
 
 
+def write_deep_search_results(
+    path: Path,
+    *,
+    query: str,
+    engine: str,
+    tier: str,
+    plan_angles: list[dict],
+    ranked_web: list[dict],
+) -> None:
+    write_json(
+        path,
+        {
+            "query": query,
+            "engine": engine,
+            "mode": tier,
+            "tier": tier,
+            "angles": plan_angles,
+            "data": {"web": ranked_web},
+        },
+    )
+
+
 def write_page_markdown(path: Path, page: Any, *, main_content_only: bool = True) -> None:
     ensure_parent(path)
     try: