90 lines
2.6 KiB
Python
90 lines
2.6 KiB
Python
"""Abstract base classes for web capability providers."""
|
|
|
|
from __future__ import annotations
|
|
|
|
from abc import ABC, abstractmethod
|
|
from typing import Any, Dict, List
|
|
|
|
|
|
class WebSearchProvider(ABC):
|
|
"""Interface for web search backends (Firecrawl, Tavily, Exa, etc.).
|
|
|
|
Implementations live in sibling modules. The user selects a provider
|
|
via ``hermes tools``; the choice is persisted as
|
|
``config["web"]["search_backend"]`` (falling back to
|
|
``config["web"]["backend"]``).
|
|
|
|
Search providers return results in a normalized format::
|
|
|
|
{
|
|
"success": True,
|
|
"data": {
|
|
"web": [
|
|
{"title": str, "url": str, "description": str, "position": int},
|
|
...
|
|
]
|
|
}
|
|
}
|
|
|
|
On failure::
|
|
|
|
{"success": False, "error": str}
|
|
"""
|
|
|
|
@abstractmethod
|
|
def provider_name(self) -> str:
|
|
"""Short, human-readable name shown in logs and diagnostics."""
|
|
|
|
@abstractmethod
|
|
def is_configured(self) -> bool:
|
|
"""Return True when all required env vars / credentials are present.
|
|
|
|
Called at tool-registration time to gate availability.
|
|
Must be cheap — no network calls.
|
|
"""
|
|
|
|
@abstractmethod
|
|
def search(self, query: str, limit: int = 5) -> Dict[str, Any]:
|
|
"""Execute a web search and return normalized results."""
|
|
|
|
|
|
class WebExtractProvider(ABC):
|
|
"""Interface for web content extraction backends.
|
|
|
|
Implementations live in sibling modules. The user selects a provider
|
|
via ``hermes tools``; the choice is persisted as
|
|
``config["web"]["extract_backend"]`` (falling back to
|
|
``config["web"]["backend"]``).
|
|
|
|
Extract providers return results in a normalized format::
|
|
|
|
{
|
|
"success": True,
|
|
"data": [
|
|
{"url": str, "title": str, "content": str,
|
|
"raw_content": str, "metadata": dict},
|
|
...
|
|
]
|
|
}
|
|
|
|
On failure::
|
|
|
|
{"success": False, "error": str}
|
|
"""
|
|
|
|
@abstractmethod
|
|
def provider_name(self) -> str:
|
|
"""Short, human-readable name shown in logs and diagnostics."""
|
|
|
|
@abstractmethod
|
|
def is_configured(self) -> bool:
|
|
"""Return True when all required env vars / credentials are present.
|
|
|
|
Called at tool-registration time to gate availability.
|
|
Must be cheap — no network calls.
|
|
"""
|
|
|
|
@abstractmethod
|
|
def extract(self, urls: List[str], **kwargs) -> Dict[str, Any]:
|
|
"""Extract content from the given URLs and return normalized results."""
|