langchain-serpkite 0.1.0__tar.gz

langchain_serpkite-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+# Mirrored from the SerpKite monorepo (sdks/langchain-serpkite); edits here are overwritten.
+# --no-sources: serpkite comes from PyPI here (the monorepo uses its ../python checkout).
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --no-sources
+      - run: uv run --no-sources ruff check .
+      - run: uv run --no-sources ruff format --check .
+      - run: uv run --no-sources mypy
+      - run: uv run --no-sources pytest -q

langchain_serpkite-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+# Mirrored from the SerpKite monorepo (sdks/langchain-serpkite); edits here are overwritten.
+# The monorepo's sdk-mirror workflow pushes tag vX.Y.Z here; this publishes PyPI `langchain-serpkite`.
+# The serpkite version it requires must already be on PyPI.
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # PyPI trusted publisher: repo SerpKite/langchain-serpkite, workflow release.yml, environment pypi.
+    environment: pypi
+    permissions:
+      contents: write # GitHub release
+      id-token: write # PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: Tag matches pyproject
+        env:
+          TAG: ${{ github.ref_name }}
+        run: test "${TAG#v}" = "$(uv version --short)"
+      - run: uv sync --no-sources && uv run --no-sources pytest -q
+      - run: uv build --no-sources --out-dir dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - name: GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: gh release create "$TAG" --verify-tag --generate-notes --title "$TAG" dist/*

langchain_serpkite-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.benchmarks/
+build/
+dist/

langchain_serpkite-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

langchain_serpkite-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing
+
+This repository is a read-only mirror, published automatically from the SerpKite
+monorepo. Issues and pull requests are welcome here. Maintainers port accepted
+changes upstream, and the next sync brings them back.
+
+`openapi/serp-api.yaml` (where present) is the SerpKite v1 OpenAPI contract that the
+SDK's types are generated from and checked against. Don't edit it here.

langchain_serpkite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SerpKite
+
+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.

langchain_serpkite-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: langchain-serpkite
+Version: 0.1.0
+Summary: LangChain integration for SerpKite, the Google search API built for AI agents: tools, a retriever and a webpage loader.
+Project-URL: Homepage, https://serpkite.com/integrations/langchain
+Project-URL: Documentation, https://serpkite.com/docs/sdks/langchain
+Project-URL: Repository, https://github.com/serpkite/langchain-serpkite
+Author-email: SerpKite <support@serpkite.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,google,langchain,llm,retriever,search,serp,serpkite,tool
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: langchain-core<2,>=0.3
+Requires-Dist: serpkite>=0.1.0
+Description-Content-Type: text/markdown
+
+# langchain-serpkite
+
+LangChain integration for [SerpKite](https://serpkite.com), the Google search API built for AI
+agents. The package gives you:
+
+| Class | What it does |
+| --- | --- |
+| `SerpKiteSearch` | Tool (`serpkite_search`) that returns Markdown, which uses few tokens, for agents |
+| `SerpKiteSearchResults` | Tool (`serpkite_search_results_json`) that returns a list of result dicts (title, link, domain, snippet, …) |
+| `SerpKiteRetriever` | Retriever that returns Google results as `Document`s, optionally with full page Markdown |
+| `SerpKiteWebpageLoader` | Document loader that fetches any public URL as clean Markdown |
+| `SerpKiteAPIWrapper` | Holds the API key and the sync and async SerpKite clients |
+
+Every class supports both sync and async (`invoke`/`ainvoke`, `load`/`alazy_load`).
+
+## Install
+
+```bash
+pip install -U langchain-serpkite
+export SERPKITE_API_KEY=skt_live_...   # https://app.serpkite.com/keys
+```
+
+## Tools
+
+```python
+from langchain_serpkite import SerpKiteSearch, SerpKiteSearchResults
+
+search = SerpKiteSearch()  # optional: endpoint="news", country="de", num=20, api_key="..."
+print(search.invoke({"query": "best espresso machine"}))  # Markdown string
+
+papers = SerpKiteSearch(endpoint="scholar")  # or news, images, videos, maps, places,
+                                             # shopping, patents, autocomplete, ai-mode
+rows = SerpKiteSearchResults(max_results=5).invoke({"query": "langgraph checkpointer"})
+# [{"position": 1, "title": "...", "link": "https://...", "domain": "...", "snippet": "..."}, ...]
+```
+
+The model can set `query`, `num`, `country`, `language` and `time`
+(`hour|day|week|month|year`). Defaults set on the tool (`country=`, `language=`, `location=`,
+`num=`) apply when the model leaves a field out. `engine=` is set on the tool only (see
+[Search engines & fallback](#search-engines--fallback)).
+
+## Agent (LangChain / LangGraph)
+
+```python
+from langchain.agents import create_agent
+from langchain_serpkite import SerpKiteSearch, SerpKiteSearchResults
+
+agent = create_agent(
+    model="provider:model-name",  # any tool-calling chat model
+    tools=[SerpKiteSearch(), SerpKiteSearchResults(max_results=5)],
+    system_prompt="You are a research assistant. Search before answering and cite links.",
+)
+out = agent.invoke({"messages": [{"role": "user", "content": "What changed in the EU AI Act this month?"}]})
+print(out["messages"][-1].content)
+```
+
+`create_agent` runs on LangGraph. The tools work the same way with
+`langgraph.prebuilt.create_react_agent(model, tools=[...])`, and in a custom `StateGraph` through
+`ToolNode`.
+
+## Retriever
+
+```python
+from langchain_serpkite import SerpKiteRetriever
+
+retriever = SerpKiteRetriever(k=5, include_content=2, country="us", language="en")
+docs = retriever.invoke("how does HNSW indexing work")
+docs = retriever.invoke("how does HNSW indexing work", k=3)  # per-call override
+
+docs[0].page_content  # page Markdown for the top include_content results, else the snippet
+docs[0].metadata      # {"title", "link", "source", "position", "domain", "snippet", "engine", ...}
+```
+
+- `include_content` (0-5) fetches the top N result pages as Markdown for +1 credit each.
+- `k` above 10 uses a deep search, which costs 7 credits for 100 results.
+- `time` limits results to the last hour, day, week, month or year.
+
+A minimal RAG chain:
+
+```python
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.runnables import RunnablePassthrough
+
+prompt = ChatPromptTemplate.from_template("Answer from these sources:\n{context}\n\nQuestion: {question}")
+chain = {"context": retriever, "question": RunnablePassthrough()} | prompt | llm
+```
+
+## Webpage loader
+
+```python
+from langchain_serpkite import SerpKiteWebpageLoader
+
+loader = SerpKiteWebpageLoader(["https://example.com", "https://serpkite.com"], continue_on_failure=True)
+docs = loader.load()                               # sync
+docs = [d async for d in loader.alazy_load()]      # async
+docs[0].metadata  # {"source", "requested_url", "status_code", "title", "description", "language", ...}
+```
+
+Each page costs 1 credit. Pass `include_html=True` to also get the raw HTML in
+`metadata["html"]`.
+
+## Search engines & fallback
+
+By default every request is answered by Google only (`engine="google"`); SerpKite already fails
+over across its own proxy pools. Opt in to other providers with `engine` on a tool, the retriever
+or the shared wrapper (you set it, never the model):
+
+```python
+search = SerpKiteSearch(engine="auto")                          # fall back when Google is unavailable
+retriever = SerpKiteRetriever(k=5, engine=["google", "brave"])  # only these providers, in order
+docs = retriever.invoke("espresso", engine="auto")              # per-call override
+docs[0].metadata["engine"]                                      # "google", or e.g. "brave"
+```
+
+- `engine` is `"google"` (default), `"auto"`, `"consensus"`, one provider (`"brave"`, `"bing"`,
+  `"yahoo"`, `"duckduckgo"`, `"mojeek"`, `"wikipedia"`) or a list. `"auto"` and `"consensus"` can't be combined
+  with other names; unknown names, or a provider that doesn't serve the endpoint, raise
+  `serpkite.BadRequestError`.
+- The retriever puts the answering provider (`meta.engine`) into each Document's `metadata["engine"]`.
+  With `engine="consensus"` (several indexes merged and ranked by agreement; costs the sum of the
+  providers that answered) it is `"consensus"`, and `metadata["sources"]` lists the providers that
+  returned each result.
+- Credits follow the answering provider's price.
+
+## Configuration
+
+Every class takes `api_key=` and `base_url=`, or a shared wrapper:
+
+```python
+from langchain_serpkite import SerpKiteAPIWrapper, SerpKiteRetriever, SerpKiteSearch
+
+wrapper = SerpKiteAPIWrapper(api_key="skt_live_...", country="de", language="de", max_retries=3)
+tool = SerpKiteSearch(api_wrapper=wrapper)
+retriever = SerpKiteRetriever(api_wrapper=wrapper, k=5)
+```
+
+API errors raise `serpkite.SerpKiteError` subclasses. Each one has `status`, `code`, `message` and
+`request_id`. See the [`serpkite`](https://pypi.org/project/serpkite/) SDK. Failed, empty and
+blocked searches are not billed.
+
+## Development
+
+```bash
+uv sync                      # installs ../python (serpkite) in editable mode
+uv run pytest                # unit tests: mocked HTTP, sockets disabled, LangChain standard tests
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+SERPKITE_API_KEY=skt_live_... uv run pytest tests/integration_tests   # live
+```
+
+## License
+
+MIT

langchain_serpkite-0.1.0/README.md

@@ -0,0 +1,153 @@
+# langchain-serpkite
+
+LangChain integration for [SerpKite](https://serpkite.com), the Google search API built for AI
+agents. The package gives you:
+
+| Class | What it does |
+| --- | --- |
+| `SerpKiteSearch` | Tool (`serpkite_search`) that returns Markdown, which uses few tokens, for agents |
+| `SerpKiteSearchResults` | Tool (`serpkite_search_results_json`) that returns a list of result dicts (title, link, domain, snippet, …) |
+| `SerpKiteRetriever` | Retriever that returns Google results as `Document`s, optionally with full page Markdown |
+| `SerpKiteWebpageLoader` | Document loader that fetches any public URL as clean Markdown |
+| `SerpKiteAPIWrapper` | Holds the API key and the sync and async SerpKite clients |
+
+Every class supports both sync and async (`invoke`/`ainvoke`, `load`/`alazy_load`).
+
+## Install
+
+```bash
+pip install -U langchain-serpkite
+export SERPKITE_API_KEY=skt_live_...   # https://app.serpkite.com/keys
+```
+
+## Tools
+
+```python
+from langchain_serpkite import SerpKiteSearch, SerpKiteSearchResults
+
+search = SerpKiteSearch()  # optional: endpoint="news", country="de", num=20, api_key="..."
+print(search.invoke({"query": "best espresso machine"}))  # Markdown string
+
+papers = SerpKiteSearch(endpoint="scholar")  # or news, images, videos, maps, places,
+                                             # shopping, patents, autocomplete, ai-mode
+rows = SerpKiteSearchResults(max_results=5).invoke({"query": "langgraph checkpointer"})
+# [{"position": 1, "title": "...", "link": "https://...", "domain": "...", "snippet": "..."}, ...]
+```
+
+The model can set `query`, `num`, `country`, `language` and `time`
+(`hour|day|week|month|year`). Defaults set on the tool (`country=`, `language=`, `location=`,
+`num=`) apply when the model leaves a field out. `engine=` is set on the tool only (see
+[Search engines & fallback](#search-engines--fallback)).
+
+## Agent (LangChain / LangGraph)
+
+```python
+from langchain.agents import create_agent
+from langchain_serpkite import SerpKiteSearch, SerpKiteSearchResults
+
+agent = create_agent(
+    model="provider:model-name",  # any tool-calling chat model
+    tools=[SerpKiteSearch(), SerpKiteSearchResults(max_results=5)],
+    system_prompt="You are a research assistant. Search before answering and cite links.",
+)
+out = agent.invoke({"messages": [{"role": "user", "content": "What changed in the EU AI Act this month?"}]})
+print(out["messages"][-1].content)
+```
+
+`create_agent` runs on LangGraph. The tools work the same way with
+`langgraph.prebuilt.create_react_agent(model, tools=[...])`, and in a custom `StateGraph` through
+`ToolNode`.
+
+## Retriever
+
+```python
+from langchain_serpkite import SerpKiteRetriever
+
+retriever = SerpKiteRetriever(k=5, include_content=2, country="us", language="en")
+docs = retriever.invoke("how does HNSW indexing work")
+docs = retriever.invoke("how does HNSW indexing work", k=3)  # per-call override
+
+docs[0].page_content  # page Markdown for the top include_content results, else the snippet
+docs[0].metadata      # {"title", "link", "source", "position", "domain", "snippet", "engine", ...}
+```
+
+- `include_content` (0-5) fetches the top N result pages as Markdown for +1 credit each.
+- `k` above 10 uses a deep search, which costs 7 credits for 100 results.
+- `time` limits results to the last hour, day, week, month or year.
+
+A minimal RAG chain:
+
+```python
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.runnables import RunnablePassthrough
+
+prompt = ChatPromptTemplate.from_template("Answer from these sources:\n{context}\n\nQuestion: {question}")
+chain = {"context": retriever, "question": RunnablePassthrough()} | prompt | llm
+```
+
+## Webpage loader
+
+```python
+from langchain_serpkite import SerpKiteWebpageLoader
+
+loader = SerpKiteWebpageLoader(["https://example.com", "https://serpkite.com"], continue_on_failure=True)
+docs = loader.load()                               # sync
+docs = [d async for d in loader.alazy_load()]      # async
+docs[0].metadata  # {"source", "requested_url", "status_code", "title", "description", "language", ...}
+```
+
+Each page costs 1 credit. Pass `include_html=True` to also get the raw HTML in
+`metadata["html"]`.
+
+## Search engines & fallback
+
+By default every request is answered by Google only (`engine="google"`); SerpKite already fails
+over across its own proxy pools. Opt in to other providers with `engine` on a tool, the retriever
+or the shared wrapper (you set it, never the model):
+
+```python
+search = SerpKiteSearch(engine="auto")                          # fall back when Google is unavailable
+retriever = SerpKiteRetriever(k=5, engine=["google", "brave"])  # only these providers, in order
+docs = retriever.invoke("espresso", engine="auto")              # per-call override
+docs[0].metadata["engine"]                                      # "google", or e.g. "brave"
+```
+
+- `engine` is `"google"` (default), `"auto"`, `"consensus"`, one provider (`"brave"`, `"bing"`,
+  `"yahoo"`, `"duckduckgo"`, `"mojeek"`, `"wikipedia"`) or a list. `"auto"` and `"consensus"` can't be combined
+  with other names; unknown names, or a provider that doesn't serve the endpoint, raise
+  `serpkite.BadRequestError`.
+- The retriever puts the answering provider (`meta.engine`) into each Document's `metadata["engine"]`.
+  With `engine="consensus"` (several indexes merged and ranked by agreement; costs the sum of the
+  providers that answered) it is `"consensus"`, and `metadata["sources"]` lists the providers that
+  returned each result.
+- Credits follow the answering provider's price.
+
+## Configuration
+
+Every class takes `api_key=` and `base_url=`, or a shared wrapper:
+
+```python
+from langchain_serpkite import SerpKiteAPIWrapper, SerpKiteRetriever, SerpKiteSearch
+
+wrapper = SerpKiteAPIWrapper(api_key="skt_live_...", country="de", language="de", max_retries=3)
+tool = SerpKiteSearch(api_wrapper=wrapper)
+retriever = SerpKiteRetriever(api_wrapper=wrapper, k=5)
+```
+
+API errors raise `serpkite.SerpKiteError` subclasses. Each one has `status`, `code`, `message` and
+`request_id`. See the [`serpkite`](https://pypi.org/project/serpkite/) SDK. Failed, empty and
+blocked searches are not billed.
+
+## Development
+
+```bash
+uv sync                      # installs ../python (serpkite) in editable mode
+uv run pytest                # unit tests: mocked HTTP, sockets disabled, LangChain standard tests
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+SERPKITE_API_KEY=skt_live_... uv run pytest tests/integration_tests   # live
+```
+
+## License
+
+MIT

langchain_serpkite-0.1.0/langchain_serpkite/__init__.py

@@ -0,0 +1,24 @@
+"""LangChain integration for SerpKite, the Google search API built for AI agents."""
+
+from importlib import metadata
+
+from langchain_serpkite._utilities import SerpKiteAPIWrapper
+from langchain_serpkite.document_loaders import SerpKiteWebpageLoader
+from langchain_serpkite.retrievers import SerpKiteRetriever
+from langchain_serpkite.tools import SerpKiteSearch, SerpKiteSearchInput, SerpKiteSearchResults
+
+try:
+    __version__ = metadata.version(__package__ or __name__)
+except metadata.PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.1.0"
+del metadata
+
+__all__ = [
+    "SerpKiteAPIWrapper",
+    "SerpKiteRetriever",
+    "SerpKiteSearch",
+    "SerpKiteSearchInput",
+    "SerpKiteSearchResults",
+    "SerpKiteWebpageLoader",
+    "__version__",
+]

langchain_serpkite-0.1.0/langchain_serpkite/_utilities.py

@@ -0,0 +1,152 @@
+"""SerpKiteAPIWrapper: holds the SerpKite clients shared by the tools, retriever and loader."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Union
+
+from langchain_core.utils import secret_from_env
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, SecretStr
+from serpkite import AsyncSerpKite, SerpKite
+from serpkite.types import SearchResponse, WebpageResponse
+
+__all__ = ["SerpKiteAPIWrapper"]
+
+VERTICALS = frozenset(
+    {
+        "search",
+        "news",
+        "images",
+        "videos",
+        "maps",
+        "places",
+        "shopping",
+        "scholar",
+        "patents",
+        "autocomplete",
+        "ai-mode",
+    }
+)
+
+
+def normalize_endpoint(endpoint: str) -> str:
+    ep = endpoint.strip().lower().replace("_", "-")
+    if ep not in VERTICALS:
+        raise ValueError(f"unknown SerpKite endpoint {endpoint!r}; use one of {', '.join(sorted(VERTICALS))}")
+    return ep
+
+
+class SerpKiteAPIWrapper(BaseModel):
+    """Thin wrapper around the ``serpkite`` SDK clients.
+
+    The API key comes from ``api_key`` or the ``SERPKITE_API_KEY`` environment variable.
+
+    Example:
+        .. code-block:: python
+
+            from langchain_serpkite import SerpKiteAPIWrapper
+
+            wrapper = SerpKiteAPIWrapper(country="de")
+            print(wrapper.markdown("beste espressomaschine"))
+    """
+
+    api_key: SecretStr = Field(
+        default_factory=secret_from_env(
+            "SERPKITE_API_KEY",
+            error_message=(
+                "No SerpKite API key. Pass api_key=... or set the SERPKITE_API_KEY environment variable "
+                "(create a key at https://app.serpkite.com/keys)."
+            ),
+        )
+    )
+    """SerpKite API key (``skt_live_…``). Defaults to ``SERPKITE_API_KEY``."""
+    base_url: Optional[str] = None
+    """API origin; defaults to ``SERPKITE_BASE_URL`` or https://api.serpkite.com."""
+    timeout: float = 60.0
+    max_retries: int = 2
+    country: Optional[str] = None
+    """Default country code (e.g. ``us``) when a call doesn't pass one."""
+    language: Optional[str] = None
+    """Default interface language (e.g. ``en``)."""
+    location: Optional[str] = None
+    """Default free-text location, e.g. ``"Austin, Texas, United States"``."""
+    engine: Optional[Union[str, list[str]]] = None
+    """Default search providers allowed to answer: ``"google"`` (the API default, Google only),
+    ``"auto"`` (fall back to other providers when Google is blocked or times out), one provider
+    (``"brave"``) or a list (``["google", "brave"]``). ``meta.engine`` names the one that answered."""
+
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    _client: Optional[SerpKite] = PrivateAttr(default=None)
+    _async_client: Optional[AsyncSerpKite] = PrivateAttr(default=None)
+
+    @property
+    def client(self) -> SerpKite:
+        """The sync SDK client (created on first use)."""
+        if self._client is None:
+            self._client = SerpKite(
+                api_key=self.api_key.get_secret_value(),
+                base_url=self.base_url,
+                timeout=self.timeout,
+                max_retries=self.max_retries,
+            )
+        return self._client
+
+    @property
+    def async_client(self) -> AsyncSerpKite:
+        """The async SDK client (created on first use)."""
+        if self._async_client is None:
+            self._async_client = AsyncSerpKite(
+                api_key=self.api_key.get_secret_value(),
+                base_url=self.base_url,
+                timeout=self.timeout,
+                max_retries=self.max_retries,
+            )
+        return self._async_client
+
+    def _body(self, query: str, params: dict[str, Any]) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "q": query,
+            "country": self.country,
+            "language": self.language,
+            "location": self.location,
+            "engine": self.engine,
+        }
+        body.update({k: v for k, v in params.items() if v is not None})
+        return body
+
+    # Sync -----------------------------------------------------------------
+
+    def markdown(self, query: str, endpoint: str = "search", **params: Any) -> str:
+        """Run ``query`` against ``endpoint`` and return the Markdown rendering."""
+        body = {**self._body(query, params), "format": "markdown"}
+        return str(self.client.request(normalize_endpoint(endpoint), body))
+
+    def raw(self, query: str, endpoint: str = "search", **params: Any) -> dict[str, Any]:
+        """Run ``query`` against ``endpoint`` and return the JSON body as a dict."""
+        result: dict[str, Any] = self.client.request(normalize_endpoint(endpoint), self._body(query, params))
+        return result
+
+    def search(self, query: str, **params: Any) -> SearchResponse:
+        """Typed ``/v1/search`` call."""
+        return SearchResponse.model_validate(self.raw(query, "search", **params))
+
+    def webpage(self, url: str, include_html: bool = False) -> WebpageResponse:
+        """Typed ``/v1/webpage`` call."""
+        return self.client.webpage(url, include_html=include_html)
+
+    # Async ----------------------------------------------------------------
+
+    async def amarkdown(self, query: str, endpoint: str = "search", **params: Any) -> str:
+        body = {**self._body(query, params), "format": "markdown"}
+        return str(await self.async_client.request(normalize_endpoint(endpoint), body))
+
+    async def araw(self, query: str, endpoint: str = "search", **params: Any) -> dict[str, Any]:
+        body = self._body(query, params)
+        result: dict[str, Any] = await self.async_client.request(normalize_endpoint(endpoint), body)
+        return result
+
+    async def asearch(self, query: str, **params: Any) -> SearchResponse:
+        return SearchResponse.model_validate(await self.araw(query, "search", **params))
+
+    async def awebpage(self, url: str, include_html: bool = False) -> WebpageResponse:
+        return await self.async_client.webpage(url, include_html=include_html)