bub-web-search 0.0.1__tar.gz

bub_web_search-0.0.1/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.3
+Name: bub-web-search
+Version: 0.0.1
+Summary: Web search tools for Bub
+Author: Frost Ming
+Author-email: Frost Ming <me@frostming.com>
+Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# bub-web-search
+
+Provider-selectable web search tools for `bub`.
+
+## Providers
+
+Set `BUB_SEARCH_PROVIDER` to enable exactly one search provider:
+
+- `ollama` registers `web.search`
+- `searxng` registers `searxng.search`
+
+If the provider is unset or its required configuration is missing, neither tool is
+registered.
+
+## Installation
+
+```bash
+bub install bub-web-search
+```
+
+## Ollama
+
+Required:
+
+- `BUB_SEARCH_PROVIDER=ollama`
+- `BUB_SEARCH_OLLAMA_API_KEY`
+
+Optional:
+
+- `BUB_SEARCH_OLLAMA_API_BASE`
+  - Default: `https://ollama.com/api`
+
+The `web.search` tool accepts `query` and `max_results`.
+
+## SearXNG
+
+Required:
+
+- `BUB_SEARCH_PROVIDER=searxng`
+- `BUB_SEARCH_SEARXNG_BASE_URL`
+
+Optional:
+
+- `BUB_SEARCH_SEARXNG_TIMEOUT_SECONDS`
+  - Default: `10`
+- `BUB_SEARCH_SEARXNG_DEFAULT_LANGUAGE`
+- `BUB_SEARCH_SEARXNG_DEFAULT_SAFE_SEARCH`
+  - `0` off, `1` moderate, `2` strict
+  - Default: `1`
+- `BUB_SEARCH_SEARXNG_USER_AGENT`
+  - Default: `bub-web-search/1.0`
+- `BUB_SEARCH_SEARXNG_AUTH_HEADER`
+- `BUB_SEARCH_SEARXNG_AUTH_VALUE`
+
+The `searxng.search` tool accepts:
+
+- `query`
+- `max_results`
+- `categories`
+- `engines`
+- `language`
+- `time_range`
+- `safe_search`
+
+The SearXNG instance must allow JSON responses from its `/search` endpoint.
+
+## Migration From bub-searxng-search
+
+Replace the package with `bub-web-search`, set
+`BUB_SEARCH_PROVIDER=searxng`, and rename the environment variables:
+
+- `BUB_SEARXNG_SEARCH_BASE_URL` to `BUB_SEARCH_SEARXNG_BASE_URL`
+- other `BUB_SEARXNG_SEARCH_*` variables to `BUB_SEARCH_SEARXNG_*`

bub_web_search-0.0.1/README.md

@@ -0,0 +1,73 @@
+# bub-web-search
+
+Provider-selectable web search tools for `bub`.
+
+## Providers
+
+Set `BUB_SEARCH_PROVIDER` to enable exactly one search provider:
+
+- `ollama` registers `web.search`
+- `searxng` registers `searxng.search`
+
+If the provider is unset or its required configuration is missing, neither tool is
+registered.
+
+## Installation
+
+```bash
+bub install bub-web-search
+```
+
+## Ollama
+
+Required:
+
+- `BUB_SEARCH_PROVIDER=ollama`
+- `BUB_SEARCH_OLLAMA_API_KEY`
+
+Optional:
+
+- `BUB_SEARCH_OLLAMA_API_BASE`
+  - Default: `https://ollama.com/api`
+
+The `web.search` tool accepts `query` and `max_results`.
+
+## SearXNG
+
+Required:
+
+- `BUB_SEARCH_PROVIDER=searxng`
+- `BUB_SEARCH_SEARXNG_BASE_URL`
+
+Optional:
+
+- `BUB_SEARCH_SEARXNG_TIMEOUT_SECONDS`
+  - Default: `10`
+- `BUB_SEARCH_SEARXNG_DEFAULT_LANGUAGE`
+- `BUB_SEARCH_SEARXNG_DEFAULT_SAFE_SEARCH`
+  - `0` off, `1` moderate, `2` strict
+  - Default: `1`
+- `BUB_SEARCH_SEARXNG_USER_AGENT`
+  - Default: `bub-web-search/1.0`
+- `BUB_SEARCH_SEARXNG_AUTH_HEADER`
+- `BUB_SEARCH_SEARXNG_AUTH_VALUE`
+
+The `searxng.search` tool accepts:
+
+- `query`
+- `max_results`
+- `categories`
+- `engines`
+- `language`
+- `time_range`
+- `safe_search`
+
+The SearXNG instance must allow JSON responses from its `/search` endpoint.
+
+## Migration From bub-searxng-search
+
+Replace the package with `bub-web-search`, set
+`BUB_SEARCH_PROVIDER=searxng`, and rename the environment variables:
+
+- `BUB_SEARXNG_SEARCH_BASE_URL` to `BUB_SEARCH_SEARXNG_BASE_URL`
+- other `BUB_SEARXNG_SEARCH_*` variables to `BUB_SEARCH_SEARXNG_*`

bub_web_search-0.0.1/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "bub-web-search"
+version = "0.0.1"
+description = "Web search tools for Bub"
+readme = "README.md"
+authors = [
+    { name = "Frost Ming", email = "me@frostming.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp>=3.13.3",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.10.1",
+]
+
+[project.entry-points.bub]
+web-search = "bub_web_search.tools"
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]

bub_web_search-0.0.1/src/bub_web_search/config.py

@@ -0,0 +1,74 @@
+from typing import Literal
+
+import bub
+from pydantic_settings import SettingsConfigDict
+
+DEFAULT_OLLAMA_API_BASE = "https://ollama.com/api"
+DEFAULT_SEARXNG_TIMEOUT_SECONDS = 10
+DEFAULT_SEARXNG_SAFE_SEARCH = 1
+DEFAULT_SEARXNG_USER_AGENT = "bub-web-search/1.0"
+
+
+@bub.config(name="web-search")
+class WebSearchSettings(bub.Settings):
+    model_config = SettingsConfigDict(
+        env_prefix="BUB_SEARCH_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    provider: Literal["ollama", "searxng"] | None = None
+
+    ollama_api_key: str | None = None
+    ollama_api_base: str = DEFAULT_OLLAMA_API_BASE
+
+    searxng_base_url: str | None = None
+    searxng_timeout_seconds: int = DEFAULT_SEARXNG_TIMEOUT_SECONDS
+    searxng_default_language: str | None = None
+    searxng_default_safe_search: int = DEFAULT_SEARXNG_SAFE_SEARCH
+    searxng_user_agent: str = DEFAULT_SEARXNG_USER_AGENT
+    searxng_auth_header: str | None = None
+    searxng_auth_value: str | None = None
+
+    @property
+    def resolved_provider(self) -> Literal["ollama", "searxng"] | None:
+        if self.provider is not None:
+            return self.provider
+        if self.ollama_api_key:
+            return "ollama"
+        if self.searxng_base_url:
+            return "searxng"
+        return None
+
+    @property
+    def resolved_searxng_base_url(self) -> str | None:
+        if self.searxng_base_url is None:
+            return None
+        base_url = self.searxng_base_url.strip().rstrip("/")
+        return base_url or None
+
+    @property
+    def resolved_searxng_timeout_seconds(self) -> int:
+        return max(1, self.searxng_timeout_seconds)
+
+    @property
+    def resolved_searxng_default_safe_search(self) -> int:
+        if self.searxng_default_safe_search in {0, 1, 2}:
+            return self.searxng_default_safe_search
+        return DEFAULT_SEARXNG_SAFE_SEARCH
+
+    @property
+    def resolved_searxng_user_agent(self) -> str:
+        user_agent = self.searxng_user_agent.strip()
+        return user_agent or DEFAULT_SEARXNG_USER_AGENT
+
+    @property
+    def resolved_searxng_auth_headers(self) -> dict[str, str]:
+        if self.searxng_auth_header is None or self.searxng_auth_value is None:
+            return {}
+        header_name = self.searxng_auth_header.strip()
+        header_value = self.searxng_auth_value.strip()
+        if not header_name or not header_value:
+            return {}
+        return {header_name: header_value}

bub_web_search-0.0.1/src/bub_web_search/ollama.py

@@ -0,0 +1,59 @@
+import json
+
+from bub_web_search.config import WebSearchSettings
+
+WEB_USER_AGENT = "bub-web-search/1.0"
+
+
+async def search(query: str, max_results: int, settings: WebSearchSettings) -> str:
+    import aiohttp
+
+    api_key = settings.ollama_api_key
+    if not api_key:
+        return "error: ollama api key is not configured"
+
+    api_base = settings.ollama_api_base.rstrip("/")
+    if not api_base:
+        return "error: invalid ollama api base url"
+
+    endpoint = f"{api_base}/web_search"
+    payload = {"query": query, "max_results": max_results}
+    try:
+        async with (
+            aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=20)) as session,
+            session.post(
+                endpoint,
+                json=payload,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {api_key}",
+                    "User-Agent": WEB_USER_AGENT,
+                },
+            ) as response,
+        ):
+            data = await response.json()
+    except aiohttp.ClientError as exc:
+        return f"HTTP error: {exc!s}"
+    except json.JSONDecodeError as exc:
+        return f"error: invalid json response: {exc!s}"
+
+    results = data.get("results")
+    if not isinstance(results, list) or not results:
+        return "none"
+    return _format_search_results(results)
+
+
+def _format_search_results(results: list[object]) -> str:
+    lines: list[str] = []
+    for idx, item in enumerate(results, start=1):
+        if not isinstance(item, dict):
+            continue
+        title = str(item.get("title") or "(untitled)")
+        url = str(item.get("url") or "")
+        content = str(item.get("content") or "")
+        lines.append(f"{idx}. {title}")
+        if url:
+            lines.append(f"   {url}")
+        if content:
+            lines.append(f"   {content}")
+    return "\n".join(lines) if lines else "none"

bub_web_search-0.0.1/src/bub_web_search/searxng.py

@@ -0,0 +1,311 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from json import JSONDecodeError
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from bub_web_search.config import WebSearchSettings
+
+MAX_RESULTS_LIMIT = 10
+MAX_SNIPPET_CHARS = 280
+MAX_TITLE_CHARS = 160
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+class SearXNGSearchInput(BaseModel):
+    query: str = Field(..., description="The search query string.")
+    max_results: int = Field(
+        5,
+        ge=1,
+        le=MAX_RESULTS_LIMIT,
+        description="Maximum number of search results to return.",
+    )
+    categories: list[str] | None = Field(
+        None,
+        description="Optional list of SearXNG categories, such as general, news, or science.",
+    )
+    engines: list[str] | None = Field(
+        None, description="Optional list of SearXNG engine names to limit the search."
+    )
+    language: str | None = Field(
+        None, description="Optional language code, such as en-US or zh-CN."
+    )
+    time_range: Literal["day", "month", "year"] | None = Field(
+        None, description="Optional SearXNG time filter."
+    )
+    safe_search: int | None = Field(
+        None,
+        ge=0,
+        le=2,
+        description="Optional safe search level: 0 off, 1 moderate, 2 strict.",
+    )
+
+    @field_validator("query")
+    @classmethod
+    def validate_query(cls, value: str) -> str:
+        query = value.strip()
+        if not query:
+            raise ValueError("query must not be blank")
+        return query
+
+
+async def search(*, param: SearXNGSearchInput, settings: WebSearchSettings) -> str:
+    import aiohttp
+
+    base_url = settings.resolved_searxng_base_url
+    if base_url is None:
+        return "error: searxng base url is not configured"
+
+    endpoint = f"{base_url}/search"
+    params = _build_request_params(param=param, settings=settings)
+    headers = {
+        "Accept": "application/json",
+        "User-Agent": settings.resolved_searxng_user_agent,
+        **settings.resolved_searxng_auth_headers,
+    }
+
+    try:
+        async with (
+            aiohttp.ClientSession(
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(
+                    total=settings.resolved_searxng_timeout_seconds
+                ),
+            ) as session,
+            session.get(endpoint, params=params) as response,
+        ):
+            body = await response.text()
+            if response.status >= 400:
+                detail = (
+                    _compact_text(body, limit=MAX_SNIPPET_CHARS) or "request failed"
+                )
+                return f"HTTP {response.status}: {detail}"
+    except aiohttp.ClientError as exc:
+        return f"HTTP error: {exc!s}"
+    except TimeoutError:
+        return (
+            "error: request timed out after "
+            f"{settings.resolved_searxng_timeout_seconds} seconds"
+        )
+
+    try:
+        payload = json.loads(body)
+    except JSONDecodeError as exc:
+        return f"error: invalid json response: {exc!s}"
+    if not isinstance(payload, dict):
+        return "error: invalid json response: expected a top-level object"
+    return _format_search_response(payload, max_results=param.max_results)
+
+
+def _build_request_params(
+    *, param: SearXNGSearchInput, settings: WebSearchSettings
+) -> dict[str, str | int]:
+    request_params: dict[str, str | int] = {
+        "q": param.query,
+        "format": "json",
+        "safesearch": (
+            param.safe_search
+            if param.safe_search is not None
+            else settings.resolved_searxng_default_safe_search
+        ),
+    }
+    if language := _clean_value(param.language) or _clean_value(
+        settings.searxng_default_language
+    ):
+        request_params["language"] = language
+    if categories := _join_csv(param.categories):
+        request_params["categories"] = categories
+    if engines := _join_csv(param.engines):
+        request_params["engines"] = engines
+    if param.time_range is not None:
+        request_params["time_range"] = param.time_range
+    return request_params
+
+
+def _format_search_response(payload: dict[str, Any], *, max_results: int) -> str:
+    lines: list[str] = []
+
+    answer_lines = _format_answer_lines(payload.get("answers"))
+    if answer_lines:
+        lines.extend(["Answers:", *answer_lines])
+
+    suggestion_lines = _format_suggestion_lines(payload.get("suggestions"))
+    if suggestion_lines:
+        if lines:
+            lines.append("")
+        lines.extend(["Suggestions:", *suggestion_lines])
+
+    infobox_lines = _format_infobox_lines(payload.get("infoboxes"))
+    if infobox_lines:
+        if lines:
+            lines.append("")
+        lines.extend(["Infoboxes:", *infobox_lines])
+
+    result_blocks = _format_result_blocks(
+        payload.get("results"), max_results=max_results
+    )
+    if result_blocks:
+        if lines:
+            lines.append("")
+        lines.extend(result_blocks)
+
+    return "\n".join(lines) if lines else "none"
+
+
+def _format_answer_lines(raw_answers: object) -> list[str]:
+    if not isinstance(raw_answers, list):
+        return []
+    lines: list[str] = []
+    for item in raw_answers:
+        text = _stringify_answer(item)
+        if text:
+            lines.append(f"- {text}")
+    return lines
+
+
+def _stringify_answer(value: object) -> str:
+    if isinstance(value, str):
+        return _compact_text(value, limit=MAX_SNIPPET_CHARS)
+    if isinstance(value, dict):
+        text = _first_non_empty(
+            value.get("answer"),
+            value.get("content"),
+            value.get("text"),
+            value.get("title"),
+        )
+        return _compact_text(text, limit=MAX_SNIPPET_CHARS)
+    return ""
+
+
+def _format_suggestion_lines(raw_suggestions: object) -> list[str]:
+    if not isinstance(raw_suggestions, list):
+        return []
+    lines: list[str] = []
+    for item in raw_suggestions:
+        if isinstance(item, str):
+            suggestion = _compact_text(item, limit=MAX_TITLE_CHARS)
+            if suggestion:
+                lines.append(f"- {suggestion}")
+    return lines
+
+
+def _format_infobox_lines(raw_infoboxes: object) -> list[str]:
+    if not isinstance(raw_infoboxes, list):
+        return []
+    lines: list[str] = []
+    for item in raw_infoboxes:
+        if not isinstance(item, dict):
+            continue
+        title = _compact_text(
+            _first_non_empty(
+                item.get("infobox"), item.get("id"), item.get("title"), "(untitled)"
+            ),
+            limit=MAX_TITLE_CHARS,
+        )
+        content = _compact_text(
+            _first_non_empty(
+                item.get("content"), item.get("description"), item.get("title")
+            ),
+            limit=MAX_SNIPPET_CHARS,
+        )
+        lines.append(f"- {title}")
+        if url := _extract_url(item):
+            lines.append(f"  {url}")
+        if content and content != title:
+            lines.append(f"  {content}")
+    return lines
+
+
+def _format_result_blocks(raw_results: object, *, max_results: int) -> list[str]:
+    if not isinstance(raw_results, list):
+        return []
+
+    lines: list[str] = []
+    rendered = 0
+    for item in raw_results:
+        if not isinstance(item, dict):
+            continue
+        title = _compact_text(
+            _first_non_empty(
+                item.get("title"), item.get("content"), item.get("url"), "(untitled)"
+            ),
+            limit=MAX_TITLE_CHARS,
+        )
+        lines.append(f"{rendered + 1}. {title}")
+        if url := _extract_url(item):
+            lines.append(f"   {url}")
+        snippet = _compact_text(
+            _first_non_empty(
+                item.get("content"), item.get("snippet"), item.get("description")
+            ),
+            limit=MAX_SNIPPET_CHARS,
+        )
+        if snippet and snippet != title:
+            lines.append(f"   {snippet}")
+
+        metadata: list[str] = []
+        if engine := _clean_value(item.get("engine")):
+            metadata.append(engine)
+        if category := _clean_value(item.get("category")):
+            metadata.append(f"[{category}]")
+        if published := _clean_value(item.get("publishedDate")):
+            metadata.append(published)
+        if metadata:
+            lines.append(f"   source: {' '.join(metadata)}")
+
+        rendered += 1
+        if rendered >= max_results:
+            break
+    return lines if rendered else []
+
+
+def _extract_url(item: dict[str, Any]) -> str:
+    if url := _clean_value(item.get("url")):
+        return url
+    raw_urls = item.get("urls")
+    if not isinstance(raw_urls, list):
+        return ""
+    for candidate in raw_urls:
+        if isinstance(candidate, str):
+            if url := _clean_value(candidate):
+                return url
+        elif isinstance(candidate, dict):
+            if url := _clean_value(candidate.get("url")):
+                return url
+    return ""
+
+
+def _join_csv(values: Iterable[object] | None) -> str:
+    if values is None:
+        return ""
+    parts = [part for value in values if (part := _clean_value(value))]
+    return ",".join(parts)
+
+
+def _clean_value(value: object) -> str:
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        value = str(value)
+    return value.strip()
+
+
+def _compact_text(value: object, *, limit: int) -> str:
+    text = _clean_value(value)
+    if not text:
+        return ""
+    compact = _WHITESPACE_RE.sub(" ", text)
+    if len(compact) <= limit:
+        return compact
+    return compact[: limit - 3].rstrip() + "..."
+
+
+def _first_non_empty(*values: object) -> str:
+    for value in values:
+        if cleaned := _clean_value(value):
+            return cleaned
+    return ""

bub_web_search-0.0.1/src/bub_web_search/tools.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+import bub
+from bub import tool
+from bub.tools import REGISTRY
+
+from bub_web_search import ollama, searxng
+from bub_web_search.config import WebSearchSettings
+
+if TYPE_CHECKING:
+    from republic import Tool
+
+SEARCH_TOOL_NAME = "web.search"
+
+
+def register_tools(
+    settings_factory: Callable[[], WebSearchSettings] = lambda: bub.ensure_config(
+        WebSearchSettings
+    ),
+) -> Tool | None:
+    REGISTRY.pop(SEARCH_TOOL_NAME, None)
+
+    settings = settings_factory()
+    provider = settings.resolved_provider
+    if provider == "ollama":
+        return _register_ollama_tool(settings)
+    elif provider == "searxng":
+        return _register_searxng_tool(settings)
+    return None
+
+
+def _register_ollama_tool(settings: WebSearchSettings) -> Tool | None:
+    if not settings.ollama_api_key:
+        return None
+
+    @tool(name=SEARCH_TOOL_NAME)
+    async def web_search_ollama(query: str, max_results: int = 10) -> str:
+        """Search the web with Ollama and return concise results."""
+        return await ollama.search(
+            query=query, max_results=max_results, settings=settings
+        )
+
+    return web_search_ollama
+
+
+def _register_searxng_tool(settings: WebSearchSettings) -> Tool | None:
+    if settings.resolved_searxng_base_url is None:
+        return None
+
+    @tool(
+        name=SEARCH_TOOL_NAME,
+        model=searxng.SearXNGSearchInput,
+        description="Search a configured SearXNG instance and return concise web results.",
+    )
+    async def searxng_search(param: searxng.SearXNGSearchInput) -> str:
+        return await searxng.search(param=param, settings=settings)
+
+    return searxng_search
+
+
+register_tools()