dspy-contextfetch 0.1.0__tar.gz

dspy_contextfetch-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+dist/
+.venv/

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

dspy_contextfetch-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: dspy-contextfetch
+Version: 0.1.0
+Summary: ContextFetch web search and page reading as DSPy tools
+Project-URL: Homepage, https://contextfetch.dev
+Project-URL: Source, https://github.com/lachy3433/dspy-contextfetch
+Author: ContextFetch
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,contextfetch,dspy,tools,web search
+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
+Description-Content-Type: text/markdown
+
+# dspy-contextfetch
+
+[ContextFetch](https://contextfetch.dev) web search and page reading as [DSPy](https://dspy.ai) tools.
+
+```bash
+pip install dspy-contextfetch
+export CONTEXTFETCH_API_KEY="..."   # optional: without a key, requests use the keyless tier
+```
+
+```python
+import dspy
+from dspy_contextfetch import read_page, web_search
+
+dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
+agent = dspy.ReAct("question -> answer", tools=[web_search, read_page])
+print(agent(question="What does asyncio.TaskGroup do when a task fails?").answer)
+```
+
+- `web_search(query, num_results=5, include_domains=None, start_published_date=None)`: the top results as
+  Markdown, each with title, URL, published date and the parts of the page relevant to the query.
+- `read_page(url, query=None)`: one page as Markdown; with `query`, only the parts relevant to it.
+
+Both are plain functions over the [`contextfetch`](https://pypi.org/project/contextfetch/) SDK, so they also
+work with `dspy.Tool(...)` or called directly. Errors from the API raise `contextfetch.ContextFetchError`.
+
+## Tests
+
+```bash
+uv run --group test pytest
+```
+
+The live test runs when `~/.contextfetch_smoke_key` exists.

dspy_contextfetch-0.1.0/README.md

@@ -0,0 +1,32 @@
+# dspy-contextfetch
+
+[ContextFetch](https://contextfetch.dev) web search and page reading as [DSPy](https://dspy.ai) tools.
+
+```bash
+pip install dspy-contextfetch
+export CONTEXTFETCH_API_KEY="..."   # optional: without a key, requests use the keyless tier
+```
+
+```python
+import dspy
+from dspy_contextfetch import read_page, web_search
+
+dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))
+agent = dspy.ReAct("question -> answer", tools=[web_search, read_page])
+print(agent(question="What does asyncio.TaskGroup do when a task fails?").answer)
+```
+
+- `web_search(query, num_results=5, include_domains=None, start_published_date=None)`: the top results as
+  Markdown, each with title, URL, published date and the parts of the page relevant to the query.
+- `read_page(url, query=None)`: one page as Markdown; with `query`, only the parts relevant to it.
+
+Both are plain functions over the [`contextfetch`](https://pypi.org/project/contextfetch/) SDK, so they also
+work with `dspy.Tool(...)` or called directly. Errors from the API raise `contextfetch.ContextFetchError`.
+
+## Tests
+
+```bash
+uv run --group test pytest
+```
+
+The live test runs when `~/.contextfetch_smoke_key` exists.

dspy_contextfetch-0.1.0/dspy_contextfetch/__init__.py

@@ -0,0 +1,46 @@
+"""ContextFetch web search and page reading as DSPy tools.
+
+Plain functions, so they work anywhere DSPy takes a tool: `dspy.ReAct(sig, tools=[web_search, read_page])`
+or `dspy.Tool(web_search)`. The API key comes from the CONTEXTFETCH_API_KEY environment variable; without
+one, requests use the keyless tier.
+"""
+
+from __future__ import annotations
+
+from contextfetch import ContextFetch
+
+__all__ = ["read_page", "web_search"]
+
+
+def web_search(
+    query: str,
+    num_results: int = 5,
+    include_domains: list[str] | None = None,
+    start_published_date: str | None = None,
+) -> str:
+    """Search the web. Returns the top results as Markdown: title, URL, published date and the parts of
+    each page relevant to the query. num_results is 1 to 25; include_domains limits results to those
+    domains; start_published_date (YYYY-MM-DD) keeps only pages published on or after that date."""
+    response = ContextFetch().search(
+        query,
+        num_results=num_results,
+        include_domains=include_domains,
+        start_published_date=start_published_date,
+        pruned_context=True,
+    )
+    results = response.get("results") or []
+    if not results:
+        return "No results found."
+    return "\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"{r.get('prunedContext') or ''}"
+        for r in results
+    )
+
+
+def read_page(url: str, query: str | None = None) -> str:
+    """Read a web page and return its content as Markdown. With query, return only the parts of the page
+    relevant to that question."""
+    return ContextFetch().read(url, query=query).markdown

dspy_contextfetch-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dspy-contextfetch"
+version = "0.1.0"
+description = "ContextFetch web search and page reading as DSPy tools"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "ContextFetch" }]
+keywords = ["dspy", "contextfetch", "web search", "tools", "agents"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["contextfetch>=0.1.0,<1.0.0"]
+
+[project.urls]
+Homepage = "https://contextfetch.dev"
+Source = "https://github.com/lachy3433/dspy-contextfetch"
+
+[dependency-groups]
+test = ["pytest>=8", "dspy>=3.0"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["dspy_contextfetch", "tests", "README.md", "LICENSE"]

dspy_contextfetch-0.1.0/tests/test_tools.py

@@ -0,0 +1,75 @@
+import json
+from pathlib import Path
+
+import dspy
+import pytest
+
+from dspy_contextfetch import read_page, web_search
+
+KEY_FILE = Path.home() / ".contextfetch_smoke_key"
+
+
+@pytest.fixture
+def mocked(monkeypatch):
+    monkeypatch.setenv("CONTEXTFETCH_API_KEY", "k")
+    # The contextfetch SDK calls urllib.request.urlopen; record each request and answer it.
+    api = {"calls": [], "search": {"results": []}}
+
+    class Res:
+        def __init__(self, body, headers=None):
+            self.body, self.headers = body, headers or {}
+
+        def read(self):
+            return self.body
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+    def urlopen(req, timeout):
+        api["calls"].append(req)
+        if req.full_url.endswith("/v1/search"):
+            return Res(json.dumps(api["search"]).encode())
+        return Res(b"# Page")
+
+    monkeypatch.setattr("urllib.request.urlopen", urlopen)
+    return api
+
+
+def test_web_search(mocked):
+    mocked["search"] = {"results": [{"title": "T", "url": "https://a.dev", "prunedContext": "body"}]}
+    out = web_search("q", num_results=3, include_domains=["a.dev"])
+    body = json.loads(mocked["calls"][0].data)
+    assert body == {
+        "query": "q",
+        "numResults": 3,
+        "includeDomains": ["a.dev"],
+        "contents": {"pruned_context": True},
+    }
+    assert mocked["calls"][0].headers["Authorization"] == "Bearer k"
+    assert out == "Title: T\nURL: https://a.dev\nPublished: unknown\n\nbody"
+
+
+def test_web_search_empty(mocked):
+    assert web_search("q") == "No results found."
+
+
+def test_read_page(mocked):
+    assert read_page("https://a.dev/x", query="what") == "# Page"
+    assert mocked["calls"][0].full_url == "https://api.contextfetch.dev/r/https://a.dev/x?q=what"
+
+
+def test_dspy_tool_schema():
+    tool = dspy.Tool(web_search)
+    assert tool.name == "web_search"
+    assert set(tool.args) == {"query", "num_results", "include_domains", "start_published_date"}
+    assert dspy.Tool(read_page).args["url"] == {"type": "string"}
+
+
+@pytest.mark.skipif(not KEY_FILE.exists(), reason="no live key")
+def test_live(monkeypatch):
+    monkeypatch.setenv("CONTEXTFETCH_API_KEY", KEY_FILE.read_text().strip())
+    assert "URL: https://" in web_search("python asyncio TaskGroup", num_results=2)
+    assert "TaskGroup" in read_page("https://docs.python.org/3/library/asyncio-task.html", "TaskGroup")