The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
from __future__ import annotations
from dataclasses import dataclass, replace
import base64
import binascii
import hashlib
import json
import time
from typing import Callable, Literal, Protocol
from pydantic import ValidationError
from hermes_constants import get_hermes_home
from tools.connectors.gateway.errors import GatewayAuthError, GatewayUnavailable, ToolGatewayError
from tools.connectors.portal.client import NotModified, validate_slug
from tools.connectors.portal.errors import PortalToolsUnavailable
from tools.connectors.portal.wire import ConnectorTool, ConnectorToolsListing
from utils import atomic_json_write, read_json_or_empty
class ToolsClient(Protocol):
def origin(self) -> str: ...
def authorization_token(self) -> str | None: ...
def tools(self, slug: str, *, if_none_match: str | None = None) -> ConnectorToolsListing | NotModified: ...
TTL_SECONDS = 24 * 60 * 60
@dataclass(frozen=True)
class ToolsRead:
connector: str
toolkit_version: str
etag: str
fetched_at: float
source: Literal["cache", "network", "revalidated"]
stale: bool
tools: list[ConnectorTool]
def _member_key(token: str | None) -> str | None:
if not isinstance(token, str):
return None
parts = token.split(".")
if len(parts) != 3:
return None
try:
payload = parts[1] + "=" * (-len(parts[1]) % 4)
claims = json.loads(base64.urlsafe_b64decode(payload))
except (binascii.Error, ValueError, UnicodeDecodeError, json.JSONDecodeError):
return None
subject = claims.get("sub") if isinstance(claims, dict) else None
if not isinstance(subject, str) or not subject:
return None
return hashlib.sha256(subject.encode("utf-8")).hexdigest()[:16]
def _cache_path(origin: str, member_key: str, slug: str):
origin_key = hashlib.sha256(origin.encode("utf-8")).hexdigest()[:16]
return get_hermes_home() / "cache" / "connectors" / origin_key / member_key / f"{slug}.json"
def _cached(path) -> ToolsRead | None:
raw = read_json_or_empty(path)
try:
tools = [ConnectorTool.model_validate(tool) for tool in raw["tools"]]
return ToolsRead(
connector=str(raw["connector"]),
toolkit_version=str(raw["toolkit_version"]),
etag=str(raw["etag"]),
fetched_at=float(raw["fetched_at"]),
source="cache",
stale=False,
tools=tools,
)
except (KeyError, TypeError, ValueError, ValidationError):
return None
def _store(path, entry: ToolsRead) -> ToolsRead:
path.parent.mkdir(parents=True, exist_ok=True)
atomic_json_write(
path,
{
"etag": entry.etag,
"toolkit_version": entry.toolkit_version,
"connector": entry.connector,
"tools": [tool.model_dump(by_alias=True) for tool in entry.tools],
"fetched_at": entry.fetched_at,
},
)
return entry
def read_tools(
slug: str,
*,
client: ToolsClient,
refresh: bool = False,
now: Callable[[], float] = time.time,
) -> ToolsRead:
validate_slug(slug)
member_key = _member_key(client.authorization_token())
if member_key is None:
listing = client.tools(slug)
if isinstance(listing, NotModified):
raise PortalToolsUnavailable("portal tools unavailable", code="INVALID_RESPONSE")
return ToolsRead(
connector=listing.connector,
toolkit_version=listing.toolkit_version,
etag=listing.etag,
fetched_at=now(),
source="network",
stale=False,
tools=listing.tools,
)
path = _cache_path(client.origin(), member_key, slug)
cached = _cached(path)
fetched_at = now()
age = fetched_at - cached.fetched_at if cached is not None else None
if cached is not None and not refresh and age is not None and 0 <= age < TTL_SECONDS:
return cached
try:
listing = client.tools(slug, if_none_match=cached.etag if cached is not None else None)
except GatewayUnavailable:
path.unlink(missing_ok=True)
raise
except GatewayAuthError:
raise
except (PortalToolsUnavailable, ToolGatewayError):
if cached is None:
raise
return replace(cached, stale=True)
if isinstance(listing, NotModified):
if cached is None:
raise PortalToolsUnavailable("portal tools unavailable", code="INVALID_RESPONSE")
return _store(path, replace(cached, fetched_at=fetched_at, source="revalidated"))
return _store(path, ToolsRead(
connector=listing.connector,
toolkit_version=listing.toolkit_version,
etag=listing.etag,
fetched_at=fetched_at,
source="network",
stale=False,
tools=listing.tools,
))