pydantic-ai-contextfetch 0.1.0__py3-none-any.whl

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

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

@@ -0,0 +1,5 @@
+pydantic_ai_contextfetch/__init__.py,sha256=Ju5JdGMGFWGuQ6aKrB0bYgn4Y5VSkXNB5PUGNwvk58Q,3916
+pydantic_ai_contextfetch-0.1.0.dist-info/METADATA,sha256=yonz8BHygNe3Lf0-dA91zDMEYt87-wjksjm8-544yKM,2438
+pydantic_ai_contextfetch-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pydantic_ai_contextfetch-0.1.0.dist-info/licenses/LICENSE,sha256=RqQqv3BiTnGfaC6tdJ9oSSRKa0fzw4e7wxJwAR9Bab4,1073
+pydantic_ai_contextfetch-0.1.0.dist-info/RECORD,,

pydantic_ai_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

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