openai-agents-contextfetch 0.1.0__tar.gz

openai_agents_contextfetch-0.1.0/.gitignore

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

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

openai_agents_contextfetch-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: openai-agents-contextfetch
+Version: 0.1.0
+Summary: ContextFetch web search and page reading tools for the OpenAI Agents SDK
+Project-URL: Homepage, https://contextfetch.dev
+Project-URL: Documentation, https://contextfetch.dev/docs/reference
+Project-URL: Repository, https://github.com/lachy3433/openai-agents-contextfetch
+Author: ContextFetch
+License-Expression: MIT
+License-File: LICENSE
+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: openai-agents>=0.20.0
+Description-Content-Type: text/markdown
+
+# openai-agents-contextfetch
+
+[ContextFetch](https://contextfetch.dev) web search and page reading as function tools for the
+[OpenAI Agents SDK](https://openai.github.io/openai-agents-python/).
+
+```bash
+pip install openai-agents-contextfetch
+export CONTEXTFETCH_API_KEY="your-api-key"  # optional: without a key, requests use the keyless tier
+```
+
+```python
+from agents import Agent, Runner
+
+from openai_agents_contextfetch import contextfetch_tools
+
+agent = Agent(name="Researcher", instructions="Answer with sources.", tools=contextfetch_tools())
+result = Runner.run_sync(agent, "What changed in the latest Python release?")
+print(result.final_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.
+
+API errors (bad URL, no credits, rate limit) go back to the model as the tool output, with the API's message.
+
+## Options
+
+```python
+contextfetch_tools(
+    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
+)
+```
+
+## Without this package
+
+The same tools are available over MCP: `npx -y @contextfetch/mcp` with the SDK's `MCPServerStdio`.
+
+## 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
+```
+
+Tested with openai-agents 0.20.0, 0.22.0 and 0.24.0. MIT licensed.

openai_agents_contextfetch-0.1.0/README.md

@@ -0,0 +1,51 @@
+# openai-agents-contextfetch
+
+[ContextFetch](https://contextfetch.dev) web search and page reading as function tools for the
+[OpenAI Agents SDK](https://openai.github.io/openai-agents-python/).
+
+```bash
+pip install openai-agents-contextfetch
+export CONTEXTFETCH_API_KEY="your-api-key"  # optional: without a key, requests use the keyless tier
+```
+
+```python
+from agents import Agent, Runner
+
+from openai_agents_contextfetch import contextfetch_tools
+
+agent = Agent(name="Researcher", instructions="Answer with sources.", tools=contextfetch_tools())
+result = Runner.run_sync(agent, "What changed in the latest Python release?")
+print(result.final_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.
+
+API errors (bad URL, no credits, rate limit) go back to the model as the tool output, with the API's message.
+
+## Options
+
+```python
+contextfetch_tools(
+    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
+)
+```
+
+## Without this package
+
+The same tools are available over MCP: `npx -y @contextfetch/mcp` with the SDK's `MCPServerStdio`.
+
+## 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
+```
+
+Tested with openai-agents 0.20.0, 0.22.0 and 0.24.0. MIT licensed.

openai_agents_contextfetch-0.1.0/openai_agents_contextfetch/__init__.py

@@ -0,0 +1,87 @@
+"""ContextFetch web search and page reading tools for the OpenAI Agents SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from agents import FunctionTool, RunContextWrapper, function_tool
+from contextfetch import ContextFetch
+
+__all__ = ("contextfetch_tools",)
+
+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"}
+
+
+def _error_message(ctx: RunContextWrapper[Any], error: Exception) -> str:
+    # The SDK's default hides the message; the API's error text tells the model what to fix.
+    return f"ContextFetch error: {error}"
+
+
+def contextfetch_tools(
+    api_key: str | None = None,
+    *,
+    num_results: int = 5,
+    content: Content = "pruned_context",
+) -> list[FunctionTool]:
+    """Returns the `contextfetch_search` and `contextfetch_read` function tools, sharing one client.
+
+    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"`.
+
+    API errors (bad URL, no credits, rate limit) are returned to the model as the tool output, with the API's message.
+    """
+    client = ContextFetch(api_key)
+    key = _RESULT_KEY[content]
+
+    # Sync functions: the SDK runs them in a worker thread (the contextfetch client is stdlib urllib).
+    @function_tool(failure_error_function=_error_message)
+    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", [])
+        ]
+
+    @function_tool(failure_error_function=_error_message)
+    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.
+        """
+        return client.read(url, query=query).markdown
+
+    return [contextfetch_search, contextfetch_read]

openai_agents_contextfetch-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openai-agents-contextfetch"
+version = "0.1.0"
+description = "ContextFetch web search and page reading tools for the OpenAI Agents SDK"
+authors = [{ name = "ContextFetch" }]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "openai-agents>=0.20.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/openai-agents-contextfetch"
+
+[dependency-groups]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["openai_agents_contextfetch", "tests", "README.md", "LICENSE"]

openai_agents_contextfetch-0.1.0/tests/test_live.py

@@ -0,0 +1,26 @@
+"""Live check against the real API (2 credits). Skipped unless CONTEXTFETCH_API_KEY is set."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import pytest
+from agents.tool_context import ToolContext
+
+from openai_agents_contextfetch import contextfetch_tools
+
+pytestmark = pytest.mark.skipif(not os.environ.get("CONTEXTFETCH_API_KEY"), reason="needs CONTEXTFETCH_API_KEY")
+
+
+async def test_live() -> None:
+    search, read = contextfetch_tools(num_results=2)
+
+    async def invoke(tool, args):
+        raw = json.dumps(args)
+        return await tool.on_invoke_tool(ToolContext(None, tool_name=tool.name, tool_call_id="1", tool_arguments=raw), raw)
+
+    results = await invoke(search, {"query": "python asyncio TaskGroup"})
+    assert results and results[0]["url"].startswith("http") and results[0]["content"]
+    page = await invoke(read, {"url": "https://docs.python.org/3/library/asyncio-task.html", "query": "TaskGroup"})
+    assert "TaskGroup" in page

openai_agents_contextfetch-0.1.0/tests/test_tools.py

@@ -0,0 +1,88 @@
+"""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 agents import FunctionTool
+from agents.tool_context import ToolContext
+from contextfetch import ContextFetch, ContextFetchError
+
+from openai_agents_contextfetch import contextfetch_tools
+
+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 _tools(**kwargs: Any) -> dict[str, FunctionTool]:
+    return {t.name: t for t in contextfetch_tools(**kwargs)}
+
+
+async def _invoke(tool: FunctionTool, args: dict[str, Any]) -> Any:
+    raw = json.dumps(args)
+    return await tool.on_invoke_tool(ToolContext(None, tool_name=tool.name, tool_call_id="1", tool_arguments=raw), raw)
+
+
+def test_schemas() -> None:
+    tools = _tools(api_key="k")
+    assert set(tools) == {"contextfetch_search", "contextfetch_read"}
+    search = tools["contextfetch_search"].params_json_schema
+    assert "query" in search["required"]
+    assert "YYYY-MM-DD" in search["properties"]["start_published_date"]["description"]
+    assert "page" in tools["contextfetch_read"].description
+
+
+async def test_search(calls: list[dict[str, Any]]) -> None:
+    out = await _invoke(_tools(api_key="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",
+        }
+    ]
+
+
+async 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 = await _invoke(_tools(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"
+
+
+async def test_read(calls: list[dict[str, Any]]) -> None:
+    out = await _invoke(_tools(api_key="k")["contextfetch_read"], {"url": "https://example.com/x", "query": "pricing"})
+    assert out == "# Page"
+    assert calls[0]["path"] == "/r/https://example.com/x?q=pricing"
+
+
+async def test_error_goes_to_model(calls: list[dict[str, Any]]) -> None:
+    out = await _invoke(_tools(api_key="k")["contextfetch_read"], {"url": "https://missing.example"})
+    assert "not found" in out