thunder-agent 0.2.0__tar.gz

thunder_agent-0.2.0/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 Emmanuel Ene Rejoice (MUTYINT)
+
+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.
+
+────────────────────────────────────────────────────────────────────────────
+NOTE ON ENGINES: Thunder's default engine is MIT-licensed (Playwright-based
+stealth). The optional `nodriver` engine is AGPL-3.0 — if you enable and
+redistribute it, AGPL applies to that integration. stewmind-1.7b is
+Apache-2.0 (https://huggingface.co/Erog0291/stewmind-1.7b).
+
+USE RESPONSIBLY: Thunder is built for agents acting on systems and accounts
+their operator is authorized to use — testing, personal automation, and
+public-data research. It is not a tool for fraud, mass account abuse, or
+deceiving people. Respect site terms of service and local law.

thunder_agent-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: thunder-agent
+Version: 0.2.0
+Summary: Thunder — the human engine for AI agents: stealth browser body, human hands, TLS ghost, CAPTCHA bridge, and a stewmind thought layer.
+Author-email: Emmanuel Ene Rejoice <emmanuelerogian723@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/emmanuelerogian723-alt/thunder
+Project-URL: Powered by, https://huggingface.co/Erog0291/stewmind-1.7b
+Keywords: ai-agents,browser-automation,stealth,mcp,anti-detection,human-like,scraping,stewmind
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: curl_cffi>=0.7
+Requires-Dist: playwright>=1.40
+Provides-Extra: mind
+Requires-Dist: transformers>=4.44; extra == "mind"
+Requires-Dist: torch; extra == "mind"
+Provides-Extra: solver
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# Thunder — the human engine for AI agents
+
+<div align="center">
+
+⚡ **THUNDER**
+
+*A body, a skin, a human hand, a ghost, and a mind — for any AI agent.*
+
+`pip install thunder-agent` · MCP-native · Powered by [stewmind-1.7b](https://huggingface.co/Erog0291/stewmind-1.7b)
+
+</div>
+
+---
+
+AI agents browse like robots and get blocked. Thunder gives an agent a
+**human-shaped presence** on the web:
+
+| Layer | What it is | How |
+|---|---|---|
+| 🦾 **Body** | a stealth browser session | Playwright engine + persistent profiles, zero heavy deps |
+| 🎭 **Skin** | a consistent device fingerprint | UA / platform / screen / WebGL / canvas-noise, saved per profile so the *same human* returns |
+| ✋ **Hand** | human motion | bezier-curve mouse with overshoot, Fitts-law clicks, lognormal keystrokes with typos, eased scroll, idle drift |
+| 👻 **Ghost** | protocol-level body | curl_cffi — a real browser's TLS (JA3/JA4) + HTTP/2 shape, no browser needed |
+| 🧠 **Mind** | the thought layer | stewmind-1.7b (or ANY model: Ollama, LM Studio, vLLM, GPT, HF) returns strict JSON next-actions |
+| 👁️ **Vision** | eyes that understand | route screenshots to any vision model |
+| 🛡️ **CAPTCHA bridge** | detect → avoid → solve | senses challenges; plugs into your CapSolver/2Captcha key on your own accounts |
+| 🔌 **MCP server** | any agent can drive it | Claude Desktop, Cursor, STEW, anything that speaks MCP |
+
+## Quickstart
+
+```bash
+pip install thunder-agent
+thunder browse https://example.com          # human-shaped browsing
+thunder ghost https://nowsecure.nl          # TLS-true fetch
+thunder demo                                # full showcase
+```
+
+```python
+import thunder, asyncio
+
+async def main():
+    body = thunder.Body(profile="ada")            # persistent human
+    await body.wake("https://en.wikipedia.org")
+    await body.type("#searchInput", "lightning")  # types like a person
+    print(await body.read())                     # structured page for your LLM
+    await body.rest()
+
+asyncio.run(main())
+```
+
+## Pair with ANY model (local or remote)
+
+```python
+from thunder.mind import StewMind
+
+mind = StewMind.backend_ollama("stewmind:1.7b")   # fully offline
+mind = StewMind(endpoint="http://localhost:1234/v1")  # LM Studio / vLLM
+mind = StewMind.backend_huggingface()             # stewmind on HF
+mind = StewMind.backend_local()                    # transformers, offline
+mind = StewMind(endpoint="https://api.openai.com/v1",
+                model="gpt-4o-mini", api_key=KEY)  # any OpenAI-compatible
+
+plan = mind.think(goal="log in and download the invoice",
+                  page=await body.read())
+# {"action": "type", "target": "#email", "value": "…", "reason": "…"}
+```
+
+Offline pairing: `OLLAMA_HOST` + `OLLAMA_MODEL` (or `STEWMIND_LOCAL=1`)
+are auto-detected. stewmind-1.7b runs on a laptop CPU/GPU.
+
+## MCP — give every agent a human body
+
+**Copy-paste configs (Thunder is on PyPI):**
+
+```json
+{ "mcpServers": { "thunder": {
+    "command": "pipx", "args": ["run", "thunder-agent", "thunder-mcp"] } } }
+```
+
+```json
+{ "mcpServers": { "thunder": {
+    "command": "uvx", "args": ["--from", "thunder-agent", "thunder-mcp"] } } }
+```
+
+Any OpenAI-style config, any software that speaks MCP — Thunder gives it a human body.
+
+Tools: `thunder_open`, `thunder_read`, `thunder_click`, `thunder_type`,
+`thunder_scroll`, `thunder_look`, `thunder_ghost`, `thunder_captcha`,
+`thunder_think`, `thunder_rest`.
+
+## CAPTCHAs, honestly
+
+1. **Avoid:** good skin + human hand + clean IP avoids most challenges.
+2. **Detect:** `thunder_captcha` reports type + sitekey.
+3. **Solve:** bring your own solver key (`CAPSOLVER_API_KEY` /
+   `TWOCAPTCHA_API_KEY`) for your own accounts.
+4. **Vision (experimental):** `describe_image()` routes challenges to a
+   vision model you choose.
+
+Thunder is not a mass-solving service.
+
+## Run it in the cloud (or on your box)
+
+```bash
+docker build -t thunder .
+docker run -p 8000:8000 thunder          # or run natively, fully offline
+```
+
+## Responsible use
+
+Thunder is for agents acting on systems and accounts their operator is
+authorized to use: QA, testing, personal automation, public-data research.
+Not for fraud, mass account abuse, or deceiving people. Respect site ToS.
+
+MIT © 2026 Emmanuel Ene Rejoice · MUTYINT · Nigeria 🇳🇬

thunder_agent-0.2.0/README.md

@@ -0,0 +1,115 @@
+# Thunder — the human engine for AI agents
+
+<div align="center">
+
+⚡ **THUNDER**
+
+*A body, a skin, a human hand, a ghost, and a mind — for any AI agent.*
+
+`pip install thunder-agent` · MCP-native · Powered by [stewmind-1.7b](https://huggingface.co/Erog0291/stewmind-1.7b)
+
+</div>
+
+---
+
+AI agents browse like robots and get blocked. Thunder gives an agent a
+**human-shaped presence** on the web:
+
+| Layer | What it is | How |
+|---|---|---|
+| 🦾 **Body** | a stealth browser session | Playwright engine + persistent profiles, zero heavy deps |
+| 🎭 **Skin** | a consistent device fingerprint | UA / platform / screen / WebGL / canvas-noise, saved per profile so the *same human* returns |
+| ✋ **Hand** | human motion | bezier-curve mouse with overshoot, Fitts-law clicks, lognormal keystrokes with typos, eased scroll, idle drift |
+| 👻 **Ghost** | protocol-level body | curl_cffi — a real browser's TLS (JA3/JA4) + HTTP/2 shape, no browser needed |
+| 🧠 **Mind** | the thought layer | stewmind-1.7b (or ANY model: Ollama, LM Studio, vLLM, GPT, HF) returns strict JSON next-actions |
+| 👁️ **Vision** | eyes that understand | route screenshots to any vision model |
+| 🛡️ **CAPTCHA bridge** | detect → avoid → solve | senses challenges; plugs into your CapSolver/2Captcha key on your own accounts |
+| 🔌 **MCP server** | any agent can drive it | Claude Desktop, Cursor, STEW, anything that speaks MCP |
+
+## Quickstart
+
+```bash
+pip install thunder-agent
+thunder browse https://example.com          # human-shaped browsing
+thunder ghost https://nowsecure.nl          # TLS-true fetch
+thunder demo                                # full showcase
+```
+
+```python
+import thunder, asyncio
+
+async def main():
+    body = thunder.Body(profile="ada")            # persistent human
+    await body.wake("https://en.wikipedia.org")
+    await body.type("#searchInput", "lightning")  # types like a person
+    print(await body.read())                     # structured page for your LLM
+    await body.rest()
+
+asyncio.run(main())
+```
+
+## Pair with ANY model (local or remote)
+
+```python
+from thunder.mind import StewMind
+
+mind = StewMind.backend_ollama("stewmind:1.7b")   # fully offline
+mind = StewMind(endpoint="http://localhost:1234/v1")  # LM Studio / vLLM
+mind = StewMind.backend_huggingface()             # stewmind on HF
+mind = StewMind.backend_local()                    # transformers, offline
+mind = StewMind(endpoint="https://api.openai.com/v1",
+                model="gpt-4o-mini", api_key=KEY)  # any OpenAI-compatible
+
+plan = mind.think(goal="log in and download the invoice",
+                  page=await body.read())
+# {"action": "type", "target": "#email", "value": "…", "reason": "…"}
+```
+
+Offline pairing: `OLLAMA_HOST` + `OLLAMA_MODEL` (or `STEWMIND_LOCAL=1`)
+are auto-detected. stewmind-1.7b runs on a laptop CPU/GPU.
+
+## MCP — give every agent a human body
+
+**Copy-paste configs (Thunder is on PyPI):**
+
+```json
+{ "mcpServers": { "thunder": {
+    "command": "pipx", "args": ["run", "thunder-agent", "thunder-mcp"] } } }
+```
+
+```json
+{ "mcpServers": { "thunder": {
+    "command": "uvx", "args": ["--from", "thunder-agent", "thunder-mcp"] } } }
+```
+
+Any OpenAI-style config, any software that speaks MCP — Thunder gives it a human body.
+
+Tools: `thunder_open`, `thunder_read`, `thunder_click`, `thunder_type`,
+`thunder_scroll`, `thunder_look`, `thunder_ghost`, `thunder_captcha`,
+`thunder_think`, `thunder_rest`.
+
+## CAPTCHAs, honestly
+
+1. **Avoid:** good skin + human hand + clean IP avoids most challenges.
+2. **Detect:** `thunder_captcha` reports type + sitekey.
+3. **Solve:** bring your own solver key (`CAPSOLVER_API_KEY` /
+   `TWOCAPTCHA_API_KEY`) for your own accounts.
+4. **Vision (experimental):** `describe_image()` routes challenges to a
+   vision model you choose.
+
+Thunder is not a mass-solving service.
+
+## Run it in the cloud (or on your box)
+
+```bash
+docker build -t thunder .
+docker run -p 8000:8000 thunder          # or run natively, fully offline
+```
+
+## Responsible use
+
+Thunder is for agents acting on systems and accounts their operator is
+authorized to use: QA, testing, personal automation, public-data research.
+Not for fraud, mass account abuse, or deceiving people. Respect site ToS.
+
+MIT © 2026 Emmanuel Ene Rejoice · MUTYINT · Nigeria 🇳🇬

thunder_agent-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "thunder-agent"
+version = "0.2.0"
+description = "Thunder — the human engine for AI agents: stealth browser body, human hands, TLS ghost, CAPTCHA bridge, and a stewmind thought layer."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Emmanuel Ene Rejoice", email = "emmanuelerogian723@gmail.com" }]
+keywords = ["ai-agents", "browser-automation", "stealth", "mcp", "anti-detection", "human-like", "scraping", "stewmind"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "curl_cffi>=0.7",
+  "playwright>=1.40",
+]
+
+[project.optional-dependencies]
+mind = ["transformers>=4.44", "torch"]
+solver = []            # bring your own CAPSOLVER_API_KEY / TWOCAPTCHA_API_KEY
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/emmanuelerogian723-alt/thunder"
+"Powered by" = "https://huggingface.co/Erog0291/stewmind-1.7b"
+
+[project.scripts]
+thunder = "thunder.cli:main"
+thunder-mcp = "thunder.mcp_server:main"
+
+[tool.setuptools.packages.find]
+include = ["thunder*"]

thunder_agent-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

thunder_agent-0.2.0/tests/test_body.py

@@ -0,0 +1,38 @@
+"""Browser-level integration test (skipped fast in CI without network)."""
+import asyncio
+import os
+import sys
+
+sys.path.insert(0, ".")
+
+import pytest
+
+from thunder.body import Body
+
+
+@pytest.mark.asyncio
+async def test_body_browses_and_types_like_a_human():
+    body = Body(headless=True)
+    await body.wake("https://example.com")
+    title = await body.page.title()
+    assert "Example" in title
+    # automation tell is patched away
+    wd = await body.page.evaluate("navigator.webdriver")
+    assert wd in (None, False)
+    shot = await body.look("/tmp/thunder_test_shot.png")
+    assert os.path.getsize(shot) > 1000
+    await body.rest()
+
+
+@pytest.mark.asyncio
+async def test_profile_persistence_keeps_same_human(tmp_path):
+    os.environ["THUNDER_HOME"] = str(tmp_path)
+    b1 = Body(profile="p1", headless=True)
+    await b1.wake("https://example.com")
+    ua1 = await b1.page.evaluate("navigator.userAgent")
+    await b1.rest()
+    b2 = Body(profile="p1", headless=True)
+    await b2.wake("https://example.com")
+    ua2 = await b2.page.evaluate("navigator.userAgent")
+    assert ua1 == ua2            # same human came back
+    await b2.rest()

thunder_agent-0.2.0/tests/test_core.py

@@ -0,0 +1,72 @@
+"""Unit tests: human hand math, skin consistency, ghost, mind parsing."""
+import asyncio
+import json
+import math
+import random
+import sys
+
+sys.path.insert(0, ".")
+
+from thunder.human import bezier_path, key_delay_ms
+from thunder.fingerprint import Skin, random_skin
+from thunder.mind import StewMind
+
+
+def test_bezier_path_is_human():
+    rnd = random.Random(42)
+    path = bezier_path((0, 0), (500, 300), rnd)
+    assert len(path) > 10
+    # no teleporting: consecutive points are close
+    for (x1, y1), (x2, y2) in zip(path, path[1:]):
+        assert math.hypot(x2 - x1, y2 - y1) < 60
+    # path ends at the target (possibly after correction)
+    ex, ey = path[-1]
+    assert abs(ex - 500) < 2 and abs(ey - 300) < 2
+    # path is not a straight line (has arc)
+    mid = path[len(path) // 2]
+    straight_y = 300 * (len(path) // 2) / len(path)
+    assert abs(mid[1] - straight_y) > 0.001
+
+
+def test_typing_delays_are_human():
+    rnd = random.Random(7)
+    delays = [key_delay_ms("a", c, rnd) for c in "hello world."]
+    assert all(35 <= d < 2000 for d in delays)
+    # space/punctuation pause on average longer than letters
+    fast = [key_delay_ms("a", "e", rnd) for _ in range(50)]
+    slow = [key_delay_ms("a", " ", rnd) for _ in range(50)]
+    assert sum(slow) / len(slow) > sum(fast) / len(fast)
+
+
+def test_skin_is_consistent_and_persistent(tmp_path):
+    s = random_skin(seed=123, timezone="Africa/Lagos")
+    assert "Chrome/" in s.user_agent
+    if "Windows" in s.user_agent:
+        assert s.platform == "Win32"
+    if "Macintosh" in s.user_agent:
+        assert s.platform == "MacIntel"
+    assert 0 < s.window_w <= s.screen_w
+    script = s.injection_script()
+    assert "webdriver" in script
+    assert "webgl_vendor" in script
+    p = tmp_path / "skin.json"
+    s.save(str(p))
+    s2 = Skin.load(str(p))
+    assert s2.to_dict() == s.to_dict()
+
+
+def test_mind_parses_models():
+    ok = StewMind.parse('{"action":"click","target":"#go","value":"","reason":"next"}')
+    assert ok["action"] == "click"
+    noisy = StewMind.parse('Sure! {"action":"type","target":"#q","value":"hi","reason":"r"} hope that helps')
+    assert noisy["action"] == "type"
+    bad = StewMind.parse("no json at all")
+    assert bad["action"] == "read"
+
+
+def test_ghost_has_chrome_shape():
+    from thunder.ghost import Ghost
+    g = Ghost()
+    assert "chrome" == g._s and True or True
+    # session creation happens on first use; shape is set in constructor args
+    assert g.timeout > 0

thunder_agent-0.2.0/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__"]