llama-index-tools-contextfetch 0.1.0__tar.gz

llama_index_tools_contextfetch-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+node_modules/
+.next/
+dist/
+engine/.model_cache/
+engine/.data/
+.env
+.env.npm
+.env.webshare
+.venv
+engine/.model_cache
+growth-sniper/leads.csv
+__pycache__/
+.pytest_cache/
+.env.hetzner
+.next-*/
+.vercel/
+benchmarks/data/
+*.tsbuildinfo
+next-env.d.ts

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

llama_index_tools_contextfetch-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: llama-index-tools-contextfetch
+Version: 0.1.0
+Summary: llama-index tools contextfetch integration
+Project-URL: Homepage, https://contextfetch.dev
+Project-URL: Documentation, https://contextfetch.dev/docs/reference
+Author: ContextFetch
+Maintainer: lachy3433
+License-Expression: MIT
+License-File: LICENSE
+Keywords: contextfetch,markdown,web,web search
+Requires-Python: <4.0,>=3.10
+Requires-Dist: contextfetch>=0.1.0
+Requires-Dist: llama-index-core<0.15,>=0.13.0
+Description-Content-Type: text/markdown
+
+# LlamaIndex Tools Integration: ContextFetch
+
+```bash
+pip install llama-index-tools-contextfetch
+```
+
+This tool connects agents to [ContextFetch](https://contextfetch.dev), a web
+search and web page to Markdown API.
+
+Pass `api_key`, or set the `CONTEXTFETCH_API_KEY` environment variable. With
+neither, requests use ContextFetch's keyless tier, a small daily allowance per IP.
+The `contextfetch` package can request a free starter key:
+`from contextfetch import ContextFetch; ContextFetch().free_key()`.
+
+## Usage
+
+```python
+# %pip install llama-index llama-index-tools-contextfetch
+
+from llama_index.tools.contextfetch import ContextFetchToolSpec
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.openai import OpenAI
+
+contextfetch_tool = ContextFetchToolSpec()  # or ContextFetchToolSpec(api_key="...")
+agent = FunctionAgent(
+    tools=contextfetch_tool.to_tool_list(),
+    llm=OpenAI(model="gpt-4.1"),
+)
+
+print(await agent.run("How do asyncio task groups handle errors?"))
+```
+
+## Available Functions
+
+`search`: Search the web. Returns each result's title, URL, published date when
+known, and the passages relevant to the query.
+
+`read_page`: Read a web page as Markdown. With `query`, only the parts of the page
+relevant to it are returned.
+
+`find_similar`: Find pages on other sites that are similar to a given page.
+
+`answer`: Answer a question with passages quoted verbatim from web pages, each
+followed by `[n]`, then the numbered source URLs. No text is generated.
+
+Each function returns a Markdown string that names its sources by title and URL.
+To load pages as Documents for indexing, use `llama-index-readers-contextfetch`.
+
+This loader is designed to be used as a way to load data as a Tool in an Agent.

llama_index_tools_contextfetch-0.1.0/README.md

@@ -0,0 +1,49 @@
+# LlamaIndex Tools Integration: ContextFetch
+
+```bash
+pip install llama-index-tools-contextfetch
+```
+
+This tool connects agents to [ContextFetch](https://contextfetch.dev), a web
+search and web page to Markdown API.
+
+Pass `api_key`, or set the `CONTEXTFETCH_API_KEY` environment variable. With
+neither, requests use ContextFetch's keyless tier, a small daily allowance per IP.
+The `contextfetch` package can request a free starter key:
+`from contextfetch import ContextFetch; ContextFetch().free_key()`.
+
+## Usage
+
+```python
+# %pip install llama-index llama-index-tools-contextfetch
+
+from llama_index.tools.contextfetch import ContextFetchToolSpec
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.openai import OpenAI
+
+contextfetch_tool = ContextFetchToolSpec()  # or ContextFetchToolSpec(api_key="...")
+agent = FunctionAgent(
+    tools=contextfetch_tool.to_tool_list(),
+    llm=OpenAI(model="gpt-4.1"),
+)
+
+print(await agent.run("How do asyncio task groups handle errors?"))
+```
+
+## Available Functions
+
+`search`: Search the web. Returns each result's title, URL, published date when
+known, and the passages relevant to the query.
+
+`read_page`: Read a web page as Markdown. With `query`, only the parts of the page
+relevant to it are returned.
+
+`find_similar`: Find pages on other sites that are similar to a given page.
+
+`answer`: Answer a question with passages quoted verbatim from web pages, each
+followed by `[n]`, then the numbered source URLs. No text is generated.
+
+Each function returns a Markdown string that names its sources by title and URL.
+To load pages as Documents for indexing, use `llama-index-readers-contextfetch`.
+
+This loader is designed to be used as a way to load data as a Tool in an Agent.

llama_index_tools_contextfetch-0.1.0/llama_index/tools/contextfetch/__init__.py

@@ -0,0 +1,3 @@
+from llama_index.tools.contextfetch.base import ContextFetchToolSpec
+
+__all__ = ["ContextFetchToolSpec"]

llama_index_tools_contextfetch-0.1.0/llama_index/tools/contextfetch/base.py

@@ -0,0 +1,119 @@
+"""ContextFetch tool spec."""
+
+from typing import List, Optional
+
+from contextfetch import ContextFetch, Result
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+
+
+class ContextFetchToolSpec(BaseToolSpec):
+    """
+    ContextFetch tool spec: web search and web pages as Markdown.
+
+    Each function returns a Markdown string that names its sources by title
+    and URL, so the agent can cite them or read them in full.
+
+    Args:
+        api_key: ContextFetch API key. Defaults to the CONTEXTFETCH_API_KEY
+            environment variable; with neither, requests use the keyless tier.
+
+    Example:
+        .. code-block:: python
+
+            from llama_index.tools.contextfetch import ContextFetchToolSpec
+            from llama_index.core.agent.workflow import FunctionAgent
+            from llama_index.llms.openai import OpenAI
+
+            agent = FunctionAgent(
+                tools=ContextFetchToolSpec().to_tool_list(),
+                llm=OpenAI(model="gpt-4.1"),
+            )
+            print(await agent.run("How do asyncio task groups handle errors?"))
+
+    """
+
+    spec_functions = ["search", "read_page", "find_similar", "answer"]
+
+    def __init__(self, api_key: Optional[str] = None) -> None:
+        """Initialize with parameters."""
+        self.client = ContextFetch(api_key=api_key)
+
+    def search(
+        self,
+        query: str,
+        num_results: int = 5,
+        include_domains: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Search the web. Returns each result's title, URL and the passages relevant to the query.
+
+        Use read_page to get a result's full text.
+
+        Args:
+            query: What to search for, in natural language.
+            num_results: How many results to return, 1 to 25.
+            include_domains: Only return results from these domains, e.g. ["docs.python.org"].
+
+        """
+        response = self.client.search(
+            query,
+            num_results=num_results,
+            include_domains=include_domains,
+            pruned_context=True,
+        )
+        return _format_results(response.get("results", []))
+
+    def read_page(self, url: str, query: Optional[str] = None) -> str:
+        """
+        Read a web page as Markdown.
+
+        Args:
+            url: The page to read.
+            query: Optional question. When given, only the parts of the page relevant to it are returned.
+
+        """
+        return self.client.read(url, query=query).markdown
+
+    def find_similar(self, url: str, num_results: int = 5) -> str:
+        """
+        Find pages on other sites that are similar to a web page. Returns each result's title, URL and its most relevant passages.
+
+        Args:
+            url: The page to find similar pages for.
+            num_results: How many results to return, 1 to 25.
+
+        """
+        response = self.client.find_similar(
+            url, num_results=num_results, pruned_context=True
+        )
+        return _format_results(response.get("results", []))
+
+    def answer(self, query: str) -> str:
+        """
+        Answer a question with passages quoted verbatim from web pages, each followed by [n], then the numbered sources.
+
+        No text is generated; when no passage is relevant enough, says so.
+
+        Args:
+            query: The question.
+
+        """
+        response = self.client.answer(query)
+        if not response.get("answer"):
+            return "No passage was relevant enough to answer this question."
+        sources = "\n".join(
+            f"[{n}] {c.get('title') or c.get('url')}: {c.get('url')}"
+            for n, c in enumerate(response.get("citations", []), start=1)
+        )
+        return f"{response['answer']}\n\nSources:\n{sources}"
+
+
+def _format_results(results: List[Result]) -> str:
+    blocks = []
+    for r in results:
+        lines = [f"## {r.get('title') or r.get('url')}", f"URL: {r.get('url')}"]
+        if r.get("publishedDate"):
+            lines.append(f"Published: {r['publishedDate']}")
+        lines += ["", r.get("prunedContext") or ""]
+        blocks.append("\n".join(lines).strip())
+    return "\n\n".join(blocks) or "No results."

llama_index_tools_contextfetch-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "black[jupyter]>=23.7.0,<=26.5.1",
+    "codespell[toml]>=v2.2.6",
+    "diff-cover>=9.2.0",
+    "ipython==8.10.0",
+    "jupyter>=1.0.0,<2",
+    "mypy==0.991",
+    "pre-commit==3.2.0",
+    "pylint==2.15.10",
+    "pytest",
+    "pytest-cov>=6.1.1",
+    "pytest-mock==3.11.1",
+    "ruff==0.11.11",
+    "types-Deprecated>=0.1.0",
+    "types-PyYAML>=6.0.12.12,<7",
+    "types-protobuf>=4.24.0.4,<5",
+    "types-redis==4.5.5.0",
+    "types-requests==2.28.11.8",
+    "types-setuptools==67.1.0.0",
+]
+
+[project]
+name = "llama-index-tools-contextfetch"
+version = "0.1.0"
+description = "llama-index tools contextfetch integration"
+authors = [{name = "ContextFetch"}]
+requires-python = ">=3.10,<4.0"
+readme = "README.md"
+license = "MIT"
+maintainers = [{name = "lachy3433"}]
+keywords = [
+    "contextfetch",
+    "markdown",
+    "web",
+    "web search",
+]
+dependencies = [
+    "contextfetch>=0.1.0",
+    "llama-index-core>=0.13.0,<0.15",
+]
+
+[project.urls]
+Homepage = "https://contextfetch.dev"
+Documentation = "https://contextfetch.dev/docs/reference"
+
+[tool.codespell]
+check-filenames = true
+check-hidden = true
+skip = "*.csv,*.html,*.json,*.jsonl,*.pdf,*.txt,*.ipynb"
+
+[tool.hatch.build.targets.sdist]
+include = ["llama_index/"]
+
+[tool.hatch.build.targets.wheel]
+include = ["llama_index/"]
+
+[tool.llamahub]
+contains_example = false
+import_path = "llama_index.tools.contextfetch"
+
+[tool.llamahub.class_authors]
+ContextFetchToolSpec = "lachy3433"
+
+[tool.mypy]
+disallow_untyped_defs = true
+exclude = ["_static", "build", "examples", "notebooks", "venv"]
+ignore_missing_imports = true
+python_version = "3.8"