langchain-contextfetch 0.1.0__tar.gz

langchain_contextfetch-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.venv/
+dist/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.benchmarks/

langchain_contextfetch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2026 ContextFetch
+
+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_contextfetch-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: langchain-contextfetch
+Version: 0.1.0
+Summary: An integration package connecting ContextFetch and LangChain
+Project-URL: Homepage, https://contextfetch.dev
+Project-URL: Documentation, https://contextfetch.dev/docs/reference
+Project-URL: Source Code, https://github.com/lachy3433/contextfetch/tree/main/integrations/langchain
+Project-URL: Repository, https://github.com/lachy3433/contextfetch
+Author: ContextFetch
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0.0,>=3.10.0
+Requires-Dist: contextfetch<1.0.0,>=0.1.0
+Requires-Dist: langchain-core<2.0.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+# langchain-contextfetch
+
+This package contains the LangChain integration with [ContextFetch](https://contextfetch.dev), a web search API that returns pages as Markdown.
+
+- `ContextFetchRetriever`: a retriever that returns search results as `Document`s.
+- `ContextFetchSearch`: a search tool for agents and tool-calling models.
+
+## Installation
+
+```bash
+pip install -U langchain-contextfetch
+```
+
+Requires Python 3.10 or later.
+
+## Credentials
+
+Set your API key in the `CONTEXTFETCH_API_KEY` environment variable, or pass `api_key=` to either class:
+
+```bash
+export CONTEXTFETCH_API_KEY="your-api-key"
+```
+
+Without a key, requests use ContextFetch's keyless tier, which has a small daily allowance per IP address. See the [API reference](https://contextfetch.dev/docs/reference) for keys and credits.
+
+## Retriever
+
+```python
+from langchain_contextfetch import ContextFetchRetriever
+
+retriever = ContextFetchRetriever(k=3)
+docs = retriever.invoke("pgvector HNSW index parameters")
+
+for doc in docs:
+    print(doc.metadata["url"], doc.metadata["title"])
+```
+
+Each `Document` has:
+
+- `page_content`: the page as Markdown (`content="text"`, the default), or only the chunks of the page relevant to the query (`content="pruned_context"`).
+- `metadata`: `id`, `url`, `title`, `score`, `published_date` and `author`. Fields the API does not return are `None`.
+
+Options:
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `k` | `5` | Number of results (1 to 25). Can also be passed per call: `retriever.invoke(query, k=10)`. |
+| `content` | `"text"` | `"text"` or `"pruned_context"`. |
+| `include_domains` | `None` | Only return results from these domains. |
+| `exclude_domains` | `None` | Never return results from these domains. |
+| `start_published_date` | `None` | Only return pages published on or after this date (`YYYY-MM-DD`). |
+| `api_key` | `CONTEXTFETCH_API_KEY` | API key. |
+
+## Search tool
+
+```python
+from langchain_contextfetch import ContextFetchSearch
+
+tool = ContextFetchSearch(num_results=3)
+tool.invoke({"query": "pgvector HNSW index parameters"})
+```
+
+The model can set `query`, `include_domains`, `exclude_domains` and `start_published_date`. `num_results` (default 5, maximum 25), `content` and `api_key` are set when the tool is created. The tool's default `content` is `"pruned_context"`, so each result contributes only its query-relevant chunks to the model's context; use `content="text"` for whole pages.
+
+The tool uses `response_format="content_and_artifact"`. Called with plain args as above, it returns the content string: each result's title, URL, published date and content. Called with a `ToolCall`, it returns a `ToolMessage` with that `content` and the raw API response as its `artifact`.
+
+```python
+msg = tool.invoke(
+    {
+        "args": {"query": "pgvector HNSW index parameters"},
+        "id": "1",
+        "name": tool.name,
+        "type": "tool_call",
+    }
+)
+msg.artifact["results"][0]["url"]
+```
+
+API errors (for example HTTP 402 when credits run out) are raised as `ToolException`. To pass the error message to the model instead, create the tool with `handle_tool_error=True`.
+
+### Use in an agent
+
+```python
+from langchain.agents import create_agent
+
+agent = create_agent(model="claude-sonnet-4-6", tools=[tool])
+agent.invoke({"messages": [{"role": "user", "content": "What changed in Python 3.14?"}]})
+```
+
+## Async
+
+Both classes support `ainvoke`. The underlying `contextfetch` SDK is synchronous, so async calls run in a thread executor (LangChain's default for tools and retrievers).
+
+## Development
+
+```bash
+make test               # unit tests, network disabled
+make integration_test   # live API tests; skipped unless CONTEXTFETCH_API_KEY is set
+make lint
+```
+
+The unit tests include LangChain's standard `ToolsUnitTests`. The integration tests run the standard `ToolsIntegrationTests` and `RetrieversIntegrationTests` suites, which make 10 searches in total.

langchain_contextfetch-0.1.0/README.md

@@ -0,0 +1,102 @@
+# langchain-contextfetch
+
+This package contains the LangChain integration with [ContextFetch](https://contextfetch.dev), a web search API that returns pages as Markdown.
+
+- `ContextFetchRetriever`: a retriever that returns search results as `Document`s.
+- `ContextFetchSearch`: a search tool for agents and tool-calling models.
+
+## Installation
+
+```bash
+pip install -U langchain-contextfetch
+```
+
+Requires Python 3.10 or later.
+
+## Credentials
+
+Set your API key in the `CONTEXTFETCH_API_KEY` environment variable, or pass `api_key=` to either class:
+
+```bash
+export CONTEXTFETCH_API_KEY="your-api-key"
+```
+
+Without a key, requests use ContextFetch's keyless tier, which has a small daily allowance per IP address. See the [API reference](https://contextfetch.dev/docs/reference) for keys and credits.
+
+## Retriever
+
+```python
+from langchain_contextfetch import ContextFetchRetriever
+
+retriever = ContextFetchRetriever(k=3)
+docs = retriever.invoke("pgvector HNSW index parameters")
+
+for doc in docs:
+    print(doc.metadata["url"], doc.metadata["title"])
+```
+
+Each `Document` has:
+
+- `page_content`: the page as Markdown (`content="text"`, the default), or only the chunks of the page relevant to the query (`content="pruned_context"`).
+- `metadata`: `id`, `url`, `title`, `score`, `published_date` and `author`. Fields the API does not return are `None`.
+
+Options:
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `k` | `5` | Number of results (1 to 25). Can also be passed per call: `retriever.invoke(query, k=10)`. |
+| `content` | `"text"` | `"text"` or `"pruned_context"`. |
+| `include_domains` | `None` | Only return results from these domains. |
+| `exclude_domains` | `None` | Never return results from these domains. |
+| `start_published_date` | `None` | Only return pages published on or after this date (`YYYY-MM-DD`). |
+| `api_key` | `CONTEXTFETCH_API_KEY` | API key. |
+
+## Search tool
+
+```python
+from langchain_contextfetch import ContextFetchSearch
+
+tool = ContextFetchSearch(num_results=3)
+tool.invoke({"query": "pgvector HNSW index parameters"})
+```
+
+The model can set `query`, `include_domains`, `exclude_domains` and `start_published_date`. `num_results` (default 5, maximum 25), `content` and `api_key` are set when the tool is created. The tool's default `content` is `"pruned_context"`, so each result contributes only its query-relevant chunks to the model's context; use `content="text"` for whole pages.
+
+The tool uses `response_format="content_and_artifact"`. Called with plain args as above, it returns the content string: each result's title, URL, published date and content. Called with a `ToolCall`, it returns a `ToolMessage` with that `content` and the raw API response as its `artifact`.
+
+```python
+msg = tool.invoke(
+    {
+        "args": {"query": "pgvector HNSW index parameters"},
+        "id": "1",
+        "name": tool.name,
+        "type": "tool_call",
+    }
+)
+msg.artifact["results"][0]["url"]
+```
+
+API errors (for example HTTP 402 when credits run out) are raised as `ToolException`. To pass the error message to the model instead, create the tool with `handle_tool_error=True`.
+
+### Use in an agent
+
+```python
+from langchain.agents import create_agent
+
+agent = create_agent(model="claude-sonnet-4-6", tools=[tool])
+agent.invoke({"messages": [{"role": "user", "content": "What changed in Python 3.14?"}]})
+```
+
+## Async
+
+Both classes support `ainvoke`. The underlying `contextfetch` SDK is synchronous, so async calls run in a thread executor (LangChain's default for tools and retrievers).
+
+## Development
+
+```bash
+make test               # unit tests, network disabled
+make integration_test   # live API tests; skipped unless CONTEXTFETCH_API_KEY is set
+make lint
+```
+
+The unit tests include LangChain's standard `ToolsUnitTests`. The integration tests run the standard `ToolsIntegrationTests` and `RetrieversIntegrationTests` suites, which make 10 searches in total.

langchain_contextfetch-0.1.0/langchain_contextfetch/__init__.py

@@ -0,0 +1,19 @@
+"""LangChain integration for ContextFetch."""
+
+from importlib import metadata
+
+from langchain_contextfetch.retrievers import ContextFetchRetriever
+from langchain_contextfetch.tools import ContextFetchSearch
+
+try:
+    __version__ = metadata.version(__package__ or "langchain_contextfetch")
+except metadata.PackageNotFoundError:
+    # Case where package metadata is not available.
+    __version__ = ""
+del metadata  # optional, avoids polluting the results of dir(__package__)
+
+__all__ = [
+    "ContextFetchRetriever",
+    "ContextFetchSearch",
+    "__version__",
+]

langchain_contextfetch-0.1.0/langchain_contextfetch/_utilities.py

@@ -0,0 +1,55 @@
+"""Helpers shared by the retriever and the tool."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from contextfetch import ContextFetch, Result, SearchResponse
+from pydantic import SecretStr
+
+Content = Literal["text", "pruned_context"]
+"""Which result content to use: the whole page as Markdown, or only the chunks
+relevant to the query."""
+
+_RESULT_KEY = {"text": "text", "pruned_context": "prunedContext"}
+
+
+def search(
+    api_key: SecretStr | None,
+    query: str,
+    *,
+    num_results: int,
+    content: Content,
+    include_domains: list[str] | None = None,
+    exclude_domains: list[str] | None = None,
+    start_published_date: str | None = None,
+) -> SearchResponse:
+    """Run one search, asking the API only for the content that will be used."""
+    # ContextFetch() falls back to CONTEXTFETCH_API_KEY, then to the keyless tier.
+    client = ContextFetch(api_key.get_secret_value() if api_key else None)
+    return client.search(
+        query,
+        num_results=num_results,
+        include_domains=include_domains,
+        exclude_domains=exclude_domains,
+        start_published_date=start_published_date,
+        text=content == "text",
+        pruned_context=content == "pruned_context",
+    )
+
+
+def page_content(result: Result, content: Content) -> str:
+    """The text of a result for the chosen content type."""
+    return result.get(_RESULT_KEY[content]) or ""  # type: ignore[return-value]
+
+
+def metadata(result: Result) -> dict[str, Any]:
+    """Result fields other than the page content."""
+    return {
+        "id": result.get("id"),
+        "url": result.get("url"),
+        "title": result.get("title"),
+        "score": result.get("score"),
+        "published_date": result.get("publishedDate"),
+        "author": result.get("author"),
+    }

langchain_contextfetch-0.1.0/langchain_contextfetch/retrievers.py

@@ -0,0 +1,122 @@
+"""ContextFetch retrievers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from langchain_core.utils import secret_from_env
+from pydantic import Field, SecretStr
+
+from langchain_contextfetch._utilities import Content, metadata, page_content, search
+
+
+class ContextFetchRetriever(BaseRetriever):
+    """ContextFetch web search retriever.
+
+    Setup:
+        Install `langchain-contextfetch` and set the environment variable
+        `CONTEXTFETCH_API_KEY`. Without a key, requests use the keyless tier.
+
+        ```bash
+        pip install -U langchain-contextfetch
+        export CONTEXTFETCH_API_KEY="your-api-key"
+        ```
+
+    Key init args:
+        k: int
+            Number of results to return (1 to 25). Default 5.
+        content: "text" | "pruned_context"
+            `"text"` uses the whole page as Markdown; `"pruned_context"` uses only
+            the chunks of the page relevant to the query. Default `"text"`.
+        include_domains: list[str] | None
+            Only return results from these domains.
+        exclude_domains: list[str] | None
+            Never return results from these domains.
+        start_published_date: str | None
+            Only return pages published on or after this ISO date.
+        api_key: SecretStr | None
+            ContextFetch API key. Defaults to `CONTEXTFETCH_API_KEY`.
+
+    Instantiate:
+        ```python
+        from langchain_contextfetch import ContextFetchRetriever
+
+        retriever = ContextFetchRetriever(k=3)
+        ```
+
+    Usage:
+        ```python
+        docs = retriever.invoke("pgvector HNSW index parameters")
+        docs[0].metadata["url"]
+        ```
+
+    Use within a chain:
+        ```python
+        from langchain_core.output_parsers import StrOutputParser
+        from langchain_core.prompts import ChatPromptTemplate
+        from langchain_core.runnables import RunnablePassthrough
+        from langchain_anthropic import ChatAnthropic
+
+        prompt = ChatPromptTemplate.from_template(
+            \"\"\"Answer the question based only on the context provided.
+
+        Context: {context}
+
+        Question: {question}\"\"\"
+        )
+
+        model = ChatAnthropic(model="claude-sonnet-4-6")
+
+
+        def format_docs(docs):
+            return "\\n\\n".join(doc.page_content for doc in docs)
+
+
+        chain = (
+            {"context": retriever | format_docs, "question": RunnablePassthrough()}
+            | prompt
+            | model
+            | StrOutputParser()
+        )
+
+        chain.invoke("How do I tune HNSW in pgvector?")
+        ```
+    """
+
+    k: int = Field(default=5, ge=1, le=25)
+    """Number of results to return (1 to 25)."""
+    content: Content = "text"
+    """`"text"` (whole page as Markdown, the default) or `"pruned_context"`
+    (query-relevant chunks of each page)."""
+    include_domains: list[str] | None = None
+    """Only return results from these domains."""
+    exclude_domains: list[str] | None = None
+    """Never return results from these domains."""
+    start_published_date: str | None = None
+    """Only return pages published on or after this ISO date (YYYY-MM-DD)."""
+    api_key: SecretStr | None = Field(
+        default_factory=secret_from_env("CONTEXTFETCH_API_KEY", default=None)
+    )
+    """ContextFetch API key. Defaults to the `CONTEXTFETCH_API_KEY` env var."""
+
+    # Async: BaseRetriever runs this method in a thread executor, since the
+    # contextfetch SDK is synchronous (stdlib urllib).
+    def _get_relevant_documents(
+        self, query: str, *, run_manager: CallbackManagerForRetrieverRun, **kwargs: Any
+    ) -> list[Document]:
+        response = search(
+            self.api_key,
+            query,
+            num_results=kwargs.get("k", self.k),
+            content=self.content,
+            include_domains=self.include_domains,
+            exclude_domains=self.exclude_domains,
+            start_published_date=self.start_published_date,
+        )
+        return [
+            Document(page_content=page_content(r, self.content), metadata=metadata(r))
+            for r in response.get("results", [])
+        ]

langchain_contextfetch-0.1.0/langchain_contextfetch/tools.py

@@ -0,0 +1,131 @@
+"""ContextFetch tools."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from contextfetch import ContextFetchError, SearchResponse
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool, ToolException
+from langchain_core.utils import secret_from_env
+from pydantic import BaseModel, Field, SecretStr
+
+from langchain_contextfetch._utilities import Content, page_content, search
+
+
+class ContextFetchSearchInput(BaseModel):
+    """Input schema for the ContextFetch search tool.
+
+    The Field descriptions are sent to the model when performing tool calling.
+    """
+
+    query: str = Field(description="The web search query.")
+    include_domains: list[str] | None = Field(
+        default=None, description="Only return results from these domains."
+    )
+    exclude_domains: list[str] | None = Field(
+        default=None, description="Never return results from these domains."
+    )
+    start_published_date: str | None = Field(
+        default=None,
+        description="Only return pages published on or after this date (YYYY-MM-DD).",
+    )
+
+
+class ContextFetchSearch(BaseTool):  # type: ignore[override]
+    """ContextFetch web search tool.
+
+    Setup:
+        Install `langchain-contextfetch` and set the environment variable
+        `CONTEXTFETCH_API_KEY`. Without a key, requests use the keyless tier.
+
+        ```bash
+        pip install -U langchain-contextfetch
+        export CONTEXTFETCH_API_KEY="your-api-key"
+        ```
+
+    Instantiation:
+        ```python
+        from langchain_contextfetch import ContextFetchSearch
+
+        tool = ContextFetchSearch(num_results=3)
+        ```
+
+    Invocation with args:
+        ```python
+        tool.invoke({"query": "pgvector HNSW index parameters"})
+        ```
+
+    Invocation with ToolCall:
+        ```python
+        tool.invoke(
+            {
+                "args": {"query": "pgvector HNSW index parameters"},
+                "id": "1",
+                "name": tool.name,
+                "type": "tool_call",
+            }
+        )
+        ```
+
+        Returns a `ToolMessage` whose `content` lists each result's title, URL,
+        published date and page content, and whose `artifact` is the raw API
+        response (a dict with `results`).
+    """
+
+    name: str = "contextfetch_search"
+    """The name that is passed to the model when performing tool calling."""
+    description: str = (
+        "Search the web. Returns the top results, each with its title, URL, "
+        "published date and page content as Markdown."
+    )
+    """The description that is passed to the model when performing tool calling."""
+    args_schema: type[BaseModel] = ContextFetchSearchInput
+    """The schema that is passed to the model when performing tool calling."""
+    response_format: Literal["content", "content_and_artifact"] = "content_and_artifact"
+
+    num_results: int = Field(default=5, ge=1, le=25)
+    """Number of results per search (1 to 25)."""
+    content: Content = "pruned_context"
+    """`"pruned_context"` (query-relevant chunks of each page, the default) or
+    `"text"` (whole page as Markdown)."""
+    api_key: SecretStr | None = Field(
+        default_factory=secret_from_env("CONTEXTFETCH_API_KEY", default=None)
+    )
+    """ContextFetch API key. Defaults to the `CONTEXTFETCH_API_KEY` env var."""
+
+    # Async: BaseTool runs this method in a thread executor, since the
+    # contextfetch SDK is synchronous (stdlib urllib).
+    def _run(
+        self,
+        query: str,
+        include_domains: list[str] | None = None,
+        exclude_domains: list[str] | None = None,
+        start_published_date: str | None = None,
+        *,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> tuple[str, SearchResponse]:
+        try:
+            response = search(
+                self.api_key,
+                query,
+                num_results=self.num_results,
+                content=self.content,
+                include_domains=include_domains,
+                exclude_domains=exclude_domains,
+                start_published_date=start_published_date,
+            )
+        except ContextFetchError as e:
+            # Raised as ToolException so handle_tool_error can pass it to the model.
+            raise ToolException(str(e)) from e
+        results = response.get("results", [])
+        if not results:
+            return "No results found.", response
+        content = "\n\n---\n\n".join(
+            f"Title: {r.get('title') or ''}\n"
+            f"URL: {r.get('url', '')}\n"
+            f"Published: {r.get('publishedDate') or 'unknown'}\n\n"
+            f"{page_content(r, self.content)}"
+            for r in results
+        )
+        return content, response

langchain_contextfetch-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-contextfetch"
+version = "0.1.0"
+description = "An integration package connecting ContextFetch and LangChain"
+authors = [{ name = "ContextFetch" }]
+license = "MIT"
+readme = "README.md"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10.0,<4.0.0"
+dependencies = [
+    "langchain-core>=1.0.0,<2.0.0",
+    "contextfetch>=0.1.0,<1.0.0",
+]
+
+[project.urls]
+Homepage = "https://contextfetch.dev"
+Documentation = "https://contextfetch.dev/docs/reference"
+"Source Code" = "https://github.com/lachy3433/contextfetch/tree/main/integrations/langchain"
+Repository = "https://github.com/lachy3433/contextfetch"
+
+[dependency-groups]
+test = [
+    "pytest>=9.0.3,<10.0.0",
+    "pytest-asyncio>=1.3.0,<2.0.0",
+    "pytest-socket>=0.7.0,<1.0.0",
+    "langchain-tests==1.1.9",
+]
+test_integration = []
+lint = ["ruff>=0.13.1,<0.14.0"]
+typing = ["mypy>=1.10,<3.0"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["langchain_contextfetch", "tests", "README.md", "LICENSE"]
+
+[tool.mypy]
+disallow_untyped_defs = true
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "T201"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.coverage.run]
+omit = ["tests/*"]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --strict-config --durations=5"
+markers = [
+    "compile: mark placeholder test used to compile integration tests without running them",
+]
+asyncio_mode = "auto"

langchain_contextfetch-0.1.0/tests/integration_tests/test_compile.py

@@ -0,0 +1,7 @@
+import pytest
+
+
+@pytest.mark.compile
+def test_placeholder() -> None:
+    """Used for compiling integration tests without running any real tests."""
+    pass

langchain_contextfetch-0.1.0/tests/integration_tests/test_retrievers.py

@@ -0,0 +1,25 @@
+import os
+
+import pytest
+from langchain_tests.integration_tests import RetrieversIntegrationTests
+
+from langchain_contextfetch import ContextFetchRetriever
+
+# These call the live API (1 credit per search; this suite makes 6 searches).
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("CONTEXTFETCH_API_KEY"), reason="CONTEXTFETCH_API_KEY not set"
+)
+
+
+class TestContextFetchRetriever(RetrieversIntegrationTests):
+    @property
+    def retriever_constructor(self) -> type[ContextFetchRetriever]:
+        return ContextFetchRetriever
+
+    @property
+    def retriever_constructor_params(self) -> dict:
+        return {"k": 2}
+
+    @property
+    def retriever_query_example(self) -> str:
+        return "python asyncio tutorial"

langchain_contextfetch-0.1.0/tests/integration_tests/test_tools.py

@@ -0,0 +1,25 @@
+import os
+
+import pytest
+from langchain_tests.integration_tests import ToolsIntegrationTests
+
+from langchain_contextfetch import ContextFetchSearch
+
+# These call the live API (1 credit per search; this suite makes 4 searches).
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("CONTEXTFETCH_API_KEY"), reason="CONTEXTFETCH_API_KEY not set"
+)
+
+
+class TestContextFetchSearch(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self) -> type[ContextFetchSearch]:
+        return ContextFetchSearch
+
+    @property
+    def tool_constructor_params(self) -> dict:
+        return {"num_results": 2}
+
+    @property
+    def tool_invoke_params_example(self) -> dict:
+        return {"query": "python asyncio tutorial"}

langchain_contextfetch-0.1.0/tests/unit_tests/conftest.py

@@ -0,0 +1,58 @@
+"""Unit test fixtures: a fake ContextFetch transport, so no test touches the network."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import pytest
+from contextfetch import ContextFetch
+
+RESULTS: list[dict[str, Any]] = [
+    {
+        "id": "r1",
+        "url": "https://example.com/a",
+        "title": "Page A",
+        "score": 0.9,
+        "publishedDate": "2026-01-02",
+        "text": "# Page A\n\nFull Markdown of A.",
+        "prunedContext": "Relevant chunk of A.",
+    },
+    {
+        "id": "r2",
+        "url": "https://example.com/b",
+        "title": None,
+        "score": 0.5,
+        "text": "# Page B",
+        "prunedContext": "Relevant chunk of B.",
+    },
+]
+
+
+class FakeAPI:
+    """Records each request body and answers with RESULTS (or raises `error`)."""
+
+    def __init__(self) -> None:
+        self.calls: list[dict[str, Any]] = []
+        self.results: list[dict[str, Any]] = RESULTS
+        self.error: Exception | None = None
+
+    def request(
+        self, client: ContextFetch, method: str, path: str, body: Any = None, **_: Any
+    ) -> tuple[bytes, dict]:
+        self.calls.append({"path": path, "body": body, "api_key": client.api_key})
+        if self.error:
+            raise self.error
+        response = {"requestId": "req", "results": self.results[: body["numResults"]]}
+        return json.dumps(response).encode(), {}
+
+
+@pytest.fixture
+def fake_api(monkeypatch: pytest.MonkeyPatch) -> FakeAPI:
+    api = FakeAPI()
+    monkeypatch.delenv("CONTEXTFETCH_API_KEY", raising=False)
+    # Patch only the SDK's HTTP call, so its request building and parsing still run.
+    monkeypatch.setattr(
+        ContextFetch, "_request", lambda self, *a, **k: api.request(self, *a, **k)
+    )
+    return api

langchain_contextfetch-0.1.0/tests/unit_tests/test_imports.py

@@ -0,0 +1,7 @@
+from langchain_contextfetch import __all__
+
+EXPECTED_ALL = ["ContextFetchRetriever", "ContextFetchSearch", "__version__"]
+
+
+def test_all_imports() -> None:
+    assert sorted(EXPECTED_ALL) == sorted(__all__)

langchain_contextfetch-0.1.0/tests/unit_tests/test_retrievers.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import pytest
+from langchain_core.documents import Document
+from pydantic import SecretStr
+
+from langchain_contextfetch import ContextFetchRetriever
+from tests.unit_tests.conftest import FakeAPI
+
+
+def test_invoke_returns_markdown_documents(fake_api: FakeAPI) -> None:
+    retriever = ContextFetchRetriever(
+        k=2,
+        api_key=SecretStr("test-key"),
+        exclude_domains=["pinterest.com"],
+        start_published_date="2026-01-01",
+    )
+    docs = retriever.invoke("q")
+
+    assert docs == [
+        Document(
+            page_content="# Page A\n\nFull Markdown of A.",
+            metadata={
+                "id": "r1",
+                "url": "https://example.com/a",
+                "title": "Page A",
+                "score": 0.9,
+                "published_date": "2026-01-02",
+                "author": None,
+            },
+        ),
+        Document(
+            page_content="# Page B",
+            metadata={
+                "id": "r2",
+                "url": "https://example.com/b",
+                "title": None,
+                "score": 0.5,
+                "published_date": None,
+                "author": None,
+            },
+        ),
+    ]
+    assert fake_api.calls == [
+        {
+            "path": "/v1/search",
+            "body": {
+                "query": "q",
+                "numResults": 2,
+                "excludeDomains": ["pinterest.com"],
+                "startPublishedDate": "2026-01-01",
+                "contents": {"text": True},
+            },
+            "api_key": "test-key",
+        }
+    ]
+
+
+def test_pruned_context_and_k_kwarg(fake_api: FakeAPI) -> None:
+    retriever = ContextFetchRetriever(k=5, content="pruned_context")
+    docs = retriever.invoke("q", k=1)
+    assert [d.page_content for d in docs] == ["Relevant chunk of A."]
+    assert fake_api.calls[0]["body"]["numResults"] == 1
+    assert fake_api.calls[0]["body"]["contents"] == {"pruned_context": True}
+
+
+def test_key_from_env(fake_api: FakeAPI, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CONTEXTFETCH_API_KEY", "env-key")
+    ContextFetchRetriever().invoke("q")
+    assert fake_api.calls[0]["api_key"] == "env-key"
+    assert fake_api.calls[0]["body"]["numResults"] == 5
+
+
+async def test_ainvoke(fake_api: FakeAPI) -> None:
+    docs = await ContextFetchRetriever(k=1).ainvoke("q")
+    assert docs[0].metadata["url"] == "https://example.com/a"

langchain_contextfetch-0.1.0/tests/unit_tests/test_tools.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import pytest
+from contextfetch import PaymentRequiredError
+from langchain_core.messages import ToolMessage
+from langchain_core.tools import ToolException
+from langchain_tests.unit_tests import ToolsUnitTests
+from pydantic import SecretStr
+
+from langchain_contextfetch import ContextFetchSearch
+from tests.unit_tests.conftest import FakeAPI
+
+
+class TestContextFetchSearchStandard(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> type[ContextFetchSearch]:
+        return ContextFetchSearch
+
+    @property
+    def tool_constructor_params(self) -> dict:
+        return {"api_key": "test-key"}
+
+    @property
+    def tool_invoke_params_example(self) -> dict:
+        return {"query": "pgvector HNSW index parameters"}
+
+    @property
+    def init_from_env_params(self) -> tuple[dict, dict, dict]:
+        return {"CONTEXTFETCH_API_KEY": "env-key"}, {}, {"api_key": "env-key"}
+
+
+def _tool_call(args: dict) -> dict:
+    return {"args": args, "id": "1", "name": "contextfetch_search", "type": "tool_call"}
+
+
+def test_tool_call_returns_content_and_artifact(fake_api: FakeAPI) -> None:
+    tool = ContextFetchSearch(num_results=2, api_key=SecretStr("test-key"))
+    msg = tool.invoke(_tool_call({"query": "q", "include_domains": ["example.com"]}))
+
+    assert isinstance(msg, ToolMessage)
+    assert "URL: https://example.com/a" in msg.content
+    assert "Relevant chunk of A." in msg.content  # pruned_context is the default
+    assert "Full Markdown of A." not in msg.content
+    assert "Published: unknown" in msg.content  # result b has no publishedDate
+    assert msg.artifact["results"][0]["id"] == "r1"
+    assert fake_api.calls == [
+        {
+            "path": "/v1/search",
+            "body": {
+                "query": "q",
+                "numResults": 2,
+                "includeDomains": ["example.com"],
+                "contents": {"pruned_context": True},
+            },
+            "api_key": "test-key",
+        }
+    ]
+
+
+def test_text_content(fake_api: FakeAPI) -> None:
+    tool = ContextFetchSearch(content="text")
+    msg = tool.invoke(_tool_call({"query": "q"}))
+    assert "Full Markdown of A." in msg.content
+    assert fake_api.calls[0]["body"]["contents"] == {"text": True}
+    assert fake_api.calls[0]["api_key"] is None  # keyless tier
+
+
+def test_no_results(fake_api: FakeAPI) -> None:
+    fake_api.results = []
+    msg = ContextFetchSearch().invoke(_tool_call({"query": "q"}))
+    assert msg.content == "No results found."
+    assert msg.artifact == {"requestId": "req", "results": []}
+
+
+def test_api_error_is_tool_exception(fake_api: FakeAPI) -> None:
+    fake_api.error = PaymentRequiredError("HTTP 402 Buy credits.", status=402)
+    with pytest.raises(ToolException, match="Buy credits"):
+        ContextFetchSearch().invoke({"query": "q"})
+
+    tool = ContextFetchSearch(handle_tool_error=True)
+    msg = tool.invoke(_tool_call({"query": "q"}))
+    assert msg.status == "error"
+    assert "Buy credits" in msg.content
+
+
+async def test_async_invoke(fake_api: FakeAPI) -> None:
+    msg = await ContextFetchSearch().ainvoke(_tool_call({"query": "q"}))
+    assert "Page A" in msg.content
+
+
+def test_api_key_is_secret() -> None:
+    tool = ContextFetchSearch(api_key="test-key")  # type: ignore[arg-type]
+    assert tool.api_key == SecretStr("test-key")
+    assert "test-key" not in repr(tool)