Metadata-Version: 2.5
Name: ory-hermes
Version: 1.8.1
Summary: Ory Agent Security for the Hermes agent framework — per-tool authorization, activity logging, and identity propagation by wrapping the tool registry. Built on ory-argus.
Author: Ory
License-Expression: Apache-2.0
Keywords: agent,ai,authorization,hermes,hermes-agent,nous,ory,permissions
Requires-Python: >=3.10
Requires-Dist: ory-argus<2,>=1
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# ory-hermes

Ory Agent Security for the [Hermes agent framework](https://github.com/NousResearch/hermes-agent).

Wraps your Hermes tool registry so every call is authorized against Ory Permissions,
audited, and tied to the user → agent identity — built on
[`ory-argus`](https://pypi.org/project/ory-argus/).

```bash
pip install ory-hermes
```

Hermes drives its loop from a `{name: callable}` tool registry (`model_tools`).
Gate it before handing it to the agent:

```python
from ory_hermes import guard_function_map

tools = guard_function_map(model_tools)   # returns a gated copy of the registry
```

Tool objects (with a `run` / `_run` method) work too:

```python
from ory_hermes import guard_tools

tools = guard_tools([search_tool, shell_tool])
```

### MCP tools

Hermes registers MCP tools as `mcp__<server>__<tool>`. Those calls are checked as
`McpServer:<server>` and `McpTool:<server>:<tool>` instead of plain tools. Give the guard
Hermes' registry and `mcp_servers` config for the most exact identity:

```python
from tools.registry import registry          # Hermes' tool registry
from hermes_cli.config import load_config

tools = guard_function_map(
    model_tools,
    registry=registry,                         # exact server from the `mcp-<server>` toolset
    mcp_servers=load_config().get("mcp_servers"),  # server names + hashed fingerprints
)
```

The server is read from the tool's `mcp-<server>` toolset when `registry` is given (Hermes
keeps the unsanitized server name there), else from the configured server whose sanitized name
prefixes the tool, else from the registry name itself. The tool is Hermes' sanitized tool name;
for a name Hermes clamped to 64 characters with a hash suffix, only the `McpServer` check
applies. With `mcp_servers` config, the server's URL host or launched package is also sent as a
hashed fingerprint so Agent Security matches the server to its catalog whatever it is named;
URLs and arguments themselves are not sent. Both arguments are optional, and other tools keep
their native checks.

In **enforce** mode a denied tool raises `OryDenialError`
before the tool body runs; Hermes surfaces the denial and the tool never executes. In
**observe** mode (default) the tool runs and a `permission.observe_deny` activity event is recorded.
Network and rate-limit errors deny in enforce mode and fail open in observe mode.

> The integration is SDK-free: it wraps Hermes' plain Python registry by duck typing.
> Hermes is installed through its own bootstrap process and does not publish an
> installable Python SDK, so this package intentionally has no Hermes dependency or
> external real-SDK compatibility test.

Credentials come from the shared `~/.config/ory-agent-plugins/config.json`, so a login
performed by any other Ory harness plugin or SDK integration is reused here.
