Metadata-Version: 2.2
Name: hermes-tinyfish-web-search
Version: 1.0.0
Summary: Live web search, content extraction, browser sessions, and agent automation for Hermes — powered by TinyFish API
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.28.1

# Hermes TinyFish Web Search

Give your Hermes agent live access to the web — powered by the TinyFish API.

When your agent needs to look something up, this plugin answers with grounded, sourced results instead of stale training data. It covers the full TinyFish API surface: search, content extraction, browser sessions, and agent automation.

## Why use this plugin?

**Real answers from the live web.** Your agent's training data ends months ago. This plugin connects it to TinyFish so it can answer questions about today's world — breaking news, current docs, recent releases, real-time events.

**Search is free.** TinyFish Search API does not consume credits. Fetch API is also credit-free. You only pay for browser and agent automation runs.

**Complete API coverage.** This plugin exposes all four TinyFish APIs as discrete tools: Search for ranked results, Fetch for page extraction, Browser for remote CDP sessions, and Agent for goal-based automation.

**Zero maintenance.** The provider self-registers with Hermes at startup. There is nothing to configure beyond pasting your API key.

## What you'll need

- **Hermes agent** installed and working (any platform — CLI, desktop, Telegram, Discord, etc.)
- **A TinyFish API key** (free tier available)

## Getting a TinyFish API key

1. Go to **[agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys)** in your browser
2. Sign up for a free account or log in if you already have one
3. Create an API key and copy it

## Installation

### One command

From inside your Hermes environment:

```bash
pip install hermes-tinyfish-web-search
```

### Or from source

```bash
git clone https://github.com/your-username/hermes-tinyfish-web-search.git
cd hermes-tinyfish-web-search
pip install .
```

## Configuration

### Step 1 — Add your API key

Open `~/.hermes/.env` in any text editor and add one line:

```bash
TINYFISH_API_KEY=your-api-key-here
```

### Step 2 — Enable the plugin

Open `~/.hermes/config.yaml` and add `hermes-tinyfish-web-search` to your enabled plugins:

```yaml
plugins:
  enabled:
    - hermes-tinyfish-web-search
```

### Step 3 — Tell Hermes to use it

In the same `config.yaml` file, under the `web` section, set the backend:

```yaml
web:
  backend: tinyfish
```

The full `config.yaml` will look something like this:

```yaml
plugins:
  enabled:
    - hermes-tinyfish-web-search

web:
  backend: tinyfish
```

### Step 4 — Restart Hermes

Quit and restart your Hermes agent. On the next question that needs web access, the agent will use TinyFish.

## Available tools

The plugin registers six tools under the `tinyfish` toolset:

| Tool                               | API          | Description                                                      |
|------------------------------------|--------------|------------------------------------------------------------------|
| `web_search_tinyfish`              | Search       | Web search with geo-targeting, date filters, news, and academics |
| `web_extract_tinyfish`             | Fetch        | Extract clean page content from a single URL                     |
| `web_extract_batch_tinyfish`       | Fetch        | Extract content from up to 10 URLs in one request                |
| `browser_create_session_tinyfish`  | Browser      | Create a remote browser session (returns CDP WebSocket URL)      |
| `browser_terminate_session_tinyfish` | Browser   | Terminate a browser session by session_id                        |
| `agent_automation_tinyfish`        | Agent        | Run goal-based browser automation with natural language          |

### Search features

- Geo-targeted results (`location`, `language`)
- Date filtering (`recency_minutes`, `after_date`, `before_date`)
- Domain type: `web` (default), `news`, `research_paper`
- Domain filtering (`include_domains`, `exclude_domains`)
- Academic search with `pub_year_min`/`pub_year_max`

### Fetch features

- Output formats: `markdown` (default), `html`, `json`
- CSS selector scoping (`include_selectors`, `exclude_selectors`)
- Cache control (`ttl`)
- Extract links and image links

### Browser features

- Create remote browser sessions with CDP WebSocket URLs
- Compatible with Playwright, Puppeteer, and any CDP client
- Configurable inactivity timeout

### Agent features

- Goal-based automation with natural language instructions
- Structured output with `output_schema`
- Browser profiles (`lite`, `stealth`)
- Step and duration limits

## How it works

When your agent calls `web_search("some query")`, the plugin sends the query to the TinyFish Search API (`GET https://api.search.tinyfish.ai`) and returns ranked results with titles, snippets, and URLs.

When your agent calls `web_extract(url)`, the plugin sends the URL to the TinyFish Fetch API (`POST https://api.fetch.tinyfish.ai`) for full-page content extraction in the requested format.

Under the hood, this uses `httpx` for HTTP requests. It is installed automatically as a dependency.

## Per-capability routing

You can use TinyFish for search only (or extract only) while routing the other capability to a different provider:

```yaml
web:
  search_backend: tinyfish     # TinyFish handles web_search
  extract_backend: keiroslabs   # KeiroLabs handles web_extract
```

## Troubleshooting

### "TINYFISH_API_KEY environment variable not set"

The plugin can't find your key. Check that:
- `~/.hermes/.env` exists and has a line starting with `TINYFISH_API_KEY=`
- There are no extra spaces or quotes around the value
- You restarted Hermes after adding the key

### "Invalid TINYFISH_API_KEY" or "access denied"

Your API key may be incorrect or expired. Visit [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys) to verify your key is still active. Generate a new key if needed.

### "TinyFish API: payment required"

Your subscription does not include access to the requested API (Browser or Agent). Visit [agent.tinyfish.ai](https://agent.tinyfish.ai) to upgrade your plan.

### "Failed to connect to TinyFish API"

Check:
- Your internet connection is working
- You can reach `https://api.search.tinyfish.ai` in a browser or with `curl`
- No firewall or VPN is blocking outbound HTTPS on port 443

## Development

```bash
git clone https://github.com/your-username/hermes-tinyfish-web-search.git
cd hermes-tinyfish-web-search
pip install -e .
pytest
```

Tests use mocks so no API key or network access is needed to run the suite.
