The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""Keenable (https://keenable.ai) web search + fetch — keyless-ring member.
Env: ``KEENABLE_API_KEY`` (optional; keyless free tier works without it).
Config: ``web.provider_tier.keenable: free|paid`` pins the tier (unset = auto).
"""
from __future__ import annotations
import logging
from typing import Any, Dict, List
from agent.ssl_verify import requests_verify
from plugins.web._common import (
SEARCH_LIMIT_CAP, BaseWebSearchProvider, document, http_status_detail, keenable_origin_error, keyless_extract, keyless_search,
keyless_variant_schema, page_error, provider_env, run_extract, run_search, search_fail, search_ok, use_keyless, web_hit,
)
logger = logging.getLogger(__name__)
_KEENABLE_API_URL = "https://api.keenable.ai"
def _keenable_headers(api_key: str) -> dict[str, str]:
# The keyless tier structurally requires an app-identifier header; no user identifiers are sent.
headers = {"X-Keenable-Title": "hermes-agent"}
if api_key:
headers["Authorization"] = f"Bearer {api_key}"
return headers
class KeenableWebSearchProvider(BaseWebSearchProvider):
"""Keenable search + extract provider (keyed or keyless)."""
NAME = "keenable"
DISPLAY_NAME = "Keenable"
KEY_ENV = "KEENABLE_API_KEY"
EXTRACT = True
KEYLESS = True
def search(self, query: str, limit: int = 5) -> dict[str, Any]:
def _body() -> dict[str, Any]:
api_key = provider_env("KEENABLE_API_KEY")
if use_keyless("keenable", api_key):
return keyless_search("Keenable", "keenable", query, limit, logger)
import requests
logger.info("Keenable search: '%s' (limit=%d)", query, limit)
# requests freezes its default CA bundle path at its own import; a replaced
# install environment leaves it dangling, so hand over a live bundle.
response = requests.post(
f"{_KEENABLE_API_URL}/v1/search",
json={"query": query, "max_results": min(max(1, int(limit)), SEARCH_LIMIT_CAP)},
headers=_keenable_headers(api_key), timeout=30, verify=requests_verify(),
)
if response.status_code >= 400:
return search_fail(f"Keenable search failed: {http_status_detail(response)}")
return search_ok([
web_hit(r.get("url") or "", r.get("title") or "", r.get("snippet") or r.get("description") or "", i + 1)
for i, r in enumerate(response.json().get("results") or [])
])
return run_search("Keenable", logger, _body, verbatim_value_error=False)
def extract(self, urls: list[str], **kwargs: Any) -> list[dict[str, Any]]:
def _body() -> list[dict[str, Any]]:
api_key = provider_env("KEENABLE_API_KEY")
if use_keyless("keenable", api_key):
return keyless_extract("Keenable", "keenable", urls, logger)
import requests
logger.info("Keenable extract: %d URL(s)", len(urls))
results: list[dict[str, Any]] = []
for url in urls:
try:
response = requests.get(f"{_KEENABLE_API_URL}/v1/fetch", params={"url": url}, headers=_keenable_headers(api_key), timeout=30, verify=requests_verify())
if response.status_code >= 400:
if origin := keenable_origin_error(response.status_code, response.text):
results.append(page_error(url, origin))
continue
raise ValueError(http_status_detail(response))
data = response.json()
results.append(document(data.get("url") or url, data.get("title") or "", data.get("content") or "", source_url=url))
except Exception as exc:
results.append(page_error(url, f"Keenable extract failed: {exc}"))
return results
return run_extract("Keenable", logger, urls, _body, verbatim_value_error=False)
def get_setup_schema(self) -> dict[str, Any]:
return keyless_variant_schema(
"Keenable", "KEENABLE_API_KEY", "https://keenable.ai",
free_tag="Independent web index for AI apps — fast search + page fetch on Keenable's anonymous free tier.",
paid_tag="Independent web index for AI apps. Keyed access with higher limits and guaranteed service.",
)