openai-agents-contextfetch 0.1.0__py3-none-any.whl

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

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

@@ -0,0 +1,5 @@
+openai_agents_contextfetch/__init__.py,sha256=1mrcBM1CLPeFsauxZbD6cVJHfEXfjHapiaBBuGdoG5k,3371
+openai_agents_contextfetch-0.1.0.dist-info/METADATA,sha256=hdof79KwkwJyiOFLTTcTa0ybYlakFgZixcf9y2W8DP0,2495
+openai_agents_contextfetch-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+openai_agents_contextfetch-0.1.0.dist-info/licenses/LICENSE,sha256=RqQqv3BiTnGfaC6tdJ9oSSRKa0fzw4e7wxJwAR9Bab4,1073
+openai_agents_contextfetch-0.1.0.dist-info/RECORD,,

openai_agents_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

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