hermes-brightdata 0.2.0__tar.gz → 0.2.2__tar.gz

hermes_brightdata-0.2.2/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: hermes-brightdata
+Version: 0.2.2
+Summary: Bright Data web data tools for Hermes Agent — search, scrape, structured datasets, residential proxy, and browser automation
+License: MIT
+Project-URL: Homepage, https://github.com/dandacompany/hermes-brightdata-plugin
+Project-URL: Repository, https://github.com/dandacompany/hermes-brightdata-plugin
+Keywords: hermes,bright-data,brightdata,web-scraping,plugin,agent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == "browser"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: pyyaml>=6; extra == "dev"
+Dynamic: license-file
+
+# hermes-brightdata
+
+**Bright Data web data tools for [NousResearch Hermes Agent](https://hermes-agent.nousresearch.com) — search, scrape, structured datasets, residential proxy, and browser automation.**
+
+[![CI](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
+[![Python](https://img.shields.io/pypi/pyversions/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+한국어 문서: [README.ko.md](./README.ko.md)
+
+This plugin exposes Bright Data's web data platform as **ten native Hermes tools**. Unlike an MCP server, these tools are also available inside `delegate_task` subagents, which do not inherit the parent's MCP toolsets. It is pure Python (`requests` + optional `playwright`) with no Node runtime.
+
+Bright Data handles the hard parts of web data collection — proxy rotation, header management, bot/CAPTCHA bypass, JavaScript rendering, and structured parsing. The plugin keeps handlers thin over focused domain modules, so each tool is a small, testable surface.
+
+## Why this plugin
+
+- **Search & scrape** — real-time SERP search, and single/batch URL scraping to clean markdown via Web Unlocker.
+- **Structured datasets** — one `web_data` tool covers 23 platforms (Amazon, LinkedIn, Instagram, TikTok, Facebook, YouTube, X, Crunchbase) through a single `platform` argument.
+- **Residential proxy** — geo-targeted fetching through real residential IPs.
+- **Browser automation** — a persistent CDP Scraping Browser session for interactive flows.
+
+## Requirements
+
+- Python 3.10+
+- A Bright Data account and API token (`BRIGHTDATA_API_TOKEN`)
+- For `browser_*` tools: the `[browser]` extra (Playwright) and `BRIGHTDATA_BROWSER_AUTH`. The core five tools run on `requests` alone.
+
+## Install
+
+### Option A — pip (recommended)
+
+The plugin ships on PyPI and registers with Hermes via an entry point:
+
+```bash
+pip install hermes-brightdata            # core tools
+pip install "hermes-brightdata[browser]" # + browser automation (Playwright)
+```
+
+### Option B — from source
+
+```bash
+git clone https://github.com/dandacompany/hermes-brightdata-plugin ~/src/hermes-brightdata-plugin
+cd ~/src/hermes-brightdata-plugin
+pip install -e ".[browser]"
+```
+
+### Verify
+
+```bash
+hermes plugins list             # brightdata appears, not enabled (opt-in by default)
+hermes plugins enable brightdata
+```
+
+Answer `no` to any tool-override prompt. Restart the gateway (`hermes gateway restart`) or `/reset` a session if the tools do not appear immediately.
+
+## Quick start
+
+```bash
+export BRIGHTDATA_API_TOKEN="your-api-token-here"
+hermes plugins enable brightdata
+```
+
+The agent can now call the tools. Example arguments:
+
+- `scrape` → `{"url": "https://example.com"}`
+- `search_engine` → `{"query": "bright data", "engine": "google"}`
+- `web_data` → `{"platform": "amazon_product", "url": "https://www.amazon.com/dp/..."}`
+- `proxy_scrape` → `{"url": "https://...", "country": "us"}`
+
+Every tool returns a JSON string; failures come back as `{"error": ..., "hint": ...}` rather than raising.
+
+## Tools
+
+| Tool               | What it does                                                   | Notes                                                                       |
+| ------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `search_engine`    | Web search via Bright Data SERP API, returning parsed results  | Bypasses bot detection; more reliable than a built-in web search            |
+| `scrape`           | Fetch a single URL as clean markdown or html                   | Web Unlocker — handles JS, CAPTCHAs, bot detection                          |
+| `scrape_batch`     | Scrape multiple URLs in one call (max 20)                      | Per-URL content or error; individual failures are isolated                  |
+| `web_data`         | Structured JSON from a supported platform                      | Web Scraper API — clean fields, not raw HTML; may take up to a minute       |
+| `proxy_scrape`     | Fetch a URL through a residential proxy, optionally by country | Requires `BRIGHTDATA_PROXY_AUTH`                                            |
+| `session_stats`    | Report Bright Data tool call counts for this session           | —                                                                           |
+| `browser_navigate` | Open a URL in a Scraping Browser (persistent CDP session)      | Requires the `[browser]` extra and `BRIGHTDATA_BROWSER_AUTH`                |
+| `browser_snapshot` | ARIA snapshot (accessibility tree) of the current page         | For reading page structure and content                                      |
+| `browser_act`      | `click`, `type`, `scroll`, or `wait` on the current page       | Target `click`/`type` with a CSS or text selector (`#submit`, `text=Login`) |
+| `browser_get`      | Read the current page: `html`, `text`, or base64 `screenshot`  | —                                                                           |
+
+The Scraping Browser session is created lazily on the first `browser_navigate` and closed automatically on session end.
+
+### Supported `web_data` platforms
+
+Pass one as the `platform` argument (all take a URL); an unknown value returns an error listing the available ones.
+
+| Group       | Platforms                                                                                 |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| Amazon      | `amazon_product`, `amazon_product_reviews`, `amazon_product_search`, `amazon_seller_info` |
+| LinkedIn    | `linkedin_person`, `linkedin_company`, `linkedin_job_listings`, `linkedin_posts`          |
+| Instagram   | `instagram_profile`, `instagram_posts`, `instagram_reels`, `instagram_comments`           |
+| TikTok      | `tiktok_profiles`, `tiktok_posts`, `tiktok_comments`                                      |
+| Facebook    | `facebook_posts`, `facebook_profiles`                                                     |
+| YouTube     | `youtube_videos`, `youtube_profiles`, `youtube_comments`                                  |
+| X (Twitter) | `x_posts`, `x_profile_posts`                                                              |
+| Business    | `crunchbase_company`                                                                      |
+
+## Configuration
+
+Credentials are read from environment variables.
+
+**Required**
+
+| Variable               | Notes                                                                                              |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `BRIGHTDATA_API_TOKEN` | Bright Data API token (Account Settings → API keys). `BRIGHTDATA_API_KEY` is accepted as an alias. |
+
+**Optional**
+
+| Variable                       | Purpose                                                                       | Default                   |
+| ------------------------------ | ----------------------------------------------------------------------------- | ------------------------- |
+| `BRIGHTDATA_WEB_UNLOCKER_ZONE` | Web Unlocker zone (alias: `WEB_UNLOCKER_ZONE`)                                | `web_unlocker1`           |
+| `BRIGHTDATA_SERP_ZONE`         | SERP API zone                                                                 | `serp_api1`               |
+| `BRIGHTDATA_BROWSER_AUTH`      | Scraping Browser auth `brd-customer-<id>-zone-<zone>:<password>`              | —                         |
+| `BRIGHTDATA_PROXY_AUTH`        | Residential proxy auth `brd-customer-<id>-zone-<residential-zone>:<password>` | —                         |
+| `BRIGHTDATA_PROXY_CA`          | Path to the Bright Data proxy CA cert (HTTPS via proxy, port 33335)           | —                         |
+| `BRIGHTDATA_PROXY_HOST`        | Proxy `host:port`                                                             | `brd.superproxy.io:33335` |
+
+## Development
+
+```bash
+git clone https://github.com/dandacompany/hermes-brightdata-plugin
+cd hermes-brightdata-plugin
+pip install -e ".[dev]"
+pytest
+```
+
+CI runs the suite across Python 3.10–3.13 on every push. The plugin is organized as thin handlers (`tools.py`) over focused domain modules (`api.py`, `browser.py`, `datasets.py`, `config.py`, `counter.py`). Every handler follows the same contract: it always returns a JSON string, accepts `**kwargs`, and never propagates exceptions.
+
+## Security
+
+The plugin talks to Bright Data over HTTPS and, in browser/proxy modes, drives a remote browser and a residential proxy. Handling of that surface:
+
+- **Credentials never leak into output.** API errors carry only status codes and hints; response bodies and the token are never serialized. On a browser connection failure the raw exception (which can embed the CDP URL, including the proxy password) is replaced with a scrubbed message.
+- **Proxy `country` is validated.** The `country` argument is LLM-supplied and is inserted into the proxy URL's userinfo section, so it is strictly validated as a 2-letter ISO code and the userinfo is URL-encoded — a value like `us:pw@evil` cannot break out and redirect credentials.
+- **HTTPS through the proxy is verified against the Bright Data CA.** OpenSSL 3's strict Authority-Key-Identifier check (which the Bright Data proxy CA cert lacks) is relaxed, but the certificate chain is still validated against the provided CA — not disabled.
+
+## License
+
+[MIT](./LICENSE) © Dante Labs
+
+---
+
+<div align="center">
+
+**Dante Labs** · **YouTube** [@dante-labs](https://youtube.com/@dante-labs) · **Email** [dante@dante-labs.com](mailto:dante@dante-labs.com) · **Discord** [Dante Labs Community](https://discord.com/invite/rXyy5e9ujs) · **Support** [Buy Me a Coffee](https://buymeacoffee.com/dante.labs)
+
+</div>

hermes_brightdata-0.2.2/README.md

@@ -0,0 +1,155 @@
+# hermes-brightdata
+
+**Bright Data web data tools for [NousResearch Hermes Agent](https://hermes-agent.nousresearch.com) — search, scrape, structured datasets, residential proxy, and browser automation.**
+
+[![CI](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
+[![Python](https://img.shields.io/pypi/pyversions/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+한국어 문서: [README.ko.md](./README.ko.md)
+
+This plugin exposes Bright Data's web data platform as **ten native Hermes tools**. Unlike an MCP server, these tools are also available inside `delegate_task` subagents, which do not inherit the parent's MCP toolsets. It is pure Python (`requests` + optional `playwright`) with no Node runtime.
+
+Bright Data handles the hard parts of web data collection — proxy rotation, header management, bot/CAPTCHA bypass, JavaScript rendering, and structured parsing. The plugin keeps handlers thin over focused domain modules, so each tool is a small, testable surface.
+
+## Why this plugin
+
+- **Search & scrape** — real-time SERP search, and single/batch URL scraping to clean markdown via Web Unlocker.
+- **Structured datasets** — one `web_data` tool covers 23 platforms (Amazon, LinkedIn, Instagram, TikTok, Facebook, YouTube, X, Crunchbase) through a single `platform` argument.
+- **Residential proxy** — geo-targeted fetching through real residential IPs.
+- **Browser automation** — a persistent CDP Scraping Browser session for interactive flows.
+
+## Requirements
+
+- Python 3.10+
+- A Bright Data account and API token (`BRIGHTDATA_API_TOKEN`)
+- For `browser_*` tools: the `[browser]` extra (Playwright) and `BRIGHTDATA_BROWSER_AUTH`. The core five tools run on `requests` alone.
+
+## Install
+
+### Option A — pip (recommended)
+
+The plugin ships on PyPI and registers with Hermes via an entry point:
+
+```bash
+pip install hermes-brightdata            # core tools
+pip install "hermes-brightdata[browser]" # + browser automation (Playwright)
+```
+
+### Option B — from source
+
+```bash
+git clone https://github.com/dandacompany/hermes-brightdata-plugin ~/src/hermes-brightdata-plugin
+cd ~/src/hermes-brightdata-plugin
+pip install -e ".[browser]"
+```
+
+### Verify
+
+```bash
+hermes plugins list             # brightdata appears, not enabled (opt-in by default)
+hermes plugins enable brightdata
+```
+
+Answer `no` to any tool-override prompt. Restart the gateway (`hermes gateway restart`) or `/reset` a session if the tools do not appear immediately.
+
+## Quick start
+
+```bash
+export BRIGHTDATA_API_TOKEN="your-api-token-here"
+hermes plugins enable brightdata
+```
+
+The agent can now call the tools. Example arguments:
+
+- `scrape` → `{"url": "https://example.com"}`
+- `search_engine` → `{"query": "bright data", "engine": "google"}`
+- `web_data` → `{"platform": "amazon_product", "url": "https://www.amazon.com/dp/..."}`
+- `proxy_scrape` → `{"url": "https://...", "country": "us"}`
+
+Every tool returns a JSON string; failures come back as `{"error": ..., "hint": ...}` rather than raising.
+
+## Tools
+
+| Tool               | What it does                                                   | Notes                                                                       |
+| ------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `search_engine`    | Web search via Bright Data SERP API, returning parsed results  | Bypasses bot detection; more reliable than a built-in web search            |
+| `scrape`           | Fetch a single URL as clean markdown or html                   | Web Unlocker — handles JS, CAPTCHAs, bot detection                          |
+| `scrape_batch`     | Scrape multiple URLs in one call (max 20)                      | Per-URL content or error; individual failures are isolated                  |
+| `web_data`         | Structured JSON from a supported platform                      | Web Scraper API — clean fields, not raw HTML; may take up to a minute       |
+| `proxy_scrape`     | Fetch a URL through a residential proxy, optionally by country | Requires `BRIGHTDATA_PROXY_AUTH`                                            |
+| `session_stats`    | Report Bright Data tool call counts for this session           | —                                                                           |
+| `browser_navigate` | Open a URL in a Scraping Browser (persistent CDP session)      | Requires the `[browser]` extra and `BRIGHTDATA_BROWSER_AUTH`                |
+| `browser_snapshot` | ARIA snapshot (accessibility tree) of the current page         | For reading page structure and content                                      |
+| `browser_act`      | `click`, `type`, `scroll`, or `wait` on the current page       | Target `click`/`type` with a CSS or text selector (`#submit`, `text=Login`) |
+| `browser_get`      | Read the current page: `html`, `text`, or base64 `screenshot`  | —                                                                           |
+
+The Scraping Browser session is created lazily on the first `browser_navigate` and closed automatically on session end.
+
+### Supported `web_data` platforms
+
+Pass one as the `platform` argument (all take a URL); an unknown value returns an error listing the available ones.
+
+| Group       | Platforms                                                                                 |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| Amazon      | `amazon_product`, `amazon_product_reviews`, `amazon_product_search`, `amazon_seller_info` |
+| LinkedIn    | `linkedin_person`, `linkedin_company`, `linkedin_job_listings`, `linkedin_posts`          |
+| Instagram   | `instagram_profile`, `instagram_posts`, `instagram_reels`, `instagram_comments`           |
+| TikTok      | `tiktok_profiles`, `tiktok_posts`, `tiktok_comments`                                      |
+| Facebook    | `facebook_posts`, `facebook_profiles`                                                     |
+| YouTube     | `youtube_videos`, `youtube_profiles`, `youtube_comments`                                  |
+| X (Twitter) | `x_posts`, `x_profile_posts`                                                              |
+| Business    | `crunchbase_company`                                                                      |
+
+## Configuration
+
+Credentials are read from environment variables.
+
+**Required**
+
+| Variable               | Notes                                                                                              |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `BRIGHTDATA_API_TOKEN` | Bright Data API token (Account Settings → API keys). `BRIGHTDATA_API_KEY` is accepted as an alias. |
+
+**Optional**
+
+| Variable                       | Purpose                                                                       | Default                   |
+| ------------------------------ | ----------------------------------------------------------------------------- | ------------------------- |
+| `BRIGHTDATA_WEB_UNLOCKER_ZONE` | Web Unlocker zone (alias: `WEB_UNLOCKER_ZONE`)                                | `web_unlocker1`           |
+| `BRIGHTDATA_SERP_ZONE`         | SERP API zone                                                                 | `serp_api1`               |
+| `BRIGHTDATA_BROWSER_AUTH`      | Scraping Browser auth `brd-customer-<id>-zone-<zone>:<password>`              | —                         |
+| `BRIGHTDATA_PROXY_AUTH`        | Residential proxy auth `brd-customer-<id>-zone-<residential-zone>:<password>` | —                         |
+| `BRIGHTDATA_PROXY_CA`          | Path to the Bright Data proxy CA cert (HTTPS via proxy, port 33335)           | —                         |
+| `BRIGHTDATA_PROXY_HOST`        | Proxy `host:port`                                                             | `brd.superproxy.io:33335` |
+
+## Development
+
+```bash
+git clone https://github.com/dandacompany/hermes-brightdata-plugin
+cd hermes-brightdata-plugin
+pip install -e ".[dev]"
+pytest
+```
+
+CI runs the suite across Python 3.10–3.13 on every push. The plugin is organized as thin handlers (`tools.py`) over focused domain modules (`api.py`, `browser.py`, `datasets.py`, `config.py`, `counter.py`). Every handler follows the same contract: it always returns a JSON string, accepts `**kwargs`, and never propagates exceptions.
+
+## Security
+
+The plugin talks to Bright Data over HTTPS and, in browser/proxy modes, drives a remote browser and a residential proxy. Handling of that surface:
+
+- **Credentials never leak into output.** API errors carry only status codes and hints; response bodies and the token are never serialized. On a browser connection failure the raw exception (which can embed the CDP URL, including the proxy password) is replaced with a scrubbed message.
+- **Proxy `country` is validated.** The `country` argument is LLM-supplied and is inserted into the proxy URL's userinfo section, so it is strictly validated as a 2-letter ISO code and the userinfo is URL-encoded — a value like `us:pw@evil` cannot break out and redirect credentials.
+- **HTTPS through the proxy is verified against the Bright Data CA.** OpenSSL 3's strict Authority-Key-Identifier check (which the Bright Data proxy CA cert lacks) is relaxed, but the certificate chain is still validated against the provided CA — not disabled.
+
+## License
+
+[MIT](./LICENSE) © Dante Labs
+
+---
+
+<div align="center">
+
+**Dante Labs** · **YouTube** [@dante-labs](https://youtube.com/@dante-labs) · **Email** [dante@dante-labs.com](mailto:dante@dante-labs.com) · **Discord** [Dante Labs Community](https://discord.com/invite/rXyy5e9ujs) · **Support** [Buy Me a Coffee](https://buymeacoffee.com/dante.labs)
+
+</div>

{hermes_brightdata-0.2.0 → hermes_brightdata-0.2.2}/brightdata_plugin/api.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+import re
 import ssl
 import time
+from urllib.parse import quote
 
 import requests
 from requests.adapters import HTTPAdapter
@@ -96,8 +98,16 @@ class BrightDataClient:
         # inserts '-country-<cc>' into the username before the password.
         user, _, password = self._cfg.proxy_auth.partition(":")
         if country:
+            # country is LLM-supplied — reject anything but a 2-letter ISO code so it
+            # cannot inject '@'/':'/'/' and break out of the userinfo section.
+            if not re.fullmatch(r"[A-Za-z]{2}", country):
+                raise BrightDataError(
+                    "invalid country code", status=0,
+                    hint="country must be a 2-letter ISO code (e.g. 'us')")
             user = f"{user}-country-{country.lower()}"
-        return f"http://{user}:{password}@{self._cfg.proxy_host}"
+        # URL-encode userinfo as defense-in-depth against stray reserved characters.
+        return (f"http://{quote(user, safe='')}:{quote(password, safe='')}"
+                f"@{self._cfg.proxy_host}")
 
     def proxy_scrape(self, url: str, country: str | None = None) -> str:
         if not self._cfg.proxy_auth:

hermes_brightdata-0.2.2/hermes_brightdata.egg-info/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: hermes-brightdata
+Version: 0.2.2
+Summary: Bright Data web data tools for Hermes Agent — search, scrape, structured datasets, residential proxy, and browser automation
+License: MIT
+Project-URL: Homepage, https://github.com/dandacompany/hermes-brightdata-plugin
+Project-URL: Repository, https://github.com/dandacompany/hermes-brightdata-plugin
+Keywords: hermes,bright-data,brightdata,web-scraping,plugin,agent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == "browser"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: pyyaml>=6; extra == "dev"
+Dynamic: license-file
+
+# hermes-brightdata
+
+**Bright Data web data tools for [NousResearch Hermes Agent](https://hermes-agent.nousresearch.com) — search, scrape, structured datasets, residential proxy, and browser automation.**
+
+[![CI](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
+[![Python](https://img.shields.io/pypi/pyversions/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+한국어 문서: [README.ko.md](./README.ko.md)
+
+This plugin exposes Bright Data's web data platform as **ten native Hermes tools**. Unlike an MCP server, these tools are also available inside `delegate_task` subagents, which do not inherit the parent's MCP toolsets. It is pure Python (`requests` + optional `playwright`) with no Node runtime.
+
+Bright Data handles the hard parts of web data collection — proxy rotation, header management, bot/CAPTCHA bypass, JavaScript rendering, and structured parsing. The plugin keeps handlers thin over focused domain modules, so each tool is a small, testable surface.
+
+## Why this plugin
+
+- **Search & scrape** — real-time SERP search, and single/batch URL scraping to clean markdown via Web Unlocker.
+- **Structured datasets** — one `web_data` tool covers 23 platforms (Amazon, LinkedIn, Instagram, TikTok, Facebook, YouTube, X, Crunchbase) through a single `platform` argument.
+- **Residential proxy** — geo-targeted fetching through real residential IPs.
+- **Browser automation** — a persistent CDP Scraping Browser session for interactive flows.
+
+## Requirements
+
+- Python 3.10+
+- A Bright Data account and API token (`BRIGHTDATA_API_TOKEN`)
+- For `browser_*` tools: the `[browser]` extra (Playwright) and `BRIGHTDATA_BROWSER_AUTH`. The core five tools run on `requests` alone.
+
+## Install
+
+### Option A — pip (recommended)
+
+The plugin ships on PyPI and registers with Hermes via an entry point:
+
+```bash
+pip install hermes-brightdata            # core tools
+pip install "hermes-brightdata[browser]" # + browser automation (Playwright)
+```
+
+### Option B — from source
+
+```bash
+git clone https://github.com/dandacompany/hermes-brightdata-plugin ~/src/hermes-brightdata-plugin
+cd ~/src/hermes-brightdata-plugin
+pip install -e ".[browser]"
+```
+
+### Verify
+
+```bash
+hermes plugins list             # brightdata appears, not enabled (opt-in by default)
+hermes plugins enable brightdata
+```
+
+Answer `no` to any tool-override prompt. Restart the gateway (`hermes gateway restart`) or `/reset` a session if the tools do not appear immediately.
+
+## Quick start
+
+```bash
+export BRIGHTDATA_API_TOKEN="your-api-token-here"
+hermes plugins enable brightdata
+```
+
+The agent can now call the tools. Example arguments:
+
+- `scrape` → `{"url": "https://example.com"}`
+- `search_engine` → `{"query": "bright data", "engine": "google"}`
+- `web_data` → `{"platform": "amazon_product", "url": "https://www.amazon.com/dp/..."}`
+- `proxy_scrape` → `{"url": "https://...", "country": "us"}`
+
+Every tool returns a JSON string; failures come back as `{"error": ..., "hint": ...}` rather than raising.
+
+## Tools
+
+| Tool               | What it does                                                   | Notes                                                                       |
+| ------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `search_engine`    | Web search via Bright Data SERP API, returning parsed results  | Bypasses bot detection; more reliable than a built-in web search            |
+| `scrape`           | Fetch a single URL as clean markdown or html                   | Web Unlocker — handles JS, CAPTCHAs, bot detection                          |
+| `scrape_batch`     | Scrape multiple URLs in one call (max 20)                      | Per-URL content or error; individual failures are isolated                  |
+| `web_data`         | Structured JSON from a supported platform                      | Web Scraper API — clean fields, not raw HTML; may take up to a minute       |
+| `proxy_scrape`     | Fetch a URL through a residential proxy, optionally by country | Requires `BRIGHTDATA_PROXY_AUTH`                                            |
+| `session_stats`    | Report Bright Data tool call counts for this session           | —                                                                           |
+| `browser_navigate` | Open a URL in a Scraping Browser (persistent CDP session)      | Requires the `[browser]` extra and `BRIGHTDATA_BROWSER_AUTH`                |
+| `browser_snapshot` | ARIA snapshot (accessibility tree) of the current page         | For reading page structure and content                                      |
+| `browser_act`      | `click`, `type`, `scroll`, or `wait` on the current page       | Target `click`/`type` with a CSS or text selector (`#submit`, `text=Login`) |
+| `browser_get`      | Read the current page: `html`, `text`, or base64 `screenshot`  | —                                                                           |
+
+The Scraping Browser session is created lazily on the first `browser_navigate` and closed automatically on session end.
+
+### Supported `web_data` platforms
+
+Pass one as the `platform` argument (all take a URL); an unknown value returns an error listing the available ones.
+
+| Group       | Platforms                                                                                 |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| Amazon      | `amazon_product`, `amazon_product_reviews`, `amazon_product_search`, `amazon_seller_info` |
+| LinkedIn    | `linkedin_person`, `linkedin_company`, `linkedin_job_listings`, `linkedin_posts`          |
+| Instagram   | `instagram_profile`, `instagram_posts`, `instagram_reels`, `instagram_comments`           |
+| TikTok      | `tiktok_profiles`, `tiktok_posts`, `tiktok_comments`                                      |
+| Facebook    | `facebook_posts`, `facebook_profiles`                                                     |
+| YouTube     | `youtube_videos`, `youtube_profiles`, `youtube_comments`                                  |
+| X (Twitter) | `x_posts`, `x_profile_posts`                                                              |
+| Business    | `crunchbase_company`                                                                      |
+
+## Configuration
+
+Credentials are read from environment variables.
+
+**Required**
+
+| Variable               | Notes                                                                                              |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `BRIGHTDATA_API_TOKEN` | Bright Data API token (Account Settings → API keys). `BRIGHTDATA_API_KEY` is accepted as an alias. |
+
+**Optional**
+
+| Variable                       | Purpose                                                                       | Default                   |
+| ------------------------------ | ----------------------------------------------------------------------------- | ------------------------- |
+| `BRIGHTDATA_WEB_UNLOCKER_ZONE` | Web Unlocker zone (alias: `WEB_UNLOCKER_ZONE`)                                | `web_unlocker1`           |
+| `BRIGHTDATA_SERP_ZONE`         | SERP API zone                                                                 | `serp_api1`               |
+| `BRIGHTDATA_BROWSER_AUTH`      | Scraping Browser auth `brd-customer-<id>-zone-<zone>:<password>`              | —                         |
+| `BRIGHTDATA_PROXY_AUTH`        | Residential proxy auth `brd-customer-<id>-zone-<residential-zone>:<password>` | —                         |
+| `BRIGHTDATA_PROXY_CA`          | Path to the Bright Data proxy CA cert (HTTPS via proxy, port 33335)           | —                         |
+| `BRIGHTDATA_PROXY_HOST`        | Proxy `host:port`                                                             | `brd.superproxy.io:33335` |
+
+## Development
+
+```bash
+git clone https://github.com/dandacompany/hermes-brightdata-plugin
+cd hermes-brightdata-plugin
+pip install -e ".[dev]"
+pytest
+```
+
+CI runs the suite across Python 3.10–3.13 on every push. The plugin is organized as thin handlers (`tools.py`) over focused domain modules (`api.py`, `browser.py`, `datasets.py`, `config.py`, `counter.py`). Every handler follows the same contract: it always returns a JSON string, accepts `**kwargs`, and never propagates exceptions.
+
+## Security
+
+The plugin talks to Bright Data over HTTPS and, in browser/proxy modes, drives a remote browser and a residential proxy. Handling of that surface:
+
+- **Credentials never leak into output.** API errors carry only status codes and hints; response bodies and the token are never serialized. On a browser connection failure the raw exception (which can embed the CDP URL, including the proxy password) is replaced with a scrubbed message.
+- **Proxy `country` is validated.** The `country` argument is LLM-supplied and is inserted into the proxy URL's userinfo section, so it is strictly validated as a 2-letter ISO code and the userinfo is URL-encoded — a value like `us:pw@evil` cannot break out and redirect credentials.
+- **HTTPS through the proxy is verified against the Bright Data CA.** OpenSSL 3's strict Authority-Key-Identifier check (which the Bright Data proxy CA cert lacks) is relaxed, but the certificate chain is still validated against the provided CA — not disabled.
+
+## License
+
+[MIT](./LICENSE) © Dante Labs
+
+---
+
+<div align="center">
+
+**Dante Labs** · **YouTube** [@dante-labs](https://youtube.com/@dante-labs) · **Email** [dante@dante-labs.com](mailto:dante@dante-labs.com) · **Discord** [Dante Labs Community](https://discord.com/invite/rXyy5e9ujs) · **Support** [Buy Me a Coffee](https://buymeacoffee.com/dante.labs)
+
+</div>

{hermes_brightdata-0.2.0 → hermes_brightdata-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hermes-brightdata"
-version = "0.2.0"
+version = "0.2.2"
 description = "Bright Data web data tools for Hermes Agent — search, scrape, structured datasets, residential proxy, and browser automation"
 readme = "README.md"
 requires-python = ">=3.10"

{hermes_brightdata-0.2.0 → hermes_brightdata-0.2.2}/tests/test_api_proxy.py

@@ -45,3 +45,19 @@ def test_proxy_scrape_http_error_raises():
     with pytest.raises(BrightDataError) as exc:
         client.proxy_scrape("https://example.com")
     assert exc.value.status == 403
+
+
+@pytest.mark.parametrize("bad", ["us@evil.com", "u", "usa", "us:pw@host", "u/x", ""])
+def test_proxy_url_rejects_non_iso_country(bad):
+    client = BrightDataClient(PROXY_CFG)
+    if bad == "":
+        # empty string is falsy -> treated as no country, builds base URL
+        assert client._proxy_url(bad).endswith("@brd.superproxy.io:33335")
+    else:
+        with pytest.raises(BrightDataError):
+            client._proxy_url(bad)
+
+
+def test_proxy_url_country_case_insensitive():
+    client = BrightDataClient(PROXY_CFG)
+    assert client._proxy_url("US") == client._proxy_url("us")

hermes_brightdata-0.2.0/PKG-INFO

@@ -1,148 +0,0 @@
-Metadata-Version: 2.4
-Name: hermes-brightdata
-Version: 0.2.0
-Summary: Bright Data web data tools for Hermes Agent — search, scrape, structured datasets, residential proxy, and browser automation
-License: MIT
-Project-URL: Homepage, https://github.com/dandacompany/hermes-brightdata-plugin
-Project-URL: Repository, https://github.com/dandacompany/hermes-brightdata-plugin
-Keywords: hermes,bright-data,brightdata,web-scraping,plugin,agent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.31
-Provides-Extra: browser
-Requires-Dist: playwright>=1.40; extra == "browser"
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: responses>=0.25; extra == "dev"
-Requires-Dist: pyyaml>=6; extra == "dev"
-Dynamic: license-file
-
-# hermes-brightdata
-
-[![CI](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml)
-[![PyPI version](https://img.shields.io/pypi/v/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
-[![Python](https://img.shields.io/pypi/pyversions/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-
-Bright Data web data tools for Hermes Agent — search, scrape, structured datasets, and browser automation.
-
-## Overview
-
-This plugin integrates Bright Data's web data APIs with Hermes, providing ten powerful tools for web data collection:
-
-- **Search & Scraping**: Real-time search, single/batch URL scraping, and structured data extraction
-- **Browser Automation**: Interactive browser sessions with persistent cookies and JavaScript rendering
-- **Bypass Detection**: Automatic handling of bot detection, CAPTCHAs, and JavaScript-heavy sites
-
-Bright Data handles all the complexity — proxy rotation, header management, retry logic, and content parsing.
-
-## Installation
-
-Install the plugin with base tools:
-
-```bash
-pip install hermes-brightdata
-```
-
-To enable browser automation tools, install with the `[browser]` extra:
-
-```bash
-pip install hermes-brightdata[browser]
-```
-
-The browser extra adds Playwright for interactive session handling (required for `browser_navigate`, `browser_snapshot`, `browser_act`, `browser_get`).
-
-## Configuration
-
-Before using any Bright Data tool, set your API credentials in environment variables:
-
-### Required
-
-`BRIGHTDATA_API_TOKEN` (required, secret)
-
-- Your Bright Data API token
-- Obtain from Account Settings → API keys in the Bright Data dashboard
-- `BRIGHTDATA_API_KEY` is accepted as an alias if `BRIGHTDATA_API_TOKEN` is unset
-
-### Optional
-
-`BRIGHTDATA_WEB_UNLOCKER_ZONE` (optional)
-
-- Zone name for Web Unlocker API
-- Default: `web_unlocker1`
-- `WEB_UNLOCKER_ZONE` is accepted as an alias if the prefixed name is unset
-
-`BRIGHTDATA_SERP_ZONE` (optional)
-
-- Zone name for SERP (Search Engine Results Page) API
-- Default: `serp_api1`
-
-`BRIGHTDATA_BROWSER_AUTH` (optional, secret)
-
-- Authentication credentials for Scraping Browser
-- Format: `brd-customer-<customer-id>-zone-<zone-name>:<password>`
-- Required only if using browser tools with authentication
-
-`BRIGHTDATA_PROXY_AUTH` (optional, secret)
-
-- Residential proxy credentials for `proxy_scrape`
-- Format: `brd-customer-<customer-id>-zone-<residential-zone>:<password>`
-
-`BRIGHTDATA_PROXY_CA` (optional)
-
-- Path to the Bright Data proxy CA certificate (needed for HTTPS through the proxy on port 33335)
-
-`BRIGHTDATA_PROXY_HOST` (optional)
-
-- Proxy `host:port` (default `brd.superproxy.io:33335`)
-
-### Example
-
-```bash
-export BRIGHTDATA_API_TOKEN="your-api-token-here"
-export BRIGHTDATA_BROWSER_AUTH="brd-customer-12345-zone-myzone:password123"
-export BRIGHTDATA_PROXY_AUTH="brd-customer-12345-zone-residential:password123"
-export BRIGHTDATA_PROXY_CA="/path/to/BrightData_proxy_ca.crt"
-```
-
-## Tools
-
-The plugin provides ten tools:
-
-| Tool               | Description                                                                                                                                                                                                   |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `search_engine`    | Search the web via Bright Data SERP API and return parsed results. Use for current events, fact-checking, finding pages, or any web search. Bypasses bot detection; more reliable than built-in web search.   |
-| `scrape`           | Fetch a single URL as clean markdown (or html) using Bright Data Web Unlocker. Handles JavaScript, CAPTCHAs, and bot detection. Use to read any webpage, article, doc, or site.                               |
-| `scrape_batch`     | Scrape multiple URLs in one call (max 20). Returns per-URL content or error. Use when you have several pages to read at once.                                                                                 |
-| `web_data`         | Get structured JSON data from a supported platform via Bright Data Web Scraper API (e.g. an Amazon product page, a LinkedIn profile). Returns clean structured fields, not raw HTML. May take up to a minute. |
-| `proxy_scrape`     | Fetch a URL through a Bright Data residential proxy, optionally from a specific country. Use for geo-targeted content (region-specific pricing, localized pages). Requires `BRIGHTDATA_PROXY_AUTH`.           |
-| `session_stats`    | Report Bright Data tool call counts for this session.                                                                                                                                                         |
-| `browser_navigate` | Open a URL in a Bright Data Scraping Browser (real browser with a persistent session). Use for interactive flows requiring clicks/typing. Requires the [browser] extra and BRIGHTDATA_BROWSER_AUTH.           |
-| `browser_snapshot` | Return an accessibility-tree snapshot of the current browser page, including element refs to use with browser_act.                                                                                            |
-| `browser_act`      | Perform an action on the current browser page: click, type, scroll, or wait. Get element refs from browser_snapshot first.                                                                                    |
-| `browser_get`      | Read the current browser page: html, text, or a base64 screenshot.                                                                                                                                            |
-
-## Activation
-
-Enable the plugin in Hermes:
-
-```bash
-hermes plugins enable brightdata
-```
-
-Verify it's loaded:
-
-```bash
-hermes plugins list
-```
-
-You should see `brightdata` listed with version `0.2.0`.
-
-## Pricing
-
-Bright Data offers a free tier with up to 5,000 requests per month. For higher volume, refer to Bright Data's pricing page for details on Web Unlocker, SERP API, Web Scraper API, and Scraping Browser plans.
-
----
-
-For more information on Bright Data services, visit [https://brightdata.com](https://brightdata.com).

hermes_brightdata-0.2.0/README.md

@@ -1,128 +0,0 @@
-# hermes-brightdata
-
-[![CI](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml)
-[![PyPI version](https://img.shields.io/pypi/v/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
-[![Python](https://img.shields.io/pypi/pyversions/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-
-Bright Data web data tools for Hermes Agent — search, scrape, structured datasets, and browser automation.
-
-## Overview
-
-This plugin integrates Bright Data's web data APIs with Hermes, providing ten powerful tools for web data collection:
-
-- **Search & Scraping**: Real-time search, single/batch URL scraping, and structured data extraction
-- **Browser Automation**: Interactive browser sessions with persistent cookies and JavaScript rendering
-- **Bypass Detection**: Automatic handling of bot detection, CAPTCHAs, and JavaScript-heavy sites
-
-Bright Data handles all the complexity — proxy rotation, header management, retry logic, and content parsing.
-
-## Installation
-
-Install the plugin with base tools:
-
-```bash
-pip install hermes-brightdata
-```
-
-To enable browser automation tools, install with the `[browser]` extra:
-
-```bash
-pip install hermes-brightdata[browser]
-```
-
-The browser extra adds Playwright for interactive session handling (required for `browser_navigate`, `browser_snapshot`, `browser_act`, `browser_get`).
-
-## Configuration
-
-Before using any Bright Data tool, set your API credentials in environment variables:
-
-### Required
-
-`BRIGHTDATA_API_TOKEN` (required, secret)
-
-- Your Bright Data API token
-- Obtain from Account Settings → API keys in the Bright Data dashboard
-- `BRIGHTDATA_API_KEY` is accepted as an alias if `BRIGHTDATA_API_TOKEN` is unset
-
-### Optional
-
-`BRIGHTDATA_WEB_UNLOCKER_ZONE` (optional)
-
-- Zone name for Web Unlocker API
-- Default: `web_unlocker1`
-- `WEB_UNLOCKER_ZONE` is accepted as an alias if the prefixed name is unset
-
-`BRIGHTDATA_SERP_ZONE` (optional)
-
-- Zone name for SERP (Search Engine Results Page) API
-- Default: `serp_api1`
-
-`BRIGHTDATA_BROWSER_AUTH` (optional, secret)
-
-- Authentication credentials for Scraping Browser
-- Format: `brd-customer-<customer-id>-zone-<zone-name>:<password>`
-- Required only if using browser tools with authentication
-
-`BRIGHTDATA_PROXY_AUTH` (optional, secret)
-
-- Residential proxy credentials for `proxy_scrape`
-- Format: `brd-customer-<customer-id>-zone-<residential-zone>:<password>`
-
-`BRIGHTDATA_PROXY_CA` (optional)
-
-- Path to the Bright Data proxy CA certificate (needed for HTTPS through the proxy on port 33335)
-
-`BRIGHTDATA_PROXY_HOST` (optional)
-
-- Proxy `host:port` (default `brd.superproxy.io:33335`)
-
-### Example
-
-```bash
-export BRIGHTDATA_API_TOKEN="your-api-token-here"
-export BRIGHTDATA_BROWSER_AUTH="brd-customer-12345-zone-myzone:password123"
-export BRIGHTDATA_PROXY_AUTH="brd-customer-12345-zone-residential:password123"
-export BRIGHTDATA_PROXY_CA="/path/to/BrightData_proxy_ca.crt"
-```
-
-## Tools
-
-The plugin provides ten tools:
-
-| Tool               | Description                                                                                                                                                                                                   |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `search_engine`    | Search the web via Bright Data SERP API and return parsed results. Use for current events, fact-checking, finding pages, or any web search. Bypasses bot detection; more reliable than built-in web search.   |
-| `scrape`           | Fetch a single URL as clean markdown (or html) using Bright Data Web Unlocker. Handles JavaScript, CAPTCHAs, and bot detection. Use to read any webpage, article, doc, or site.                               |
-| `scrape_batch`     | Scrape multiple URLs in one call (max 20). Returns per-URL content or error. Use when you have several pages to read at once.                                                                                 |
-| `web_data`         | Get structured JSON data from a supported platform via Bright Data Web Scraper API (e.g. an Amazon product page, a LinkedIn profile). Returns clean structured fields, not raw HTML. May take up to a minute. |
-| `proxy_scrape`     | Fetch a URL through a Bright Data residential proxy, optionally from a specific country. Use for geo-targeted content (region-specific pricing, localized pages). Requires `BRIGHTDATA_PROXY_AUTH`.           |
-| `session_stats`    | Report Bright Data tool call counts for this session.                                                                                                                                                         |
-| `browser_navigate` | Open a URL in a Bright Data Scraping Browser (real browser with a persistent session). Use for interactive flows requiring clicks/typing. Requires the [browser] extra and BRIGHTDATA_BROWSER_AUTH.           |
-| `browser_snapshot` | Return an accessibility-tree snapshot of the current browser page, including element refs to use with browser_act.                                                                                            |
-| `browser_act`      | Perform an action on the current browser page: click, type, scroll, or wait. Get element refs from browser_snapshot first.                                                                                    |
-| `browser_get`      | Read the current browser page: html, text, or a base64 screenshot.                                                                                                                                            |
-
-## Activation
-
-Enable the plugin in Hermes:
-
-```bash
-hermes plugins enable brightdata
-```
-
-Verify it's loaded:
-
-```bash
-hermes plugins list
-```
-
-You should see `brightdata` listed with version `0.2.0`.
-
-## Pricing
-
-Bright Data offers a free tier with up to 5,000 requests per month. For higher volume, refer to Bright Data's pricing page for details on Web Unlocker, SERP API, Web Scraper API, and Scraping Browser plans.
-
----
-
-For more information on Bright Data services, visit [https://brightdata.com](https://brightdata.com).

hermes_brightdata-0.2.0/hermes_brightdata.egg-info/PKG-INFO

@@ -1,148 +0,0 @@
-Metadata-Version: 2.4
-Name: hermes-brightdata
-Version: 0.2.0
-Summary: Bright Data web data tools for Hermes Agent — search, scrape, structured datasets, residential proxy, and browser automation
-License: MIT
-Project-URL: Homepage, https://github.com/dandacompany/hermes-brightdata-plugin
-Project-URL: Repository, https://github.com/dandacompany/hermes-brightdata-plugin
-Keywords: hermes,bright-data,brightdata,web-scraping,plugin,agent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.31
-Provides-Extra: browser
-Requires-Dist: playwright>=1.40; extra == "browser"
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: responses>=0.25; extra == "dev"
-Requires-Dist: pyyaml>=6; extra == "dev"
-Dynamic: license-file
-
-# hermes-brightdata
-
-[![CI](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/dandacompany/hermes-brightdata-plugin/actions/workflows/ci.yml)
-[![PyPI version](https://img.shields.io/pypi/v/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
-[![Python](https://img.shields.io/pypi/pyversions/hermes-brightdata.svg)](https://pypi.org/project/hermes-brightdata/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-
-Bright Data web data tools for Hermes Agent — search, scrape, structured datasets, and browser automation.
-
-## Overview
-
-This plugin integrates Bright Data's web data APIs with Hermes, providing ten powerful tools for web data collection:
-
-- **Search & Scraping**: Real-time search, single/batch URL scraping, and structured data extraction
-- **Browser Automation**: Interactive browser sessions with persistent cookies and JavaScript rendering
-- **Bypass Detection**: Automatic handling of bot detection, CAPTCHAs, and JavaScript-heavy sites
-
-Bright Data handles all the complexity — proxy rotation, header management, retry logic, and content parsing.
-
-## Installation
-
-Install the plugin with base tools:
-
-```bash
-pip install hermes-brightdata
-```
-
-To enable browser automation tools, install with the `[browser]` extra:
-
-```bash
-pip install hermes-brightdata[browser]
-```
-
-The browser extra adds Playwright for interactive session handling (required for `browser_navigate`, `browser_snapshot`, `browser_act`, `browser_get`).
-
-## Configuration
-
-Before using any Bright Data tool, set your API credentials in environment variables:
-
-### Required
-
-`BRIGHTDATA_API_TOKEN` (required, secret)
-
-- Your Bright Data API token
-- Obtain from Account Settings → API keys in the Bright Data dashboard
-- `BRIGHTDATA_API_KEY` is accepted as an alias if `BRIGHTDATA_API_TOKEN` is unset
-
-### Optional
-
-`BRIGHTDATA_WEB_UNLOCKER_ZONE` (optional)
-
-- Zone name for Web Unlocker API
-- Default: `web_unlocker1`
-- `WEB_UNLOCKER_ZONE` is accepted as an alias if the prefixed name is unset
-
-`BRIGHTDATA_SERP_ZONE` (optional)
-
-- Zone name for SERP (Search Engine Results Page) API
-- Default: `serp_api1`
-
-`BRIGHTDATA_BROWSER_AUTH` (optional, secret)
-
-- Authentication credentials for Scraping Browser
-- Format: `brd-customer-<customer-id>-zone-<zone-name>:<password>`
-- Required only if using browser tools with authentication
-
-`BRIGHTDATA_PROXY_AUTH` (optional, secret)
-
-- Residential proxy credentials for `proxy_scrape`
-- Format: `brd-customer-<customer-id>-zone-<residential-zone>:<password>`
-
-`BRIGHTDATA_PROXY_CA` (optional)
-
-- Path to the Bright Data proxy CA certificate (needed for HTTPS through the proxy on port 33335)
-
-`BRIGHTDATA_PROXY_HOST` (optional)
-
-- Proxy `host:port` (default `brd.superproxy.io:33335`)
-
-### Example
-
-```bash
-export BRIGHTDATA_API_TOKEN="your-api-token-here"
-export BRIGHTDATA_BROWSER_AUTH="brd-customer-12345-zone-myzone:password123"
-export BRIGHTDATA_PROXY_AUTH="brd-customer-12345-zone-residential:password123"
-export BRIGHTDATA_PROXY_CA="/path/to/BrightData_proxy_ca.crt"
-```
-
-## Tools
-
-The plugin provides ten tools:
-
-| Tool               | Description                                                                                                                                                                                                   |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `search_engine`    | Search the web via Bright Data SERP API and return parsed results. Use for current events, fact-checking, finding pages, or any web search. Bypasses bot detection; more reliable than built-in web search.   |
-| `scrape`           | Fetch a single URL as clean markdown (or html) using Bright Data Web Unlocker. Handles JavaScript, CAPTCHAs, and bot detection. Use to read any webpage, article, doc, or site.                               |
-| `scrape_batch`     | Scrape multiple URLs in one call (max 20). Returns per-URL content or error. Use when you have several pages to read at once.                                                                                 |
-| `web_data`         | Get structured JSON data from a supported platform via Bright Data Web Scraper API (e.g. an Amazon product page, a LinkedIn profile). Returns clean structured fields, not raw HTML. May take up to a minute. |
-| `proxy_scrape`     | Fetch a URL through a Bright Data residential proxy, optionally from a specific country. Use for geo-targeted content (region-specific pricing, localized pages). Requires `BRIGHTDATA_PROXY_AUTH`.           |
-| `session_stats`    | Report Bright Data tool call counts for this session.                                                                                                                                                         |
-| `browser_navigate` | Open a URL in a Bright Data Scraping Browser (real browser with a persistent session). Use for interactive flows requiring clicks/typing. Requires the [browser] extra and BRIGHTDATA_BROWSER_AUTH.           |
-| `browser_snapshot` | Return an accessibility-tree snapshot of the current browser page, including element refs to use with browser_act.                                                                                            |
-| `browser_act`      | Perform an action on the current browser page: click, type, scroll, or wait. Get element refs from browser_snapshot first.                                                                                    |
-| `browser_get`      | Read the current browser page: html, text, or a base64 screenshot.                                                                                                                                            |
-
-## Activation
-
-Enable the plugin in Hermes:
-
-```bash
-hermes plugins enable brightdata
-```
-
-Verify it's loaded:
-
-```bash
-hermes plugins list
-```
-
-You should see `brightdata` listed with version `0.2.0`.
-
-## Pricing
-
-Bright Data offers a free tier with up to 5,000 requests per month. For higher volume, refer to Bright Data's pricing page for details on Web Unlocker, SERP API, Web Scraper API, and Scraping Browser plans.
-
----
-
-For more information on Bright Data services, visit [https://brightdata.com](https://brightdata.com).