Metadata-Version: 2.2
Name: hermes-gemini-web-search
Version: 1.0.0
Summary: Live web search and content extraction for Hermes agent — powered by Google Gemini Search Grounding
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
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-genai<3,>=2.2.0
Requires-Dist: httpx<1,>=0.28.1

# Hermes Gemini Web Search

Give your Hermes agent live access to the web — powered by Google's search index, delivered through the Gemini API.

When your agent needs to look something up, this plugin answers with grounded, sourced results instead of stale training data. It works for both quick searches ("what's the latest Python release?") and deep page extraction ("summarize this RFC for me").

## Why use this plugin?

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

**Grounded, not guessed.** Every result is backed by Google's search index. The agent sees actual search snippets and supporting sources, not hallucinations. When you ask "what changed in React 19?" you get the real changelog, not a confident-sounding fabrication.

**Search and extract in one.** Some providers only search. This one does both — find information and pull full page content — so you don't need two plugins wired together.

**Free to start.** Google offers a generous free tier. You only pay if your usage grows past it. No credit card required to get a key.

**Runs on Gemini's speed.** Uses `gemini-3.1-flash-lite` by default — fast, cheap, and purpose-built for search grounding. You can swap in any Gemini model.

**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 Google API key** (free, takes 30 seconds)

That's it. No other accounts, no credit card, no setup scripts.

## Getting a Google API key

1. Go to **[Google AI Studio](https://aistudio.google.com/app/apikey)** in your browser
2. Sign in with any Google account (personal Gmail works)
3. Click **"Create API Key"**
4. Copy the key that appears — it will look like `AIza...`

The free tier gives you a generous number of queries per minute. You will get an email if you approach the limit — upgrade to a paid plan only if you need more.

## Installation

### One command

From inside your Hermes environment:

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

### Or from source

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

### Or by copying into Hermes directly

```bash
mkdir -p ~/.hermes/plugins/web/gemini
cp hermes_gemini_web_search/* ~/.hermes/plugins/web/gemini/
```

The pip install method is recommended — it keeps the plugin up to date and discoverable.

## Configuration

Three short steps. Everything happens in two files inside `~/.hermes/`.

### Step 1 — Add your API key

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

```bash
GEMINI_API_KEY=AIza...your-key-here
```

You can also use `GOOGLE_API_KEY` if you already have one set for other Google services. The plugin checks both.

### Step 2 — Enable the plugin

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

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

If you already have other plugins enabled, just add this one to the list. If you have never enabled a plugin before, the `plugins` section might not exist yet — create it at the top level of the file and add both keys exactly as shown.

### Step 3 — Tell Hermes to use it

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

```yaml
web:
  backend: gemini
```

The full `config.yaml` will look something like this (your file may have other sections — that's fine):

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

web:
  backend: gemini
```

### Step 4 — Restart Hermes

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

## Verifying it works

Ask your agent something that requires live web access:

```
> what is the latest stable version of Python?

> who won the most recent Formula 1 race?

> summarize the top story on Hacker News today
```

If the agent returns current, factual answers, the plugin is working.

You can also check with the Hermes tools picker:

```bash
hermes tools
```

Navigate to **Web Search** — you should see "Gemini Google Search Grounding" listed with a green checkmark and "free tier available" badge.

## How it works

When your agent calls `web_search("some query")`, the plugin sends the query to Gemini's API with a `google_search` grounding tool enabled. Gemini searches the live web, retrieves relevant pages, and returns:

- A **grounded answer** — Gemini's summary of what it found, backed by the search results
- **Supporting sources** — links to the actual pages so the agent (and you) can verify claims

When your agent calls `web_extract(url)`, the plugin asks Gemini to fetch and summarize the full page content at that URL.

Under the hood, this uses the official [`google-genai`](https://pypi.org/project/google-genai/) Python SDK. The SDK is installed automatically as a dependency — you never need to think about it.

## Advanced configuration

### Choosing a model

The default model is `gemini-3.1-flash-lite` — fast, cheap, and well-suited to search grounding. You can override it in `config.yaml`:

```yaml
web:
  backend: gemini
  gemini_model: gemini-2.5-flash
```

Any model that supports the `google_search` grounding tool will work. Faster models keep agent response times low. Larger models may produce richer summaries but cost more and take longer.

### Using a Google API key instead of a Gemini key

If you use Google Cloud and already have a `GOOGLE_API_KEY` set, the plugin picks it up automatically:

```bash
# ~/.hermes/.env
GOOGLE_API_KEY=AIza...your-google-cloud-key
```

No extra configuration needed.

### Per-capability routing

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

```yaml
web:
  search_backend: gemini       # Gemini handles web_search
  extract_backend: firecrawl   # Firecrawl handles web_extract
```

### Configuring via `hermes tools`

If you prefer the interactive terminal UI:

```bash
hermes tools
```

Navigate to **Web Search**, select **Gemini Google Search Grounding**, and follow the prompts. The picker will ask for your API key and set everything up for you.

## Troubleshooting

### "GEMINI_API_KEY environment variable not set"

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

### "hermes-gemini-web-search is not enabled"

Hermes found the plugin but hasn't been told to activate it. Check that `~/.hermes/config.yaml` contains:

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

### "Google GenAI SDK not installed"

Run `pip install google-genai` inside your Hermes environment, then restart.

### "Gemini search failed" with a permission error

Your API key may not have the Gemini API enabled. Visit [Google AI Studio](https://aistudio.google.com/app/apikey), select your key, and verify the Gemini API is toggled on. If you are using a Google Cloud key, enable the Gemini API in the [Cloud Console](https://console.cloud.google.com/apis/library/generativelanguage.googleapis.com).

### The agent is not using the plugin

Make sure you restarted Hermes after making the configuration changes. Plugin discovery happens at startup.

## Development

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

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

