src/hermes/tools/documentation.py

"""Documentation search tool implementation."""

from __future__ import annotations

import logging
from typing import Any

from hermes.tools.base.tool import BaseTool, ToolSchema

logger = logging.getLogger(__name__)


class DocumentationTool(BaseTool):
    """Tool for searching and retrieving documentation."""

    def __init__(self) -> None:
        super().__init__()
        self._doc_cache: dict[str, dict[str, Any]] = {}

    def _define_schema(self) -> ToolSchema:
        return ToolSchema(
            name="documentation_search",
            description="Search and retrieve documentation from various sources",
            parameters={
                "query": {
                    "type": "string",
                    "description": "Documentation search query",
                },
                "source": {
                    "type": "string",
                    "description": "Documentation source (python, javascript, general)",
                    "default": "general",
                },
                "max_results": {
                    "type": "integer",
                    "description": "Maximum number of results",
                    "default": 5,
                },
            },
            required=["query"],
            category="research",
            tags=["documentation", "docs", "search"],
        )

    async def execute(self, **kwargs: Any) -> dict[str, Any]:
        """Search documentation."""
        query = kwargs["query"]
        source = kwargs.get("source", "general")
        max_results = kwargs.get("max_results", 5)

        try:
            results = await self._search_docs(query, source, max_results)
            return {
                "query": query,
                "source": source,
                "results": results,
                "total": len(results),
            }
        except Exception as e:
            logger.error(f"Documentation search error: {e}")
            return {"error": str(e), "query": query, "results": []}

    async def _search_docs(
        self, query: str, source: str, max_results: int
    ) -> list[dict[str, Any]]:
        """Search documentation sources."""
        results = []

        doc_sources = {
            "python": "https://docs.python.org/3/",
            "javascript": "https://developer.mozilla.org/en-US/docs/Web/JavaScript",
            "fastapi": "https://fastapi.tiangolo.com/",
            "pydantic": "https://docs.pydantic.dev/",
        }

        base_url = doc_sources.get(source, "https://docs.python.org/3/")

        results.append(
            {
                "title": f"Documentation for: {query}",
                "url": f"{base_url}search?q={query.replace(' ', '+')}",
                "snippet": f"Search results for '{query}' in {source} documentation",
                "source": source,
            }
        )

        common_docs = {
            "fastapi": [
                {
                    "title": "FastAPI Request Body",
                    "url": "https://fastapi.tiangolo.com/tutorial/request-body/",
                    "snippet": "Request body with Pydantic models for FastAPI endpoints.",
                },
                {
                    "title": "FastAPI Dependencies",
                    "url": "https://fastapi.tiangolo.com/tutorial/dependencies/",
                    "snippet": "Dependency injection in FastAPI for shared logic.",
                },
            ],
            "pydantic": [
                {
                    "title": "Pydantic Models",
                    "url": "https://docs.pydantic.dev/latest/concepts/models/",
                    "snippet": "Data validation using Pydantic BaseModel classes.",
                },
                {
                    "title": "Pydantic Settings",
                    "url": "https://docs.pydantic.dev/latest/concepts/pydantic_settings/",
                    "snippet": "Settings management using pydantic-settings.",
                },
            ],
        }

        if source in common_docs:
            results.extend(common_docs[source][:max_results])

        return results[:max_results]