mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-04-30 01:41:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

feat: devex help, add Makefile, ruff, pre-commit, and modernize CI

Browse source
This commit is contained in:
Brooklyn Nicholson 2026-03-09 20:36:51 -05:00
parent 172a38c344
commit f4d7e6a29e
111 changed files with 11655 additions and 10200 deletions
Download patch file Download diff file Expand all files Collapse all files

301
toolsets.py
View file

@ -15,55 +15,75 @@ Features:
Usage:
from toolsets import get_toolset, resolve_toolset, get_all_toolsets
# Get tools for a specific toolset
tools = get_toolset("research")
# Resolve a toolset to get all tool names (including from composed toolsets)
all_tools = resolve_toolset("full_stack")
"""
from typing import List, Dict, Any, Set, Optional
from typing import Any
# Shared tool list for CLI and all messaging platform toolsets.
# Edit this once to update all platforms simultaneously.
_HERMES_CORE_TOOLS = [
# Web
"web_search", "web_extract",
"web_search",
"web_extract",
# Terminal + process management
"terminal", "process",
"terminal",
"process",
# File manipulation
"read_file", "write_file", "patch", "search_files",
"read_file",
"write_file",
"patch",
"search_files",
# Vision + image generation
"vision_analyze", "image_generate",
"vision_analyze",
"image_generate",
# MoA
"mixture_of_agents",
# Skills
"skills_list", "skill_view", "skill_manage",
"skills_list",
"skill_view",
"skill_manage",
# Browser automation
"browser_navigate", "browser_snapshot", "browser_click",
"browser_type", "browser_scroll", "browser_back",
"browser_press", "browser_close", "browser_get_images",
"browser_navigate",
"browser_snapshot",
"browser_click",
"browser_type",
"browser_scroll",
"browser_back",
"browser_press",
"browser_close",
"browser_get_images",
"browser_vision",
# Text-to-speech
"text_to_speech",
# Planning & memory
"todo", "memory",
"todo",
"memory",
# Session history search
"session_search",
# Clarifying questions
"clarify",
# Code execution + delegation
"execute_code", "delegate_task",
"execute_code",
"delegate_task",
# Cronjob management
"schedule_cronjob", "list_cronjobs", "remove_cronjob",
"schedule_cronjob",
"list_cronjobs",
"remove_cronjob",
# Cross-platform messaging (gated on gateway running via check_fn)
"send_message",
# Honcho user context (gated on honcho being active via check_fn)
"query_user_context",
# Home Assistant smart home control (gated on HASS_TOKEN via check_fn)
"ha_list_entities", "ha_get_state", "ha_list_services", "ha_call_service",
"ha_list_entities",
"ha_get_state",
"ha_list_services",
"ha_call_service",
]
@ -74,149 +94,125 @@ TOOLSETS = {
"web": {
"description": "Web research and content extraction tools",
"tools": ["web_search", "web_extract"],
"includes": [] # No other toolsets included
"includes": [], # No other toolsets included
},
"search": {
"description": "Web search only (no content extraction/scraping)",
"tools": ["web_search"],
"includes": []
"includes": [],
},
"vision": {
"description": "Image analysis and vision tools",
"tools": ["vision_analyze"],
"includes": []
},
"image_gen": {
"description": "Creative generation tools (images)",
"tools": ["image_generate"],
"includes": []
},
"vision": {"description": "Image analysis and vision tools", "tools": ["vision_analyze"], "includes": []},
"image_gen": {"description": "Creative generation tools (images)", "tools": ["image_generate"], "includes": []},
"terminal": {
"description": "Terminal/command execution and process management tools",
"tools": ["terminal", "process"],
"includes": []
"includes": [],
},
"moa": {
"description": "Advanced reasoning and problem-solving tools",
"tools": ["mixture_of_agents"],
"includes": []
"includes": [],
},
"skills": {
"description": "Access, create, edit, and manage skill documents with specialized instructions and knowledge",
"tools": ["skills_list", "skill_view", "skill_manage"],
"includes": []
"includes": [],
},
"browser": {
"description": "Browser automation for web interaction (navigate, click, type, scroll, iframes, hold-click) with web search for finding URLs",
"tools": [
"browser_navigate", "browser_snapshot", "browser_click",
"browser_type", "browser_scroll", "browser_back",
"browser_press", "browser_close", "browser_get_images",
"browser_vision", "web_search"
"browser_navigate",
"browser_snapshot",
"browser_click",
"browser_type",
"browser_scroll",
"browser_back",
"browser_press",
"browser_close",
"browser_get_images",
"browser_vision",
"web_search",
],
"includes": []
"includes": [],
},
"cronjob": {
"description": "Cronjob management tools - schedule, list, and remove automated tasks",
"tools": ["schedule_cronjob", "list_cronjobs", "remove_cronjob"],
"includes": []
"includes": [],
},
"rl": {
"description": "RL training tools for running reinforcement learning on Tinker-Atropos",
"tools": [
"rl_list_environments", "rl_select_environment",
"rl_get_current_config", "rl_edit_config",
"rl_start_training", "rl_check_status",
"rl_stop_training", "rl_get_results",
"rl_list_runs", "rl_test_inference"
"rl_list_environments",
"rl_select_environment",
"rl_get_current_config",
"rl_edit_config",
"rl_start_training",
"rl_check_status",
"rl_stop_training",
"rl_get_results",
"rl_list_runs",
"rl_test_inference",
],
"includes": []
"includes": [],
},
"file": {
"description": "File manipulation tools: read, write, patch (with fuzzy matching), and search (content + files)",
"tools": ["read_file", "write_file", "patch", "search_files"],
"includes": []
"includes": [],
},
"tts": {
"description": "Text-to-speech: convert text to audio with Edge TTS (free), ElevenLabs, or OpenAI",
"tools": ["text_to_speech"],
"includes": []
"includes": [],
},
"todo": {
"description": "Task planning and tracking for multi-step work",
"tools": ["todo"],
"includes": []
},
"todo": {"description": "Task planning and tracking for multi-step work", "tools": ["todo"], "includes": []},
"memory": {
"description": "Persistent memory across sessions (personal notes + user profile)",
"tools": ["memory"],
"includes": []
"includes": [],
},
"session_search": {
"description": "Search and recall past conversations with summarization",
"tools": ["session_search"],
"includes": []
"includes": [],
},
"clarify": {
"description": "Ask the user clarifying questions (multiple-choice or open-ended)",
"tools": ["clarify"],
"includes": []
"includes": [],
},
"code_execution": {
"description": "Run Python scripts that call tools programmatically (reduces LLM round trips)",
"tools": ["execute_code"],
"includes": []
"includes": [],
},
"delegation": {
"description": "Spawn subagents with isolated context for complex subtasks",
"tools": ["delegate_task"],
"includes": []
"includes": [],
},
"honcho": {
"description": "Honcho AI-native memory for persistent cross-session user modeling",
"tools": ["query_user_context"],
"includes": []
"includes": [],
},
"homeassistant": {
"description": "Home Assistant smart home control and monitoring",
"tools": ["ha_list_entities", "ha_get_state", "ha_list_services", "ha_call_service"],
"includes": []
"includes": [],
},
# Scenario-specific toolsets
"debugging": {
"description": "Debugging and troubleshooting toolkit",
"tools": ["terminal", "process"],
"includes": ["web", "file"] # For searching error messages and solutions, and file operations
"includes": ["web", "file"], # For searching error messages and solutions, and file operations
},
"safe": {
"description": "Safe toolkit without terminal access",
"tools": ["mixture_of_agents"],
"includes": ["web", "vision", "image_gen"]
"includes": ["web", "vision", "image_gen"],
},
# ==========================================================================
# Full Hermes toolsets (CLI + messaging platforms)
#
@ -224,65 +220,63 @@ TOOLSETS = {
# All platforms share the same core tools (including send_message,
# which is gated on gateway running via its check_fn).
# ==========================================================================
"hermes-cli": {
"description": "Full interactive CLI toolset - all default tools plus cronjob management",
"tools": _HERMES_CORE_TOOLS,
"includes": []
"includes": [],
},
"hermes-telegram": {
"description": "Telegram bot toolset - full access for personal use (terminal has safety checks)",
"tools": _HERMES_CORE_TOOLS,
"includes": []
"includes": [],
},
"hermes-discord": {
"description": "Discord bot toolset - full access (terminal has safety checks via dangerous command approval)",
"tools": _HERMES_CORE_TOOLS,
"includes": []
"includes": [],
},
"hermes-whatsapp": {
"description": "WhatsApp bot toolset - similar to Telegram (personal messaging, more trusted)",
"tools": _HERMES_CORE_TOOLS,
"includes": []
"includes": [],
},
"hermes-slack": {
"description": "Slack bot toolset - full access for workspace use (terminal has safety checks)",
"tools": _HERMES_CORE_TOOLS,
"includes": []
"includes": [],
},
"hermes-signal": {
"description": "Signal bot toolset - encrypted messaging platform (full access)",
"tools": _HERMES_CORE_TOOLS,
"includes": []
"includes": [],
},
"hermes-homeassistant": {
"description": "Home Assistant bot toolset - smart home event monitoring and control",
"tools": _HERMES_CORE_TOOLS,
"includes": []
"includes": [],
},
"hermes-gateway": {
"description": "Gateway toolset - union of all messaging platform tools",
"tools": [],
"includes": ["hermes-telegram", "hermes-discord", "hermes-whatsapp", "hermes-slack", "hermes-signal", "hermes-homeassistant"]
}
"includes": [
"hermes-telegram",
"hermes-discord",
"hermes-whatsapp",
"hermes-slack",
"hermes-signal",
"hermes-homeassistant",
],
},
}
def get_toolset(name: str) -> Optional[Dict[str, Any]]:
def get_toolset(name: str) -> dict[str, Any] | None:
"""
Get a toolset definition by name.
Args:
name (str): Name of the toolset
Returns:
Dict: Toolset definition with description, tools, and includes
None: If toolset not found
@ -291,27 +285,27 @@ def get_toolset(name: str) -> Optional[Dict[str, Any]]:
return TOOLSETS.get(name)
def resolve_toolset(name: str, visited: Set[str] = None) -> List[str]:
def resolve_toolset(name: str, visited: set[str] = None) -> list[str]:
"""
Recursively resolve a toolset to get all tool names.
This function handles toolset composition by recursively resolving
included toolsets and combining all tools.
Args:
name (str): Name of the toolset to resolve
visited (Set[str]): Set of already visited toolsets (for cycle detection)
Returns:
List[str]: List of all tool names in the toolset
"""
if visited is None:
visited = set()
# Special aliases that represent all tools across every toolset
# This ensures future toolsets are automatically included without changes.
if name in {"all", "*"}:
all_tools: Set[str] = set()
all_tools: set[str] = set()
for toolset_name in get_toolset_names():
# Use a fresh visited set per branch to avoid cross-branch contamination
resolved = resolve_toolset(toolset_name, visited.copy())
@ -322,73 +316,71 @@ def resolve_toolset(name: str, visited: Set[str] = None) -> List[str]:
if name in visited:
print(f"⚠️ Circular dependency detected in toolset '{name}'")
return []
visited.add(name)
# Get toolset definition
toolset = TOOLSETS.get(name)
if not toolset:
return []
# Collect direct tools
tools = set(toolset.get("tools", []))
# Recursively resolve included toolsets
for included_name in toolset.get("includes", []):
included_tools = resolve_toolset(included_name, visited.copy())
tools.update(included_tools)
return list(tools)
def resolve_multiple_toolsets(toolset_names: List[str]) -> List[str]:
def resolve_multiple_toolsets(toolset_names: list[str]) -> list[str]:
"""
Resolve multiple toolsets and combine their tools.
Args:
toolset_names (List[str]): List of toolset names to resolve
Returns:
List[str]: Combined list of all tool names (deduplicated)
"""
all_tools = set()
for name in toolset_names:
tools = resolve_toolset(name)
all_tools.update(tools)
return list(all_tools)
def get_all_toolsets() -> Dict[str, Dict[str, Any]]:
def get_all_toolsets() -> dict[str, dict[str, Any]]:
"""
Get all available toolsets with their definitions.
Returns:
Dict: All toolset definitions
"""
return TOOLSETS.copy()
def get_toolset_names() -> List[str]:
def get_toolset_names() -> list[str]:
"""
Get names of all available toolsets (excluding aliases).
Returns:
List[str]: List of toolset names
"""
return list(TOOLSETS.keys())
def validate_toolset(name: str) -> bool:
"""
Check if a toolset name is valid.
Args:
name (str): Toolset name to validate
Returns:
bool: True if valid, False otherwise
"""
@ -398,46 +390,35 @@ def validate_toolset(name: str) -> bool:
return name in TOOLSETS
def create_custom_toolset(
name: str,
description: str,
tools: List[str] = None,
includes: List[str] = None
) -> None:
def create_custom_toolset(name: str, description: str, tools: list[str] = None, includes: list[str] = None) -> None:
"""
Create a custom toolset at runtime.
Args:
name (str): Name for the new toolset
description (str): Description of the toolset
tools (List[str]): Direct tools to include
includes (List[str]): Other toolsets to include
"""
TOOLSETS[name] = {
"description": description,
"tools": tools or [],
"includes": includes or []
}
TOOLSETS[name] = {"description": description, "tools": tools or [], "includes": includes or []}
def get_toolset_info(name: str) -> Dict[str, Any]:
def get_toolset_info(name: str) -> dict[str, Any]:
"""
Get detailed information about a toolset including resolved tools.
Args:
name (str): Toolset name
Returns:
Dict: Detailed toolset information
"""
toolset = get_toolset(name)
if not toolset:
return None
resolved_tools = resolve_toolset(name)
return {
"name": name,
"description": toolset["description"],
@ -445,32 +426,32 @@ def get_toolset_info(name: str) -> Dict[str, Any]:
"includes": toolset["includes"],
"resolved_tools": resolved_tools,
"tool_count": len(resolved_tools),
"is_composite": len(toolset["includes"]) > 0
"is_composite": len(toolset["includes"]) > 0,
}
def print_toolset_tree(name: str, indent: int = 0) -> None:
"""
Print a tree view of a toolset and its composition.
Args:
name (str): Toolset name
indent (int): Current indentation level
"""
prefix = " " * indent
toolset = get_toolset(name)
if not toolset:
print(f"{prefix}❌ Unknown toolset: {name}")
return
# Print toolset name and description
print(f"{prefix}📦 {name}: {toolset['description']}")
# Print direct tools
if toolset["tools"]:
print(f"{prefix} 🔧 Tools: {', '.join(toolset['tools'])}")
# Print included toolsets
if toolset["includes"]:
print(f"{prefix} 📂 Includes:")
@ -481,7 +462,7 @@ def print_toolset_tree(name: str, indent: int = 0) -> None:
if __name__ == "__main__":
print("Toolsets System Demo")
print("=" * 60)
print("\nAvailable Toolsets:")
print("-" * 40)
for name, toolset in get_all_toolsets().items():
@ -489,29 +470,29 @@ if __name__ == "__main__":
composite = "[composite]" if info["is_composite"] else "[leaf]"
print(f" {composite} {name:20} - {toolset['description']}")
print(f" Tools: {len(info['resolved_tools'])} total")
print("\nToolset Resolution Examples:")
print("-" * 40)
for name in ["web", "terminal", "safe", "debugging"]:
tools = resolve_toolset(name)
print(f"\n {name}:")
print(f" Resolved to {len(tools)} tools: {', '.join(sorted(tools))}")
print("\nMultiple Toolset Resolution:")
print("-" * 40)
combined = resolve_multiple_toolsets(["web", "vision", "terminal"])
print(f" Combining ['web', 'vision', 'terminal']:")
print(" Combining ['web', 'vision', 'terminal']:")
print(f" Result: {', '.join(sorted(combined))}")
print("\nCustom Toolset Creation:")
print("-" * 40)
create_custom_toolset(
name="my_custom",
description="My custom toolset for specific tasks",
tools=["web_search"],
includes=["terminal", "vision"]
includes=["terminal", "vision"],
)
custom_info = get_toolset_info("my_custom")
print(f" Created 'my_custom' toolset:")
print(" Created 'my_custom' toolset:")
print(f" Description: {custom_info['description']}")
print(f" Resolved tools: {', '.join(custom_info['resolved_tools'])}")