pydantic-ai-contextfetch 0.1.0__tar.gz

pydantic_ai_contextfetch-0.1.0/.gitignore

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

pydantic_ai_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.

pydantic_ai_contextfetch-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: pydantic-ai-contextfetch
+Version: 0.1.0
+Summary: ContextFetch web search and page reading tools for Pydantic AI
+Project-URL: Homepage, https://contextfetch.dev
+Project-URL: Documentation, https://contextfetch.dev/docs/reference
+Project-URL: Repository, https://github.com/lachy3433/pydantic-ai-contextfetch
+Author: ContextFetch
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: contextfetch<1.0.0,>=0.1.0
+Requires-Dist: pydantic-ai-slim>=1.0.0
+Description-Content-Type: text/markdown
+
+# pydantic-ai-contextfetch
+
+[ContextFetch](https://contextfetch.dev) web search and page reading tools for [Pydantic AI](https://ai.pydantic.dev), as a toolset.
+
+```bash
+pip install pydantic-ai-contextfetch
+export CONTEXTFETCH_API_KEY="your-api-key"  # optional: without a key, requests use the keyless tier
+```
+
+```python
+from pydantic_ai import Agent
+
+from pydantic_ai_contextfetch import ContextFetchToolset
+
+agent = Agent('openai:gpt-5.2', toolsets=[ContextFetchToolset()])
+result = agent.run_sync('What changed in the latest Python release?')
+print(result.output)
+```
+
+## Tools
+
+- `contextfetch_search(query, include_domains?, exclude_domains?, start_published_date?)`: web search. Returns a list
+  of `{title, url, published_date, content}`, where `content` is the page as Markdown: by default only the parts
+  relevant to the query.
+- `contextfetch_read(url, query?)`: one page as Markdown. With `query`, only the parts relevant to it. A bad or
+  unreachable URL raises `ModelRetry`, so the model can correct it.
+
+## Options
+
+```python
+ContextFetchToolset(
+    api_key=None,              # defaults to CONTEXTFETCH_API_KEY
+    num_results=5,             # results per search, 1 to 25
+    content='pruned_context',  # or 'text' for whole pages
+    id=None,                   # toolset id for durable execution
+)
+```
+
+To expose only one tool, use Pydantic AI's toolset filtering:
+`ContextFetchToolset().filtered(lambda ctx, tool: tool.name == 'contextfetch_search')`.
+
+## Tests
+
+```bash
+uv run --group test pytest tests                                   # unit tests, no network
+CONTEXTFETCH_API_KEY=... uv run --group test pytest tests/test_live.py  # live, 2 credits
+```
+
+MIT licensed.

pydantic_ai_contextfetch-0.1.0/README.md

@@ -0,0 +1,49 @@
+# pydantic-ai-contextfetch
+
+[ContextFetch](https://contextfetch.dev) web search and page reading tools for [Pydantic AI](https://ai.pydantic.dev), as a toolset.
+
+```bash
+pip install pydantic-ai-contextfetch
+export CONTEXTFETCH_API_KEY="your-api-key"  # optional: without a key, requests use the keyless tier
+```
+
+```python
+from pydantic_ai import Agent
+
+from pydantic_ai_contextfetch import ContextFetchToolset
+
+agent = Agent('openai:gpt-5.2', toolsets=[ContextFetchToolset()])
+result = agent.run_sync('What changed in the latest Python release?')
+print(result.output)
+```
+
+## Tools
+
+- `contextfetch_search(query, include_domains?, exclude_domains?, start_published_date?)`: web search. Returns a list
+  of `{title, url, published_date, content}`, where `content` is the page as Markdown: by default only the parts
+  relevant to the query.
+- `contextfetch_read(url, query?)`: one page as Markdown. With `query`, only the parts relevant to it. A bad or
+  unreachable URL raises `ModelRetry`, so the model can correct it.
+
+## Options
+
+```python
+ContextFetchToolset(
+    api_key=None,              # defaults to CONTEXTFETCH_API_KEY
+    num_results=5,             # results per search, 1 to 25
+    content='pruned_context',  # or 'text' for whole pages
+    id=None,                   # toolset id for durable execution
+)
+```
+
+To expose only one tool, use Pydantic AI's toolset filtering:
+`ContextFetchToolset().filtered(lambda ctx, tool: tool.name == 'contextfetch_search')`.
+
+## Tests
+
+```bash
+uv run --group test pytest tests                                   # unit tests, no network
+CONTEXTFETCH_API_KEY=... uv run --group test pytest tests/test_live.py  # live, 2 credits
+```
+
+MIT licensed.

pydantic_ai_contextfetch-0.1.0/pydantic_ai_contextfetch/__init__.py

@@ -0,0 +1,102 @@
+"""ContextFetch web search and page reading tools for Pydantic AI."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from contextfetch import ContextFetch, ContextFetchError
+from pydantic_ai import ModelRetry
+from pydantic_ai.toolsets import FunctionToolset
+
+__all__ = ("ContextFetchToolset",)
+
+Content = Literal["pruned_context", "text"]
+"""`"pruned_context"`: only the parts of each page relevant to the query. `"text"`: the whole page as Markdown."""
+
+_RESULT_KEY = {"pruned_context": "prunedContext", "text": "text"}
+
+
+class ContextFetchToolset(FunctionToolset[Any]):
+    """A toolset with two tools that share one ContextFetch client.
+
+    - `contextfetch_search`: web search; each result carries the page content as Markdown.
+    - `contextfetch_read`: one URL as Markdown, optionally only the parts relevant to a question.
+
+    ```python
+    from pydantic_ai import Agent
+
+    from pydantic_ai_contextfetch import ContextFetchToolset
+
+    agent = Agent('openai:gpt-5.2', toolsets=[ContextFetchToolset()])
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        num_results: int = 5,
+        content: Content = "pruned_context",
+        id: str | None = None,
+    ):
+        """Creates the toolset.
+
+        Args:
+            api_key: The ContextFetch API key. Defaults to the `CONTEXTFETCH_API_KEY` environment variable;
+                without either, requests use the keyless tier.
+            num_results: Results per search (1 to 25). Defaults to 5.
+            content: Which page content search results carry. Defaults to `"pruned_context"`.
+            id: Optional ID for the toolset, used for durable execution environments.
+        """
+        client = ContextFetch(api_key)
+        key = _RESULT_KEY[content]
+
+        def contextfetch_search(
+            query: str,
+            include_domains: list[str] | None = None,
+            exclude_domains: list[str] | None = None,
+            start_published_date: str | None = None,
+        ) -> list[dict[str, Any]]:
+            """Searches the web and returns the top results with their page content as Markdown.
+
+            Args:
+                query: The web search query.
+                include_domains: Only return results from these domains.
+                exclude_domains: Never return results from these domains.
+                start_published_date: Only return pages published on or after this date (YYYY-MM-DD).
+            """
+            response = 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",
+            )
+            return [
+                {
+                    "title": r.get("title"),
+                    "url": r.get("url"),
+                    "published_date": r.get("publishedDate"),
+                    "content": r.get(key) or "",
+                }
+                for r in response.get("results", [])
+            ]
+
+        def contextfetch_read(url: str, query: str | None = None) -> str:
+            """Reads a web page and returns it as Markdown.
+
+            Args:
+                url: The URL of the page.
+                query: If set, only the parts of the page relevant to this question are returned.
+            """
+            try:
+                return client.read(url, query=query).markdown
+            except ContextFetchError as e:
+                # A bad or unreachable URL is something the model can fix; auth, credit and server errors are not.
+                if e.status in (400, 404, 422):
+                    raise ModelRetry(str(e)) from e
+                raise
+
+        super().__init__([contextfetch_search, contextfetch_read], id=id)

pydantic_ai_contextfetch-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pydantic-ai-contextfetch"
+version = "0.1.0"
+description = "ContextFetch web search and page reading tools for Pydantic AI"
+authors = [{ name = "ContextFetch" }]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Framework :: Pydantic",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pydantic-ai-slim>=1.0.0",
+    "contextfetch>=0.1.0,<1.0.0",
+]
+
+[project.urls]
+Homepage = "https://contextfetch.dev"
+Documentation = "https://contextfetch.dev/docs/reference"
+Repository = "https://github.com/lachy3433/pydantic-ai-contextfetch"
+
+[dependency-groups]
+test = ["pytest>=8"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["pydantic_ai_contextfetch", "tests", "README.md", "LICENSE"]

pydantic_ai_contextfetch-0.1.0/tests/test_live.py

@@ -0,0 +1,19 @@
+"""Live check against the real API (2 credits). Skipped unless CONTEXTFETCH_API_KEY is set."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from pydantic_ai_contextfetch import ContextFetchToolset
+
+pytestmark = pytest.mark.skipif(not os.environ.get("CONTEXTFETCH_API_KEY"), reason="needs CONTEXTFETCH_API_KEY")
+
+
+def test_live() -> None:
+    tools = ContextFetchToolset(num_results=2).tools
+    results = tools["contextfetch_search"].function("python asyncio TaskGroup")
+    assert results and results[0]["url"].startswith("http") and results[0]["content"]
+    page = tools["contextfetch_read"].function("https://docs.python.org/3/library/asyncio-task.html", query="TaskGroup")
+    assert "TaskGroup" in page

pydantic_ai_contextfetch-0.1.0/tests/test_toolset.py

@@ -0,0 +1,109 @@
+"""Unit tests: the SDK's HTTP call is patched, so nothing touches the network."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import pytest
+from contextfetch import ContextFetch, ContextFetchError
+from pydantic_ai import Agent, ModelRetry
+from pydantic_ai.messages import ModelMessage, ModelResponse, TextPart, ToolCallPart, ToolReturnPart
+from pydantic_ai.models.function import AgentInfo, FunctionModel
+
+from pydantic_ai_contextfetch import ContextFetchToolset
+
+RESULTS = [
+    {"url": "https://example.com/a", "title": "A", "publishedDate": "2026-01-02", "text": "# A", "prunedContext": "chunk A"},
+    {"url": "https://example.com/b", "title": None, "text": "# B", "prunedContext": "chunk B"},
+]
+
+
+@pytest.fixture
+def calls(monkeypatch: pytest.MonkeyPatch) -> list[dict[str, Any]]:
+    calls: list[dict[str, Any]] = []
+    monkeypatch.delenv("CONTEXTFETCH_API_KEY", raising=False)
+
+    def request(self: ContextFetch, method: str, path: str, body: Any = None, **_: Any) -> tuple[bytes, dict]:
+        calls.append({"method": method, "path": path, "body": body, "api_key": self.api_key})
+        if path.startswith("/r/https://missing"):
+            raise ContextFetchError("not found", status=404)
+        if path.startswith("/r/"):
+            return b"# Page", {}
+        return json.dumps({"results": RESULTS[: body["numResults"]]}).encode(), {}
+
+    monkeypatch.setattr(ContextFetch, "_request", request)
+    return calls
+
+
+def _call(toolset: ContextFetchToolset, tool: str, args: dict[str, Any]) -> Any:
+    """Runs one tool call through a real Agent with a scripted model, returning the tool's return value."""
+
+    def model(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        if len(messages) == 1:
+            return ModelResponse(parts=[ToolCallPart(tool, args)])
+        return ModelResponse(parts=[TextPart("done")])
+
+    result = Agent(FunctionModel(model), toolsets=[toolset]).run_sync("go")
+    returns = [p for m in result.all_messages() for p in m.parts if isinstance(p, ToolReturnPart)]
+    return returns[0].content
+
+
+def test_tool_schemas() -> None:
+    def model(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        tools = {t.name: t for t in info.function_tools}
+        assert set(tools) == {"contextfetch_search", "contextfetch_read"}
+        search = tools["contextfetch_search"]
+        assert search.parameters_json_schema["required"] == ["query"]
+        assert "YYYY-MM-DD" in search.parameters_json_schema["properties"]["start_published_date"]["description"]
+        assert tools["contextfetch_read"].parameters_json_schema["required"] == ["url"]
+        return ModelResponse(parts=[TextPart("done")])
+
+    Agent(FunctionModel(model), toolsets=[ContextFetchToolset("k")]).run_sync("go")
+
+
+def test_search(calls: list[dict[str, Any]]) -> None:
+    out = _call(ContextFetchToolset("k", num_results=2), "contextfetch_search", {"query": "q", "include_domains": ["example.com"]})
+    assert out == [
+        {"title": "A", "url": "https://example.com/a", "published_date": "2026-01-02", "content": "chunk A"},
+        {"title": None, "url": "https://example.com/b", "published_date": None, "content": "chunk B"},
+    ]
+    assert calls == [
+        {
+            "method": "POST",
+            "path": "/v1/search",
+            "body": {"query": "q", "numResults": 2, "includeDomains": ["example.com"], "contents": {"pruned_context": True}},
+            "api_key": "k",
+        }
+    ]
+
+
+def test_search_text_content_and_env_key(calls: list[dict[str, Any]], monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CONTEXTFETCH_API_KEY", "env-key")
+    out = _call(ContextFetchToolset(num_results=1, content="text"), "contextfetch_search", {"query": "q"})
+    assert out[0]["content"] == "# A"
+    assert calls[0]["body"]["contents"] == {"text": True}
+    assert calls[0]["api_key"] == "env-key"
+
+
+def test_read(calls: list[dict[str, Any]]) -> None:
+    out = _call(ContextFetchToolset("k"), "contextfetch_read", {"url": "https://example.com/x", "query": "pricing"})
+    assert out == "# Page"
+    assert calls[0]["path"] == "/r/https://example.com/x?q=pricing"
+
+
+def test_read_bad_url_is_retried(calls: list[dict[str, Any]]) -> None:
+    toolset = ContextFetchToolset("k")
+    read = toolset.tools["contextfetch_read"].function
+    with pytest.raises(ModelRetry, match="not found"):
+        read("https://missing.example")
+
+
+def test_read_auth_error_propagates(monkeypatch: pytest.MonkeyPatch) -> None:
+    def request(self: ContextFetch, *a: Any, **k: Any) -> Any:
+        raise ContextFetchError("bad key", status=401)
+
+    monkeypatch.setattr(ContextFetch, "_request", request)
+    read = ContextFetchToolset("k").tools["contextfetch_read"].function
+    with pytest.raises(ContextFetchError, match="bad key"):
+        read("https://example.com")