bookmark-research 0.5.0-beta.1

package/src/routing.py

@@ -0,0 +1,202 @@
+"""Choose research entrypoints from observed host capabilities; never launch work."""
+
+from service_http import ResearchHttp
+from settings import Settings
+from web_search import SearchProviders
+from credentials import Credentials
+
+
+class ResearchRouting:
+    HOSTS = ("codex", "claude_code", "pi", "dsh", "unknown")
+    METHODS = {
+        "comparative_analysis": "skills/bookmark-research/references/research-methods.md",
+        "fact_check": "skills/bookmark-research/references/research-methods.md",
+        "benchmark_review": "skills/bookmark-research/references/research-methods.md",
+        "wiki_synthesis": "skills/bookmark-research/references/wiki-and-evaluation.md",
+    }
+
+    def __init__(self, settings=None):
+        self.settings = settings if settings is not None else Settings()
+        self.credentials = Credentials(self.settings)
+
+    @staticmethod
+    def _names(values, label):
+        if values is None:
+            return []
+        if (not isinstance(values, list) or len(values) > 1000
+                or any(not isinstance(x, str) or not x.strip() or len(x) > 300 for x in values)):
+            raise ValueError(label + " must be a list of names observed in the current host")
+        return list(dict.fromkeys(values))
+
+    @staticmethod
+    def _has(tools, *names):
+        return any(tool == name or tool.endswith(("__" + name, "." + name, ":" + name))
+                   for tool in tools for name in names)
+
+    def route(self, depth=None, host="unknown", task_shape="investigation", observed_tools=None,
+              available_commands=None, installed_extensions=None, provider=None, failed_routes=None):
+        settings = self.settings.load()
+        depth = settings["research"]["depth"] if depth is None else depth
+        if depth not in ("auto", "quick", "agentic", "deep") or host not in self.HOSTS:
+            raise ValueError("Unsupported research depth or host")
+        if task_shape not in ("lookup", "investigation", "batch_research"):
+            raise ValueError("task_shape must be lookup, investigation or batch_research")
+        if provider not in (None, "openai", "parallel"):
+            raise ValueError("Professional provider must be openai or parallel")
+        tools = self._names(observed_tools, "observed_tools")
+        commands = self._names(available_commands, "available_commands")
+        extensions = self._names(installed_extensions, "installed_extensions")
+        failed = self._names(failed_routes, "failed_routes")
+        retrieval = SearchProviders(settings=self.settings)
+        selected_depth = ({"lookup": "quick", "investigation": "agentic", "batch_research": "deep"}[task_shape]
+                          if depth == "auto" else depth)
+        if provider is not None:
+            selected_depth = "deep"
+        ordinary_agentic = selected_depth == "agentic" and task_shape != "batch_research"
+        candidates = []
+        missing = []
+        if selected_depth == "quick":
+            candidates.append({"route": "direct_retrieval", "entrypoint": "fetch_web / search_web",
+                               "available": True, "execution_owner": "host",
+                               "reason": "Read known URLs directly; use search when sources must be discovered."})
+        else:
+            if host == "claude_code":
+                packaged = "/bookmark-research:bookmark-research" in commands
+                if packaged or self._has(tools, "Workflow", "workflow"):
+                    candidates.append({"route": "host_workflow",
+                        "entrypoint": "/bookmark-research:bookmark-research" if packaged else "Workflow",
+                        "available": True, "execution_owner": "claude_code", "run_mode": "background",
+                        "resume_scope": "same_session_with_possible_child_replay",
+                        "recipe": "hosts/claude/runtime.js"})
+                else:
+                    missing.append("Claude workflow tool or packaged workflow command is not observed")
+                if "/deep-research" in commands and selected_depth == "deep" and task_shape != "batch_research":
+                    candidates.append({"route": "host_deep_research", "entrypoint": "/deep-research",
+                        "available": True, "execution_owner": "claude_code", "run_mode": "background",
+                        "invocation": "explicit_command_required",
+                        "scope_note": "Builtin question research does not guarantee enumeration of a local package."})
+            elif host == "dsh":
+                if self._has(tools, "workflow"):
+                    candidates.append({"route": "host_workflow", "entrypoint": "workflow",
+                        "available": True, "execution_owner": "dsh", "run_mode": "blocking",
+                        "resume_scope": "not_established", "recipe": "hosts/dsh/workflow-call.py",
+                        "result_note": "Persist the canonical result; rendered text may be truncated."})
+                else:
+                    missing.append("The loaded DSH profile does not expose a workflow tool")
+            elif host == "pi":
+                if self._has(tools, "pi_subagent_workflow"):
+                    candidates.append({"route": "host_workflow", "entrypoint": "pi_subagent_workflow",
+                        "available": True, "execution_owner": "pi_subagents_extension", "run_mode": "detached",
+                        "resume_scope": "registry_does_not_add_replay", "recipe": "hosts/pi/register-workflow.py"})
+                else:
+                    missing.append("Pi workflow extension tool is not observed; installed package names alone are insufficient")
+            elif host == "codex":
+                missing.append("An equivalent standalone scripted workflow runtime was not established by the researched Codex docs")
+            if selected_depth == "deep" and provider is None:
+                for name, info in retrieval.registry["providers"].items():
+                    native_research = info.get("native_research", {})
+                    required = native_research.get("required_tools", [])
+                    if required and all(self._has(tools, tool) for tool in required):
+                        workflow_tools = [next(tool for tool in tools if self._has([tool], required_tool))
+                                          for required_tool in native_research["workflow_tools"]]
+                        candidates.append({"route": "host_research_mcp", "provider": name,
+                            "entrypoint": workflow_tools[0], "workflow_tools": workflow_tools,
+                            "available": True, "execution_owner": name, "invocation_owner": "host", "run_mode": "provider_background",
+                            "availability_basis": "observed_tools", "authentication_verified": False,
+                            "resume_note": "Keep the returned run ID. Resume or observe that run until terminal; a timeout is not a new submission."})
+            native = {"codex": ("spawn_agent",), "claude_code": ("Agent", "Task", "subagent"),
+                      "pi": ("subagent",), "dsh": ("subagent", "agent"), "unknown": ()}[host]
+            native_tools = [tool for tool in tools if self._has([tool], *native)]
+            if native_tools:
+                candidates.append({"route": "host_subagents", "entrypoint": native_tools[0],
+                    "available": True, "execution_owner": host, "run_mode": "host_defined",
+                    "recipe": "hosts/codex/delegate.md" if host == "codex" else "skills/bookmark-research/references/host-workflows.md"})
+            services = settings["professional_research"]
+            if selected_depth == "deep" or provider is not None:
+                for name in ([provider] if provider else ["openai", "parallel"]):
+                    key = ResearchHttp.PROVIDERS[name]["key_env"]
+                    credential = bool(self.credentials.get(key))
+                    candidates.append({"route": "professional_service", "provider": name,
+                        "entrypoint": "research_service_start", "execution_owner": name, "run_mode": "provider_background",
+                        "available": services["enabled"] and credential, "authentication_verified": False,
+                        "missing": ([] if services["enabled"] else ["professional_research.enabled"])
+                                   + ([] if credential else [key])})
+            candidates.append({"route": "host_iterative_research",
+                "entrypoint": "search_web / fetch_web" if ordinary_agentic else "research_start / research_*",
+                "available": True, "execution_owner": "host", "run_mode": "host_defined",
+                "reason": "The current host model plans the inquiry, reads evidence, evaluates it and follows gaps; retrieval services support this loop."})
+        for candidate in candidates:
+            candidate["route_id"] = candidate["route"] + (":" + candidate["provider"] if "provider" in candidate else "")
+            if candidate["route_id"] in failed:
+                candidate["available"] = False
+                candidate["excluded_reason"] = "caller_reported_confirmed_failure"
+        if provider is not None:
+            choices = [c for c in candidates if c["route"] == "professional_service" and c.get("provider") == provider]
+            selected = next((c for c in choices if c["available"]), None)
+        else:
+            choices = candidates[:]
+            host_priority = (["host_workflow", "host_subagents", "host_iterative_research"]
+                             if task_shape == "batch_research" and settings["research"]["prefer_host_workflows"] else
+                             ["host_subagents", "host_iterative_research", "host_workflow"])
+            if ordinary_agentic:
+                host_priority.remove("host_iterative_research")
+                host_priority.insert(0, "host_iterative_research")
+            configured = settings["professional_research"]["provider"]
+            # Host reasoning is the baseline. A saved API preference orders
+            # optional services; only an explicit provider overrides host work.
+            choices.sort(key=lambda c: host_priority.index(c["route"]) if c["route"] in host_priority else
+                len(host_priority) if c["route"] == "professional_service" and c.get("provider") == configured else
+                len(host_priority) + 1)
+            selected = next((c for c in choices if c["available"]), None)
+        if selected is None:
+            next_action = ({"tool": "research_services", "arguments": {"provider": provider},
+                            "reason": "Inspect the explicitly selected service's configuration or confirmed failure; it was not substituted."}
+                           if provider is not None else {"tool": "research_status",
+                            "reason": "No untried applicable route remains. Inspect the existing evidence and report the unresolved gaps."})
+            workflow = []
+        elif selected_depth == "quick":
+            next_action = {"tools": ["fetch_web", "search_web"],
+                           "reason": "Read known URLs; search only when a source must be discovered, then read it."}
+            workflow = ["fetch_web", "answer_with_sources"]
+        elif ordinary_agentic and selected["route"] == "host_iterative_research":
+            next_action = {"tools": ["search_web", "fetch_web"],
+                           "reason": "The current host model first plans from the question and available context. Read known sources or search for missing evidence, assess the pages, then target unresolved questions. Use persistent research records when the task needs a resumable report."}
+            workflow = ["search_web", "fetch_web", "answer_with_sources"]
+        else:
+            next_action = {"tool": "research_start",
+                           "reason": "The current host model first defines the questions, evidence gaps and work assignments. Freeze the full scope for new research; reuse existing research_status and evidence before delegating or retrieving more."}
+            workflow = ["research_start", "research_inventory"]
+            if selected["route"] == "professional_service":
+                workflow += ["research_service_prepare", "research_service_start", "research_service_status",
+                             "research_service_result", "research_service_import", "research_fetch"]
+            elif selected["route"] == "host_research_mcp":
+                workflow += selected["workflow_tools"] + ["research_record", "research_import_evidence", "research_fetch"]
+            else:
+                workflow += [selected["entrypoint"]] if selected["route"] != "host_iterative_research" else []
+                workflow += ["research_search", "research_fetch"]
+            workflow += ["research_source", "research_record", "research_coverage", "research_finish"]
+        process = {"owner": "current_host_model",
+                   "steps": (["read_or_search", "answer_with_sources"] if selected_depth == "quick" else
+                             ["plan", "search_or_read", "assess_evidence", "follow_evidence_gaps"] +
+                             (["independent_review", "coverage_check", "synthesize_report"] if selected_depth == "deep" else
+                              ["synthesize_answer"])),
+                   "collaboration": "Delegate independent questions, sources or verification only through currently available and permitted host capabilities. The parent plans and reviews the result; no subagent is required for the basic loop.",
+                   "external_research": "Optional scoped support after host assessment, or an explicit user-selected service. Tool presence and saved API credentials do not replace the host's first pass."}
+        return {"depth": selected_depth, "host": host, "task_shape": task_shape, "selected": selected,
+                "candidates": candidates, "missing_or_unconfirmed": missing,
+                "next_action": next_action, "workflow": workflow, "research_process": process,
+                "fallback": {"execution_owner": "host", "failed_routes": failed,
+                             "remaining_routes": [c["route_id"] for c in choices if c["available"] and c is not selected],
+                             "on_confirmed_failure": "Call research_route again with cumulative failed_routes and current host observations; execute the next route in the same research session.",
+                             "hold_on": ["pending", "queued", "in_progress", "unknown_outcome", "cancelled"],
+                             "explicit_provider_is_exclusive": provider is not None},
+                "retrieval": {"search": {"providers": settings["search"]["providers"],
+                                         "fallback_providers": settings["search"]["fallback_providers"],
+                                         "mode": "parallel_then_fallback" if settings["search"]["fallback_providers"] else "parallel"},
+                              "fetch": {"providers": Settings.fetch_providers(settings), "mode": "primary_then_parallel_fallback"}},
+                "observations": {"tools": tools, "commands": commands, "extensions": extensions,
+                                 "basis": "caller_reported_current_host", "runtime_tested": False},
+                "methods": [{"name": name, "reference": self.METHODS[name]} for name in settings["research"]["methods"]],
+                "source_scope": "Keep the frozen research inventory complete across groups and rounds; finish checks coverage.",
+                "execution_started": False, "configuration_changed": False,
+                "provider_fallback": "An explicitly selected unavailable service is reported unavailable; never silently substituted."}

package/src/search_results.py

@@ -0,0 +1,244 @@
+"""Fuse normalized search batches without fetching pages or verifying claims.
+
+RRF contributions are unique per (target, provider, query, canonical URL).
+An optional ``targets`` list identifies requested targets with no batch at all.
+Only snippets are retained; full source text belongs in a later fetch step.
+"""
+
+from collections import OrderedDict
+from urllib.parse import urlsplit, urlunsplit
+import ipaddress
+import re
+
+
+RRF_K = 60
+MAX_SNIPPET_CHARS = 1200
+MAX_RANK = 2147483647
+
+
+def _nonempty_string(value):
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _canonical_url(raw_url):
+    """Conservative URL identity, retaining queries and client-side routes."""
+    if not _nonempty_string(raw_url):
+        raise ValueError("url must be a nonempty string")
+    if any(c.isspace() or ord(c) < 32 or ord(c) == 127 for c in raw_url):
+        raise ValueError("url contains whitespace or control characters")
+    if "\\" in raw_url:
+        raise ValueError("url contains a backslash")
+    try:
+        parts = urlsplit(raw_url)
+        if parts.scheme.lower() not in ("http", "https"):
+            raise ValueError("only http and https URLs are accepted")
+        host = parts.hostname
+        port = parts.port
+        if not host or parts.username is not None or parts.password is not None:
+            raise ValueError("url must have a host and no userinfo")
+        if parts.netloc.startswith("[") or ":" in host:
+            ipaddress.IPv6Address(host)
+            host = "[" + host.lower() + "]"
+        else:
+            ascii_host = host.encode("idna").decode("ascii")
+            if not re.fullmatch(r"[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*\.?", ascii_host):
+                raise ValueError("invalid URL host")
+            host = host.lower()
+    except (UnicodeError, ValueError) as exc:
+        raise ValueError(str(exc)) from exc
+    scheme = parts.scheme.lower()
+    if port is not None and (scheme, port) not in (("http", 80), ("https", 443)):
+        host += ":" + str(port)
+    # Ordinary anchors share a page. Hash-router URLs may represent other pages.
+    fragment = parts.fragment if parts.fragment.startswith(("/", "!")) else ""
+    # HTTP(S) requests use '/' for an empty path (RFC 3986 section 6.2.3).
+    canonical = urlunsplit((scheme, host, parts.path or "/", parts.query, fragment))
+    if not parts.query and "?" in raw_url.split("#", 1)[0]:
+        before_fragment, marker, after_fragment = canonical.partition("#")
+        canonical = before_fragment + "?" + (marker + after_fragment if marker else "")
+    return canonical
+
+
+def _bucket():
+    return {"submitted": 0, "streams": {}, "error_count": 0, "invalid_count": 0}
+
+
+def _mode(providers, query_count):
+    if not providers:
+        return "no_provider"
+    if len(providers) > 1:
+        return "multi_provider"
+    return "single_provider_multi_query" if query_count > 1 else "single_provider_single_query"
+
+
+def fuse_results(payload):
+    """Return independently ranked targets, provenance, failures and coverage.
+
+    Malformed top-level configuration raises ValueError. Invalid batches/results
+    are reported and do not discard valid siblings. Provider counts include
+    failed providers; successful-provider coverage is reported separately.
+    """
+    if not isinstance(payload, dict) or not isinstance(payload.get("batches"), list):
+        raise ValueError("payload must be an object with a batches array")
+    limit = payload.get("limit_per_target", 10)
+    if isinstance(limit, bool) or not isinstance(limit, int) or limit < 1:
+        raise ValueError("limit_per_target must be a positive integer")
+    requested = payload.get("targets", [])
+    if not isinstance(requested, list) or any(not _nonempty_string(t) for t in requested):
+        raise ValueError("targets must be an array of nonempty strings")
+    buckets = OrderedDict((target.strip(), _bucket()) for target in requested)
+    errors, invalid_results = [], []
+
+    def error(batch_index, message, target=None, provider=None, query=None, kind="invalid_batch"):
+        errors.append({"batch_index": batch_index, "target": target,
+                       "provider": provider, "query": query, "kind": kind, "error": message})
+        if target in buckets:
+            buckets[target]["error_count"] += 1
+
+    for batch_index, batch in enumerate(payload["batches"]):
+        if not isinstance(batch, dict):
+            error(batch_index, "batch must be an object")
+            continue
+        target = batch.get("target")
+        if not _nonempty_string(target):
+            error(batch_index, "target must be a nonempty string")
+            continue
+        target = target.strip()
+        bucket = buckets.setdefault(target, _bucket())
+        bucket["submitted"] += 1
+        provider, query = batch.get("provider"), batch.get("query")
+        if not _nonempty_string(provider) or not _nonempty_string(query):
+            error(batch_index, "provider and query must be nonempty strings", target)
+            continue
+        provider, query = provider.strip().lower(), query.strip()
+        stream = bucket["streams"].setdefault((provider, query),
+                                             {"ok": False, "failed": False, "urls": {}})
+        status = batch.get("status")
+        if status not in ("ok", "error"):
+            stream["failed"] = True
+            error(batch_index, "status must be ok or error", target, provider, query)
+            continue
+        if status == "error":
+            stream["failed"] = True
+            error(batch_index, batch.get("error") or "provider returned an error",
+                  target, provider, query, "provider_error")
+            continue
+        results = batch.get("results")
+        if not isinstance(results, list):
+            stream["failed"] = True
+            error(batch_index, "an ok batch must have a results array", target, provider, query)
+            continue
+        stream["ok"] = True
+        for position, item in enumerate(results, 1):
+            try:
+                if not isinstance(item, dict):
+                    raise ValueError("result must be an object")
+                raw_url = item.get("url")
+                canonical = _canonical_url(raw_url)
+                rank = item.get("rank", position)
+                if isinstance(rank, bool) or not isinstance(rank, int) or not 1 <= rank <= MAX_RANK:
+                    raise ValueError("rank must be an integer between 1 and " + str(MAX_RANK))
+                title = item.get("title", "")
+                if not isinstance(title, str):
+                    raise ValueError("title must be a string")
+                snippet = item.get("snippet")
+                if snippet is None:
+                    snippet = item.get("text", "")
+                if not isinstance(snippet, str):
+                    raise ValueError("text or snippet must be a string")
+            except ValueError as exc:
+                invalid_results.append({"batch_index": batch_index, "result_position": position,
+                                        "target": target, "provider": provider, "query": query,
+                                        "raw_url": item.get("url") if isinstance(item, dict) else None,
+                                        "reason": str(exc)})
+                bucket["invalid_count"] += 1
+                continue
+            snippet, truncated = snippet[:MAX_SNIPPET_CHARS], len(snippet) > MAX_SNIPPET_CHARS
+            existing = stream["urls"].get(canonical)
+            if existing is None:
+                stream["urls"][canonical] = {
+                    "rank": rank, "raw_urls": {raw_url}, "title": title,
+                    "snippet": snippet, "snippet_truncated": truncated,
+                }
+            else:
+                existing["rank"] = min(existing["rank"], rank)
+                existing["raw_urls"].add(raw_url)
+                if title:
+                    existing["title"] = min(t for t in (existing["title"], title) if t)
+                old = (len(existing["snippet"]), existing["snippet"], existing["snippet_truncated"])
+                new = (len(snippet), snippet, truncated)
+                if new > old:
+                    existing["snippet"], existing["snippet_truncated"] = snippet, truncated
+
+    targets, all_providers, all_successful_providers = [], set(), set()
+    query_count = 0
+    for target, bucket in buckets.items():
+        streams = bucket["streams"]
+        by_url, by_provider = {}, {}
+        for (provider, query), stream in sorted(streams.items()):
+            coverage = by_provider.setdefault(provider, {"query_count": 0, "successful_queries": 0,
+                                                         "failed_queries": 0, "unique_urls": set()})
+            coverage["query_count"] += 1
+            coverage["successful_queries"] += int(stream["ok"])
+            coverage["failed_queries"] += int(stream["failed"])
+            coverage["unique_urls"].update(stream["urls"])
+            for canonical, hit in stream["urls"].items():
+                raw_urls = sorted(hit["raw_urls"])
+                by_url.setdefault(canonical, []).append({
+                    "provider": provider, "query": query, "rank": hit["rank"],
+                    "url": raw_urls[0], "raw_urls": raw_urls, "title": hit["title"],
+                    "snippet": hit["snippet"], "snippet_truncated": hit["snippet_truncated"],
+                })
+        ranked = []
+        for canonical, sources in by_url.items():
+            sources.sort(key=lambda source: (source["rank"], source["provider"], source["query"]))
+            ranked.append({
+                "url": sources[0]["url"], "canonical_url": canonical,
+                "raw_urls": sorted({url for source in sources for url in source["raw_urls"]}),
+                "title": next((source["title"] for source in sources if source["title"]), ""),
+                "rrf_score": sum(1.0 / (RRF_K + source["rank"]) for source in sources),
+                "provider_count": len({source["provider"] for source in sources}),
+                "evidence_count": len(sources), "sources": sources,
+            })
+        ranked.sort(key=lambda hit: (-hit["rrf_score"], hit["canonical_url"]))
+        successful_queries = sum(int(stream["ok"]) for stream in streams.values())
+        failed_queries = sum(int(stream["failed"]) for stream in streams.values())
+        has_issues = bool(bucket["error_count"] or bucket["invalid_count"])
+        if not bucket["submitted"]:
+            status = "missing"
+        elif not successful_queries:
+            status = "error"
+        elif has_issues:
+            status = "partial"
+        else:
+            status = "ok" if ranked else "empty"
+        successful_providers = sorted(p for p, coverage in by_provider.items() if coverage["successful_queries"])
+        for coverage in by_provider.values():
+            coverage["unique_urls"] = len(coverage["unique_urls"])
+        targets.append({
+            "target": target, "status": status, "providers": sorted(by_provider),
+            "provider_count": len(by_provider), "query_count": len(streams),
+            "mode": _mode(by_provider, len(streams)),
+            "coverage": {"submitted_batches": bucket["submitted"], "unique_queries": len(streams),
+                         "successful_queries": successful_queries, "failed_queries": failed_queries,
+                         "successful_providers": successful_providers,
+                         "invalid_results": bucket["invalid_count"], "unique_urls": len(ranked),
+                         "returned_urls": min(limit, len(ranked)), "truncated": len(ranked) > limit,
+                         "by_provider": by_provider},
+            "results": ranked[:limit],
+        })
+        all_providers.update(by_provider)
+        all_successful_providers.update(successful_providers)
+        query_count += len(streams)
+    return {
+        "provider_count": len(all_providers), "providers": sorted(all_providers),
+        "successful_provider_count": len(all_successful_providers),
+        "target_count": len(targets), "query_count": query_count,
+        "mode": _mode(all_providers, query_count), "limit_per_target": limit,
+        "ranking": {"method": "rrf", "k": RRF_K,
+                    "evidence_unit": "unique provider/query retrieval for this target and URL",
+                    "independent_fact_confirmation": False},
+        "missing_targets": [item["target"] for item in targets if item["status"] == "missing"],
+        "uncovered_targets": [item["target"] for item in targets if not item["results"]],
+        "targets": targets, "errors": errors, "invalid_results": invalid_results,
+    }

package/src/service_http.py

@@ -0,0 +1,139 @@
+"""Single-request HTTP transport for documented research APIs, without retries."""
+
+import json
+import http.client
+import math
+import re
+import socket
+import urllib.error
+import urllib.request
+from urllib.parse import urlsplit
+from credentials import Credentials
+
+
+class ServiceError(RuntimeError):
+    def __init__(self, kind, message, uncertain=False, http_status=None, retry_after=None):
+        super().__init__(message)
+        self.kind = kind
+        self.uncertain = uncertain
+        self.http_status = http_status
+        self.retry_after = retry_after
+
+    def details(self):
+        return {"error_kind": self.kind, "error": str(self),
+                "request_outcome_unknown": self.uncertain,
+                "http_status": self.http_status, "retry_after_seconds": self.retry_after}
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        # Provider credentials must never follow an unexpected redirect.
+        return None
+
+
+class ResearchHttp:
+    PROVIDERS = {
+        "openai": {"origin": "https://api.openai.com", "key_env": "OPENAI_API_KEY"},
+        "parallel": {"origin": "https://api.parallel.ai", "key_env": "PARALLEL_API_KEY"},
+    }
+    MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+
+    def __init__(self, timeout=30, credentials=None):
+        if type(timeout) not in (int, float) or not math.isfinite(timeout) or not 0 < timeout <= 60:
+            raise ValueError("Research API timeout must be greater than 0 and at most 60 seconds")
+        self.timeout = timeout
+        self.credentials = credentials if credentials is not None else Credentials()
+
+    @staticmethod
+    def _unique_object(pairs):
+        value = {}
+        for key, item in pairs:
+            if key in value:
+                raise ValueError("Duplicate JSON field")
+            value[key] = item
+        return value
+
+    @staticmethod
+    def _invalid_constant(value):
+        raise ValueError("Non-finite JSON number")
+
+    @staticmethod
+    def _finite_float(value):
+        number = float(value)
+        if not math.isfinite(number):
+            raise ValueError("Non-finite JSON number")
+        return number
+
+    @classmethod
+    def _endpoint(cls, provider, method, path, payload):
+        if not isinstance(provider, str) or provider not in cls.PROVIDERS:
+            raise ValueError("Unsupported research provider")
+        if not isinstance(path, str) or not isinstance(method, str):
+            raise ValueError("Unsupported research API request")
+        parsed = urlsplit(path)
+        if parsed.scheme or parsed.netloc or parsed.fragment or any(ord(char) < 32 for char in path):
+            raise ValueError("Unsupported research API request")
+        suffix = r"[A-Za-z0-9_-]{1,192}"
+        if provider == "openai":
+            create = path == "/v1/responses" and method == "POST"
+            read = method == "GET" and (re.fullmatch(r"/v1/responses/resp_" + suffix, path)
+                    or path in ("/v1/models/o3-deep-research", "/v1/models/o4-mini-deep-research"))
+            cancel = method == "POST" and re.fullmatch(r"/v1/responses/resp_" + suffix + r"/cancel", path)
+        else:
+            create = path == "/v1/tasks/runs" and method == "POST"
+            read = method == "GET" and re.fullmatch(r"/v1/tasks/runs/trun_" + suffix + r"(?:/result\?timeout=1)?", path)
+            cancel = False
+        if not (create or read or cancel):
+            raise ValueError("Unsupported research API request")
+        if (create and not isinstance(payload, dict)) or (read and payload is not None) or (cancel and payload not in (None, {})):
+            raise ValueError("Invalid payload for this research API operation")
+
+    def request(self, provider, method, path, payload=None):
+        self._endpoint(provider, method, path, payload)
+        info = self.PROVIDERS[provider]
+        key = self.credentials.get(info["key_env"])
+        if not key or any(not 33 <= ord(char) <= 126 for char in key):
+            raise ServiceError("authentication_required", "Configure " + info["key_env"] + " with setup or in the host environment")
+        headers = {"Content-Type": "application/json", "Accept": "application/json"}
+        if provider == "openai":
+            headers["Authorization"] = "Bearer " + key
+        else:
+            headers["x-api-key"] = key
+        try:
+            data = None if payload is None else json.dumps(payload, ensure_ascii=False, allow_nan=False).encode("utf-8")
+        except (TypeError, ValueError, UnicodeError):
+            raise ValueError("Research API payload must contain valid JSON") from None
+        request = urllib.request.Request(info["origin"] + path, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.build_opener(_NoRedirect()).open(request, timeout=self.timeout) as response:
+                body = response.read(self.MAX_RESPONSE_BYTES + 1)
+            if len(body) > self.MAX_RESPONSE_BYTES:
+                raise ServiceError("response_too_large", "Research API response exceeds the local size limit", uncertain=True)
+            result = json.loads(body.decode("utf-8"), object_pairs_hook=self._unique_object,
+                                parse_constant=self._invalid_constant, parse_float=self._finite_float)
+            if not isinstance(result, dict):
+                raise ServiceError("result_format", "Research API returned a non-object response", uncertain=True)
+            return result
+        except urllib.error.HTTPError as error:
+            status = error.code
+            kind = {401: "authentication_required", 403: "authentication_required", 404: "run_unavailable",
+                    408: "result_pending", 429: "rate_limited", 400: "invalid_request", 422: "invalid_request"}.get(status, "http_error")
+            retry = error.headers.get("Retry-After") if error.headers else None
+            retry = int(retry) if isinstance(retry, str) and len(retry) <= 5 and retry.isascii() and retry.isdigit() and int(retry) <= 86400 else None
+            try:
+                error.close()
+            except OSError:
+                pass
+            raise ServiceError(kind, "Research API HTTP " + str(status),
+                               uncertain=status >= 500 or status == 408 or (method == "POST" and 300 <= status < 400),
+                               http_status=status, retry_after=retry) from None
+        except (TimeoutError, socket.timeout):
+            raise ServiceError("timeout", "Research API observation timed out", uncertain=True) from None
+        except urllib.error.URLError:
+            raise ServiceError("connection_error", "Research API connection failed", uncertain=True) from None
+        except (OSError, http.client.HTTPException):
+            # IncompleteRead and low-level socket failures may carry response
+            # bytes or request context. Never expose their exception strings.
+            raise ServiceError("connection_error", "Research API connection failed or response was interrupted", uncertain=True) from None
+        except (ValueError, UnicodeError):
+            raise ServiceError("result_format", "Research API response is not valid JSON", uncertain=True) from None