2025-10-01 23:29:25 +00:00
|
|
|
[build-system]
|
|
|
|
|
requires = ["setuptools>=61.0"]
|
|
|
|
|
build-backend = "setuptools.build_meta"
|
|
|
|
|
|
|
|
|
|
[project]
|
|
|
|
|
name = "hermes-agent"
|
chore: release v0.5.0 (v2026.3.28) (#3568)
The hardening release — Nous Portal 400+ models, Hugging Face provider,
Telegram Private Chat Topics, native Modal SDK, plugin lifecycle hooks,
improved OpenAI model reliability, Nix flake, supply chain hardening,
Anthropic output limits fix, and 50+ security/reliability fixes.
165 merged PRs, 65 closed issues across a 5-day window.
2026-03-28 13:11:39 -07:00
|
|
|
version = "0.5.0"
|
docs: rebrand messaging — 'the self-improving AI agent'
- Lead with the learning loop: autonomous skill creation, skill
self-improvement, memory nudges, FTS5 session search, Honcho
dialectic user modeling
- 'Runs anywhere' angle: 6 backends, serverless persistence with
Daytona/Modal, not tied to your laptop
- 'Built by model trainers' replaces 'model-agnostic'
- Updated README tagline, feature table, subtitle
- Updated docs landing page hero, description, key features
- Updated docusaurus tagline and pyproject.toml description
2026-03-06 04:34:06 -08:00
|
|
|
description = "The self-improving AI agent — creates skills from experience, improves them during use, and runs anywhere"
|
2025-10-01 23:29:25 +00:00
|
|
|
readme = "README.md"
|
2026-03-05 17:04:08 -08:00
|
|
|
requires-python = ">=3.11"
|
2026-01-29 22:36:07 +00:00
|
|
|
authors = [{ name = "Nous Research" }]
|
2025-10-01 23:29:25 +00:00
|
|
|
license = { text = "MIT" }
|
|
|
|
|
dependencies = [
|
2026-03-24 08:25:17 -07:00
|
|
|
# Core — pinned to known-good ranges to limit supply chain attack surface
|
|
|
|
|
"openai>=2.21.0,<3",
|
2026-03-31 00:37:14 +00:00
|
|
|
"anthropic>=0.39.0,<1",
|
|
|
|
|
"google-genai>=1.2.0,<2",
|
2026-03-24 08:25:17 -07:00
|
|
|
"python-dotenv>=1.2.1,<2",
|
|
|
|
|
"fire>=0.7.1,<1",
|
|
|
|
|
"httpx>=0.28.1,<1",
|
|
|
|
|
"rich>=14.3.3,<15",
|
|
|
|
|
"tenacity>=9.1.4,<10",
|
|
|
|
|
"pyyaml>=6.0.2,<7",
|
2026-03-25 16:43:21 -07:00
|
|
|
"requests>=2.33.0,<3", # CVE-2026-25645
|
2026-03-24 08:25:17 -07:00
|
|
|
"jinja2>=3.1.5,<4",
|
|
|
|
|
"pydantic>=2.12.5,<3",
|
2026-02-07 00:05:04 +00:00
|
|
|
# Interactive CLI (prompt_toolkit is used directly by cli.py)
|
2026-03-24 08:25:17 -07:00
|
|
|
"prompt_toolkit>=3.0.52,<4",
|
2026-01-29 22:36:07 +00:00
|
|
|
# Tools
|
2026-03-28 17:35:53 -07:00
|
|
|
"exa-py>=2.9.0,<3",
|
2026-03-24 08:25:17 -07:00
|
|
|
"firecrawl-py>=4.16.0,<5",
|
|
|
|
|
"parallel-web>=0.4.2,<1",
|
|
|
|
|
"fal-client>=0.13.1,<1",
|
2026-02-14 16:08:14 -08:00
|
|
|
# Text-to-speech (Edge TTS is free, no API key needed)
|
2026-03-24 08:25:17 -07:00
|
|
|
"edge-tts>=7.2.7,<8",
|
|
|
|
|
"faster-whisper>=1.0.0,<2",
|
Add Skills Hub — universal skill search, install, and management from online registries
Implements the Hermes Skills Hub with agentskills.io spec compliance,
multi-registry skill discovery, security scanning, and user-driven
management via CLI and /skills slash command.
Core features:
- Security scanner (tools/skills_guard.py): 120 threat patterns across
12 categories, trust-aware install policy (builtin/trusted/community),
structural checks, unicode injection detection, LLM audit pass
- Hub client (tools/skills_hub.py): GitHub, ClawHub, Claude Code
marketplace, and LobeHub source adapters with shared GitHubAuth
(PAT + gh CLI + GitHub App), lock file provenance tracking, quarantine
flow, and unified search across all sources
- CLI interface (hermes_cli/skills_hub.py): search, install, inspect,
list, audit, uninstall, publish (GitHub PR), snapshot export/import,
and tap management — powers both `hermes skills` and `/skills`
Spec conformance (Phase 0):
- Upgraded frontmatter parser to yaml.safe_load with fallback
- Migrated 39 SKILL.md files: tags/related_skills to metadata.hermes.*
- Added assets/ directory support and compatibility/metadata fields
- Excluded .hub/ from skill discovery in skills_tool.py
Updated 13 config/doc files including README, AGENTS.md, .env.example,
setup wizard, doctor, status, pyproject.toml, and docs.
2026-02-18 16:09:05 -08:00
|
|
|
# Skills Hub (GitHub App JWT auth — optional, only needed for bot identity)
|
2026-03-25 16:43:21 -07:00
|
|
|
"PyJWT[crypto]>=2.12.0,<3", # CVE-2026-32597
|
2025-10-01 23:29:25 +00:00
|
|
|
]
|
|
|
|
|
|
2026-01-29 22:36:07 +00:00
|
|
|
[project.optional-dependencies]
|
2026-03-28 11:21:44 -07:00
|
|
|
modal = ["modal>=1.0.0,<2"]
|
2026-03-24 08:25:17 -07:00
|
|
|
daytona = ["daytona>=0.148.0,<1"]
|
|
|
|
|
dev = ["pytest>=9.0.2,<10", "pytest-asyncio>=1.3.0,<2", "pytest-xdist>=3.0,<4", "mcp>=1.2.0,<2"]
|
|
|
|
|
messaging = ["python-telegram-bot>=22.6,<23", "discord.py[voice]>=2.7.1,<3", "aiohttp>=3.13.3,<4", "slack-bolt>=1.18.0,<2", "slack-sdk>=3.27.0,<4"]
|
|
|
|
|
cron = ["croniter>=6.0.0,<7"]
|
|
|
|
|
slack = ["slack-bolt>=1.18.0,<2", "slack-sdk>=3.27.0,<4"]
|
|
|
|
|
matrix = ["matrix-nio[e2e]>=0.24.0,<1"]
|
|
|
|
|
cli = ["simple-term-menu>=1.0,<2"]
|
|
|
|
|
tts-premium = ["elevenlabs>=1.0,<2"]
|
|
|
|
|
voice = ["sounddevice>=0.4.6,<1", "numpy>=1.24.0,<3"]
|
2026-03-05 17:02:51 -05:00
|
|
|
pty = [
|
2026-03-24 08:25:17 -07:00
|
|
|
"ptyprocess>=0.7.0,<1; sys_platform != 'win32'",
|
|
|
|
|
"pywinpty>=2.0.0,<3; sys_platform == 'win32'",
|
2026-03-05 17:02:51 -05:00
|
|
|
]
|
2026-03-24 08:25:17 -07:00
|
|
|
honcho = ["honcho-ai>=2.0.1,<3"]
|
|
|
|
|
mcp = ["mcp>=1.2.0,<2"]
|
|
|
|
|
homeassistant = ["aiohttp>=3.9.0,<4"]
|
|
|
|
|
sms = ["aiohttp>=3.9.0,<4"]
|
2026-03-26 19:21:34 -07:00
|
|
|
acp = ["agent-client-protocol>=0.8.1,<0.9"]
|
2026-03-24 08:25:17 -07:00
|
|
|
dingtalk = ["dingtalk-stream>=0.1.0,<1"]
|
feat(gateway): add Feishu/Lark platform support (#3817)
Adds Feishu (ByteDance's enterprise messaging platform) as a gateway
platform adapter with full feature parity: WebSocket + webhook transports,
message batching, dedup, rate limiting, rich post/card content parsing,
media handling (images/audio/files/video), group @mention gating,
reaction routing, and interactive card button support.
Cherry-picked from PR #1793 by penwyp with:
- Moved to current main (PR was 458 commits behind)
- Fixed _send_with_retry shadowing BasePlatformAdapter method (renamed to
_feishu_send_with_retry to avoid signature mismatch crash)
- Fixed import structure: aiohttp/websockets imported independently of
lark_oapi so they remain available when SDK is missing
- Fixed get_hermes_home import (hermes_constants, not hermes_cli.config)
- Added skip decorators for tests requiring lark_oapi SDK
- All 16 integration points added surgically to current main
New dependency: lark-oapi>=1.5.3,<2 (optional, pip install hermes-agent[feishu])
Fixes #1788
Co-authored-by: penwyp <penwyp@users.noreply.github.com>
2026-03-29 18:17:42 -07:00
|
|
|
feishu = ["lark-oapi>=1.5.3,<2"]
|
2026-03-12 09:11:44 -07:00
|
|
|
rl = [
|
|
|
|
|
"atroposlib @ git+https://github.com/NousResearch/atropos.git",
|
|
|
|
|
"tinker @ git+https://github.com/thinking-machines-lab/tinker.git",
|
2026-03-24 08:25:17 -07:00
|
|
|
"fastapi>=0.104.0,<1",
|
|
|
|
|
"uvicorn[standard]>=0.24.0,<1",
|
|
|
|
|
"wandb>=0.15.0,<1",
|
2026-03-12 09:11:44 -07:00
|
|
|
]
|
2026-03-24 08:42:45 -07:00
|
|
|
yc-bench = ["yc-bench @ git+https://github.com/collinear-ai/yc-bench.git ; python_version >= '3.12'"]
|
2026-02-07 21:11:01 +00:00
|
|
|
all = [
|
|
|
|
|
"hermes-agent[modal]",
|
2026-03-05 11:13:12 -08:00
|
|
|
"hermes-agent[daytona]",
|
2026-02-07 21:11:01 +00:00
|
|
|
"hermes-agent[messaging]",
|
2026-03-29 21:53:28 -07:00
|
|
|
"hermes-agent[matrix]",
|
2026-02-07 21:11:01 +00:00
|
|
|
"hermes-agent[cron]",
|
|
|
|
|
"hermes-agent[cli]",
|
|
|
|
|
"hermes-agent[dev]",
|
2026-02-14 16:08:14 -08:00
|
|
|
"hermes-agent[tts-premium]",
|
Add messaging platform enhancements: STT, stickers, Discord UX, Slack, pairing, hooks
Major feature additions inspired by OpenClaw/ClawdBot integration analysis:
Voice Message Transcription (STT):
- Auto-transcribe voice/audio messages via OpenAI Whisper API
- Download voice to ~/.hermes/audio_cache/ on Telegram/Discord/WhatsApp
- Inject transcript as text so all models can understand voice input
- Configurable model (whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe)
Telegram Sticker Understanding:
- Describe static stickers via vision tool with JSON-backed cache
- Cache keyed by file_unique_id avoids redundant API calls
- Animated/video stickers get emoji-based fallback description
Discord Rich UX:
- Native slash commands (/ask, /reset, /status, /stop) via app_commands
- Button-based exec approvals (Allow Once / Always Allow / Deny)
- ExecApprovalView with user authorization and timeout handling
Slack Integration:
- Full SlackAdapter using slack-bolt with Socket Mode
- DMs, channel messages (mention-gated), /hermes slash command
- File attachment handling with bot-token-authenticated downloads
DM Pairing System:
- Code-based user authorization as alternative to static allowlists
- 8-char codes from unambiguous alphabet, 1-hour expiry
- Rate limiting, lockout after failed attempts, chmod 0600 on data
- CLI: hermes pairing list/approve/revoke/clear-pending
Event Hook System:
- File-based hook discovery from ~/.hermes/hooks/
- HOOK.yaml + handler.py per hook, sync/async handler support
- Events: gateway:startup, session:start/reset, agent:start/step/end
- Wildcard matching (command:* catches all command events)
Cross-Channel Messaging:
- send_message agent tool for delivering to any connected platform
- Enables cron job delivery and cross-platform notifications
Human-Like Response Pacing:
- Configurable delays between message chunks (off/natural/custom)
- HERMES_HUMAN_DELAY_MODE env var with min/max ms settings
Warm Injection Message Style:
- Retrofitted image vision messages with friendly kawaii-consistent tone
- All new injection messages (STT, stickers, errors) use warm style
Also: updated config migration to prompt for optional keys interactively,
bumped config version, updated README, AGENTS.md, .env.example,
cli-config.yaml.example, install scripts, pyproject.toml, and toolsets.
2026-02-15 21:38:59 -08:00
|
|
|
"hermes-agent[slack]",
|
Add background process management with process tool, wait, PTY, and stdin support
New process registry and tool for managing long-running background processes
across all terminal backends (local, Docker, Singularity, Modal, SSH).
Process Registry (tools/process_registry.py):
- ProcessSession tracking with rolling 200KB output buffer
- spawn_local() with optional PTY via ptyprocess for interactive CLIs
- spawn_via_env() for non-local backends (runs inside sandbox, never on host)
- Background reader threads per process (Popen stdout or PTY)
- wait() with timeout clamping, interrupt support, and transparent limit reporting
- JSON checkpoint to ~/.hermes/processes.json for gateway crash recovery
- Module-level singleton shared across agent loop, gateway, and RL
Process Tool (model_tools.py):
- 7 actions: list, poll, log, wait, kill, write, submit
- Paired with terminal in all toolsets (CLI, messaging, RL)
- Timeout clamping with transparent notes in response
Terminal Tool Updates (tools/terminal_tool.py):
- Replaced nohup background mode with registry spawn (returns session_id)
- Added workdir parameter for per-command working directory
- Added check_interval parameter for gateway auto-check watchers
- Added pty parameter for interactive CLI tools (Codex, Claude Code)
- Updated TERMINAL_TOOL_DESCRIPTION with full background workflow docs
- Cleanup thread now respects active background processes (won't reap sandbox)
Gateway Integration (gateway/run.py, session.py, config.py):
- Session reset protection: sessions with active processes exempt from reset
- Default idle timeout increased from 2 hours to 24 hours
- from_dict fallback aligned to match (was 120, now 1440)
- session_key env var propagated to process registry for session mapping
- Crash recovery on gateway startup via checkpoint probe
- check_interval watcher: asyncio task polls process, delivers updates to platform
RL Safety (environments/):
- tool_context.py cleanup() kills background processes on episode end
- hermes_base_env.py warns when enabled_toolsets is None (loads all tools)
- Process tool safe in RL via wait() blocking the agent loop
Also:
- Added ptyprocess as optional dependency (in pyproject.toml [pty] extra + [all])
- Fixed pre-existing bug: rl_test_inference missing from TOOL_TO_TOOLSET_MAP
- Updated AGENTS.md with process management docs and project structure
- Updated README.md terminal section with process management overview
2026-02-17 02:51:31 -08:00
|
|
|
"hermes-agent[pty]",
|
2026-02-25 19:34:25 -05:00
|
|
|
"hermes-agent[honcho]",
|
feat: add MCP (Model Context Protocol) client support
Connect to external MCP servers via stdio transport, discover their tools
at startup, and register them into the hermes-agent tool registry.
- New tools/mcp_tool.py: config loading, server connection via background
event loop, tool handler factories, discovery, and graceful shutdown
- model_tools.py: trigger MCP discovery after built-in tool imports
- cli.py: call shutdown_mcp_servers in _run_cleanup
- pyproject.toml: add mcp>=1.2.0 as optional dependency
- 27 unit tests covering config, schema conversion, handlers, registration,
SDK interaction, toolset injection, graceful fallback, and shutdown
Config format (in ~/.hermes/config.yaml):
mcp_servers:
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
2026-03-02 21:03:14 +03:00
|
|
|
"hermes-agent[mcp]",
|
2026-02-28 13:32:48 +03:00
|
|
|
"hermes-agent[homeassistant]",
|
feat: add SMS (Twilio) platform adapter
Add SMS as a first-class messaging platform via the Twilio API.
Shares credentials with the existing telephony skill — same
TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER env vars.
Adapter (gateway/platforms/sms.py):
- aiohttp webhook server for inbound (Twilio form-encoded POSTs)
- Twilio REST API with Basic auth for outbound
- Markdown stripping, smart chunking at 1600 chars
- Echo loop prevention, phone number redaction in logs
Integration (13 files):
- gateway config, run, channel_directory
- agent prompt_builder (SMS platform hint)
- cron scheduler, cronjob tools
- send_message_tool (_send_sms via Twilio API)
- toolsets (hermes-sms + hermes-gateway)
- gateway setup wizard, status display
- pyproject.toml (sms optional extra)
- 21 tests
Docs:
- website/docs/user-guide/messaging/sms.md (full setup guide)
- Updated messaging index (architecture, toolsets, security, links)
- Updated environment-variables.md reference
Inspired by PR #1575 (@sunsakis), rewritten for Twilio.
2026-03-17 03:14:53 -07:00
|
|
|
"hermes-agent[sms]",
|
2026-03-14 00:09:05 -07:00
|
|
|
"hermes-agent[acp]",
|
2026-03-03 16:17:05 +03:00
|
|
|
"hermes-agent[voice]",
|
2026-03-22 04:08:49 -07:00
|
|
|
"hermes-agent[dingtalk]",
|
feat(gateway): add Feishu/Lark platform support (#3817)
Adds Feishu (ByteDance's enterprise messaging platform) as a gateway
platform adapter with full feature parity: WebSocket + webhook transports,
message batching, dedup, rate limiting, rich post/card content parsing,
media handling (images/audio/files/video), group @mention gating,
reaction routing, and interactive card button support.
Cherry-picked from PR #1793 by penwyp with:
- Moved to current main (PR was 458 commits behind)
- Fixed _send_with_retry shadowing BasePlatformAdapter method (renamed to
_feishu_send_with_retry to avoid signature mismatch crash)
- Fixed import structure: aiohttp/websockets imported independently of
lark_oapi so they remain available when SDK is missing
- Fixed get_hermes_home import (hermes_constants, not hermes_cli.config)
- Added skip decorators for tests requiring lark_oapi SDK
- All 16 integration points added surgically to current main
New dependency: lark-oapi>=1.5.3,<2 (optional, pip install hermes-agent[feishu])
Fixes #1788
Co-authored-by: penwyp <penwyp@users.noreply.github.com>
2026-03-29 18:17:42 -07:00
|
|
|
"hermes-agent[feishu]",
|
2026-02-07 21:11:01 +00:00
|
|
|
]
|
2026-01-29 22:36:07 +00:00
|
|
|
|
2025-10-01 23:29:25 +00:00
|
|
|
[project.scripts]
|
2026-02-02 19:01:51 -08:00
|
|
|
hermes = "hermes_cli.main:main"
|
2025-10-01 23:29:25 +00:00
|
|
|
hermes-agent = "run_agent:main"
|
2026-03-14 00:09:05 -07:00
|
|
|
hermes-acp = "acp_adapter.entry:main"
|
2025-10-01 23:29:25 +00:00
|
|
|
|
|
|
|
|
[tool.setuptools]
|
2026-03-24 08:19:14 -07:00
|
|
|
py-modules = ["run_agent", "model_tools", "toolsets", "batch_runner", "trajectory_compressor", "toolset_distributions", "cli", "hermes_constants", "hermes_state", "hermes_time", "rl_cli", "utils"]
|
2025-10-01 23:29:25 +00:00
|
|
|
|
|
|
|
|
[tool.setuptools.packages.find]
|
2026-03-14 00:09:05 -07:00
|
|
|
include = ["agent", "tools", "tools.*", "hermes_cli", "gateway", "gateway.*", "cron", "honcho_integration", "acp_adapter"]
|
test: reorganize test structure and add missing unit tests
Reorganize flat tests/ directory to mirror source code structure
(tools/, gateway/, hermes_cli/, integration/). Add 11 new test files
covering previously untested modules: registry, patch_parser,
fuzzy_match, todo_tool, approval, file_tools, gateway session/config/
delivery, and hermes_cli config/models. Total: 147 unit tests passing,
9 integration tests gated behind pytest marker.
2026-02-26 03:20:08 +03:00
|
|
|
|
|
|
|
|
[tool.pytest.ini_options]
|
|
|
|
|
testpaths = ["tests"]
|
|
|
|
|
markers = [
|
|
|
|
|
"integration: marks tests requiring external services (API keys, Modal, etc.)",
|
|
|
|
|
]
|
2026-03-09 20:47:34 -05:00
|
|
|
addopts = "-m 'not integration' -n auto"
|