Metadata-Version: 2.4
Name: hermes-plugin-haunt
Version: 0.1.0
Summary: Haunt web extraction provider for Hermes Agent
Project-URL: Homepage, https://hauntapi.com?utm_source=hermes&utm_medium=integration&utm_campaign=sweep-2026-07
Project-URL: Documentation, https://hauntapi.com/docs?utm_source=hermes&utm_medium=integration&utm_campaign=sweep-2026-07
Project-URL: Repository, https://github.com/Darko893/hermes-plugin-haunt
Project-URL: Issues, https://github.com/Darko893/hermes-plugin-haunt/issues
Author-email: Haunt API <support@hauntapi.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,haunt,hermes-agent,mcp,web-extraction
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install hermes-plugin-haunt
```

Add your Haunt API key:

```bash
export HAUNT_API_KEY="your-key"
```

Get a free key with 1,000 monthly credits at
[hauntapi.com](https://hauntapi.com/?utm_source=hermes&utm_medium=integration&utm_campaign=sweep-2026-07#signup).

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

```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:

```yaml
web:
  search_backend: brave-free
  extract_backend: haunt
```

## Failure shape

A blocked page remains a failed page:

```json
{
  "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

```bash
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](https://hauntapi.com/docs?utm_source=hermes&utm_medium=integration&utm_campaign=sweep-2026-07)
- [Haunt MCP server](https://github.com/Darko893/haunt-mcp-server)
- [Hermes web provider documentation](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/developer-guide/web-search-provider-plugin.md)

## License

MIT
