Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
"""`hpr scholar` CLI surface.
No network and no real provider: the registry is monkeypatched to hand back
fakes defined here. That is deliberate — these tests must keep passing while
provider modules are added, renamed, or removed, and they must not depend on
whoever runs them holding an API key.
"""
from __future__ import annotations
import json
from typing import Any
import pytest
from typer.testing import CliRunner
from hyperresearch.cli import app
from hyperresearch.scholar.base import Paper, ProviderError, SearchProvider
runner = CliRunner()
# ---------------------------------------------------------------------------
# Fakes
# ---------------------------------------------------------------------------
def make_provider(
slug: str,
*,
papers: tuple[Paper, ...] = (),
raises: Exception | None = None,
needs_key: bool = False,
key_env: tuple[str, ...] = (),
covers: str = "Fake coverage",
) -> SearchProvider:
"""A concrete SearchProvider built at test time, with a call log."""
calls: list[dict[str, Any]] = []
def search(
self: SearchProvider,
conn: Any,
query: str,
limit: int,
*,
fresh: bool = False,
) -> list[Paper]:
calls.append({"query": query, "limit": limit, "fresh": fresh, "conn": conn})
if raises is not None:
raise raises
return list(papers)
cls = type(
f"Fake_{slug}",
(SearchProvider,),
{
"slug": slug,
"label": f"{slug.capitalize()} Index",
"covers": covers,
"needs_key": needs_key,
"key_env": key_env,
"search": search,
"calls": calls,
},
)
return cls() # type: ignore[no-any-return]
def install(monkeypatch: pytest.MonkeyPatch, *providers: SearchProvider) -> None:
"""Point the registry at `providers` and keep the search cache out of it."""
from hyperresearch.cli import scholar_cmd
from hyperresearch.scholar import registry
def fake_get_providers(
slugs: list[str] | None = None,
*,
scope: str = "all",
include_unavailable: bool = False,
) -> list[SearchProvider]:
found = list(providers)
if scope == "papers":
found = [p for p in found if p.slug in registry.PAPER_SLUGS]
if slugs:
wanted = {s.strip().lower() for s in slugs if s.strip()}
found = [p for p in found if p.slug in wanted]
if not include_unavailable:
found = [p for p in found if p.available()]
return found
monkeypatch.setattr(registry, "get_providers", fake_get_providers)
# No vault in these tests; the command must not need one.
monkeypatch.setattr(scholar_cmd, "_open_cache", lambda: (None, None))
def payload(result: Any) -> dict[str, Any]:
assert result.exit_code == 0, result.output
parsed: dict[str, Any] = json.loads(result.output)
assert parsed["ok"] is True
return parsed
ALPHA_PAPER = Paper(
title="Attention Is All You Need",
source="alpha",
doi="10.1/attn",
year=2017,
authors=("Vaswani, A.",),
citation_count=100,
url="https://alpha/attn",
)
BETA_SAME = Paper(
title="attention is all you need",
source="beta",
doi="https://doi.org/10.1/ATTN",
year=2018,
authors=("Vaswani, A.", "Shazeer, N."),
citation_count=9000,
abstract="The dominant sequence transduction models...",
)
BETA_OTHER = Paper(
title="Deep Residual Learning",
source="beta",
doi="10.1/resnet",
year=2016,
)
# ---------------------------------------------------------------------------
# scholar sources
# ---------------------------------------------------------------------------
def test_sources_runs_with_zero_providers_installed(monkeypatch: pytest.MonkeyPatch) -> None:
"""The registry tolerates missing provider modules; so must the CLI."""
install(monkeypatch)
result = runner.invoke(app, ["scholar", "sources"])
assert result.exit_code == 0
assert "No discovery providers" in result.output
def test_sources_json_lists_slug_label_covers_and_availability(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv("FAKE_GAMMA_KEY", raising=False)
install(
monkeypatch,
make_provider("alpha", covers="Everything with a DOI"),
make_provider("gamma", needs_key=True, key_env=("FAKE_GAMMA_KEY",)),
)
rows = payload(runner.invoke(app, ["scholar", "sources", "--json"]))["data"]
assert [r["slug"] for r in rows] == ["alpha", "gamma"]
assert rows[0]["covers"] == "Everything with a DOI"
assert rows[0]["available"] is True
assert rows[0]["reason"] is None
# An unavailable provider is listed WITH its reason rather than hidden.
assert rows[1]["available"] is False
assert "FAKE_GAMMA_KEY" in rows[1]["reason"]
def test_sources_human_output_shows_the_missing_key(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv("FAKE_GAMMA_KEY", raising=False)
install(monkeypatch, make_provider("gamma", needs_key=True, key_env=("FAKE_GAMMA_KEY",)))
result = runner.invoke(app, ["scholar", "sources"])
assert result.exit_code == 0
assert "gamma" in result.output
assert "FAKE_GAMMA_KEY" in result.output
def test_sources_rejects_an_unknown_scope(monkeypatch: pytest.MonkeyPatch) -> None:
install(monkeypatch, make_provider("alpha"))
result = runner.invoke(app, ["scholar", "sources", "--scope", "banana", "--json"])
assert result.exit_code == 1
assert json.loads(result.output)["error_code"] == "BAD_SCOPE"
# ---------------------------------------------------------------------------
# scholar search
# ---------------------------------------------------------------------------
def test_search_json_shape_and_cross_provider_merge(monkeypatch: pytest.MonkeyPatch) -> None:
install(
monkeypatch,
make_provider("alpha", papers=(ALPHA_PAPER,)),
make_provider("beta", papers=(BETA_SAME, BETA_OTHER)),
)
data = payload(runner.invoke(app, ["scholar", "search", "transformers", "--json"]))["data"]
assert data["query"] == "transformers"
assert data["providers"] == ["alpha", "beta"]
assert data["per_source"] == {"alpha": 1, "beta": 2}
assert data["raw_records"] == 3
assert data["merged_records"] == 2
assert data["failed"] == []
first = data["results"][0]
assert first["title"] == "Attention Is All You Need"
assert first["source"] == "alpha"
# Merge rules reach the wire format: max citations, longest author list,
# the abstract only the second provider had, and the corroboration trail.
assert first["citation_count"] == 9000
assert first["authors"] == ["Vaswani, A.", "Shazeer, N."]
assert first["abstract"].startswith("The dominant")
assert first["extra"]["also_in"] == "alpha,beta"
assert data["results"][1]["title"] == "Deep Residual Learning"
def test_search_source_filter_queries_only_that_provider(monkeypatch: pytest.MonkeyPatch) -> None:
alpha = make_provider("alpha", papers=(ALPHA_PAPER,))
beta = make_provider("beta", papers=(BETA_OTHER,))
install(monkeypatch, alpha, beta)
data = payload(
runner.invoke(app, ["scholar", "search", "q", "-s", "beta", "--json"])
)["data"]
assert data["providers"] == ["beta"]
assert [r["title"] for r in data["results"]] == ["Deep Residual Learning"]
assert alpha.calls == [] # type: ignore[attr-defined]
assert len(beta.calls) == 1 # type: ignore[attr-defined]
def test_search_passes_limit_and_fresh_through_to_providers(monkeypatch: pytest.MonkeyPatch) -> None:
alpha = make_provider("alpha", papers=(ALPHA_PAPER,))
install(monkeypatch, alpha)
payload(runner.invoke(app, ["scholar", "search", "q", "-n", "7", "--fresh", "--json"]))
call = alpha.calls[0] # type: ignore[attr-defined]
assert call["limit"] == 7
assert call["fresh"] is True
def test_search_survives_a_provider_that_raises(monkeypatch: pytest.MonkeyPatch) -> None:
install(
monkeypatch,
make_provider("alpha", raises=ProviderError("alpha is down")),
make_provider("beta", papers=(BETA_OTHER,)),
)
data = payload(runner.invoke(app, ["scholar", "search", "q", "--json"]))["data"]
assert data["failed"] == [{"source": "alpha", "error": "alpha is down"}]
assert [r["title"] for r in data["results"]] == ["Deep Residual Learning"]
assert "alpha" not in data["per_source"]
def test_search_survives_an_unexpected_exception(monkeypatch: pytest.MonkeyPatch) -> None:
install(
monkeypatch,
make_provider("alpha", raises=ValueError("boom")),
make_provider("beta", papers=(BETA_OTHER,)),
)
data = payload(runner.invoke(app, ["scholar", "search", "q", "--json"]))["data"]
assert data["failed"][0]["source"] == "alpha"
assert "ValueError: boom" in data["failed"][0]["error"]
assert len(data["results"]) == 1
def test_search_empty_results(monkeypatch: pytest.MonkeyPatch) -> None:
install(monkeypatch, make_provider("alpha"))
parsed = payload(runner.invoke(app, ["scholar", "search", "nothing here", "--json"]))
assert parsed["count"] == 0
assert parsed["data"]["results"] == []
assert parsed["data"]["merged_records"] == 0
def test_search_empty_results_human_output(monkeypatch: pytest.MonkeyPatch) -> None:
install(monkeypatch, make_provider("alpha"))
result = runner.invoke(app, ["scholar", "search", "nothing here"])
assert result.exit_code == 0
assert "No results" in result.output
def test_search_reports_why_a_source_was_skipped(monkeypatch: pytest.MonkeyPatch) -> None:
"""A silently smaller corpus is worse than a loud one."""
monkeypatch.delenv("FAKE_GAMMA_KEY", raising=False)
install(
monkeypatch,
make_provider("alpha", papers=(ALPHA_PAPER,)),
make_provider("gamma", needs_key=True, key_env=("FAKE_GAMMA_KEY",)),
)
data = payload(runner.invoke(app, ["scholar", "search", "q", "--json"]))["data"]
assert data["providers"] == ["alpha"]
assert any("FAKE_GAMMA_KEY" in note for note in data["unavailable"])
def test_search_year_from_drops_older_records(monkeypatch: pytest.MonkeyPatch) -> None:
undated = Paper(title="Undated Work", source="alpha")
install(monkeypatch, make_provider("alpha", papers=(ALPHA_PAPER, BETA_OTHER, undated)))
data = payload(
runner.invoke(app, ["scholar", "search", "q", "--year-from", "2017", "--json"])
)["data"]
titles = [r["title"] for r in data["results"]]
assert "Deep Residual Learning" not in titles
assert "Attention Is All You Need" in titles
# Undated records are kept: we drop what we can show is too old, not what
# we simply cannot date.
assert "Undated Work" in titles
def test_search_limit_is_per_provider_not_a_merged_cap(monkeypatch: pytest.MonkeyPatch) -> None:
"""A post-merge cap would hide every provider but the first.
Merge order is provider precedence, so capping the merged list at `-n`
means a two-source search at `-n 2` returns only the first source's two
records and the second source appears empty. The limit is passed to each
provider; the merged list is whatever survives dedup.
"""
alpha = tuple(Paper(title=f"A {i}", source="alpha", doi=f"10.1/a{i}") for i in range(2))
beta = tuple(Paper(title=f"B {i}", source="beta", doi=f"10.1/b{i}") for i in range(2))
install(
monkeypatch,
make_provider("alpha", papers=alpha),
make_provider("beta", papers=beta),
)
data = payload(runner.invoke(app, ["scholar", "search", "q", "-n", "2", "--json"]))["data"]
assert data["merged_records"] == 4
assert data["returned"] == 4
assert {r["source"] for r in data["results"]} == {"alpha", "beta"}
def test_search_scope_papers_narrows_the_provider_set(monkeypatch: pytest.MonkeyPatch) -> None:
from hyperresearch.scholar import registry
monkeypatch.setattr(registry, "PAPER_SLUGS", frozenset({"alpha"}))
install(
monkeypatch,
make_provider("alpha", papers=(ALPHA_PAPER,)),
make_provider("beta", papers=(BETA_OTHER,)),
)
data = payload(
runner.invoke(app, ["scholar", "search", "q", "--scope", "papers", "--json"])
)["data"]
assert data["providers"] == ["alpha"]
def test_search_errors_when_no_provider_matches_the_filter(monkeypatch: pytest.MonkeyPatch) -> None:
install(monkeypatch, make_provider("alpha"))
result = runner.invoke(app, ["scholar", "search", "q", "-s", "nope", "--json"])
assert result.exit_code == 1
parsed = json.loads(result.output)
assert parsed["ok"] is False
assert parsed["error_code"] == "NO_PROVIDERS"
def test_search_errors_with_zero_providers_installed(monkeypatch: pytest.MonkeyPatch) -> None:
install(monkeypatch)
result = runner.invoke(app, ["scholar", "search", "q", "--json"])
assert result.exit_code == 1
assert json.loads(result.output)["error_code"] == "NO_PROVIDERS"
def test_search_rejects_an_unknown_scope(monkeypatch: pytest.MonkeyPatch) -> None:
install(monkeypatch, make_provider("alpha"))
result = runner.invoke(app, ["scholar", "search", "q", "--scope", "banana", "--json"])
assert result.exit_code == 1
assert json.loads(result.output)["error_code"] == "BAD_SCOPE"
def test_search_human_output_shows_the_merge_trail(monkeypatch: pytest.MonkeyPatch) -> None:
install(
monkeypatch,
make_provider("alpha", papers=(ALPHA_PAPER,)),
make_provider("beta", papers=(BETA_SAME,)),
)
result = runner.invoke(app, ["scholar", "search", "transformers"])
assert result.exit_code == 0
assert "Attention Is All You Need" in result.output
assert "also in" in result.output