keenable 0.1.0__py3-none-any.whl

keenable/__init__.py

@@ -0,0 +1,44 @@
+"""Keenable: web search and page fetch for AI agents.
+
+Keyless by default. ``Keenable()`` works with no account; an API key only lifts
+the hourly rate limit.
+
+    from keenable import Keenable
+
+    keenable = Keenable()
+    results = keenable.search("fastest inference providers 2026")
+    context = results.to_context()
+"""
+
+from .client import DEFAULT_BASE_URL, AsyncKeenable, Keenable
+from .errors import (
+    KeenableAPIError,
+    KeenableAuthError,
+    KeenableConnectionError,
+    KeenableError,
+    KeenableInvalidRequestError,
+    KeenableRateLimitError,
+)
+from .models import Page, SearchResponse, SearchResult
+from .tools import FETCH_TOOL, SEARCH_TOOL, TOOLS, run_tool_call
+
+__all__ = [
+    "AsyncKeenable",
+    "DEFAULT_BASE_URL",
+    "FETCH_TOOL",
+    "Keenable",
+    "KeenableAPIError",
+    "KeenableAuthError",
+    "KeenableConnectionError",
+    "KeenableError",
+    "KeenableInvalidRequestError",
+    "KeenableRateLimitError",
+    "Page",
+    "SEARCH_TOOL",
+    "SearchResponse",
+    "SearchResult",
+    "TOOLS",
+    "run_tool_call",
+]
+
+__version__ = "0.1.0"

keenable/client.py

@@ -0,0 +1,401 @@
+"""Sync and async clients for the Keenable API."""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from .errors import (
+    KeenableAPIError,
+    KeenableAuthError,
+    KeenableConnectionError,
+    KeenableInvalidRequestError,
+    KeenableRateLimitError,
+)
+from .models import Page, SearchResponse
+
+__all__ = ["Keenable", "AsyncKeenable"]
+
+try:  # pragma: no cover - trivial
+    from importlib import metadata
+
+    _VERSION = metadata.version("keenable")
+except Exception:  # pragma: no cover - source checkouts
+    _VERSION = "unknown"
+
+DEFAULT_BASE_URL = "https://api.keenable.ai"
+DEFAULT_TIMEOUT = 30.0
+
+# Keyless endpoints. A key is not a prerequisite for any call: it only lifts
+# the hourly rate limit, so the client picks the endpoint by key presence.
+_SEARCH_PUBLIC = "/v1/search/public"
+_SEARCH_KEYED = "/v1/search"
+_FETCH_PUBLIC = "/v1/fetch/public"
+_FETCH_KEYED = "/v1/fetch"
+
+
+def _resolve_base_url(base_url: str | None) -> str:
+    """Resolve and validate the API base URL, enforcing HTTPS off-localhost."""
+    base = (base_url or os.environ.get("KEENABLE_API_URL") or DEFAULT_BASE_URL).rstrip(
+        "/"
+    )
+    parsed = urlsplit(base)
+    if parsed.hostname:
+        if parsed.scheme == "https":
+            return base
+        if parsed.scheme == "http" and parsed.hostname in {
+            "localhost",
+            "127.0.0.1",
+            "::1",
+        }:
+            return base
+    raise KeenableInvalidRequestError(
+        f"base_url must be an https:// URL with a host, got {base!r}"
+    )
+
+
+def _reject_private_fetch_target(url: str) -> None:
+    """Refuse obviously internal fetch targets before a request leaves the host.
+
+    The backend enforces this too, but stopping here keeps an internal hostname
+    out of an outbound request in the first place.
+    """
+    if not url.lower().startswith(("http://", "https://")):
+        raise KeenableInvalidRequestError(f"fetch() needs an http(s) URL, got {url!r}")
+
+    host = (urlsplit(url).hostname or "").strip().lower()
+    if not host:
+        raise KeenableInvalidRequestError(f"fetch() URL has no host: {url!r}")
+    if host in {"localhost", "metadata.google.internal"}:
+        raise KeenableInvalidRequestError(f"refusing to fetch internal host {host!r}")
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return  # A hostname; the backend's SSRF guard is the backstop.
+    if (
+        ip.is_loopback
+        or ip.is_private
+        or ip.is_link_local
+        or ip.is_reserved
+        or ip.is_multicast
+        or ip.is_unspecified
+    ):
+        raise KeenableInvalidRequestError(f"refusing to fetch private address {host!r}")
+
+
+def _search_payload(
+    query: str,
+    mode: str | None,
+    site: str | None,
+    published_after: str | None,
+    published_before: str | None,
+    acquired_after: str | None,
+    acquired_before: str | None,
+    snippet_max_length: int | None,
+) -> dict[str, Any]:
+    if not query or not query.strip():
+        raise KeenableInvalidRequestError("search() needs a non-empty query")
+
+    payload: dict[str, Any] = {"query": query, "mode": mode or "pro"}
+    optional = (
+        ("site", site),
+        ("published_after", published_after),
+        ("published_before", published_before),
+        ("acquired_after", acquired_after),
+        ("acquired_before", acquired_before),
+        ("snippet_max_length", snippet_max_length),
+    )
+    for name, value in optional:
+        if value is not None:
+            payload[name] = value
+    return payload
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Turn a non-2xx response into the most specific SDK error available."""
+    if response.is_success:
+        return
+
+    detail = ""
+    try:
+        body = response.json()
+        if isinstance(body, dict):
+            detail = str(
+                body.get("message") or body.get("error") or body.get("detail") or ""
+            )
+    except ValueError:
+        detail = (response.text or "").strip()
+
+    status = response.status_code
+    label = {
+        401: "Keenable authentication failed (401)",
+        403: "Keenable authentication failed (403)",
+        402: "Keenable: insufficient credits (402)",
+        429: "Keenable rate limit exceeded (429)",
+    }.get(status, f"Keenable API error ({status})")
+    message = f"{label}: {detail}" if detail else label
+
+    if status in (401, 403):
+        raise KeenableAuthError(message, status, detail or None)
+    if status == 429:
+        raise KeenableRateLimitError(message, status, detail or None)
+    raise KeenableAPIError(message, status, detail or None)
+
+
+def _decode(response: httpx.Response) -> dict[str, Any]:
+    _raise_for_status(response)
+    try:
+        data = response.json()
+    except ValueError as exc:
+        snippet = (response.text or "")[:200]
+        raise KeenableAPIError(
+            f"Keenable API returned a non-JSON response: {snippet!r}",
+            response.status_code,
+        ) from exc
+    if not isinstance(data, dict):
+        raise KeenableAPIError(
+            f"Unexpected response from the Keenable API: {data!r}",
+            response.status_code,
+        )
+    return data
+
+
+class _BaseClient:
+    """Shared configuration for the sync and async clients."""
+
+    _sdk_flavor = "python"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("KEENABLE_API_KEY")
+        self._api_key = (key or "").strip() or None
+        self._base_url = _resolve_base_url(base_url)
+        self._timeout = timeout
+
+    @property
+    def keyless(self) -> bool:
+        """True when no API key is configured and the public tier is in use."""
+        return self._api_key is None
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "User-Agent": f"keenable-{self._sdk_flavor}/{_VERSION}",
+            "X-Keenable-Title": "Keenable SDK (Python)",
+        }
+        if self._api_key is not None:
+            headers["X-API-Key"] = self._api_key
+        return headers
+
+    def _search_url(self) -> str:
+        path = _SEARCH_PUBLIC if self._api_key is None else _SEARCH_KEYED
+        return f"{self._base_url}{path}"
+
+    def _fetch_url(self) -> str:
+        path = _FETCH_PUBLIC if self._api_key is None else _FETCH_KEYED
+        return f"{self._base_url}{path}"
+
+
+class Keenable(_BaseClient):
+    """Synchronous client for the Keenable web search API.
+
+    Keyless by default: with no API key the client calls the public endpoints,
+    which are rate limited per hour. Pass ``api_key`` (or set
+    ``KEENABLE_API_KEY``) to lift that limit. Create a key at
+    https://keenable.ai/console.
+
+    Example:
+        >>> from keenable import Keenable
+        >>> keenable = Keenable()
+        >>> results = keenable.search("cerebras inference benchmarks")
+        >>> print(results.to_context())
+
+    The client can be reused across calls and is safe to keep for the lifetime
+    of your process. Use it as a context manager (or call :meth:`close`) to
+    release the underlying connection pool.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout)
+        self._client = client or httpx.Client(timeout=timeout)
+        self._owns_client = client is None
+
+    def __enter__(self) -> Keenable:
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        if self._owns_client:
+            self._client.close()
+
+    def search(
+        self,
+        query: str,
+        *,
+        mode: str | None = None,
+        site: str | None = None,
+        published_after: str | None = None,
+        published_before: str | None = None,
+        acquired_after: str | None = None,
+        acquired_before: str | None = None,
+        snippet_max_length: int | None = None,
+    ) -> SearchResponse:
+        """Search the web and return ranked results with page text.
+
+        Args:
+            query: What to look for. Describe the ideal page in natural
+                language ("blog post comparing React and Vue performance")
+                rather than typing keywords; the index is semantic.
+            mode: Search mode. ``"pro"`` (the default) does deeper retrieval.
+            site: Restrict results to one domain, e.g. ``"arxiv.org"``.
+            published_after: Keep pages published on or after ``YYYY-MM-DD``.
+            published_before: Keep pages published on or before ``YYYY-MM-DD``.
+            acquired_after: Keep pages Keenable indexed on or after
+                ``YYYY-MM-DD``. Use this for "what is new since ..." queries,
+                where the publication date is unreliable or missing.
+            acquired_before: Keep pages indexed on or before ``YYYY-MM-DD``.
+            snippet_max_length: Cap the characters of page text per result.
+
+        Returns:
+            A :class:`SearchResponse`; iterate it for results or call
+            :meth:`SearchResponse.to_context` to build a prompt block.
+        """
+        payload = _search_payload(
+            query,
+            mode,
+            site,
+            published_after,
+            published_before,
+            acquired_after,
+            acquired_before,
+            snippet_max_length,
+        )
+        try:
+            response = self._client.post(
+                self._search_url(), json=payload, headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            raise KeenableConnectionError(
+                f"could not reach the Keenable API: {exc!r}"
+            ) from exc
+        return SearchResponse._from_json(_decode(response), query)
+
+    def fetch(self, url: str) -> Page:
+        """Fetch one URL and return its main content as markdown.
+
+        Use this after :meth:`search` when a snippet is not enough and the
+        model needs the full page.
+        """
+        _reject_private_fetch_target(url)
+        try:
+            response = self._client.get(
+                self._fetch_url(), params={"url": url}, headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            raise KeenableConnectionError(
+                f"could not reach the Keenable API: {exc!r}"
+            ) from exc
+        return Page._from_json(_decode(response), url)
+
+
+class AsyncKeenable(_BaseClient):
+    """Asynchronous client for the Keenable web search API.
+
+    Mirrors :class:`Keenable` with awaitable methods.
+
+    Example:
+        >>> import asyncio
+        >>> from keenable import AsyncKeenable
+        >>> async def main():
+        ...     async with AsyncKeenable() as keenable:
+        ...         results = await keenable.search("wafer scale engine")
+        ...         print(results.to_context())
+        >>> asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout)
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = client is None
+
+    async def __aenter__(self) -> AsyncKeenable:
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def search(
+        self,
+        query: str,
+        *,
+        mode: str | None = None,
+        site: str | None = None,
+        published_after: str | None = None,
+        published_before: str | None = None,
+        acquired_after: str | None = None,
+        acquired_before: str | None = None,
+        snippet_max_length: int | None = None,
+    ) -> SearchResponse:
+        """Search the web. See :meth:`Keenable.search` for the arguments."""
+        payload = _search_payload(
+            query,
+            mode,
+            site,
+            published_after,
+            published_before,
+            acquired_after,
+            acquired_before,
+            snippet_max_length,
+        )
+        try:
+            response = await self._client.post(
+                self._search_url(), json=payload, headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            raise KeenableConnectionError(
+                f"could not reach the Keenable API: {exc!r}"
+            ) from exc
+        return SearchResponse._from_json(_decode(response), query)
+
+    async def fetch(self, url: str) -> Page:
+        """Fetch one URL as markdown. See :meth:`Keenable.fetch`."""
+        _reject_private_fetch_target(url)
+        try:
+            response = await self._client.get(
+                self._fetch_url(), params={"url": url}, headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            raise KeenableConnectionError(
+                f"could not reach the Keenable API: {exc!r}"
+            ) from exc
+        return Page._from_json(_decode(response), url)

keenable/errors.py

@@ -0,0 +1,40 @@
+"""Exceptions raised by the Keenable SDK."""
+
+from __future__ import annotations
+
+
+class KeenableError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class KeenableConnectionError(KeenableError):
+    """The Keenable API could not be reached (DNS, TLS, timeout, ...)."""
+
+
+class KeenableAPIError(KeenableError):
+    """The Keenable API returned a non-2xx response.
+
+    ``status_code`` is the HTTP status and ``body`` the decoded error message
+    from the API when it sent one.
+    """
+
+    def __init__(self, message: str, status_code: int, body: str | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class KeenableAuthError(KeenableAPIError):
+    """The API key was rejected (HTTP 401/403)."""
+
+
+class KeenableRateLimitError(KeenableAPIError):
+    """The rate limit was exceeded (HTTP 429).
+
+    Keyless requests share a lower hourly cap. Setting ``KEENABLE_API_KEY``
+    lifts it; a key is never required to make a request.
+    """
+
+
+class KeenableInvalidRequestError(KeenableError):
+    """The arguments passed to the SDK are invalid; no request was sent."""

keenable/models.py

@@ -0,0 +1,158 @@
+"""Typed results returned by the Keenable API."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import Any
+
+# Default budget for `to_context()`. Roughly 3k tokens: large enough that a
+# handful of results keep their substance, small enough to sit in front of a
+# user question without crowding out the rest of the prompt.
+DEFAULT_CONTEXT_MAX_CHARS = 12_000
+
+
+def _str_or_none(value: Any) -> str | None:
+    """Return a non-empty string, or None for anything else (incl. "")."""
+    if isinstance(value, str) and value.strip():
+        return value
+    return None
+
+
+@dataclass
+class SearchResult:
+    """A single web page returned by :meth:`Keenable.search`."""
+
+    title: str
+    url: str
+    snippet: str
+    """Page text extracted for this query. This is the field to put in a
+    prompt: it carries the actual content, unlike ``description``."""
+
+    description: str | None = None
+    """The page's meta description. Often absent; prefer ``snippet``."""
+
+    published_at: str | None = None
+    """ISO-8601 timestamp of publication, when the page exposes one."""
+
+    acquired_at: str | None = None
+    """ISO-8601 timestamp of when Keenable indexed the page."""
+
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+    """The unmodified JSON object, so new API fields are reachable before this
+    SDK models them."""
+
+    @classmethod
+    def _from_json(cls, data: dict[str, Any]) -> SearchResult:
+        return cls(
+            title=str(data.get("title") or ""),
+            url=str(data.get("url") or ""),
+            snippet=str(data.get("snippet") or ""),
+            description=_str_or_none(data.get("description")),
+            published_at=_str_or_none(data.get("published_at")),
+            acquired_at=_str_or_none(data.get("acquired_at")),
+            raw=data,
+        )
+
+
+@dataclass
+class SearchResponse:
+    """The result set for one :meth:`Keenable.search` call."""
+
+    query: str
+    results: list[SearchResult]
+    mode: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def __iter__(self) -> Iterator[SearchResult]:
+        return iter(self.results)
+
+    def __len__(self) -> int:
+        return len(self.results)
+
+    def __getitem__(self, index: int) -> SearchResult:
+        return self.results[index]
+
+    @classmethod
+    def _from_json(cls, data: dict[str, Any], query: str) -> SearchResponse:
+        raw_results = data.get("results")
+        results = (
+            [SearchResult._from_json(r) for r in raw_results if isinstance(r, dict)]
+            if isinstance(raw_results, list)
+            else []
+        )
+        return cls(
+            query=str(data.get("query") or query),
+            results=results,
+            mode=_str_or_none(data.get("mode")),
+            raw=data,
+        )
+
+    def to_context(
+        self,
+        max_chars: int = DEFAULT_CONTEXT_MAX_CHARS,
+        max_results: int | None = None,
+        include_dates: bool = True,
+    ) -> str:
+        """Render the results as a numbered, citable block for a prompt.
+
+        Each result becomes a ``[n] title (url)`` header followed by its
+        snippet, which lets the model cite sources by number and lets you map
+        those numbers back to URLs. Results are added whole until ``max_chars``
+        is reached, so a truncated context never ends mid-sentence.
+
+        Args:
+            max_chars: Approximate character budget for the whole block.
+            max_results: Keep at most this many results before the budget is
+                applied.
+            include_dates: Append the publication date to each header when the
+                page exposes one. Useful when recency matters to the answer.
+        """
+        blocks: list[str] = []
+        used = 0
+        selected = self.results if max_results is None else self.results[:max_results]
+
+        for index, result in enumerate(selected, start=1):
+            header = f"[{index}] {result.title} ({result.url})"
+            if include_dates and result.published_at:
+                header += f" - published {result.published_at}"
+            body = result.snippet or result.description or ""
+            block = f"{header}\n{body}".strip()
+
+            # +2 for the blank line between blocks. Stop rather than truncate:
+            # a half-sentence source reads as corrupted context to the model.
+            cost = len(block) + (2 if blocks else 0)
+            if blocks and used + cost > max_chars:
+                break
+            blocks.append(block)
+            used += cost
+
+        return "\n\n".join(blocks)
+
+
+@dataclass
+class Page:
+    """A web page fetched by :meth:`Keenable.fetch`, extracted as markdown."""
+
+    url: str
+    title: str
+    content: str
+    """The page's main content as markdown, with navigation and boilerplate
+    stripped."""
+
+    description: str | None = None
+    author: str | None = None
+    published_at: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def _from_json(cls, data: dict[str, Any], url: str) -> Page:
+        return cls(
+            url=str(data.get("url") or url),
+            title=str(data.get("title") or ""),
+            content=str(data.get("content") or ""),
+            description=_str_or_none(data.get("description")),
+            author=_str_or_none(data.get("author")),
+            published_at=_str_or_none(data.get("published_at")),
+            raw=data,
+        )

keenable/tools.py

@@ -0,0 +1,160 @@
+"""Ready-made tool definitions for OpenAI-compatible tool calling.
+
+Every major inference API (Cerebras, OpenAI, and anything speaking the same
+schema) takes tools in this shape, so these constants can be passed straight
+into a ``chat.completions.create(tools=...)`` call:
+
+    from keenable import Keenable, TOOLS, run_tool_call
+
+    tools = TOOLS  # search + fetch
+    ...
+    output = run_tool_call(keenable, tool_call.function.name,
+                           tool_call.function.arguments)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .client import AsyncKeenable, Keenable
+from .errors import KeenableInvalidRequestError
+
+__all__ = ["SEARCH_TOOL", "FETCH_TOOL", "TOOLS", "run_tool_call", "arun_tool_call"]
+
+SEARCH_TOOL: dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "keenable_search",
+        "description": (
+            "Search the web for current information. Returns ranked pages with "
+            "their title, URL and extracted page text. Use this whenever the "
+            "answer depends on recent events or facts you are unsure about."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": (
+                        "What to look for, described in natural language "
+                        "rather than keywords."
+                    ),
+                },
+                "site": {
+                    "type": "string",
+                    "description": (
+                        "Optional. Restrict results to one domain, e.g. 'arxiv.org'."
+                    ),
+                },
+                "published_after": {
+                    "type": "string",
+                    "description": (
+                        "Optional. Only pages published on or after this date "
+                        "(YYYY-MM-DD)."
+                    ),
+                },
+            },
+            "required": ["query"],
+        },
+    },
+}
+
+FETCH_TOOL: dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "keenable_fetch",
+        "description": (
+            "Fetch one web page and return its main content as markdown. Use "
+            "after keenable_search when a search snippet is not enough."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "The URL of the page to read.",
+                },
+            },
+            "required": ["url"],
+        },
+    },
+}
+
+TOOLS: list[dict[str, Any]] = [SEARCH_TOOL, FETCH_TOOL]
+
+
+def _parse_arguments(arguments: str | dict[str, Any]) -> dict[str, Any]:
+    """Accept the model's raw JSON string or an already-decoded dict."""
+    if isinstance(arguments, dict):
+        return arguments
+    try:
+        parsed = json.loads(arguments or "{}")
+    except json.JSONDecodeError as exc:
+        raise KeenableInvalidRequestError(
+            f"tool call arguments are not valid JSON: {arguments!r}"
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise KeenableInvalidRequestError(
+            f"tool call arguments must be a JSON object, got {parsed!r}"
+        )
+    return parsed
+
+
+def _search_kwargs(args: dict[str, Any]) -> dict[str, Any]:
+    """Keep only the arguments the tool schema exposes to the model."""
+    allowed = ("site", "published_after")
+    return {name: args[name] for name in allowed if args.get(name)}
+
+
+def run_tool_call(
+    client: Keenable,
+    name: str,
+    arguments: str | dict[str, Any],
+) -> str:
+    """Execute one tool call and return the string to send back as the result.
+
+    Args:
+        client: The :class:`Keenable` client to run the call against.
+        name: The tool name the model chose (``keenable_search`` or
+            ``keenable_fetch``).
+        arguments: The model's arguments, as the raw JSON string from the API
+            or an already-decoded dict.
+
+    Returns:
+        Text ready to be attached to a ``role="tool"`` message.
+    """
+    args = _parse_arguments(arguments)
+    if name == "keenable_search":
+        query = args.get("query")
+        if not isinstance(query, str) or not query.strip():
+            raise KeenableInvalidRequestError("keenable_search needs a 'query'")
+        return client.search(query, **_search_kwargs(args)).to_context()
+    if name == "keenable_fetch":
+        url = args.get("url")
+        if not isinstance(url, str) or not url.strip():
+            raise KeenableInvalidRequestError("keenable_fetch needs a 'url'")
+        return client.fetch(url).content
+    raise KeenableInvalidRequestError(f"unknown Keenable tool: {name!r}")
+
+
+async def arun_tool_call(
+    client: AsyncKeenable,
+    name: str,
+    arguments: str | dict[str, Any],
+) -> str:
+    """Async counterpart of :func:`run_tool_call`."""
+    args = _parse_arguments(arguments)
+    if name == "keenable_search":
+        query = args.get("query")
+        if not isinstance(query, str) or not query.strip():
+            raise KeenableInvalidRequestError("keenable_search needs a 'query'")
+        response = await client.search(query, **_search_kwargs(args))
+        return response.to_context()
+    if name == "keenable_fetch":
+        url = args.get("url")
+        if not isinstance(url, str) or not url.strip():
+            raise KeenableInvalidRequestError("keenable_fetch needs a 'url'")
+        page = await client.fetch(url)
+        return page.content
+    raise KeenableInvalidRequestError(f"unknown Keenable tool: {name!r}")

keenable-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: keenable
+Version: 0.1.0
+Summary: Official Python SDK for the Keenable web search API, built for AI agents
+Project-URL: Homepage, https://keenable.ai
+Project-URL: Documentation, https://github.com/keenableai/keenable-sdk#readme
+Project-URL: Repository, https://github.com/keenableai/keenable-sdk
+Project-URL: Issues, https://github.com/keenableai/keenable-sdk/issues
+Author-email: Keenable <support@keenable.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,grounding,keenable,llm,rag,search,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# keenable
+
+Official Python SDK for [Keenable](https://keenable.ai), a web search API built
+for AI agents: ranked results that come back with the page text already
+extracted, plus a fetch endpoint that returns any URL as clean markdown.
+
+**Keyless by default.** Every call works with no account and no key. An optional
+`KEENABLE_API_KEY` only lifts the hourly rate limit.
+
+```bash
+pip install keenable
+```
+
+## Search
+
+```python
+from keenable import Keenable
+
+keenable = Keenable()  # or Keenable("keen_...") / set KEENABLE_API_KEY
+
+results = keenable.search("how wafer scale chips avoid the memory bottleneck")
+
+for result in results:
+    print(result.title, result.url)
+    print(result.snippet)
+```
+
+Results carry the page text in `snippet`. (`description` is the page's meta
+description and is empty for most pages, so build prompts from `snippet`.)
+
+Filters are optional and combine freely:
+
+```python
+results = keenable.search(
+    "post-training quantization results",
+    site="arxiv.org",
+    published_after="2026-01-01",
+    snippet_max_length=500,
+)
+```
+
+| Argument | What it does |
+|---|---|
+| `site` | Restrict to one domain, e.g. `"arxiv.org"` |
+| `published_after` / `published_before` | Filter by publication date (`YYYY-MM-DD`) |
+| `acquired_after` / `acquired_before` | Filter by when Keenable indexed the page |
+| `snippet_max_length` | Cap the page text returned per result |
+| `mode` | Search mode; `"pro"` (default) does deeper retrieval |
+
+## Ground a model in one line
+
+`to_context()` renders the result set as a numbered, citable block you can drop
+straight into a prompt:
+
+```python
+context = keenable.search("cerebras inference benchmarks").to_context()
+
+prompt = f"Answer using only these sources, citing them by number.\n\n{context}\n\nQuestion: ..."
+```
+
+It emits `[1] Title (url)` headers followed by the page text, adds results whole
+until the character budget is reached (`max_chars=12000` by default), and never
+truncates a source mid-sentence.
+
+## Read a full page
+
+```python
+page = keenable.fetch("https://cerebras.ai/chip")
+print(page.title)
+print(page.content)  # markdown, boilerplate stripped
+```
+
+## Tool calling
+
+The SDK ships OpenAI-compatible tool definitions, so any inference API that
+speaks that schema can call Keenable directly:
+
+```python
+from keenable import Keenable, TOOLS, run_tool_call
+
+keenable = Keenable()
+response = client.chat.completions.create(model=..., messages=messages, tools=TOOLS)
+
+for call in response.choices[0].message.tool_calls or []:
+    messages.append(
+        {
+            "role": "tool",
+            "tool_call_id": call.id,
+            "content": run_tool_call(
+                keenable, call.function.name, call.function.arguments
+            ),
+        }
+    )
+```
+
+`TOOLS` exposes `keenable_search` and `keenable_fetch`; `run_tool_call` executes
+whichever the model picked and returns text ready for the `tool` message.
+
+## Async
+
+`AsyncKeenable` mirrors the sync client:
+
+```python
+import asyncio
+from keenable import AsyncKeenable
+
+
+async def main():
+    async with AsyncKeenable() as keenable:
+        results = await keenable.search("wafer scale engine")
+        print(results.to_context())
+
+
+asyncio.run(main())
+```
+
+## Errors
+
+All errors subclass `KeenableError`:
+
+| Exception | When |
+|---|---|
+| `KeenableRateLimitError` | HTTP 429. Set `KEENABLE_API_KEY` to lift the keyless cap |
+| `KeenableAuthError` | HTTP 401/403, the key was rejected |
+| `KeenableAPIError` | Any other non-2xx response; carries `status_code` |
+| `KeenableConnectionError` | The API could not be reached |
+| `KeenableInvalidRequestError` | Bad arguments; no request was sent |
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `KEENABLE_API_KEY` | unset | Lifts the hourly rate limit. Create one at [keenable.ai/console](https://keenable.ai/console) |
+| `KEENABLE_API_URL` | `https://api.keenable.ai` | Override the API base URL |
+
+## License
+
+MIT

keenable-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+keenable/__init__.py,sha256=_c5WPBIN6wpyYfZL69gpXaw_zYnonXzO38eoI6g8ZgU,1076
+keenable/client.py,sha256=R6e3yQpbKkD5AJeF2zeiKLiQPt_p6KRnRSzdJLQrHD0,13536
+keenable/errors.py,sha256=7R2EqlsKbscRJsLl40MLXxTZFNkrejXlt3mg6eiiZhA,1153
+keenable/models.py,sha256=Wc4J7jIV3BuBDRpNQaXO1kQpB6qIRi1bwkdhxE6yGLU,5511
+keenable/tools.py,sha256=GavCXdlEGlKJoBClE0tvHZ-IHiQGnjLWhF-Y2lxJzEM,5633
+keenable-0.1.0.dist-info/METADATA,sha256=PWyX0QvoDxdBmlPWLsAE13y0FXz0G9uno4XFy3M9s8Y,5079
+keenable-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+keenable-0.1.0.dist-info/licenses/LICENSE,sha256=EZtgxOtuBfSwLWl3m9_IuFTRWnHGDj_0fCcfSbR4hM4,1065
+keenable-0.1.0.dist-info/RECORD,,

keenable-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

keenable-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keenable
+
+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.