thunder-agent 0.2.0__py3-none-any.whl

thunder/__init__.py

@@ -0,0 +1,28 @@
+"""Thunder — the human engine for AI agents.
+
+Thunder gives agents a human-shaped presence on the web:
+a stealth browser body, a fingerprint skin, a human hand
+(mouse + typing), a ghost-mode TLS layer, a CAPTCHA bridge,
+and a mind (stewmind-1.7b).
+
+    import thunder
+
+    body = thunder.Body()                      # a human-shaped browser
+    await body.wake("https://example.com")    # open like a person
+    await body.type("#q", "hello world")      # type like a person
+    shot = await body.look()                  # see the page
+
+Dual-licensed spirit: MIT core, optional AGPL engines (nodriver).
+Use Thunder on systems and accounts you are authorized to use.
+"""
+try:  # optional strongest engine (needs real Chrome + pip install nodriver)
+    from thunder.nodriver_body import NodriverBody
+except Exception:  # pragma: no cover
+    NodriverBody = None
+from thunder.body import Body
+from thunder.ghost import Ghost
+from thunder.mind import StewMind
+from thunder.fingerprint import Skin, random_skin
+
+__version__ = "0.2.0"
+__all__ = ["Body", "Ghost", "StewMind", "Skin", "random_skin", "NodriverBody", "__version__"]

thunder/body.py

@@ -0,0 +1,231 @@
+"""Body — Thunder's browser body.
+
+A Body is a full human-shaped browser session:
+  * a Skin (consistent device fingerprint)
+  * stealth patches injected on every page (init script)
+  * a Hand (human mouse/typing/scroll)
+  * eyes (screenshots, structured page reading)
+  * optional video recording of everything it does
+  * persistent context (cookies/localStorage) per profile
+
+Engines:
+  * "playwright-stealth"  — default, zero heavy deps, works everywhere
+  * "nodriver"            — optional, strongest anti-detection (AGPL-3
+                             engine; see README license notes)
+
+    import thunder
+    body = thunder.Body(profile="ada")     # persistent human profile
+    await body.wake("https://example.com")
+    await body.type("input[name=q]", "thunder agent")
+    shot_path = await body.look()
+    await body.rest()
+
+Run Thunder only on systems and accounts you are authorized to use.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import random
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .fingerprint import Skin, random_skin
+from .human import Hand
+
+THUNDER_HOME = Path(os.getenv("THUNDER_HOME", Path.home() / ".thunder"))
+
+
+class Body:
+    def __init__(self, profile: str = "default", skin: Optional[Skin] = None,
+                 engine: str = "playwright-stealth", headless: bool = True,
+                 record_video: bool = False, viewport: Optional[dict] = None,
+                 locale: str = "en-US", timezone: str = "Africa/Lagos"):
+        self.profile = profile
+        self.engine = engine
+        self.headless = headless
+        self.viewport = viewport
+        self.record = record_video
+        self.locale = locale
+        self.timezone = timezone
+        self.user_data_dir = THUNDER_HOME / "profiles" / profile
+        self.user_data_dir.mkdir(parents=True, exist_ok=True)
+        skin_path = self.user_data_dir / "skin.json"
+        if skin is None:
+            if skin_path.exists():
+                self.skin = Skin.load(str(skin_path))
+            else:
+                self.skin = random_skin(timezone=timezone)
+                self.skin.save(str(skin_path))
+        else:
+            self.skin = skin
+            self.skin.save(str(skin_path))
+        self._pw = None
+        self._browser = None
+        self._context = None
+        self.page = None
+        self.hand: Optional[Hand] = None
+        self._video_dir = THUNDER_HOME / "videos"
+
+    # ── lifecycle ──────────────────────────────────────────────────
+    async def wake(self, url: Optional[str] = None):
+        """Start the body's browser; optionally open a first page."""
+        from playwright.async_api import async_playwright
+
+        self._pw = await async_playwright().start()
+        launch_kw: Dict[str, Any] = dict(
+            headless=self.headless,
+            record_video_dir=str(self._video_dir) if self.record else None,
+            record_video_size={"width": 1366, "height": 900} if self.record else None,
+            args=[
+                "--disable-blink-features=AutomationControlled",
+                "--no-sandbox", "--disable-dev-shm-usage",
+                "--disable-infobars", "--window-size=1380,860",
+                f"--window-position={random.randint(0,60)},{random.randint(0,40)}",
+            ])
+        if self.engine == "chrome":
+            # REAL Google Chrome (channel), not bundled Chromium
+            import shutil
+            launch_kw["channel"] = "chrome" if shutil.which("google-chrome") else "chromium"
+        if self.engine == "nodriver":
+            # nodriver is a stronger, separate engine; supported via
+            # thunder.nodriver_engine when installed (AGPL-3).
+            raise ValueError("use thunder.nodriver_engine.NodriverBody for the nodriver engine")
+        launch_kw.update({
+            "user_agent": self.skin.user_agent,     # header + JS always match the Skin
+            "viewport": {"width": self.skin.window_w, "height": self.skin.window_h},
+            "locale": self.locale,
+            "timezone_id": self.timezone,
+        })
+        self._browser = await self._pw.chromium.launch_persistent_context(
+            str(self.user_data_dir), **launch_kw)
+        ctx = self._browser
+        vp = self.viewport or {"width": self.skin.window_w, "height": self.skin.window_h}
+        try:
+            await ctx.add_init_script(self.skin.injection_script())
+        except Exception:
+            pass
+        self.page = ctx.pages[0] if ctx.pages else await ctx.new_page()
+        await self.page.set_viewport_size(vp)
+        try:
+            await self.page.set_locale(self.locale)
+        except Exception:
+            pass
+        try:
+            await ctx.set_default_timeout(20000)
+        except Exception:
+            pass
+        # pages created later must also wear the skin
+        ctx.on("page", lambda p: asyncio.ensure_future(self._dress(p)))
+        self.hand = Hand(self.page, seed=self.skin.seed)
+        if self.record:
+            self._video_dir.mkdir(parents=True, exist_ok=True)
+        if url:
+            await self.go(url)
+        return self
+
+    async def _dress(self, page):
+        try:
+            await page.add_init_script(self.skin.injection_script())
+        except Exception:
+            pass
+
+    async def rest(self):
+        """Close the body gracefully (context persists to disk)."""
+        try:
+            if self.page and self.record:
+                await self.page.wait_for_timeout(300)
+            if self._browser:
+                await self._browser.close()
+            if self._pw:
+                await self._pw.stop()
+        except Exception:
+            pass
+        finally:
+            self._browser = None
+            self.page = None
+
+    # ── actions (human-shaped) ─────────────────────────────────────
+    async def go(self, url: str, human: bool = True):
+        """Navigate like a person: sometimes pause before, sometimes
+        read the page after."""
+        if human and random.random() < 0.4:
+            await asyncio.sleep(random.uniform(0.4, 1.8))
+        r = await self.page.goto(url, wait_until="domcontentloaded")
+        try:
+            await self.page.wait_for_load_state("networkidle", timeout=8000)
+        except Exception:
+            pass          # heavy sites never go idle; a human keeps reading anyway
+        await asyncio.sleep(random.uniform(0.3, 0.9))
+        return r
+
+    async def look(self, path: Optional[str] = None) -> str:
+        """Eyes: full-page screenshot."""
+        p = path or str(self._video_dir / f"see_{int(time.time())}.png") \
+            if self.record else path
+        if not p:
+            import tempfile
+            fd, p = tempfile.mkstemp(suffix=".png")
+            os.close(fd)
+        await self.page.screenshot(path=p, full_page=False)
+        return p
+
+    async def read(self) -> Dict[str, Any]:
+        """Eyes + understanding: structured outline of the page for
+        LLMs (title, url, text excerpt, interactive elements)."""
+        return await self.page.evaluate(
+            "(() => {" + _read.__doc__ + "})()" if False else """(() => {
+            const els = [];
+            for (const el of document.querySelectorAll(
+                    "a, button, input, textarea, select, [role=button], [contenteditable=true]")) {
+                const r = el.getBoundingClientRect();
+                if (r.width === 0 || r.height === 0) continue;
+                let sel = el.id ? "#" + el.id : "";
+                if (!sel && el.name) sel = el.tagName.toLowerCase() + '[name="' + el.name + '"]';
+                if (!sel && el.className && typeof el.className === "string") {
+                    const c = el.className.trim().split(/\\s+/)[0];
+                    if (c) sel = el.tagName.toLowerCase() + "." + c;
+                }
+                els.push({
+                    tag: el.tagName.toLowerCase(),
+                    text: (el.innerText || el.value || el.placeholder || "").slice(0, 80),
+                    selector: sel,
+                    meta: el.getAttribute("href") || el.getAttribute("type") || "",
+                });
+                if (els.length >= 60) break;
+            }
+            return {
+                title: document.title,
+                url: location.href,
+                text: document.body ? document.body.innerText.slice(0, 4000) : "",
+                elements: els,
+            };
+        })()""")
+
+    async def click(self, selector: str):
+        await self.hand.click(selector)
+
+    async def type(self, selector: str, text: str):
+        await self.hand.type(selector, text)
+
+    async def scroll(self, amount: int = 600):
+        await self.hand.scroll(amount)
+
+    async def extract(self, selector: str = "body") -> str:
+        loc = self.page.locator(selector).first
+        return await loc.inner_text()
+
+    async def wait_human(self, seconds: float = 1.5):
+        await self.hand.idle(seconds)
+
+    # ── persistence ───────────────────────────────────────────────
+    async def save_state(self):
+        st = self.user_data_dir / "state.json"
+        if self.page:
+            st.write_text(json.dumps({
+                "storage": await self.page.evaluate(
+                    "JSON.stringify({l: localStorage, s: sessionStorage})"),
+            }, indent=2))
+        return str(st)

thunder/captcha.py

@@ -0,0 +1,153 @@
+"""CAPTCHA bridge — detect, classify, and solve.
+
+Thunder's stance on CAPTCHAs:
+  1. AVOID: with a good Skin, human hands and a residential IP,
+     most challenges never fire. That is the first line.
+  2. DETECT: senses() reports exactly which challenge (if any)
+     is on the page, so an agent can decide.
+  3. SOLVE: on your own accounts, plug in your existing solver
+     subscription (CapSolver or 2Captcha API key). Thunder formats
+     the task, polls, and injects the token.
+  4. VISION (experimental): an LLM vision hook describes the
+     challenge — the beginning of stewmind-native solving.
+
+Thunder does not ship solver keys and is not a mass-solving
+service. Use it where you have authorization.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import time
+from typing import Any, Dict, Optional
+
+DETECT_JS = """(() => {
+  const out = {found: false, type: null, sitekey: null, selector: null};
+  const q = (sel) => document.querySelector(sel);
+  const cf = q('.cf-turnstile, [data-sitekey]');
+  if (cf) { out.found = true; out.type = 'turnstile';
+            out.sitekey = cf.getAttribute('data-sitekey'); out.selector = '.cf-turnstile'; return out; }
+  const rc = q('iframe[src*="recaptcha"]');
+  if (rc) { out.found = true; out.type = 'recaptcha';
+            const m = document.documentElement.innerHTML.match(/sitekey["']?\\s*[:=]\\s*["']([\\w-]{40})/);
+            out.sitekey = m ? m[1] : null; out.selector = 'iframe[src*="recaptcha"]'; return out; }
+  const hc = q('iframe[src*="hcaptcha"], [data-hcaptcha-sitekey]');
+  if (hc) { out.found = true; out.type = 'hcaptcha';
+            const m = document.documentElement.innerHTML.match(/sitekey["']?\\s*[:=]\\s*["']([\\w-]{30,})/);
+            out.sitekey = m ? m[1] : null; return out; }
+  const slide = q('.slider, .geetest_slider, [class*=slider]');
+  if (slide) { out.found = true; out.type = 'slider'; return out; }
+  return out;
+})()"""
+
+
+async def senses(page) -> Dict[str, Any]:
+    """Look at the page and report any CAPTCHA challenge found."""
+    try:
+        return await page.evaluate(DETECT_JS)
+    except Exception:
+        return {"found": False, "type": None}
+
+
+class SolverBridge:
+    """Routes a challenge to your solver subscription."""
+
+    def __init__(self, capsolver_key: Optional[str] = None,
+                 twocaptcha_key: Optional[str] = None):
+        self.capsolver = capsolver_key or os.getenv("CAPSOLVER_API_KEY", "")
+        self.twocaptcha = twocaptcha_key or os.getenv("TWOCAPTCHA_API_KEY", "")
+
+    def available(self) -> bool:
+        return bool(self.capsolver or self.twocaptcha)
+
+    async def solve(self, page, challenge: Dict[str, Any],
+                    page_url: Optional[str] = None) -> Dict[str, Any]:
+        """Solve the given challenge and inject the token."""
+        import httpx
+
+        url = page_url or page.url
+        ctype = challenge.get("type")
+        sitekey = challenge.get("sitekey") or ""
+        if not self.available():
+            return {"solved": False,
+                    "error": "no solver key: set CAPSOLVER_API_KEY or TWOCAPTCHA_API_KEY",
+                    "hint": "Thunder avoids most challenges with a good skin + human hand"}
+        if not sitekey:
+            return {"solved": False, "error": "no sitekey found on page"}
+
+        async with httpx.AsyncClient(timeout=120) as c:
+            token = None
+            if self.capsolver and ctype == "turnstile":
+                task = {"type": "AntiTurnstileTaskProxyLess",
+                        "websiteURL": url, "websiteKey": sitekey}
+                token = await self._capsolver(c, task)
+            elif self.capsolver and ctype == "recaptcha":
+                token = await self._capsolver(c, {
+                    "type": "ReCaptchaV2TaskProxyLess",
+                    "websiteURL": url, "websiteKey": sitekey})
+            elif self.capsolver and ctype == "hcaptcha":
+                token = await self._capsolver(c, {
+                    "type": "HCaptchaTaskProxyLess",
+                    "websiteURL": url, "websiteKey": sitekey})
+            elif self.twocaptcha:
+                token = await self._twocaptcha(c, ctype, url, sitekey)
+            if not token:
+                return {"solved": False, "error": "solver returned no token"}
+            inject = {
+                "turnstile": "document.querySelector('[name=cf-turnstile-response]'"
+                             ",input[name=cf-turnstile-response]').value = t;"
+                             "window.turnbridge_token = t;",
+                "recaptcha": "document.getElementById('g-recaptcha-response')"
+                             ".innerHTML = t; window.turnbridge_token = t;",
+                "hcaptcha": "document.querySelector('[name=h-captcha-response]'"
+                            ",textarea[name=g-recaptcha-response]').value = t;",
+            }.get(ctype, "window.turnbridge_token = t;")
+            await page.evaluate(f"(() => {{ const t = {token!r}; {inject} }})()")
+            return {"solved": True, "type": ctype, "token": token[:24] + "..."}
+
+    async def _capsolver(self, c, task: dict) -> Optional[str]:
+        r = await c.post("https://api.capsolver.com/createTask",
+                         json={"clientKey": self.capsolver, "task": task})
+        d = r.json()
+        if d.get("errorId"):
+            return None
+        tid = d["taskId"]
+        for _ in range(40):
+            await asyncio.sleep(3)
+            r = await c.post("https://api.capsolver.com/getTaskResult",
+                             json={"clientKey": self.capsolver, "taskId": tid})
+            g = r.json().get("solution", {})
+            if g.get("gRecaptchaResponse") or g.get("token"):
+                return g.get("gRecaptchaResponse") or g.get("token")
+        return None
+
+    async def _twocaptcha(self, c, ctype: str, url: str, sitekey: str) -> Optional[str]:
+        kind = {"recaptcha": "userrecaptcha", "hcaptcha": "hcaptcha"}.get(ctype)
+        if not kind:
+            return None
+        r = await c.post("https://2captcha.com/in.php",
+                        data={"key": self.twocaptcha, "method": kind,
+                              "sitekey": sitekey, "pageurl": url, "json": 1})
+        tid = r.json().get("request")
+        if not tid:
+            return None
+        for _ in range(60):
+            await asyncio.sleep(5)
+            r = await c.get("https://2captcha.com/res.php",
+                            params={"key": self.twocaptcha,
+                                    "action": "get", "id": tid, "json": 1})
+            d = r.json()
+            if d.get("status") == 1:
+                return d["request"]
+        return None
+
+
+async def describe_challenge(page, mind=None) -> str:
+    """Experimental: stewmind vision describing a challenge."""
+    shot = await page.screenshot()
+    prompt = ("Describe this CAPTCHA challenge and the exact steps a human "
+              "would take to solve it. Be brief.")
+    if mind is None:
+        return prompt  # caller routes screenshot + prompt to a vision model
+    return prompt

thunder/cli.py

@@ -0,0 +1,101 @@
+"""Thunder CLI.
+
+    thunder browse https://example.com     # open with the human body
+    thunder ghost https://example.com      # TLS-true fetch
+    thunder think "find the pricing page"  # stewmind's next action
+    thunder serve                          # run the MCP server (stdio)
+    thunder demo                           # full showcase run
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="thunder",
+                                description="Thunder — the human engine for AI agents")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    b = sub.add_parser("browse", help="open a URL with the human body")
+    b.add_argument("url")
+    b.add_argument("--shot", default=None)
+    b.add_argument("--scroll", type=int, default=0)
+    b.add_argument("--record", action="store_true", help="save a video")
+
+    g = sub.add_parser("ghost", help="fetch with a browser TLS fingerprint")
+    g.add_argument("url")
+    g.add_argument("--head", action="store_true")
+
+    t = sub.add_parser("think", help="stewmind decides the next action")
+    t.add_argument("goal")
+    t.add_argument("--endpoint", default=None)
+    t.add_argument("--local", action="store_true")
+
+    sub.add_parser("serve", help="run the MCP server over stdio")
+    sub.add_parser("demo", help="run the full Thunder showcase")
+
+    a = p.parse_args(argv)
+
+    if a.cmd == "serve":
+        from thunder.mcp_server import main as serve
+        serve()
+        return 0
+
+    if a.cmd == "browse":
+        from thunder.body import Body
+
+        async def run():
+            body = Body(headless=True, record_video=a.record)
+            await body.wake(a.url)
+            if a.scroll:
+                await body.scroll(a.scroll)
+            shot = a.shot or "thunder_shot.png"
+            await body.look(shot)
+            print(json.dumps({"url": body.page.url,
+                              "title": await body.page.title(),
+                              "screenshot": shot}, indent=2))
+            await body.rest()
+        asyncio.run(run())
+        return 0
+
+    if a.cmd == "ghost":
+        from thunder.ghost import Ghost
+
+        async def run():
+            gh = Ghost()
+            r = await gh.get(a.url)
+            if a.head:
+                print(json.dumps({"status": r.status_code,
+                                  "headers": dict(r.headers)}, indent=2)[:2000])
+            else:
+                print(r.text[:4000])
+            await gh.close()
+        asyncio.run(run())
+        return 0
+
+    if a.cmd == "think":
+        from thunder.body import Body
+        from thunder.mind import StewMind
+
+        async def run():
+            mind = StewMind(endpoint=a.endpoint, local=a.local)
+            body = Body()
+            await body.wake()
+            page = await body.read()
+            print(json.dumps(mind.think(a.goal, page), indent=2))
+            await body.rest()
+        asyncio.run(run())
+        return 0
+
+    if a.cmd == "demo":
+        from thunder.demo import run as run_demo
+        asyncio.run(run_demo())
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

thunder/demo.py

@@ -0,0 +1,55 @@
+"""Thunder end-to-end showcase.
+
+1. Ghost handshake test (requests vs thunder TLS shape)
+2. Body wakes, opens a page like a human, types with the human hand
+3. stewmind decides the next action
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+
+
+async def run():
+    print("⚡ THUNDER — human engine demo\n" + "─" * 46)
+
+    # 1 ── Ghost: TLS-true HTTP
+    from thunder.ghost import Ghost
+    print("[1/3] Ghost: comparing handshakes on a bot-blocking target…")
+    gh = Ghost()
+    url = "https://nowsecure.nl"          # classic Cloudflare gate
+    try:
+        r = await gh.get(url)
+        print(f"      thunder ghost status: {r.status_code} "
+              f"(raw requests/urllib would be challenged)")
+    except Exception as e:
+        print(f"      ghost: {type(e).__name__}: {str(e)[:100]}")
+    await gh.close()
+
+    # 2 ── Body: human-shaped browsing on a real form
+    from thunder.body import Body
+    print("[2/3] Body: opening a page and typing like a human…")
+    body = Body(headless=True)
+    await body.wake("https://www.wikipedia.org")
+    await body.type("#searchInput", "lightning")     # human cadence
+    await asyncio.sleep(0.4)
+    shot = await body.look("thunder_demo.png")
+    page = await body.read()
+    print(f"      opened: {page['title']}")
+    print(f"      typed with human hand, screenshot → {shot}")
+    await body.rest()
+
+    # 3 ── StewMind
+    print("[3/3] StewMind: deciding the next action…")
+    try:
+        from thunder.mind import StewMind
+        mind = StewMind()
+        d = mind.think("Find the article about lightning storms", page)
+        print("      stewmind says:", json.dumps(d, indent=2)[:400])
+    except Exception as e:
+        print(f"      (stewmind offline here: {str(e)[:90]})")
+    print("─" * 46 + "\n⚡ demo done. Thunder never sleeps.")
+
+
+if __name__ == "__main__":
+    asyncio.run(run())