hermes-brightdata 0.1.0__tar.gz

hermes_brightdata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dante Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_brightdata-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: hermes-brightdata
+Version: 0.1.0
+Summary: Bright Data web data tools for Hermes Agent — search, scrape, structured datasets, 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 nine 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
+
+### Example
+
+```bash
+export BRIGHTDATA_API_TOKEN="your-api-token-here"
+export BRIGHTDATA_BROWSER_AUTH="brd-customer-12345-zone-myzone:password123"
+```
+
+## Tools
+
+The plugin provides nine 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. |
+| `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.1.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.1.0/README.md

@@ -0,0 +1,112 @@
+# 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 nine 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
+
+### Example
+
+```bash
+export BRIGHTDATA_API_TOKEN="your-api-token-here"
+export BRIGHTDATA_BROWSER_AUTH="brd-customer-12345-zone-myzone:password123"
+```
+
+## Tools
+
+The plugin provides nine 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. |
+| `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.1.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.1.0/brightdata_plugin/__init__.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+
+from . import schemas
+from .api import BrightDataClient
+from .browser import BrowserSession
+from .config import Config, load_config
+from .counter import SessionCounter
+from .tools import make_browser_handlers, make_core_handlers
+
+
+def build_handlers(cfg: Config | None = None) -> dict:
+    cfg = cfg or load_config()
+    counter = SessionCounter()
+
+    _client: dict = {}
+    def get_client() -> BrightDataClient:
+        if "c" not in _client:
+            _client["c"] = BrightDataClient(cfg)
+        return _client["c"]
+
+    _session: dict = {}
+    def get_session() -> BrowserSession:
+        if "s" not in _session:
+            _session["s"] = BrowserSession(cfg)
+        return _session["s"]
+
+    handlers = {}
+    handlers.update(make_core_handlers(get_client, counter))
+    handlers.update(make_browser_handlers(get_session, counter))
+    # private keys popped by register(); not real tools
+    handlers["_counter"] = counter  # type: ignore
+    handlers["_get_session"] = get_session  # type: ignore
+    handlers["_session_holder"] = _session  # type: ignore
+    return handlers
+
+
+def register(ctx) -> None:
+    cfg = load_config()
+    handlers = build_handlers(cfg)
+    counter = handlers.pop("_counter")
+    handlers.pop("_get_session")
+    session_holder = handlers.pop("_session_holder")
+
+    for name, handler in handlers.items():
+        ctx.register_tool(name, "brightdata", schemas.TOOL_SCHEMAS[name], handler)
+
+    def brightdata_cmd(args, **kwargs) -> str:
+        return json.dumps(counter.stats(), ensure_ascii=False)
+    ctx.register_command("brightdata", brightdata_cmd,
+                         description="Show Bright Data session usage stats")
+
+    def on_session_end(*args, **kwargs):
+        # only close if a browser session was actually created this session
+        s = session_holder.get("s")
+        if s is not None:
+            try:
+                s.close()
+            except Exception:  # noqa: BLE001
+                pass
+    ctx.register_hook("on_session_end", on_session_end)

hermes_brightdata-0.1.0/brightdata_plugin/api.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import time
+
+import requests
+
+from .config import Config
+
+BASE_URL = "https://api.brightdata.com"
+REQUEST_ENDPOINT = f"{BASE_URL}/request"
+DATASET_TRIGGER = f"{BASE_URL}/datasets/v3/trigger"
+DATASET_PROGRESS = f"{BASE_URL}/datasets/v3/progress"
+DATASET_SNAPSHOT = f"{BASE_URL}/datasets/v3/snapshot"
+
+_HINTS = {
+    401: "API token invalid or missing — check BRIGHTDATA_API_TOKEN.",
+    402: "Free quota (5,000 req/month) may be exhausted — check billing.",
+    429: "Rate limited or quota exhausted — retry later or raise plan limit.",
+}
+
+
+class BrightDataError(Exception):
+    def __init__(self, message: str, status: int, hint: str = ""):
+        super().__init__(message)
+        self.status = status
+        self.hint = hint or _HINTS.get(status, "Unexpected Bright Data API error.")
+
+
+class BrightDataClient:
+    def __init__(self, cfg: Config, timeout: int = 60):
+        self._cfg = cfg
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {cfg.token}",
+            "Content-Type": "application/json",
+        })
+
+    def _post_request(self, payload: dict) -> requests.Response:
+        resp = self._session.post(REQUEST_ENDPOINT, json=payload, timeout=self._timeout)
+        if resp.status_code >= 400:
+            raise BrightDataError(
+                f"Bright Data /request failed: {resp.status_code}",
+                status=resp.status_code,
+            )
+        return resp
+
+    def unlock(self, url: str, data_format: str = "markdown", render: bool = False) -> str:
+        payload = {
+            "zone": self._cfg.unlocker_zone,
+            "url": url,
+            "format": "raw",
+            "data_format": data_format,
+        }
+        if render:
+            payload["render"] = True
+        return self._post_request(payload).text
+
+    def serp(self, search_url: str, parse_json: bool = True) -> str:
+        url = search_url
+        if parse_json and "brd_json=" not in url:
+            sep = "&" if "?" in url else "?"
+            url = f"{url}{sep}brd_json=1"
+        payload = {"zone": self._cfg.serp_zone, "url": url, "format": "raw"}
+        return self._post_request(payload).text
+
+    def trigger_dataset(self, dataset_id: str, urls: list[str]) -> str:
+        body = [{"url": u} for u in urls]
+        resp = self._session.post(
+            DATASET_TRIGGER, params={"dataset_id": dataset_id},
+            json=body, timeout=self._timeout,
+        )
+        if resp.status_code >= 400:
+            raise BrightDataError(
+                f"trigger failed: {resp.status_code}", status=resp.status_code)
+        return resp.json()["snapshot_id"]
+
+    def poll_snapshot(self, snapshot_id: str) -> str:
+        resp = self._session.get(
+            f"{DATASET_PROGRESS}/{snapshot_id}", timeout=self._timeout)
+        if resp.status_code >= 400:
+            raise BrightDataError(
+                f"progress failed: {resp.status_code}", status=resp.status_code)
+        return resp.json()["status"]
+
+    def download_snapshot(self, snapshot_id: str, fmt: str = "json") -> str:
+        resp = self._session.get(
+            f"{DATASET_SNAPSHOT}/{snapshot_id}", params={"format": fmt},
+            timeout=self._timeout,
+        )
+        if resp.status_code >= 400:
+            raise BrightDataError(
+                f"snapshot failed: {resp.status_code}", status=resp.status_code)
+        return resp.text
+
+    def collect_dataset(self, dataset_id: str, urls: list[str],
+                        poll_interval: float = 2.0, max_wait: float = 60.0,
+                        sleep=time.sleep, now=time.monotonic) -> dict:
+        snapshot_id = self.trigger_dataset(dataset_id, urls)
+        start = now()
+        while now() - start <= max_wait:
+            status = self.poll_snapshot(snapshot_id)
+            if status == "ready":
+                return {"status": "ready",
+                        "data": self.download_snapshot(snapshot_id)}
+            if status == "failed":
+                return {"status": "failed", "snapshot_id": snapshot_id}
+            sleep(poll_interval)
+        return {"status": "timeout", "snapshot_id": snapshot_id}

hermes_brightdata-0.1.0/brightdata_plugin/browser.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import base64
+
+from .config import Config
+
+CDP_HOST = "brd.superproxy.io:9222"
+
+
+class BrowserUnavailable(Exception):
+    def __init__(self, message: str, hint: str = ""):
+        super().__init__(message)
+        self.hint = hint
+
+
+def _default_connector(cfg: Config):
+    def connect(cdp_url: str):
+        if cfg.browser_auth is None:
+            raise BrowserUnavailable(
+                "browser auth not configured",
+                "set BRIGHTDATA_BROWSER_AUTH to 'brd-customer-<id>-zone-<zone>:<pw>'")
+        try:
+            from playwright.sync_api import sync_playwright
+        except ImportError as e:
+            raise BrowserUnavailable(
+                "playwright not installed",
+                "install with: pip install hermes-brightdata[browser]") from e
+        pw = sync_playwright().start()
+        try:
+            browser_obj = pw.chromium.connect_over_cdp(cdp_url)
+            page = browser_obj.new_page()
+        except BrowserUnavailable:
+            pw.stop()
+            raise
+        except Exception:
+            pw.stop()
+            # never surface the raw exception: it can embed the CDP URL,
+            # which contains the browser_auth password.
+            raise BrowserUnavailable(
+                "browser connection failed",
+                "check BRIGHTDATA_BROWSER_AUTH and that the Scraping Browser zone is active",
+            ) from None
+        page._bd_pw = pw  # keep ref for teardown
+        page._bd_browser = browser_obj
+        return page
+    return connect
+
+
+class BrowserSession:
+    def __init__(self, cfg: Config, connector=None):
+        self._cfg = cfg
+        self._connector = connector or _default_connector(cfg)
+        self._page = None
+
+    def _cdp_url(self) -> str:
+        return f"wss://{self._cfg.browser_auth}@{CDP_HOST}"
+
+    def _ensure_page(self):
+        if self._page is None:
+            self._page = self._connector(self._cdp_url())
+        return self._page
+
+    def navigate(self, url: str) -> dict:
+        page = self._ensure_page()
+        page.goto(url)
+        return {"url": url, "ok": True}
+
+    def snapshot(self) -> dict:
+        page = self._ensure_page()
+        return {"snapshot": page.aria_snapshot()}
+
+    def act(self, action: str, ref: str | None = None, value: str | None = None) -> dict:
+        page = self._ensure_page()
+        if action == "click":
+            page.click(ref)
+        elif action == "type":
+            if value is None:
+                raise ValueError("'value' is required for type action")
+            page.fill(ref, value)
+        elif action == "scroll":
+            delta = int(value) if value else 800
+            page.mouse.wheel(0, delta)
+        elif action == "wait":
+            timeout_ms = float(value) if value else 1000.0
+            page.wait_for_timeout(timeout_ms)
+        else:
+            raise ValueError(f"unknown action '{action}'")
+        return {"action": action, "ok": True}
+
+    def get(self, kind: str) -> dict:
+        page = self._ensure_page()
+        if kind == "html":
+            return {"kind": "html", "data": page.content()}
+        if kind == "text":
+            return {"kind": "text", "data": page.inner_text("body")}
+        if kind == "screenshot":
+            png = page.screenshot()
+            return {"kind": "screenshot", "encoding": "base64",
+                    "data": base64.b64encode(png).decode()}
+        raise ValueError(f"unknown kind '{kind}'")
+
+    def close(self) -> None:
+        page = self._page
+        if page is None:
+            return
+        for closer in (
+            page.close,
+            getattr(getattr(page, "_bd_browser", None), "close", None),
+            getattr(getattr(page, "_bd_pw", None), "stop", None),
+        ):
+            if closer is None:
+                continue
+            try:
+                closer()
+            except Exception:  # noqa: BLE001 — best-effort teardown
+                pass
+        self._page = None

hermes_brightdata-0.1.0/brightdata_plugin/config.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Config:
+    token: str
+    unlocker_zone: str
+    serp_zone: str
+    browser_auth: str | None
+
+
+def load_config(env: dict | None = None) -> Config:
+    env = os.environ if env is None else env
+    # BRIGHTDATA_API_KEY is Bright Data's canonical env name; accept it as an alias.
+    token = env.get("BRIGHTDATA_API_TOKEN") or env.get("BRIGHTDATA_API_KEY")
+    if not token:
+        raise ConfigError("BRIGHTDATA_API_TOKEN (or BRIGHTDATA_API_KEY) is not set")
+    unlocker_zone = (
+        env.get("BRIGHTDATA_WEB_UNLOCKER_ZONE")
+        or env.get("WEB_UNLOCKER_ZONE")
+        or "web_unlocker1"
+    )
+    return Config(
+        token=token,
+        unlocker_zone=unlocker_zone,
+        serp_zone=env.get("BRIGHTDATA_SERP_ZONE", "serp_api1"),
+        browser_auth=env.get("BRIGHTDATA_BROWSER_AUTH"),
+    )

hermes_brightdata-0.1.0/brightdata_plugin/counter.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from collections import Counter
+
+
+class SessionCounter:
+    def __init__(self):
+        self._counts: Counter[str] = Counter()
+
+    def record(self, tool: str) -> None:
+        self._counts[tool] += 1
+
+    def stats(self) -> dict:
+        return {"total": sum(self._counts.values()),
+                "by_tool": dict(self._counts)}
+
+    def reset(self) -> None:
+        self._counts.clear()

hermes_brightdata-0.1.0/brightdata_plugin/datasets.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+# 공식 문서 curl 예시에서 직접 확인된 dataset_id만 등록.
+# 추가 platform은 docs.brightdata.com에서 dataset_id 확인 후 등재할 것.
+DATASET_IDS: dict[str, str] = {
+    "amazon_product": "gd_l7q7dkf244hwjntr0",
+    "linkedin_person": "gd_l1viktl72bvl7bjuj0",
+    "instagram_profile": "gd_l1vikfch901nx3by4",
+}
+
+
+class UnknownPlatform(ValueError):
+    def __init__(self, platform: str, available: list[str]):
+        super().__init__(f"Unknown platform '{platform}'. Available: {available}")
+        self.platform = platform
+        self.available = available
+
+
+def resolve(platform: str) -> str:
+    key = platform.strip().lower()
+    if key not in DATASET_IDS:
+        raise UnknownPlatform(platform, platforms())
+    return DATASET_IDS[key]
+
+
+def platforms() -> list[str]:
+    return sorted(DATASET_IDS)