contextfetch 0.1.0__tar.gz

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

contextfetch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

contextfetch-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: contextfetch
+Version: 0.1.0
+Summary: Python client for the ContextFetch API: web search and web pages as Markdown for AI agents.
+Project-URL: Homepage, https://contextfetch.dev
+Project-URL: Documentation, https://contextfetch.dev/docs/reference
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,contextfetch,llm,markdown,rag,search,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# contextfetch
+
+Python client for the [ContextFetch](https://contextfetch.dev) API: web search, pages as Markdown, extractive answers, research, crawl and site maps for AI agents.
+
+- No dependencies: standard library only (`urllib`, `json`).
+- Typed: ships `py.typed`; responses are `TypedDict`s.
+- Python 3.9 or newer.
+
+## Install
+
+```bash
+pip install contextfetch
+```
+
+## Quickstart
+
+```python
+from contextfetch import ContextFetch
+
+client = ContextFetch()  # reads CONTEXTFETCH_API_KEY; with no key it uses the keyless tier
+
+res = client.search("python asyncio timeout", num_results=5, highlights=True, pruned_context=True)
+for r in res["results"]:
+    print(r["url"], r.get("title"))
+    print(r.get("prunedContext", "")[:300])
+
+page = client.read("https://docs.python.org/3/library/asyncio-task.html", query="task groups")
+print(page.markdown)
+```
+
+No key yet? Get a free starter key (one per network, no signup):
+
+```python
+key = ContextFetch().free_key()["apiKey"]
+client = ContextFetch(key)
+```
+
+## Methods
+
+| Method | Endpoint |
+|---|---|
+| `search(query, *, num_results, include_domains, exclude_domains, start_published_date, text, highlights, pruned_context)` | `POST /v1/search` |
+| `find_similar(url, *, ...same options as search)` | `POST /v1/findSimilar` |
+| `contents(urls, *, text=True, highlights, pruned_context)` | `POST /v1/contents` |
+| `answer(query, *, num_results, text)` | `POST /v1/answer` (extractive: passages quoted verbatim with `[n]` citations) |
+| `research(query, *, sub_queries, num_results_per_query)` | `POST /v1/research` |
+| `crawl(url, *, limit, max_depth, max_breadth, query, include_paths, exclude_paths)` | `POST /v1/crawl` |
+| `map(url, *, limit, include_paths, exclude_paths)` | `POST /v1/map` |
+| `read(url, *, query)` | `GET /r/{url}`, returns a `Page` (`markdown`, `raw_tokens`, `output_tokens`, `token_savings`) |
+| `balance()` | `GET /v1/balance` |
+| `free_key()` | `POST /v1/keys/free` |
+
+`text`, `highlights` and `pruned_context` take `True` or an options object as described in the [API reference](https://contextfetch.dev/docs/reference), for example `highlights={"query": "task groups", "highlightsPerUrl": 2}`. Responses are the API's JSON as dicts, with the API's field names (`publishedDate`, `prunedContext`, ...).
+
+Options: `ContextFetch(api_key=None, *, base_url="https://api.contextfetch.dev", timeout=60.0)`.
+
+## Errors
+
+Every error is a `ContextFetchError` with `status`, `code` (the body's `error` field) and `body`.
+
+- `AuthenticationError`: HTTP 401, the key is not recognised.
+- `PaymentRequiredError`: HTTP 402, credits or the keyless allowance ran out. `payment_url` is a one-click checkout link and `prompt_to_user` is a sentence to show your user; stop retrying until they pay.
+- `APIConnectionError`: no response (DNS, connection or timeout).
+
+```python
+from contextfetch import ContextFetch, PaymentRequiredError
+
+try:
+    ContextFetch().search("rust async runtimes")
+except PaymentRequiredError as e:
+    print(e.prompt_to_user)  # includes e.payment_url
+```
+
+## Development
+
+```bash
+python -m unittest discover tests                                       # unit tests, local fake server
+CONTEXTFETCH_API_KEY=... python -m unittest tests.test_live -v          # live smoke test, a few credits
+```
+
+## License
+
+MIT

contextfetch-0.1.0/README.md

@@ -0,0 +1,83 @@
+# contextfetch
+
+Python client for the [ContextFetch](https://contextfetch.dev) API: web search, pages as Markdown, extractive answers, research, crawl and site maps for AI agents.
+
+- No dependencies: standard library only (`urllib`, `json`).
+- Typed: ships `py.typed`; responses are `TypedDict`s.
+- Python 3.9 or newer.
+
+## Install
+
+```bash
+pip install contextfetch
+```
+
+## Quickstart
+
+```python
+from contextfetch import ContextFetch
+
+client = ContextFetch()  # reads CONTEXTFETCH_API_KEY; with no key it uses the keyless tier
+
+res = client.search("python asyncio timeout", num_results=5, highlights=True, pruned_context=True)
+for r in res["results"]:
+    print(r["url"], r.get("title"))
+    print(r.get("prunedContext", "")[:300])
+
+page = client.read("https://docs.python.org/3/library/asyncio-task.html", query="task groups")
+print(page.markdown)
+```
+
+No key yet? Get a free starter key (one per network, no signup):
+
+```python
+key = ContextFetch().free_key()["apiKey"]
+client = ContextFetch(key)
+```
+
+## Methods
+
+| Method | Endpoint |
+|---|---|
+| `search(query, *, num_results, include_domains, exclude_domains, start_published_date, text, highlights, pruned_context)` | `POST /v1/search` |
+| `find_similar(url, *, ...same options as search)` | `POST /v1/findSimilar` |
+| `contents(urls, *, text=True, highlights, pruned_context)` | `POST /v1/contents` |
+| `answer(query, *, num_results, text)` | `POST /v1/answer` (extractive: passages quoted verbatim with `[n]` citations) |
+| `research(query, *, sub_queries, num_results_per_query)` | `POST /v1/research` |
+| `crawl(url, *, limit, max_depth, max_breadth, query, include_paths, exclude_paths)` | `POST /v1/crawl` |
+| `map(url, *, limit, include_paths, exclude_paths)` | `POST /v1/map` |
+| `read(url, *, query)` | `GET /r/{url}`, returns a `Page` (`markdown`, `raw_tokens`, `output_tokens`, `token_savings`) |
+| `balance()` | `GET /v1/balance` |
+| `free_key()` | `POST /v1/keys/free` |
+
+`text`, `highlights` and `pruned_context` take `True` or an options object as described in the [API reference](https://contextfetch.dev/docs/reference), for example `highlights={"query": "task groups", "highlightsPerUrl": 2}`. Responses are the API's JSON as dicts, with the API's field names (`publishedDate`, `prunedContext`, ...).
+
+Options: `ContextFetch(api_key=None, *, base_url="https://api.contextfetch.dev", timeout=60.0)`.
+
+## Errors
+
+Every error is a `ContextFetchError` with `status`, `code` (the body's `error` field) and `body`.
+
+- `AuthenticationError`: HTTP 401, the key is not recognised.
+- `PaymentRequiredError`: HTTP 402, credits or the keyless allowance ran out. `payment_url` is a one-click checkout link and `prompt_to_user` is a sentence to show your user; stop retrying until they pay.
+- `APIConnectionError`: no response (DNS, connection or timeout).
+
+```python
+from contextfetch import ContextFetch, PaymentRequiredError
+
+try:
+    ContextFetch().search("rust async runtimes")
+except PaymentRequiredError as e:
+    print(e.prompt_to_user)  # includes e.payment_url
+```
+
+## Development
+
+```bash
+python -m unittest discover tests                                       # unit tests, local fake server
+CONTEXTFETCH_API_KEY=... python -m unittest tests.test_live -v          # live smoke test, a few credits
+```
+
+## License
+
+MIT

contextfetch-0.1.0/contextfetch/__init__.py

@@ -0,0 +1,404 @@
+"""ContextFetch: web search and web pages as Markdown for AI agents.
+
+A thin client for https://api.contextfetch.dev that uses only the Python standard library.
+API reference: https://contextfetch.dev/docs/reference
+"""
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from email.message import Message
+from typing import Any, Dict, List, Optional, Tuple, TypedDict, Union
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "APIConnectionError",
+    "AnswerResponse",
+    "AuthenticationError",
+    "Balance",
+    "ContentsResponse",
+    "ContextFetch",
+    "ContextFetchError",
+    "CrawlResponse",
+    "DEFAULT_BASE_URL",
+    "FreeKey",
+    "MapResponse",
+    "Page",
+    "PaymentRequiredError",
+    "ResearchResponse",
+    "Result",
+    "SearchResponse",
+]
+
+DEFAULT_BASE_URL = "https://api.contextfetch.dev"
+
+# A contents option: True, or an options object as the API reference describes it,
+# e.g. highlights={"query": "task groups", "highlightsPerUrl": 2}.
+Option = Union[bool, Dict[str, Any]]
+
+
+# ---- responses (JSON as the API returns it; every key is optional) ----
+
+
+class Result(TypedDict, total=False):
+    id: str
+    url: str
+    title: Optional[str]
+    score: Optional[float]
+    publishedDate: Optional[str]
+    author: Optional[str]
+    text: str  # the page as Markdown
+    highlights: List[str]
+    highlightScores: List[float]
+    prunedContext: str
+    subQueries: List[str]  # research: the sub-queries that found this page
+    depth: int  # crawl: link hops from the start URL
+
+
+class SearchResponse(TypedDict, total=False):
+    requestId: str
+    results: List[Result]
+    costDollars: Dict[str, float]
+    searchTimeMs: float
+    contextfetch: Dict[str, Any]  # cache, timingsMs, tokens, sources
+    notice: str
+
+
+class ContentsResponse(SearchResponse, total=False):
+    statuses: List[Dict[str, Any]]  # one per URL: {"id", "status": "success" | "error", "error"?}
+
+
+class ResearchResponse(SearchResponse, total=False):
+    query: str
+    subQueries: List[Dict[str, Any]]  # {"query", "status", "results"}
+    evidence: str  # one Markdown document with numbered [n] sources quoted verbatim
+
+
+class CrawlResponse(SearchResponse, total=False):
+    baseUrl: str
+
+
+class Citation(TypedDict, total=False):
+    id: str
+    url: str
+    title: Optional[str]
+    publishedDate: Optional[str]
+    author: Optional[str]
+    text: str
+
+
+class Passage(TypedDict, total=False):
+    text: str
+    score: float
+    citation: int  # 1-based index into citations
+
+
+class AnswerResponse(TypedDict, total=False):
+    answer: str  # passages quoted verbatim, each followed by [n]; "" when nothing is relevant enough
+    type: str  # always "extractive"
+    note: str
+    citations: List[Citation]
+    passages: List[Passage]
+    costDollars: Dict[str, float]
+    contextfetch: Dict[str, Any]
+    notice: str
+
+
+class MapResponse(TypedDict, total=False):
+    requestId: str
+    baseUrl: str
+    results: List[str]
+    costDollars: Dict[str, float]
+    contextfetch: Dict[str, Any]
+    notice: str
+
+
+class Balance(TypedDict, total=False):
+    credits: int
+    auto_reload: Dict[str, Any]
+    burn_rate_per_day: float
+
+
+class FreeKey(TypedDict, total=False):
+    apiKey: str
+    credits: int
+    buy: Dict[str, str]  # pack id -> checkout link
+
+
+@dataclass(frozen=True)
+class Page:
+    """A page read through GET /r/{url}."""
+
+    url: str
+    markdown: str
+    raw_tokens: Optional[int] = None  # X-Raw-Tokens
+    output_tokens: Optional[int] = None  # X-Output-Tokens
+    token_savings: Optional[float] = None  # X-Token-Savings, percent
+
+
+# ---- errors ----
+
+
+class ContextFetchError(Exception):
+    """An API or transport error.
+
+    status is the HTTP status (None when no response arrived), code the body's "error" field
+    (e.g. "invalid_api_key", "recall_unavailable") and body the parsed JSON body, if any.
+    """
+
+    def __init__(self, message: str, status: Optional[int] = None, code: Optional[str] = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body = body
+
+
+class AuthenticationError(ContextFetchError):
+    """HTTP 401: the API key is not recognised."""
+
+
+class PaymentRequiredError(ContextFetchError):
+    """HTTP 402: the key's credits or the keyless daily allowance ran out.
+
+    Show prompt_to_user to your human and stop retrying. payment_url (the X-Payment-URL header)
+    opens Stripe Checkout in one click; packs lists every pack with its own checkout_url.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        body: Any = None,
+        payment_url: Optional[str] = None,
+        prompt_to_user: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status, code, body)
+        self.payment_url = payment_url
+        self.prompt_to_user = prompt_to_user
+        self.packs: List[Dict[str, Any]] = (body.get("packs") or []) if isinstance(body, dict) else []
+
+
+class APIConnectionError(ContextFetchError):
+    """No HTTP response: DNS, connection or timeout failure."""
+
+
+# ---- client ----
+
+
+class ContextFetch:
+    """Client for the ContextFetch API.
+
+    api_key defaults to the CONTEXTFETCH_API_KEY environment variable. With no key the client uses the
+    keyless tier (a small daily allowance per IP); free_key() returns a starter key with no signup.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 60.0) -> None:
+        self.api_key = (api_key if api_key is not None else os.environ.get("CONTEXTFETCH_API_KEY")) or None
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def search(
+        self,
+        query: str,
+        *,
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_published_date: Optional[str] = None,
+        text: Option = False,
+        highlights: Option = False,
+        pruned_context: Option = False,
+    ) -> SearchResponse:
+        """POST /v1/search. Results carry page text, highlights or prunedContext only when asked for."""
+        body = {
+            "query": query,
+            "numResults": num_results,
+            "includeDomains": include_domains,
+            "excludeDomains": exclude_domains,
+            "startPublishedDate": start_published_date,
+            "contents": _contents(text, highlights, pruned_context),
+        }
+        return self._post("/v1/search", body)  # type: ignore[return-value]
+
+    def find_similar(
+        self,
+        url: str,
+        *,
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_published_date: Optional[str] = None,
+        text: Option = False,
+        highlights: Option = False,
+        pruned_context: Option = False,
+    ) -> SearchResponse:
+        """POST /v1/findSimilar: pages like url, from other domains. Same shape as search()."""
+        body = {
+            "url": url,
+            "numResults": num_results,
+            "includeDomains": include_domains,
+            "excludeDomains": exclude_domains,
+            "startPublishedDate": start_published_date,
+            "contents": _contents(text, highlights, pruned_context),
+        }
+        return self._post("/v1/findSimilar", body)  # type: ignore[return-value]
+
+    def contents(
+        self,
+        urls: List[str],
+        *,
+        text: Option = True,
+        highlights: Option = False,
+        pruned_context: Option = False,
+    ) -> ContentsResponse:
+        """POST /v1/contents: pages as Markdown. URLs that fail come back in statuses and are not billed."""
+        body = {"urls": list(urls), "text": text, "highlights": highlights or None, "pruned_context": pruned_context or None}
+        return self._post("/v1/contents", body)  # type: ignore[return-value]
+
+    def answer(self, query: str, *, num_results: Optional[int] = None, text: bool = False) -> AnswerResponse:
+        """POST /v1/answer: an extractive answer, passages quoted verbatim with [n] citations. Nothing is generated."""
+        return self._post("/v1/answer", {"query": query, "numResults": num_results, "text": text or None})  # type: ignore[return-value]
+
+    def research(
+        self,
+        query: str,
+        *,
+        sub_queries: Optional[List[str]] = None,
+        num_results_per_query: Optional[int] = None,
+    ) -> ResearchResponse:
+        """POST /v1/research: several searches in one call, ranked together into an evidence pack."""
+        body = {"query": query, "subQueries": sub_queries, "numResultsPerQuery": num_results_per_query}
+        return self._post("/v1/research", body)  # type: ignore[return-value]
+
+    def crawl(
+        self,
+        url: str,
+        *,
+        limit: Optional[int] = None,
+        max_depth: Optional[int] = None,
+        max_breadth: Optional[int] = None,
+        query: Optional[str] = None,
+        include_paths: Optional[List[str]] = None,
+        exclude_paths: Optional[List[str]] = None,
+    ) -> CrawlResponse:
+        """POST /v1/crawl: one site from a start URL, every page as Markdown. robots.txt is obeyed."""
+        body = {
+            "url": url,
+            "limit": limit,
+            "maxDepth": max_depth,
+            "maxBreadth": max_breadth,
+            "query": query,
+            "includePaths": include_paths,
+            "excludePaths": exclude_paths,
+        }
+        return self._post("/v1/crawl", body)  # type: ignore[return-value]
+
+    def map(
+        self,
+        url: str,
+        *,
+        limit: Optional[int] = None,
+        include_paths: Optional[List[str]] = None,
+        exclude_paths: Optional[List[str]] = None,
+    ) -> MapResponse:
+        """POST /v1/map: a site's URLs from its links and sitemaps, without fetching the pages."""
+        body = {"url": url, "limit": limit, "includePaths": include_paths, "excludePaths": exclude_paths}
+        return self._post("/v1/map", body)  # type: ignore[return-value]
+
+    def read(self, url: str, *, query: Optional[str] = None) -> Page:
+        """GET /r/{url}: any public URL as Markdown. With query, only the chunks relevant to it."""
+        target = urllib.parse.urldefrag(url)[0]
+        path = "/r/" + urllib.parse.quote(target, safe=":/?&=%@+,;~!$'()*[]")
+        if query:
+            path += ("&" if "?" in target else "?") + urllib.parse.urlencode({"q": query})
+        raw, headers = self._request("GET", path)
+        return Page(
+            url=target,
+            markdown=raw.decode("utf-8", "replace"),
+            raw_tokens=_number(headers.get("X-Raw-Tokens"), int),
+            output_tokens=_number(headers.get("X-Output-Tokens"), int),
+            token_savings=_number(headers.get("X-Token-Savings"), float),
+        )
+
+    def balance(self) -> Balance:
+        """GET /v1/balance: credits left on this key and its auto-reload settings. Free."""
+        return _json(self._request("GET", "/v1/balance")[0])  # type: ignore[return-value]
+
+    def free_key(self) -> FreeKey:
+        """POST /v1/keys/free: a free starter key, one per network. Sent without this client's key."""
+        return _json(self._request("POST", "/v1/keys/free", auth=False)[0])  # type: ignore[return-value]
+
+    # ---- transport ----
+
+    def _post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        return _json(self._request("POST", path, {k: v for k, v in body.items() if v is not None})[0])
+
+    def _request(
+        self, method: str, path: str, body: Optional[Dict[str, Any]] = None, auth: bool = True
+    ) -> Tuple[bytes, Message]:
+        headers = {"User-Agent": f"contextfetch-python/{__version__}"}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if auth and self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        req = urllib.request.Request(self.base_url + path, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                return res.read(), res.headers
+        except urllib.error.HTTPError as e:
+            raise _api_error(e.code, e.read(), e.headers) from None
+        except (urllib.error.URLError, OSError) as e:  # OSError covers timeouts
+            reason = getattr(e, "reason", None) or e
+            raise APIConnectionError(f"Could not reach the ContextFetch API at {self.base_url}: {reason}") from e
+
+
+def _contents(text: Option, highlights: Option, pruned_context: Option) -> Optional[Dict[str, Option]]:
+    wanted = {"text": text, "highlights": highlights, "pruned_context": pruned_context}
+    return {k: v for k, v in wanted.items() if v} or None
+
+
+def _json(raw: bytes) -> Dict[str, Any]:
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        data = None
+    if not isinstance(data, dict):
+        raise ContextFetchError(f"The ContextFetch API returned an unreadable response: {raw[:200]!r}")
+    return data
+
+
+def _number(value: Optional[str], kind: Any) -> Any:
+    try:
+        return kind(value) if value is not None else None
+    except ValueError:
+        return None
+
+
+def _api_error(status: int, raw: bytes, headers: Message) -> ContextFetchError:
+    try:
+        body: Any = json.loads(raw)
+    except ValueError:
+        body = None
+    info: Dict[str, Any] = body if isinstance(body, dict) else {}
+    code = info.get("error") if isinstance(info.get("error"), str) else None
+    detail = info.get("message") or info.get("detail") or code or raw.decode("utf-8", "replace")[:300]
+    if not isinstance(detail, str):
+        detail = json.dumps(detail)[:300]
+    message = f"ContextFetch API returned HTTP {status}" + (f" ({code})" if code else "") + (f": {detail}" if detail and detail != code else "")
+    if status == 401:
+        return AuthenticationError(message, status, code, body)
+    if status == 402:
+        action: Dict[str, Any] = info["action"] if isinstance(info.get("action"), dict) else {}
+        prompt = action.get("prompt_to_user")
+        if prompt and prompt not in message:
+            message += f" {prompt}"
+        return PaymentRequiredError(message, status, code, body, headers.get("X-Payment-URL") or action.get("url"), prompt)
+    return ContextFetchError(message, status, code, body)

contextfetch-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "contextfetch"
+version = "0.1.0"
+description = "Python client for the ContextFetch API: web search and web pages as Markdown for AI agents."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = []
+keywords = ["search", "web-search", "markdown", "ai-agents", "llm", "rag", "contextfetch"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://contextfetch.dev"
+Documentation = "https://contextfetch.dev/docs/reference"
+
+[tool.hatch.build.targets.sdist]
+include = ["contextfetch", "tests", "README.md", "LICENSE"]

contextfetch-0.1.0/tests/test_client.py

@@ -0,0 +1,204 @@
+"""Unit tests against a local fake of the API (stdlib http.server). No network."""
+
+import json
+import os
+import socket
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from unittest import mock
+
+from contextfetch import (
+    APIConnectionError,
+    AuthenticationError,
+    ContextFetch,
+    ContextFetchError,
+    Page,
+    PaymentRequiredError,
+)
+
+PAY_URL = "https://api.contextfetch.dev/buy/instant"
+PAYMENT_BODY = {
+    "error": "insufficient_credits",
+    "message": "This key is out of credits.",
+    "checkout_url": "https://contextfetch.dev/#buy",
+    "packs": [{"id": "instant", "credits": 1000, "checkout_url": PAY_URL}],
+    "action": {"type": "payment_link", "url": PAY_URL, "prompt_to_user": f"ContextFetch credits ran out: {PAY_URL}"},
+}
+
+
+class Handler(BaseHTTPRequestHandler):
+    def handle_any(self) -> None:
+        length = int(self.headers.get("Content-Length") or 0)
+        raw = self.rfile.read(length) if length else b""
+        self.server.requests.append(  # type: ignore[attr-defined]
+            {"method": self.command, "path": self.path, "headers": self.headers, "body": json.loads(raw) if raw else None}
+        )
+        status, headers, payload = self.server.reply  # type: ignore[attr-defined]
+        data = payload if isinstance(payload, bytes) else json.dumps(payload).encode()
+        self.send_response(status)
+        for k, v in headers.items():
+            self.send_header(k, v)
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    do_GET = do_POST = handle_any
+
+    def log_message(self, *args: object) -> None:
+        pass
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.base = f"http://127.0.0.1:{cls.server.server_address[1]}"
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def setUp(self) -> None:
+        self.server.requests = []
+        self.server.reply = (200, {"Content-Type": "application/json"}, {"results": []})
+        self.client = ContextFetch("cf_live_test", base_url=self.base + "/")
+
+    @property
+    def last(self) -> dict:
+        return self.server.requests[-1]
+
+    def test_search_sends_key_and_camel_case_body(self) -> None:
+        self.server.reply = (200, {}, {"requestId": "r1", "results": [{"url": "https://a.example", "text": "# A"}]})
+        out = self.client.search("vector databases", num_results=3, exclude_domains=["pinterest.com"], text=True, pruned_context=True)
+        self.assertEqual(out["results"][0]["text"], "# A")
+        self.assertEqual((self.last["method"], self.last["path"]), ("POST", "/v1/search"))
+        self.assertEqual(self.last["headers"]["Authorization"], "Bearer cf_live_test")
+        self.assertTrue(self.last["headers"]["User-Agent"].startswith("contextfetch-python/"))
+        self.assertEqual(
+            self.last["body"],
+            {"query": "vector databases", "numResults": 3, "excludeDomains": ["pinterest.com"], "contents": {"text": True, "pruned_context": True}},
+        )
+
+    def test_search_without_contents_omits_it(self) -> None:
+        self.client.search("q")
+        self.assertEqual(self.last["body"], {"query": "q"})
+
+    def test_endpoint_bodies(self) -> None:
+        cases = [
+            (lambda c: c.find_similar("https://a.example", num_results=2, highlights={"query": "x"}), "/v1/findSimilar",
+             {"url": "https://a.example", "numResults": 2, "contents": {"highlights": {"query": "x"}}}),
+            (lambda c: c.contents(["https://a.example"]), "/v1/contents", {"urls": ["https://a.example"], "text": True}),
+            (lambda c: c.contents(("https://a.example",), text=False, highlights=True), "/v1/contents",
+             {"urls": ["https://a.example"], "text": False, "highlights": True}),
+            (lambda c: c.answer("why?", num_results=4, text=True), "/v1/answer", {"query": "why?", "numResults": 4, "text": True}),
+            (lambda c: c.research("topic", sub_queries=["a", "b"], num_results_per_query=2), "/v1/research",
+             {"query": "topic", "subQueries": ["a", "b"], "numResultsPerQuery": 2}),
+            (lambda c: c.crawl("https://a.example", limit=5, max_depth=2, query="t", include_paths=["/docs"]), "/v1/crawl",
+             {"url": "https://a.example", "limit": 5, "maxDepth": 2, "query": "t", "includePaths": ["/docs"]}),
+            (lambda c: c.map("https://a.example", limit=50, exclude_paths=["/blog"]), "/v1/map",
+             {"url": "https://a.example", "limit": 50, "excludePaths": ["/blog"]}),
+        ]
+        for call, path, body in cases:
+            with self.subTest(path=path):
+                call(self.client)
+                self.assertEqual((self.last["method"], self.last["path"], self.last["body"]), ("POST", path, body))
+
+    def test_balance_is_a_get_with_the_key(self) -> None:
+        self.server.reply = (200, {}, {"credits": 2499, "auto_reload": {"enabled": False}, "burn_rate_per_day": 1})
+        self.assertEqual(self.client.balance()["credits"], 2499)
+        self.assertEqual((self.last["method"], self.last["path"], self.last["body"]), ("GET", "/v1/balance", None))
+        self.assertEqual(self.last["headers"]["Authorization"], "Bearer cf_live_test")
+
+    def test_free_key_is_sent_without_a_key(self) -> None:
+        self.server.reply = (201, {}, {"apiKey": "cf_live_" + "0" * 32, "credits": 2500})
+        self.assertEqual(self.client.free_key()["credits"], 2500)
+        self.assertEqual((self.last["method"], self.last["path"]), ("POST", "/v1/keys/free"))
+        self.assertIsNone(self.last["headers"].get("Authorization"))
+
+    def test_keyless_when_no_key_anywhere(self) -> None:
+        with mock.patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("CONTEXTFETCH_API_KEY", None)
+            ContextFetch(base_url=self.base).search("q")
+        self.assertIsNone(self.last["headers"].get("Authorization"))
+
+    def test_key_from_environment(self) -> None:
+        with mock.patch.dict(os.environ, {"CONTEXTFETCH_API_KEY": "cf_live_env"}):
+            ContextFetch(base_url=self.base).search("q")
+        self.assertEqual(self.last["headers"]["Authorization"], "Bearer cf_live_env")
+
+    def test_read_returns_markdown_and_token_headers(self) -> None:
+        headers = {"Content-Type": "text/markdown; charset=utf-8", "X-Token-Savings": "91.0", "X-Raw-Tokens": "18240", "X-Output-Tokens": "1650"}
+        self.server.reply = (200, headers, "## Task Groups\n\nÜnïcode".encode())
+        page = self.client.read("https://docs.python.org/3/library/asyncio-task.html#frag", query="task groups")
+        self.assertEqual(page, Page("https://docs.python.org/3/library/asyncio-task.html", "## Task Groups\n\nÜnïcode", 18240, 1650, 91.0))
+        self.assertEqual(self.last["path"], "/r/https://docs.python.org/3/library/asyncio-task.html?q=task+groups")
+
+    def test_read_keeps_the_target_query_and_encodes_spaces(self) -> None:
+        self.server.reply = (200, {}, b"x")
+        page = self.client.read("https://a.example/a b?id=1", query="q")
+        self.assertEqual(self.last["path"], "/r/https://a.example/a%20b?id=1&q=q")
+        self.assertIsNone(page.raw_tokens)
+
+    def test_402_exposes_payment_link(self) -> None:
+        self.server.reply = (402, {"X-Payment-URL": PAY_URL}, PAYMENT_BODY)
+        with self.assertRaises(PaymentRequiredError) as ctx:
+            self.client.search("q")
+        e = ctx.exception
+        self.assertEqual((e.status, e.code, e.payment_url), (402, "insufficient_credits", PAY_URL))
+        self.assertEqual(e.prompt_to_user, PAYMENT_BODY["action"]["prompt_to_user"])
+        self.assertEqual(e.packs[0]["id"], "instant")
+        self.assertIn(PAY_URL, str(e))
+
+    def test_402_without_header_falls_back_to_action_url(self) -> None:
+        self.server.reply = (402, {}, PAYMENT_BODY)
+        with self.assertRaises(PaymentRequiredError) as ctx:
+            self.client.read("https://a.example")
+        self.assertEqual(ctx.exception.payment_url, PAY_URL)
+
+    def test_401_is_authentication_error(self) -> None:
+        self.server.reply = (401, {}, {"error": "invalid_api_key"})
+        with self.assertRaises(AuthenticationError) as ctx:
+            self.client.balance()
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (401, "invalid_api_key"))
+
+    def test_other_errors_carry_status_code_and_message(self) -> None:
+        self.server.reply = (503, {}, {"error": "recall_unavailable", "message": "Web search backends are down."})
+        with self.assertRaises(ContextFetchError) as ctx:
+            self.client.search("q")
+        e = ctx.exception
+        self.assertNotIsInstance(e, PaymentRequiredError)
+        self.assertEqual((e.status, e.code), (503, "recall_unavailable"))
+        self.assertIn("Web search backends are down.", str(e))
+
+    def test_validation_error_detail_is_in_the_message(self) -> None:
+        self.server.reply = (422, {}, {"detail": [{"loc": ["body", "query"], "msg": "too long"}]})
+        with self.assertRaises(ContextFetchError) as ctx:
+            self.client.search("q")
+        self.assertIn("too long", str(ctx.exception))
+
+    def test_non_json_error_body(self) -> None:
+        self.server.reply = (502, {"Content-Type": "text/html"}, b"<html>Bad Gateway</html>")
+        with self.assertRaises(ContextFetchError) as ctx:
+            self.client.search("q")
+        self.assertEqual((ctx.exception.status, ctx.exception.code, ctx.exception.body), (502, None, None))
+        self.assertIn("Bad Gateway", str(ctx.exception))
+
+    def test_unreadable_success_body(self) -> None:
+        self.server.reply = (200, {}, b"not json")
+        with self.assertRaises(ContextFetchError):
+            self.client.search("q")
+
+    def test_connection_failure(self) -> None:
+        with socket.socket() as s:
+            s.bind(("127.0.0.1", 0))
+            port = s.getsockname()[1]
+        with self.assertRaises(APIConnectionError) as ctx:
+            ContextFetch("k", base_url=f"http://127.0.0.1:{port}", timeout=5).search("q")
+        self.assertIsNone(ctx.exception.status)
+
+
+if __name__ == "__main__":
+    unittest.main()

contextfetch-0.1.0/tests/test_live.py

@@ -0,0 +1,34 @@
+"""Live smoke test against the real API. Runs only when CONTEXTFETCH_API_KEY is set; uses about 3 credits."""
+
+import os
+import unittest
+
+from contextfetch import ContextFetch
+
+ZEN = "https://peps.python.org/pep-0020/"
+
+
+@unittest.skipUnless(os.environ.get("CONTEXTFETCH_API_KEY"), "CONTEXTFETCH_API_KEY not set")
+class LiveTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.client = ContextFetch(base_url=os.environ.get("CONTEXTFETCH_API_BASE", "https://api.contextfetch.dev"))
+
+    def test_balance(self) -> None:
+        self.assertIsInstance(self.client.balance()["credits"], int)
+
+    def test_search(self) -> None:
+        out = self.client.search("python asyncio timeout", num_results=3, highlights=True)
+        self.assertGreater(len(out["results"]), 0)
+        self.assertTrue(out["results"][0]["url"].startswith("http"))
+
+    def test_read(self) -> None:
+        page = self.client.read(ZEN)
+        self.assertIn("Beautiful is better than ugly", page.markdown)
+
+    def test_contents(self) -> None:
+        out = self.client.contents([ZEN])
+        self.assertIn("Beautiful is better than ugly", out["results"][0]["text"])
+
+
+if __name__ == "__main__":
+    unittest.main()