langchain-contextfetch 0.1.0__py3-none-any.whl

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/_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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+langchain_contextfetch/__init__.py,sha256=PuSElyC8k3iCofeOMHmqV3jdsqA2qHN_oR3W-RfRQCw,564
+langchain_contextfetch/_utilities.py,sha256=EgInXZQjgLJ7P3hYwRHqfceII7UJ7n28LkYjrYBErJU,1798
+langchain_contextfetch/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_contextfetch/retrievers.py,sha256=9_AV8_CUPwIxYkuL2eFD6Y5-yKyKV60IkcevVRt6eYg,4249
+langchain_contextfetch/tools.py,sha256=LIJVmDeF7XjtUhRqYtBEb0vPXp5Cep9YLYiHQqUdhfo,4731
+langchain_contextfetch-0.1.0.dist-info/METADATA,sha256=85wdlSXxbRBjzxMlK6kXQMRTS3De9nWiAHZTSK150Cs,4933
+langchain_contextfetch-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+langchain_contextfetch-0.1.0.dist-info/licenses/LICENSE,sha256=RqQqv3BiTnGfaC6tdJ9oSSRKa0fzw4e7wxJwAR9Bab4,1073
+langchain_contextfetch-0.1.0.dist-info/RECORD,,

langchain_contextfetch-0.1.0.dist-info/WHEEL

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

langchain_contextfetch-0.1.0.dist-info/licenses/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.