langchain-hyperresearch 0.1.0__py3-none-any.whl

langchain_hyperresearch/__init__.py

@@ -0,0 +1,27 @@
+"""LangChain integration for Hyperresearch Answers."""
+
+from langchain_hyperresearch._client import (
+    DEFAULT_BASE_URL,
+    HyperresearchClient,
+    HyperresearchError,
+    __version__,
+)
+from langchain_hyperresearch.retrievers import HyperresearchRetriever
+from langchain_hyperresearch.tools import (
+    HyperresearchAnswerInput,
+    HyperresearchAnswerTool,
+    HyperresearchSearchInput,
+    HyperresearchSearchTool,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "HyperresearchAnswerInput",
+    "HyperresearchAnswerTool",
+    "HyperresearchClient",
+    "HyperresearchError",
+    "HyperresearchRetriever",
+    "HyperresearchSearchInput",
+    "HyperresearchSearchTool",
+    "__version__",
+]

langchain_hyperresearch/_client.py

@@ -0,0 +1,301 @@
+"""A small client for the Hyperresearch Answers REST API.
+
+    POST /v1/answers          ask: one short answer checked against quoted sources, or an honest not_found
+    POST /v1/answers/search   search: ranked sources with word-for-word passages, no synthesis
+    GET  /v1/answers/{id}     a stored call (used to collect an ask that came back 202 pending)
+
+Auth is ``Authorization: Bearer <hr_live_... key>`` with the ``answers:ask`` scope.
+Every call is billed from the account's prepaid Answers balance.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+import uuid
+from typing import Any, Literal, Optional
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.hyperresearch.ai"
+API_KEY_ENV = "HYPERRESEARCH_API_KEY"
+BASE_URL_ENV = "HYPERRESEARCH_BASE_URL"
+__version__ = "0.1.0"
+
+AskMode = Literal["fast", "standard", "max"]
+SearchMode = Literal["standard", "max"]
+
+POLL_WAIT_SECONDS = 45
+MAX_RETRY_DELAY_S = 30.0
+
+
+class HyperresearchError(Exception):
+    """A non-2xx response, carrying the API's error envelope."""
+
+    def __init__(
+        self,
+        status: int,
+        message: str,
+        *,
+        type: Optional[str] = None,
+        code: Optional[str] = None,
+        param: Optional[str] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.type = type
+        self.code = code
+        self.param = param
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.body = body
+
+    def __repr__(self) -> str:
+        return f"HyperresearchError(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+def _parse(response: httpx.Response) -> dict[str, Any]:
+    try:
+        data = response.json() if response.content else {}
+    except ValueError:
+        data = {"raw": response.text}
+    return data if isinstance(data, dict) else {"data": data}
+
+
+def _err(body: dict[str, Any]) -> dict[str, Any]:
+    e = body.get("error")
+    return e if isinstance(e, dict) else {}
+
+
+def _retry_after(response: httpx.Response, body: dict[str, Any]) -> Optional[float]:
+    err = _err(body)
+    if isinstance(err.get("retry_after"), (int, float)):
+        return float(err["retry_after"])
+    try:
+        return float(response.headers.get("Retry-After", ""))
+    except ValueError:
+        return None
+
+
+def _error(response: httpx.Response, body: dict[str, Any]) -> HyperresearchError:
+    err = _err(body)
+    return HyperresearchError(
+        response.status_code,
+        err.get("message") or f"Hyperresearch API error {response.status_code}",
+        type=err.get("type"),
+        code=err.get("code"),
+        param=err.get("param"),
+        request_id=err.get("request_id"),
+        retry_after=_retry_after(response, body),
+        body=body,
+    )
+
+
+class HyperresearchClient:
+    """Sync and async access to the Answers API.
+
+    Args:
+        api_key: Defaults to the ``HYPERRESEARCH_API_KEY`` environment variable.
+        base_url: Defaults to ``HYPERRESEARCH_BASE_URL``, then https://api.hyperresearch.ai.
+        ask_timeout: Seconds an ask may take end to end, including polling. Default 360 (max mode runs up to about 5 minutes).
+        search_timeout: Seconds a search may take. Default 90.
+        max_retries: Retries on 429/503 (capacity), honouring Retry-After. Default 2.
+        transport / async_transport: httpx transports (tests, proxies).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        ask_timeout: float = 360.0,
+        search_timeout: float = 90.0,
+        max_retries: int = 2,
+        headers: Optional[dict[str, str]] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+        async_transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get(API_KEY_ENV)
+        self.base_url = (base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL).rstrip("/")
+        self.ask_timeout = ask_timeout
+        self.search_timeout = search_timeout
+        self.max_retries = max_retries
+        self.extra_headers = dict(headers or {})
+        self._transport = transport
+        self._async_transport = async_transport
+        # Test seams.
+        self._sleep = time.sleep
+        self._asleep = asyncio.sleep
+
+    # ---- shared ----
+
+    def _headers(self, extra: Optional[dict[str, str]] = None) -> dict[str, str]:
+        if not self.api_key:
+            raise HyperresearchError(
+                401,
+                f"No Hyperresearch API key. Set {API_KEY_ENV} or pass api_key. "
+                "Create one with the answers:ask scope at https://console.hyperresearch.ai/#/keys",
+                code="missing_api_key",
+            )
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"langchain-hyperresearch/{__version__}",
+            **self.extra_headers,
+            **(extra or {}),
+        }
+
+    @staticmethod
+    def _ask_body(question: str, mode: str, as_of: Optional[str], max_cost_cents: Optional[float]) -> dict[str, Any]:
+        body: dict[str, Any] = {"question": question, "mode": mode}
+        if as_of is not None:
+            body["as_of"] = as_of
+        if max_cost_cents is not None:
+            body["max_cost_cents"] = max_cost_cents
+        return body
+
+    def _delay(self, attempt: int, retry_after: Optional[float]) -> float:
+        return min(retry_after if retry_after is not None else 2.0**attempt, MAX_RETRY_DELAY_S)
+
+    # ---- sync ----
+
+    def _request(
+        self, client: httpx.Client, method: str, path: str, *, json: Any = None, headers: Optional[dict[str, str]] = None
+    ) -> tuple[int, dict[str, Any]]:
+        attempt = 0
+        while True:
+            response = client.request(method, f"{self.base_url}{path}", json=json, headers=self._headers(headers))
+            body = _parse(response)
+            if response.is_success:
+                return response.status_code, body
+            if response.status_code in (429, 503) and attempt < self.max_retries:
+                self._sleep(self._delay(attempt, _retry_after(response, body)))
+                attempt += 1
+                continue
+            raise _error(response, body)
+
+    def ask(self, question: str, mode: AskMode = "standard", *, as_of: Optional[str] = None, max_cost_cents: Optional[float] = None) -> dict[str, Any]:
+        """Ask one question. A 202 ``pending`` is collected from GET /v1/answers/{id} (charged once)."""
+        deadline = time.monotonic() + self.ask_timeout
+        with httpx.Client(transport=self._transport, timeout=httpx.Timeout(self.ask_timeout)) as client:
+            status, body = self._request(
+                client,
+                "POST",
+                "/v1/answers",
+                json=self._ask_body(question, mode, as_of, max_cost_cents),
+                headers={"Idempotency-Key": str(uuid.uuid4()), "Prefer": f"respond-async; wait={POLL_WAIT_SECONDS + 5}"},
+            )
+            while status == 202 or body.get("status") == "pending":
+                call_id = body.get("id")
+                if not call_id:
+                    raise HyperresearchError(status, "The API answered pending without a call id.", body=body)
+                if time.monotonic() > deadline:
+                    raise HyperresearchError(
+                        408, f"Ask {call_id} did not finish within {self.ask_timeout:.0f}s; fetch it later with get_call().", code="client_timeout", body=body
+                    )
+                status, body = self._request(client, "GET", f"/v1/answers/{call_id}?wait={POLL_WAIT_SECONDS}")
+            return body
+
+    def search(self, query: str, max_results: int = 10, mode: SearchMode = "standard") -> dict[str, Any]:
+        """Ranked raw sources with verbatim passages."""
+        with httpx.Client(transport=self._transport, timeout=httpx.Timeout(self.search_timeout)) as client:
+            _, body = self._request(
+                client,
+                "POST",
+                "/v1/answers/search",
+                json={"query": query, "max_results": max_results, "mode": mode},
+                headers={"Idempotency-Key": str(uuid.uuid4())},
+            )
+            return body
+
+    def get_call(self, call_id: str, wait: Optional[int] = None) -> dict[str, Any]:
+        """A stored call. Free."""
+        path = f"/v1/answers/{call_id}" + (f"?wait={wait}" if wait is not None else "")
+        with httpx.Client(transport=self._transport, timeout=httpx.Timeout(60.0)) as client:
+            _, body = self._request(client, "GET", path)
+            return body
+
+    # ---- async ----
+
+    async def _arequest(
+        self, client: httpx.AsyncClient, method: str, path: str, *, json: Any = None, headers: Optional[dict[str, str]] = None
+    ) -> tuple[int, dict[str, Any]]:
+        attempt = 0
+        while True:
+            response = await client.request(method, f"{self.base_url}{path}", json=json, headers=self._headers(headers))
+            body = _parse(response)
+            if response.is_success:
+                return response.status_code, body
+            if response.status_code in (429, 503) and attempt < self.max_retries:
+                await self._asleep(self._delay(attempt, _retry_after(response, body)))
+                attempt += 1
+                continue
+            raise _error(response, body)
+
+    async def aask(self, question: str, mode: AskMode = "standard", *, as_of: Optional[str] = None, max_cost_cents: Optional[float] = None) -> dict[str, Any]:
+        deadline = time.monotonic() + self.ask_timeout
+        async with httpx.AsyncClient(transport=self._async_transport, timeout=httpx.Timeout(self.ask_timeout)) as client:
+            status, body = await self._arequest(
+                client,
+                "POST",
+                "/v1/answers",
+                json=self._ask_body(question, mode, as_of, max_cost_cents),
+                headers={"Idempotency-Key": str(uuid.uuid4()), "Prefer": f"respond-async; wait={POLL_WAIT_SECONDS + 5}"},
+            )
+            while status == 202 or body.get("status") == "pending":
+                call_id = body.get("id")
+                if not call_id:
+                    raise HyperresearchError(status, "The API answered pending without a call id.", body=body)
+                if time.monotonic() > deadline:
+                    raise HyperresearchError(
+                        408, f"Ask {call_id} did not finish within {self.ask_timeout:.0f}s; fetch it later with get_call().", code="client_timeout", body=body
+                    )
+                status, body = await self._arequest(client, "GET", f"/v1/answers/{call_id}?wait={POLL_WAIT_SECONDS}")
+            return body
+
+    async def asearch(self, query: str, max_results: int = 10, mode: SearchMode = "standard") -> dict[str, Any]:
+        async with httpx.AsyncClient(transport=self._async_transport, timeout=httpx.Timeout(self.search_timeout)) as client:
+            _, body = await self._arequest(
+                client,
+                "POST",
+                "/v1/answers/search",
+                json={"query": query, "max_results": max_results, "mode": mode},
+                headers={"Idempotency-Key": str(uuid.uuid4())},
+            )
+            return body
+
+
+def compact_answer(r: dict[str, Any]) -> dict[str, Any]:
+    """The form a model reads: the answer, its quotes, and what it cost."""
+    out: dict[str, Any] = {
+        "id": r.get("id"),
+        "status": r.get("status"),
+        "answer": r.get("answer", ""),
+        "evidence": [
+            {k: e.get(k) for k in ("url", "title", "quote", "check") if e.get(k) is not None} for e in (r.get("evidence") or []) if isinstance(e, dict)
+        ],
+    }
+    if r.get("caveat"):
+        out["caveat"] = r["caveat"]
+    if r.get("escalated"):
+        out["escalated"] = True
+    if r.get("error"):
+        out["error"] = r["error"]
+    out["price_cents"] = r.get("price_cents")
+    return out
+
+
+def compact_search(r: dict[str, Any]) -> dict[str, Any]:
+    results = []
+    for x in r.get("results") or []:
+        if not isinstance(x, dict):
+            continue
+        row = {k: x.get(k) for k in ("rank", "url", "title", "published", "source") if x.get(k) is not None}
+        row["passages"] = [{"text": p.get("text"), "verified": p.get("verified")} for p in (x.get("passages") or []) if isinstance(p, dict)]
+        results.append(row)
+    return {"id": r.get("id"), "status": r.get("status"), "query": r.get("query"), "results": results, "price_cents": r.get("price_cents")}

langchain_hyperresearch/retrievers.py

@@ -0,0 +1,78 @@
+"""A LangChain retriever over Hyperresearch Answers ``search``."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from langchain_core.callbacks import AsyncCallbackManagerForRetrieverRun, CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from pydantic import ConfigDict, Field, SecretStr, model_validator
+
+from langchain_hyperresearch._client import HyperresearchClient, SearchMode
+
+
+def _to_documents(res: dict[str, Any]) -> list[Document]:
+    docs = []
+    for r in res.get("results") or []:
+        if not isinstance(r, dict):
+            continue
+        passages = [p for p in (r.get("passages") or []) if isinstance(p, dict)]
+        texts = [p["text"] for p in passages if p.get("text")]
+        docs.append(
+            Document(
+                page_content="\n\n".join(texts) if texts else (r.get("snippet") or ""),
+                metadata={
+                    "url": r.get("url"),
+                    "title": r.get("title"),
+                    "rank": r.get("rank"),
+                    "source": r.get("source"),
+                    "published": r.get("published"),
+                    "verified": all(p.get("verified") is not False for p in passages),
+                    "call_id": res.get("id"),
+                },
+            )
+        )
+    return docs
+
+
+class HyperresearchRetriever(BaseRetriever):
+    """Ranked sources from Hyperresearch Answers ``search``, one Document per source.
+
+    ``page_content`` is the matched passages, verbatim (or the snippet when there are none).
+    ``metadata`` carries url, title, rank, source, published, verified and the call id.
+    Each retrieval is one billed ``search`` call (standard 5¢, max 15¢).
+
+    Example:
+        .. code-block:: python
+
+            from langchain_hyperresearch import HyperresearchRetriever
+
+            retriever = HyperresearchRetriever(max_results=5)
+            docs = retriever.invoke("minimum age to serve as a US senator")
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    max_results: int = Field(default=10, ge=1, le=25)
+    mode: SearchMode = "standard"
+    api_key: Optional[SecretStr] = Field(default=None, exclude=True)
+    base_url: Optional[str] = None
+    client: Optional[HyperresearchClient] = Field(default=None, exclude=True)
+
+    @model_validator(mode="after")
+    def _build_client(self) -> HyperresearchRetriever:
+        if self.client is None:
+            self.client = HyperresearchClient(
+                api_key=self.api_key.get_secret_value() if self.api_key else None,
+                base_url=self.base_url,
+            )
+        return self
+
+    def _get_relevant_documents(self, query: str, *, run_manager: CallbackManagerForRetrieverRun) -> list[Document]:
+        assert self.client is not None
+        return _to_documents(self.client.search(query, self.max_results, self.mode))
+
+    async def _aget_relevant_documents(self, query: str, *, run_manager: AsyncCallbackManagerForRetrieverRun) -> list[Document]:
+        assert self.client is not None
+        return _to_documents(await self.client.asearch(query, self.max_results, self.mode))

langchain_hyperresearch/tools.py

@@ -0,0 +1,202 @@
+"""Hyperresearch Answers tools for LangChain."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal, Optional
+
+from langchain_core.callbacks import AsyncCallbackManagerForToolRun, CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+from langchain_hyperresearch._client import (
+    AskMode,
+    HyperresearchClient,
+    SearchMode,
+    compact_answer,
+    compact_search,
+)
+
+ANSWER_DESCRIPTION = (
+    "Answer one factual question with Hyperresearch Answers. Researches the open web and about 45 structured sources "
+    "(filings, statistics, registers, scholarly indexes, books) on the server and returns one short answer with the quotes it rests on, "
+    "each checked word for word against its page, or status not_found when nothing supports an answer. "
+    "Prefer this over a loop of searches for any factual lookup. Modes: fast (5¢), standard (10¢, 20¢ if it digs deeper; default), "
+    "max (50¢, numbers confirmed on two sites). Each call is charged to the user's prepaid Hyperresearch Answers balance."
+)
+
+SEARCH_DESCRIPTION = (
+    "Search the web and Hyperresearch's ~45 structured sources (filings, statistics, registers, scholarly, books). "
+    "Returns ranked raw sources with verbatim passages. No synthesis. Use when you need to read the sources yourself. "
+    "Modes: standard (5¢, default), max (15¢: every provider plus structured data rows and PDF tables, for hard lookups). "
+    "Each call is charged to the user's prepaid Hyperresearch Answers balance."
+)
+
+
+class HyperresearchAnswerInput(BaseModel):
+    """Input for HyperresearchAnswerTool."""
+
+    question: str = Field(min_length=1, max_length=2000, description="One factual question, asked the way you would ask a researcher.")
+    mode: Optional[Literal["fast", "standard", "max"]] = Field(
+        default=None,
+        description="How hard to look: fast (5¢, about 45 s), standard (10¢, 20¢ if it digs deeper; default, up to about 3 min) "
+        "or max (50¢, up to about 5 min).",
+    )
+    as_of: Optional[str] = Field(default=None, pattern=r"^\d{4}-\d{2}-\d{2}$", description="Answer as of this date (YYYY-MM-DD). Omit for today.")
+
+
+class HyperresearchSearchInput(BaseModel):
+    """Input for HyperresearchSearchTool."""
+
+    query: str = Field(min_length=1, max_length=1000, description="What to find, as a question or a precise phrase.")
+    max_results: Optional[int] = Field(
+        default=None, ge=1, le=25, description="How many ranked sources to return (1-25, default 10). The price does not change."
+    )
+    mode: Optional[Literal["standard", "max"]] = Field(
+        default=None,
+        description="standard (5¢, default) or max (15¢: every provider, plus structured data rows and PDF tables, for hard lookups).",
+    )
+
+
+class _HyperresearchBase(BaseTool):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    api_key: Optional[SecretStr] = Field(default=None, exclude=True)
+    """Defaults to the HYPERRESEARCH_API_KEY environment variable."""
+    base_url: Optional[str] = None
+    """Defaults to HYPERRESEARCH_BASE_URL, then https://api.hyperresearch.ai."""
+    client: Optional[HyperresearchClient] = Field(default=None, exclude=True)
+    """Share one client between tools and retrievers."""
+
+    response_format: Literal["content_and_artifact"] = "content_and_artifact"
+
+    @model_validator(mode="after")
+    def _build_client(self) -> _HyperresearchBase:
+        if self.client is None:
+            self.client = HyperresearchClient(
+                api_key=self.api_key.get_secret_value() if self.api_key else None,
+                base_url=self.base_url,
+            )
+        return self
+
+
+class HyperresearchAnswerTool(_HyperresearchBase):
+    """Hyperresearch Answers ``ask``: one checked answer with its quotes, or ``not_found``.
+
+    Setup:
+        .. code-block:: bash
+
+            pip install -U langchain-hyperresearch
+            export HYPERRESEARCH_API_KEY="hr_live_..."
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_hyperresearch import HyperresearchAnswerTool
+
+            tool = HyperresearchAnswerTool()  # the model picks the mode
+            tool = HyperresearchAnswerTool(mode="fast", max_cost_cents=5)
+
+    Invoke directly:
+        .. code-block:: python
+
+            tool.invoke({"question": "How old must a US senator be?", "mode": "fast"})
+
+    Invoke with a ToolCall (returns a ToolMessage; ``artifact`` is the full API response):
+        .. code-block:: python
+
+            tool.invoke({"args": {"question": "How old must a US senator be?"}, "id": "1", "name": tool.name, "type": "tool_call"})
+    """
+
+    name: str = "hyperresearch_answer"
+    description: str = ANSWER_DESCRIPTION
+    args_schema: type[BaseModel] = HyperresearchAnswerInput
+
+    mode: Optional[AskMode] = None
+    """Fix the mode; the model then cannot choose it."""
+    max_cost_cents: Optional[float] = None
+    """Cap every call, in cents. A standard ask under 20 never escalates."""
+
+    def _mode(self, mode: Optional[str]) -> str:
+        return self.mode or mode or "standard"
+
+    def _run(
+        self,
+        question: str,
+        mode: Optional[str] = None,
+        as_of: Optional[str] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> tuple[str, dict[str, Any]]:
+        assert self.client is not None
+        raw = self.client.ask(question, self._mode(mode), as_of=as_of, max_cost_cents=self.max_cost_cents)  # type: ignore[arg-type]
+        return json.dumps(compact_answer(raw), ensure_ascii=False), raw
+
+    async def _arun(
+        self,
+        question: str,
+        mode: Optional[str] = None,
+        as_of: Optional[str] = None,
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+    ) -> tuple[str, dict[str, Any]]:
+        assert self.client is not None
+        raw = await self.client.aask(question, self._mode(mode), as_of=as_of, max_cost_cents=self.max_cost_cents)  # type: ignore[arg-type]
+        return json.dumps(compact_answer(raw), ensure_ascii=False), raw
+
+
+class HyperresearchSearchTool(_HyperresearchBase):
+    """Hyperresearch Answers ``search``: ranked raw sources with verbatim passages.
+
+    Setup:
+        .. code-block:: bash
+
+            pip install -U langchain-hyperresearch
+            export HYPERRESEARCH_API_KEY="hr_live_..."
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_hyperresearch import HyperresearchSearchTool
+
+            tool = HyperresearchSearchTool(max_results=5)
+
+    Invoke:
+        .. code-block:: python
+
+            tool.invoke({"query": "minimum age to serve as a US senator"})
+    """
+
+    name: str = "hyperresearch_search"
+    description: str = SEARCH_DESCRIPTION
+    args_schema: type[BaseModel] = HyperresearchSearchInput
+
+    mode: Optional[SearchMode] = None
+    """Fix the mode; the model then cannot choose it."""
+    max_results: Optional[int] = Field(default=None, ge=1, le=25)
+    """Fix the number of results (1-25)."""
+
+    def _args(self, max_results: Optional[int], mode: Optional[str]) -> tuple[int, str]:
+        return self.max_results or max_results or 10, self.mode or mode or "standard"
+
+    def _run(
+        self,
+        query: str,
+        max_results: Optional[int] = None,
+        mode: Optional[str] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> tuple[str, dict[str, Any]]:
+        assert self.client is not None
+        n, m = self._args(max_results, mode)
+        raw = self.client.search(query, n, m)  # type: ignore[arg-type]
+        return json.dumps(compact_search(raw), ensure_ascii=False), raw
+
+    async def _arun(
+        self,
+        query: str,
+        max_results: Optional[int] = None,
+        mode: Optional[str] = None,
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+    ) -> tuple[str, dict[str, Any]]:
+        assert self.client is not None
+        n, m = self._args(max_results, mode)
+        raw = await self.client.asearch(query, n, m)  # type: ignore[arg-type]
+        return json.dumps(compact_search(raw), ensure_ascii=False), raw

langchain_hyperresearch-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: langchain-hyperresearch
+Version: 0.1.0
+Summary: LangChain integration for Hyperresearch Answers: a cited, quote-checked answer tool, a raw-source search tool and a retriever.
+Project-URL: Homepage, https://hyperresearch.ai/answers
+Project-URL: Documentation, https://hyperresearch.ai/docs/answers/langchain
+Project-URL: Repository, https://github.com/jordan-gibbs/hyperresearch-answers
+Project-URL: Source, https://github.com/jordan-gibbs/hyperresearch-answers/tree/main/packages/langchain-python
+Project-URL: Issues, https://github.com/jordan-gibbs/hyperresearch-answers/issues
+Author: Hyperresearch
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,answers,citations,hyperresearch,langchain,retriever,search,tools,web-search
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: langchain-core<2.0.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+# langchain-hyperresearch
+
+This package contains the LangChain integration for [Hyperresearch Answers](https://hyperresearch.ai/answers): cited, quote-checked answers and ranked raw sources for agents.
+
+## Overview
+
+### Details
+
+| Class | Package | Serializable | JS support |
+| :--- | :--- | :---: | :---: |
+| `HyperresearchAnswerTool` | `langchain-hyperresearch` | ❌ | ✅ (`@hyperresearch/langchain`) |
+| `HyperresearchSearchTool` | `langchain-hyperresearch` | ❌ | ✅ |
+| `HyperresearchRetriever` | `langchain-hyperresearch` | ❌ | ✅ |
+
+### Features
+
+- **`HyperresearchAnswerTool`** (`hyperresearch_answer`): one factual question in, one short answer out, with the quotes it rests on, each checked word for word against its page. When nothing supports an answer it returns `not_found` instead of a guess. The research runs on the Hyperresearch side: one tool call instead of a loop of searches, and no pages in the agent's context.
+- **`HyperresearchSearchTool`** (`hyperresearch_search`): ranked raw sources from the open web and about 45 structured sources (company filings, statistics agencies, scholarly indexes, books, government records), with word-for-word passages. No summary.
+- **`HyperresearchRetriever`**: `search` as a retriever, one `Document` per ranked source.
+- Sync and async (`invoke` / `ainvoke`). Tools use `response_format="content_and_artifact"`: the model reads a compact JSON string, and `ToolMessage.artifact` holds the full API response.
+
+## Setup
+
+### Credentials
+
+Create an API key with the `answers:ask` scope at <https://console.hyperresearch.ai/#/keys>. Every account gets $5 of free credit, no card needed.
+
+```python
+import getpass
+import os
+
+if "HYPERRESEARCH_API_KEY" not in os.environ:
+    os.environ["HYPERRESEARCH_API_KEY"] = getpass.getpass("Enter your Hyperresearch API key: ")
+```
+
+### Installation
+
+```bash
+pip install -U langchain-hyperresearch
+# or
+uv add langchain-hyperresearch
+```
+
+## Instantiation
+
+```python
+from langchain_hyperresearch import HyperresearchAnswerTool, HyperresearchSearchTool
+
+answer = HyperresearchAnswerTool()                 # the model picks the mode
+cheap = HyperresearchAnswerTool(mode="fast", max_cost_cents=5)
+search = HyperresearchSearchTool(max_results=5)
+```
+
+| Parameter | Default | |
+|---|---|---|
+| `api_key` | `HYPERRESEARCH_API_KEY` | |
+| `mode` | the model's choice, else `standard` | Fix the mode. Ask: `fast` 5¢ · `standard` 10¢ (20¢ when it digs deeper) · `max` 50¢. Search: `standard` 5¢ · `max` 15¢. |
+| `max_cost_cents` | none | Answer tool. Caps every call; a standard ask under 20 never escalates. |
+| `max_results` | the model's choice, else 10 | Search tool and retriever. 1-25. |
+| `client` | new client | Share one `HyperresearchClient` (it also takes `base_url`, timeouts, `max_retries`). |
+
+## Invocation
+
+### Directly
+
+```python
+answer.invoke({"question": "How old must a US senator be?", "mode": "fast"})
+```
+
+```json
+{"id": "ans_01J...", "status": "answered", "answer": "At least 30 years old (US Constitution, Article I, Section 3).", "evidence": [{"url": "https://www.archives.gov/founding-docs/constitution-transcript", "title": "The Constitution of the United States: A Transcription", "quote": "No Person shall be a Senator who shall not have attained to the Age of thirty Years", "check": "verified"}], "price_cents": 5}
+```
+
+`status` is one of `answered`, `false_premise`, `unconfirmed`, `not_found` or `error`.
+
+```python
+search.invoke({"query": "minimum age to serve as a US senator"})
+```
+
+### As a ToolCall
+
+```python
+model_generated_tool_call = {
+    "args": {"question": "How old must a US senator be?"},
+    "id": "1",
+    "name": answer.name,
+    "type": "tool_call",
+}
+msg = answer.invoke(model_generated_tool_call)
+msg.content    # the compact JSON the model reads
+msg.artifact   # the full API response, including balance_cents
+```
+
+### Within an agent
+
+```python
+from langchain.agents import create_agent
+
+agent = create_agent(
+    model="claude-sonnet-4-6",
+    tools=[HyperresearchAnswerTool(), HyperresearchSearchTool()],
+)
+
+agent.invoke(
+    {"messages": [{"role": "user", "content": "What was the US federal deficit in fiscal 2025, with a source?"}]}
+)
+```
+
+## Retriever
+
+```python
+from langchain_hyperresearch import HyperresearchRetriever
+
+retriever = HyperresearchRetriever(max_results=5)
+docs = retriever.invoke("minimum age to serve as a US senator")
+docs[0].page_content   # the matched passages, verbatim
+docs[0].metadata       # url, title, rank, source, published, verified, call_id
+```
+
+Each retrieval is one billed `search` call.
+
+## Pricing
+
+| Call | Price | If not found |
+|---|---|---|
+| ask · fast | 5¢ | 1¢–5¢ |
+| ask · standard (default) | 10¢, 20¢ when it digs deeper | 2¢–20¢ |
+| ask · max | 50¢ | 10¢–50¢ |
+| search · standard (default) | 5¢ | 0¢–5¢ |
+| search · max | 15¢ | 0¢–15¢ |
+
+A call that fails on our side costs nothing. Current list: <https://hyperresearch.ai/answers#pricing>.
+
+## API contract
+
+The package calls the Answers REST API at `https://api.hyperresearch.ai` with `Authorization: Bearer <key>`.
+
+- `POST /v1/answers` `{question (1-2000 chars), mode?: fast|standard|max, as_of?: YYYY-MM-DD, max_cost_cents?}` returns `{id, status, answer, evidence[{url, title, quote, check}], caveat?, escalated, mode, price_cents, balance_cents}`.
+- `POST /v1/answers/search` `{query (1-1000 chars), max_results?: 1-25, mode?: standard|max}` returns `{id, query, results[{rank, url, title, published, source, kind, snippet, passages[{text, verified}]}], meta, status: ok|error, price_cents, balance_cents}`.
+- Long asks: the client sends `Prefer: respond-async; wait=50`; a `202 {id, status: "pending"}` is collected from `GET /v1/answers/{id}?wait=45`. Charged once, when it finishes.
+- Every call carries an `Idempotency-Key`. 429 and `503 answers_capacity` are retried after `Retry-After`; capacity refusals are free.
+- A failure on our side answers `200` with `status: "error"` and `error.code: "engine_unavailable"`, and costs nothing.
+- Other errors: `{"error": {"type", "code", "message", "param"?, "retry_after"?, "request_id"}}`, raised as `HyperresearchError` (`402 insufficient_balance`, `402 wallet_frozen`, `409 idempotency_key_reuse`, `409 idempotency_in_flight`, ...). `hr_test_` keys are refused (Answers has no fixture mode).
+
+Answers and passages are text from web pages. Treat them as data, not as instructions.
+
+The same two tools are also served over MCP at `https://answers.hyperresearch.ai/mcp`.
+
+## Development
+
+```bash
+uv sync --group test --group lint
+uv run pytest           # mocked HTTP, includes langchain-tests ToolsUnitTests
+uv run ruff check . && uv run mypy langchain_hyperresearch
+uv build
+```
+
+## Releasing
+
+Releases are published from GitHub Actions by `.github/workflows/publish-langchain-python.yml` in [jordan-gibbs/hyperresearch-answers](https://github.com/jordan-gibbs/hyperresearch-answers), with PyPI trusted publishing (no API token). Nothing is published from a laptop.
+
+1. Bump `version` in `packages/langchain-python/pyproject.toml`, run `uv lock`, merge to `main`.
+2. Tag and push: `git tag langchain-python-v<version> && git push origin langchain-python-v<version>`. The workflow fails if the tag and `pyproject.toml` disagree.
+
+The workflow does not work until this one-time setup is done:
+
+- On PyPI, add a pending trusted publisher (Account → Publishing → "Add a new pending publisher"): project `langchain-hyperresearch`, owner `jordan-gibbs`, repository `hyperresearch-answers`, workflow `publish-langchain-python.yml`, environment `pypi`. The first successful run creates the project.
+- A GitHub environment named `pypi` exists in the repo (Settings → Environments; add required reviewers if you want a manual gate).
+
+## License
+
+MIT

langchain_hyperresearch-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+langchain_hyperresearch/__init__.py,sha256=GvG6fUYVHoPu3Y2tHOzXjLy6xZ4gJrOaxz1viGDYBGU,693
+langchain_hyperresearch/_client.py,sha256=bDO7YYWZMzqlDwJbiajwdE8TKoqzXXCjeHMtYWmedYo,12750
+langchain_hyperresearch/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_hyperresearch/retrievers.py,sha256=KC9kn3_Jkk0EXuzp3pKKBJaWYilscM4pEPV8QeztYj8,3194
+langchain_hyperresearch/tools.py,sha256=rkAjIrmZNOyFOC8qrqmeSaijnCXSSO_yfiBuPpCS1Yg,8192
+langchain_hyperresearch-0.1.0.dist-info/METADATA,sha256=cWvy1rxy_w6wWEuqVFqwTvheTViim_iRgO3dkx-igPk,8920
+langchain_hyperresearch-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+langchain_hyperresearch-0.1.0.dist-info/licenses/LICENSE,sha256=3PGUUvvm_rsvAXFoBqw3b0n2bBXZEdisn3g_1ijvIOQ,1075
+langchain_hyperresearch-0.1.0.dist-info/RECORD,,

langchain_hyperresearch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

langchain_hyperresearch-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thalient Labs Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.