hermes-plugin-haunt 0.1.0

Haunt web extraction provider for Hermes Agent

Haunt for Hermes Agent

Use Haunt as the web_extract provider inside Hermes Agent.

Haunt turns permitted public pages into clean Markdown. When a page cannot be read, it returns an explicit error such as captcha_required, login_required, or not_found. It does not turn an error page into a successful answer, and failed calls are not charged.

Install

pip install hermes-plugin-haunt

Add your Haunt API key:

export HAUNT_API_KEY="your-key"

Get a free key with 1,000 monthly credits at hauntapi.com.

Select Haunt for extraction in ~/.hermes/config.yaml:

web:
  extract_backend: haunt

Hermes discovers the package through its hermes_agent.plugins entry point. You can also run hermes tools and choose Haunt in the Web Extract picker.

What it does

• Implements Hermes Agent's native WebSearchProvider.
• Provides web_extract.
• Returns Markdown by default and raw HTML when Hermes requests HTML.
• Preserves Haunt's failure code, billing outcome, and request ID in metadata.
• Supports more than one URL while keeping the input order.
• Does not provide web search. Pair it with a search provider if needed.

Example configuration:

web:
  search_backend: brave-free
  extract_backend: haunt

Failure shape

A blocked page remains a failed page:

{
  "url": "https://example.com/challenge",
  "title": "",
  "content": "",
  "error": "captcha_required: The page requires human verification.",
  "metadata": {
    "provider": "haunt",
    "error_code": "captcha_required",
    "charged": false,
    "credits_used": 0
  }
}

This lets the agent retry another provider, ask for an authorised session, or explain the failure instead of reasoning from empty content.

Development

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/ruff check .

The package is independent of Hermes at import time so its unit tests can run without a full Hermes installation.

Links

• Haunt documentation
• Haunt MCP server
• Hermes web provider documentation

License

MIT