Metadata-Version: 2.4
Name: hermes-nimble-agent
Version: 0.1.0
Summary: Nimble Agent API V2 plugin for Hermes — durable, cited deep-research runs you can start now and resume from any session
Author: Nimble
License-Expression: MIT
Project-URL: Homepage, https://www.nimbleway.com
Project-URL: Documentation, https://docs.nimbleway.com
Project-URL: Source, https://github.com/Nimbleway/hermes-nimble-agent
Project-URL: Repository, https://github.com/Nimbleway/hermes-nimble-agent
Project-URL: Release Notes, https://github.com/Nimbleway/hermes-nimble-agent/releases
Keywords: hermes,hermes-agent,plugin,nimble,research,web-research,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nimble-python<2,>=1.0.0
Provides-Extra: dev
Requires-Dist: hermes-agent==0.19.0; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: pyyaml<7,>=6; extra == "dev"
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Requires-Dist: mypy<2,>=1.14; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Dynamic: license-file

# hermes-nimble-agent

Nimble Agent API V2 plugin for [Hermes](https://github.com/NousResearch/hermes-agent) — durable,
citation-backed deep-research runs your agent can **start now and resume from any session**.

Ask Hermes for researched answers from Telegram, Slack, Discord, or the CLI: the run executes on
Nimble's infrastructure (tens of seconds to minutes), Hermes replies immediately with a durable run
id, and any later conversation — even in a different process, days later — can pick up the cited
result with the id alone.

This is a standalone plugin, installed the way Hermes's third-party-integration policy prescribes:
into `~/.hermes/plugins/` or via the `hermes_agent.plugins` pip entry point. It never modifies
Hermes core.

## What you get

Five tools in a `nimble_agent` toolset, visible to the model only when `NIMBLE_API_KEY` is set:

| Tool | Purpose |
|---|---|
| `nimble_agents_list` | Discover the Web Search Agents already in your account (reuse first) |
| `nimble_agent_bootstrap` | List Nimble's prebuilt research templates, or materialize an agent from one |
| `nimble_agent_run_start` | Start an async research run — returns `run_id` + status **immediately** |
| `nimble_agent_run_status` | Check any run later, from any session, with the ids alone |
| `nimble_agent_run_result` | Fetch the terminal answer: prose or structured JSON **plus trust metadata** — overall confidence with reasoning, sources (primary/secondary), and per-claim citations with verbatim excerpts |

Plus a bundled orchestration skill, `nimble-agent:agent-research`, that teaches the model the full
lifecycle (load it with `skill_view("nimble-agent:agent-research")`).

## Install

Requires Hermes ≥ 0.19 and Python ≥ 3.11.

**Via pip (recommended):**

```bash
pip install hermes-nimble-agent        # same environment as hermes-agent
hermes plugins enable nimble-agent
```

**As a directory plugin:** copy the inner package directory into your Hermes home:

```bash
cp -r src/hermes_nimble_agent ~/.hermes/plugins/nimble-agent
pip install "nimble-python>=1.0.0,<2"   # the SDK must be importable by Hermes
hermes plugins enable nimble-agent
```

Both modes are exercised by the test suite against the real Hermes plugin loader.

## Authentication

Set `NIMBLE_API_KEY` in Hermes's `.env` (get a key from your
[Nimble account](https://app.nimbleway.com)). Without the key the tools stay hidden from the
model — no crash, no half-working state. The key is read by the SDK from the environment; the
plugin never stores, logs, or echoes it, and scrubs it from any error text defensively.

Every request the plugin makes carries `X-Client-Source: hermes` so Nimble can attribute
Hermes-originated traffic.

## The lifecycle in practice

```
You:    Research the current state of EU AI Act enforcement. Use the Nimble
        research agent, medium effort, and give me the run id.

Hermes: → nimble_agents_list            (finds your research agent, wsa_…)
        → nimble_agent_run_start        (returns immediately)
        Started! Run task_run_4f2… on agent wsa_1ab… — medium effort usually
        takes a couple of minutes. Ask me to check it anytime.

[ … later, any session, even another device … ]

You:    Check Nimble run task_run_4f2… and give me the answer.

Hermes: → nimble_agent_run_status       (completed)
        → nimble_agent_run_result
        Here's what the research found … [cited answer]
        Sources: 8 (5 primary) · Confidence: high — "multiple official
        sources agree on the enforcement timeline."
```

First time in an account with no agents? `nimble_agent_bootstrap` lists Nimble's prebuilt
templates (company-profile, due-diligence, competitive-intelligence, market scans, …) and creates a
persistent agent from the one you pick. Creation is deliberate — the plugin never auto-creates
agents behind your back.

### Effort levels

`low` → `medium` → `high` → `x-high` → `max`. Higher is slower and more thorough. `low` can finish
in under a minute but may consult few or no live sources (the trust block will honestly say so);
use `medium` or higher when citations matter.

## Output shape

Every tool returns JSON. A completed result looks like:

```json
{
  "success": true,
  "run": {"run_id": "task_run_…", "agent_id": "wsa_…", "status": "completed", "effort": "medium", "…": "…"},
  "output": {
    "type": "text",
    "content": "The researched answer …",
    "trust": {
      "confidence": "high",
      "reasoning": "Multiple primary sources agree.",
      "sources": [{"url": "https://…", "title": "…", "type": "primary"}],
      "claims": [{"callout": 1, "confidence": "high", "citations": [{"url": "https://…", "excerpts": ["…"]}]}]
    }
  },
  "sources_count": 8,
  "claims_count": 5
}
```

Structured runs (agents configured with an output schema) return `"type": "json"` with
`content` as an object/array and claims keyed by JSON path.

## Errors you'll actually see

All failures come back as structured JSON with a stable `error_type`, a `retriable` flag, and —
always — whatever `agent_id`/`run_id` were in play, so a run is never lost to an error message:

| `error_type` | Meaning | What to do |
|---|---|---|
| `not_ready` | Result requested while the run is still `queued`/`running` (HTTP 409); payload includes the live status | Check status, retry later |
| `terminal_failure` | Run `failed`/`cancelled` (HTTP 422); includes the server's error message | Start a new run |
| `auth` / `permission` | 401 / 403 | Check `NIMBLE_API_KEY`; confirm the account has access to the operation |
| `not_found` | Unknown `agent_id`/`run_id` | Verify ids via `nimble_agents_list` |
| `rate_limited` | 429 | Wait and retry; started runs keep executing |
| `timeout` / `connection` | Transport trouble | Retry; server-side runs are unaffected |
| `validation` | Bad/missing arguments (caught before any API call) | Fix the arguments |
| `dependency` | `nimble-python` not installed (directory installs) | `pip install "nimble-python>=1.0.0,<2"` |
| `protocol` | The API answered outside its documented contract | Report it — includes the ids |

## Troubleshooting

- **Tools don't appear in the model's toolset** — is `NIMBLE_API_KEY` set in Hermes's `.env`? Is the
  plugin enabled (`hermes plugins list`)? Enabling takes effect on the next session.
- **Plugin doesn't show in `hermes plugins list`** — pip mode: is it installed in the same
  environment as `hermes-agent`? Directory mode: the folder must be
  `~/.hermes/plugins/nimble-agent/` containing `plugin.yaml` and `__init__.py` directly. Debug any
  discovery issue with `HERMES_PLUGINS_DEBUG=1 hermes plugins list`.
- **`not_ready` keeps coming back** — higher efforts genuinely take minutes; space checks tens of
  seconds apart (each check is an API call).
- **Lost the run id** — recent runs are visible in your Nimble dashboard; the id is also in the
  conversation where the run was started.

## Development

```bash
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest -q        # the full suite drives the REAL Hermes plugin loader
.venv/bin/ruff check src tests && .venv/bin/ruff format --check src tests
.venv/bin/mypy
.venv/bin/python -m build
```

The test suite exercises both install modes through the actual `hermes_cli` PluginManager from the
released `hermes-agent` wheel — discovery, opt-in enable flow, registration, model-visibility
gating, the full error matrix, credential redaction, and on-the-wire `X-Client-Source` evidence via
a mocked HTTP transport.

## License

MIT
