cykani-stealth 1.3.4__tar.gz

cykani_stealth-1.3.4/MANIFEST.in

@@ -0,0 +1 @@
+include src/cykani_sdk/py.typed

cykani_stealth-1.3.4/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: cykani-stealth
+Version: 1.3.4
+Summary: Cykani Python SDK — stealth browser automation with fingerprint evasion, human-like behavior, and autonomous browsing
+License: MIT
+Project-URL: Homepage, https://github.com/cykani/cykani-stealth
+Project-URL: Repository, https://github.com/cykani/cykani-stealth
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cdp-use>=1.4.5
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: orjson>=3.9.0
+Provides-Extra: geoip
+Requires-Dist: geoip2>=5.0.0; extra == "geoip"
+Requires-Dist: maxminddb>=2.6.0; extra == "geoip"
+
+# cykani-sdk
+
+**Python SDK — standalone end-to-end stealth browser automation with fingerprint evasion, human-like behavior, and autonomous browsing.**
+
+Complete browser automation in Python. Launches Chrome/Chromium directly over CDP, applies fingerprint configuration, and automates with human-like behavioral patterns. No external browser process or Node.js dependency required.
+
+## Installation
+
+```bash
+pip install cykani-sdk
+```
+
+Or with geoip support:
+
+```bash
+pip install cykani-sdk[geoip]
+```
+
+## Quick Start
+
+```python
+from cykani_sdk import strike, Maestro
+
+# Launch Chrome directly — fully standalone, no Node.js needed
+session = await strike()
+await session.goto("https://example.com")
+await session.close()
+
+# Or use Maestro for multi-session control
+maestro = Maestro()
+session = await maestro.launch({"fingerprint": 4242})
+await session.goto("https://example.com")
+await session.close()
+```
+
+## Presets
+
+| Preset | Hesitation | Precision | Latency | Humor |
+|---|---|---|---|---|
+| `strike()` | 0.5 | 0.7 | human | off |
+| `highTrust()` | 0.8 | 0.95 | human | off |
+| `aggressive()` | 0.1 | 0.99 | robotic | off |
+| `natural()` | 0.5 | 0.7 | organic | yes |
+| `stealth()` | 0.5 | 0.7 | human | yes |
+
+## What the SDK Does (End-to-End)
+
+cykani-sdk is a **complete standalone** browser automation SDK. Each preset and launch call handles the full lifecycle:
+
+1. **Launch** — spawns a Chrome/Chromium process directly via subprocess
+2. **Configure** — applies fingerprint (platform, GPU, screen, hardware concurrency), proxy, viewport, locale, timezone
+3. **Connect** — establishes CDP WebSocket connection via `cdp-use`
+4. **Act** — navigates, clicks, types with human-like behavioral patterns
+5. **Close** — terminates the browser process and cleans up
+
+## Behavioral Engine
+
+The Python SDK mirrors `cykani-stealth`'s `behaviors.js` — same anti-detection patterns, independent implementation:
+
+| Feature | Description |
+|---|---|
+| `cognitiveHesitation` | Pauses before actions based on page interaction density |
+| `idleMicroMovement` | Random cursor jitter simulating natural idle behavior |
+| `coffeeBreak` | Occasional long pauses (8% chance) simulating distraction |
+| `bezierCurve` / `strikeMove` | Bézier curve mouse movement with drift points and correction curves |
+| `typingDelay` | Per-character typing delays varying by character type (punctuation gets longer) |
+| `microTremor` | Small Gaussian jitter preventing linear cursor tracking |
+| `scrollCurve` | Smooth scrolling with eased acceleration/deceleration |
+| `attentionDrift` | Simulated looking away at the screen, then refocusing |
+
+## Connecting to an Existing Browser
+
+If you already have a Chrome instance running, connect to it directly:
+
+```python
+session = await Session.create({
+    "_cdp_endpoint": "ws://127.0.0.1:9222/devtools/browser",
+    "fingerprint": 4242,
+})
+```
+
+## End-to-End in Two Languages
+
+Both SDKs provide complete end-to-end browser automation — choose whichever language fits your team:
+
+| | cykani-stealth (Node.js) | cykani-sdk (Python) |
+|---|---|---|
+| Browser launching | Native Chromium binary | Spawns Chrome via subprocess |
+| Fingerprint evasion | C++ patches in binary | CDP-level configuration |
+| Behavioral engine | Bézier curves, humanization | Same behavioral patterns |
+| CDP protocol | Direct CDP WebSocket | `cdp-use` library |
+| Auto-detection | Yes | Yes |
+| Standalone | Yes, no Python needed | Yes, no Node.js needed |
+
+Both share the same behavioral DNA — same Bézier curves, same typing delays, same cognitive hesitation, same micro-tremor. Pick your language and get the full experience.
+
+## Architecture
+
+```
+cykani-stealth/
+├── src/                    # Node.js stealth engine (C++ patches, CDP)
+│   └── ...                 # Full standalone browser automation
+├── packages/
+│   └── python/
+│       └── cykani-python/  # Python SDK — complete standalone solution
+│           ├── src/cykani_sdk/
+│           │   ├── maestro.py      # Browser session orchestration
+│           │   ├── session.py      # Standalone CDP browser session
+│           │   ├── stealth/        # Behavioral engine + stealth
+│           │   ├── agents/         # Autonomous navigation agents
+│           │   └── utils/          # Cookies, proxy, geoip, session
+│           ├── pyproject.toml
+│           └── README.md
+└── README.md
+```
+
+## License
+
+MIT

cykani_stealth-1.3.4/README.md

@@ -0,0 +1,119 @@
+# cykani-sdk
+
+**Python SDK — standalone end-to-end stealth browser automation with fingerprint evasion, human-like behavior, and autonomous browsing.**
+
+Complete browser automation in Python. Launches Chrome/Chromium directly over CDP, applies fingerprint configuration, and automates with human-like behavioral patterns. No external browser process or Node.js dependency required.
+
+## Installation
+
+```bash
+pip install cykani-sdk
+```
+
+Or with geoip support:
+
+```bash
+pip install cykani-sdk[geoip]
+```
+
+## Quick Start
+
+```python
+from cykani_sdk import strike, Maestro
+
+# Launch Chrome directly — fully standalone, no Node.js needed
+session = await strike()
+await session.goto("https://example.com")
+await session.close()
+
+# Or use Maestro for multi-session control
+maestro = Maestro()
+session = await maestro.launch({"fingerprint": 4242})
+await session.goto("https://example.com")
+await session.close()
+```
+
+## Presets
+
+| Preset | Hesitation | Precision | Latency | Humor |
+|---|---|---|---|---|
+| `strike()` | 0.5 | 0.7 | human | off |
+| `highTrust()` | 0.8 | 0.95 | human | off |
+| `aggressive()` | 0.1 | 0.99 | robotic | off |
+| `natural()` | 0.5 | 0.7 | organic | yes |
+| `stealth()` | 0.5 | 0.7 | human | yes |
+
+## What the SDK Does (End-to-End)
+
+cykani-sdk is a **complete standalone** browser automation SDK. Each preset and launch call handles the full lifecycle:
+
+1. **Launch** — spawns a Chrome/Chromium process directly via subprocess
+2. **Configure** — applies fingerprint (platform, GPU, screen, hardware concurrency), proxy, viewport, locale, timezone
+3. **Connect** — establishes CDP WebSocket connection via `cdp-use`
+4. **Act** — navigates, clicks, types with human-like behavioral patterns
+5. **Close** — terminates the browser process and cleans up
+
+## Behavioral Engine
+
+The Python SDK mirrors `cykani-stealth`'s `behaviors.js` — same anti-detection patterns, independent implementation:
+
+| Feature | Description |
+|---|---|
+| `cognitiveHesitation` | Pauses before actions based on page interaction density |
+| `idleMicroMovement` | Random cursor jitter simulating natural idle behavior |
+| `coffeeBreak` | Occasional long pauses (8% chance) simulating distraction |
+| `bezierCurve` / `strikeMove` | Bézier curve mouse movement with drift points and correction curves |
+| `typingDelay` | Per-character typing delays varying by character type (punctuation gets longer) |
+| `microTremor` | Small Gaussian jitter preventing linear cursor tracking |
+| `scrollCurve` | Smooth scrolling with eased acceleration/deceleration |
+| `attentionDrift` | Simulated looking away at the screen, then refocusing |
+
+## Connecting to an Existing Browser
+
+If you already have a Chrome instance running, connect to it directly:
+
+```python
+session = await Session.create({
+    "_cdp_endpoint": "ws://127.0.0.1:9222/devtools/browser",
+    "fingerprint": 4242,
+})
+```
+
+## End-to-End in Two Languages
+
+Both SDKs provide complete end-to-end browser automation — choose whichever language fits your team:
+
+| | cykani-stealth (Node.js) | cykani-sdk (Python) |
+|---|---|---|
+| Browser launching | Native Chromium binary | Spawns Chrome via subprocess |
+| Fingerprint evasion | C++ patches in binary | CDP-level configuration |
+| Behavioral engine | Bézier curves, humanization | Same behavioral patterns |
+| CDP protocol | Direct CDP WebSocket | `cdp-use` library |
+| Auto-detection | Yes | Yes |
+| Standalone | Yes, no Python needed | Yes, no Node.js needed |
+
+Both share the same behavioral DNA — same Bézier curves, same typing delays, same cognitive hesitation, same micro-tremor. Pick your language and get the full experience.
+
+## Architecture
+
+```
+cykani-stealth/
+├── src/                    # Node.js stealth engine (C++ patches, CDP)
+│   └── ...                 # Full standalone browser automation
+├── packages/
+│   └── python/
+│       └── cykani-python/  # Python SDK — complete standalone solution
+│           ├── src/cykani_sdk/
+│           │   ├── maestro.py      # Browser session orchestration
+│           │   ├── session.py      # Standalone CDP browser session
+│           │   ├── stealth/        # Behavioral engine + stealth
+│           │   ├── agents/         # Autonomous navigation agents
+│           │   └── utils/          # Cookies, proxy, geoip, session
+│           ├── pyproject.toml
+│           └── README.md
+└── README.md
+```
+
+## License
+
+MIT

cykani_stealth-1.3.4/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cykani-stealth"
+version = "1.3.4"
+description = "Cykani Python SDK — stealth browser automation with fingerprint evasion, human-like behavior, and autonomous browsing"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [
+    "cdp-use>=1.4.5",
+    "httpx>=0.27.0",
+    "pydantic>=2.0",
+    "numpy>=1.26.0",
+    "orjson>=3.9.0",
+]
+
+[project.optional-dependencies]
+geoip = ["geoip2>=5.0.0", "maxminddb>=2.6.0"]
+
+[project.urls]
+Homepage = "https://github.com/cykani/cykani-stealth"
+Repository = "https://github.com/cykani/cykani-stealth"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88

cykani_stealth-1.3.4/setup.cfg

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

cykani_stealth-1.3.4/src/cykani_sdk/__init__.py

@@ -0,0 +1,93 @@
+from cykani_sdk.maestro import Maestro
+from cykani_sdk.session import Session
+from cykani_sdk.stealth.constellation import CdpWorld
+from cykani_sdk.stealth.phantom import Phantom
+from cykani_sdk.stealth.behavior import BehaviorEngine
+from cykani_sdk.agents.strategist import Strategist
+from cykani_sdk.agents.autonomous import Autonomous
+from cykani_sdk.agents.observer import Observer
+from cykani_sdk.agents.diagnostic import Diagnostic
+from cykani_sdk.agents.perceptor import Perceptor
+from cykani_sdk.utils.cookies import CookieJar
+from cykani_sdk.utils.proxy import ProxyManager, resolve_proxy_config
+from cykani_sdk.utils.geoip import resolve_geoip, COUNTRY_LOCALE_MAP
+from cykani_sdk.utils.session import SessionState
+from cykani_sdk.utils.errors import StealthError, ValidationError, SessionError
+from cykani_sdk.utils.hooks import Hooks
+from cykani_sdk.utils.poolize import Poolize
+
+
+async def strike(entity: dict | None = None) -> Session:
+    maestro = Maestro()
+    return await maestro.launch(entity or {})
+
+
+async def summon(entity: dict | None = None) -> Session:
+    return await strike(entity)
+
+
+async def unleash(entity: dict | None = None) -> Session:
+    return await strike(entity)
+
+
+async def launch_persistent_context(entity: dict | None = None) -> Session:
+    maestro = Maestro()
+    return await maestro.launchPersistentContext(entity or {})
+
+
+def create_maestro(opts: dict | None = None) -> Maestro:
+    return Maestro(opts or {})
+
+
+async def high_trust(entity: dict | None = None) -> Session:
+    maestro = Maestro(strategy="highTrust")
+    return await maestro.launch(entity or {})
+
+
+async def aggressive(entity: dict | None = None) -> Session:
+    maestro = Maestro(strategy="aggressive")
+    return await maestro.launch(entity or {})
+
+
+async def natural(entity: dict | None = None) -> Session:
+    maestro = Maestro(strategy="natural")
+    return await maestro.launch(entity or {})
+
+
+async def stealth_launch(entity: dict | None = None) -> Session:
+    maestro = Maestro(strategy="stealth")
+    return await maestro.launch(entity or {})
+
+
+__all__ = [
+    "Maestro",
+    "Session",
+    "CdpWorld",
+    "Phantom",
+    "BehaviorEngine",
+    "Strategist",
+    "Autonomous",
+    "Observer",
+    "Diagnostic",
+    "Perceptor",
+    "CookieJar",
+    "ProxyManager",
+    "resolve_proxy_config",
+    "resolve_geoip",
+    "COUNTRY_LOCALE_MAP",
+    "SessionState",
+    "StealthError",
+    "ValidationError",
+    "SessionError",
+    "Hooks",
+    "Poolize",
+    "strike",
+    "summon",
+    "unleash",
+    "launch_persistent_context",
+    "create_maestro",
+    "high_trust",
+    "aggressive",
+    "natural",
+    "stealth_launch",
+]

cykani_stealth-1.3.4/src/cykani_sdk/adapters/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+import logging
+
+logging.basicConfig(level=logging.INFO)

cykani_stealth-1.3.4/src/cykani_sdk/adapters/playwright.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("cykani.adapters.playwright")
+
+
+async def adapt_to_playwright(session: Any) -> Any:
+    """Adapt cykani-sdk session to Playwright-compatible interface."""
+    return session
+
+
+class PlaywrightAdapter:
+    """Adapter for Playwright-compatible session interface."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    async def goto(self, url: str, **kwargs) -> Any:
+        return await self._session.goto(url, kwargs)
+
+    async def click(self, selector: str, **kwargs) -> Any:
+        return await self._session.click(selector, kwargs)
+
+    async def type(self, selector: str, text: str, **kwargs) -> Any:
+        return await self._session.type(selector, text, kwargs)

cykani_stealth-1.3.4/src/cykani_sdk/agents/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+import logging
+
+logging.basicConfig(level=logging.INFO)

cykani_stealth-1.3.4/src/cykani_sdk/agents/autoPilot.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("cykani.agents.autoPilot")
+
+
+class AutoPilot:
+    """AutoPilot agent for automated browsing."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    async def go(self, url: str) -> Any:
+        return await self._session.goto(url)
+
+    async def interact(self, action: str, target: str, value: str | None = None) -> Any:
+        if action == "click":
+            return await self._session.click(target)
+        elif action == "type":
+            return await self._session.type(target, value or "")
+        elif action == "fill":
+            return await self._session.fill(target, value or "")
+        elif action == "hover":
+            return await self._session.hover(target)
+        elif action == "goto":
+            return await self._session.goto(target)
+        return None

cykani_stealth-1.3.4/src/cykani_sdk/agents/autonomous.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("cykani.agents.autonomous")
+
+
+class Autonomous:
+    """Autonomous browsing agent."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    async def signIn(self, email: str, password: str, **opts: Any) -> Any:
+        return await self._session.evaluate(
+            "(email, password) => { /* sign in logic */ }", email, password
+        )
+
+    async def fillForm(self, selector: str, data: dict) -> Any:
+        return await self._session.evaluate(
+            "(data) => { /* form fill logic */ }", data
+        )
+
+    async def navigateFlow(self, steps: list) -> Any:
+        for step in steps:
+            action = step.get("action")
+            if action == "goto":
+                await self._session.goto(step["url"])
+            elif action == "click":
+                await self._session.click(step["selector"])
+            elif action == "type":
+                await self._session.type(step["selector"], step["text"])
+        return {"steps_completed": len(steps)}

cykani_stealth-1.3.4/src/cykani_sdk/agents/diagnostic.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("cykani.agents.diagnostic")
+
+
+class Diagnostic:
+    """Diagnostic agent for page analysis."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    async def scanForDetections(self) -> dict:
+        return await self._session.evaluate(
+            "() => ({ "
+            "navigator_webdriver: navigator.webdriver, "
+            "plugins_count: navigator.plugins.length, "
+            "languages: navigator.languages, "
+            "webgl_renderer: (() => { try { return document.createElement('canvas').getContext('webgl').getParameter(document.createElement('canvas').getContext('webgl').RENDERER); } catch(e) { return null; } })(), "
+            "})"
+        )

cykani_stealth-1.3.4/src/cykani_sdk/agents/observer.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("cykani.agents.observer")
+
+
+class Observer:
+    """Observes page state and DOM changes."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    async def captureSnapshot(self) -> dict:
+        return await self._session.evaluate("() => ({ url: location.href, title: document.title })")
+
+    async def observe(self, selector: str) -> Any:
+        return await self._session.evaluate("(sel) => { const el = document.querySelector(sel); return el ? el.textContent : null; }", selector)
+
+    async def onMutation(self, callback) -> None:
+        await self._session.evaluate(
+            "(cb) => { new MutationObserver(cb).observe(document.body, {childList: true, subtree: true}); }",
+            callback,
+        )

cykani_stealth-1.3.4/src/cykani_sdk/agents/perceptor.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("cykani.agents.perceptor")
+
+
+class Perceptor:
+    """Perceptor agent for visual understanding."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    async def captureVisual(self) -> bytes:
+        return await self._session.screenshot()
+
+    async def readPageContent(self) -> str:
+        return await self._session.content()
+
+    async def extractLinks(self) -> list[dict]:
+        return await self._session.evaluate(
+            "() => Array.from(document.querySelectorAll('a')).map(a => ({href: a.href, text: a.textContent.trim()}))"
+        )

cykani_stealth-1.3.4/src/cykani_sdk/agents/perceptual.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("cykani.agents.perceptual")
+
+
+class Perceptual:
+    """Perceptual agent for cognitive modeling."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    async def assessPage(self) -> dict:
+        return await self._session.evaluate(
+            "() => ({ "
+            "isLoginPage: !!document.querySelector('input[type=password]'), "
+            "hasForm: !!document.querySelector('form'), "
+            "mainContent: document.querySelector('main') ? document.querySelector('main').textContent.substring(0, 500) : '', "
+            "})"
+        )

cykani_stealth-1.3.4/src/cykani_sdk/agents/realworld.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("cykani.agents.realworld")
+
+
+class RealWorld:
+    """Real-world interaction agent."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    async def simulateHumanJourney(self, steps: list[dict]) -> Any:
+        results = []
+        for step in steps:
+            action = step.get("action")
+            if action == "wait":
+                import asyncio
+                await asyncio.sleep(step.get("duration", 1.0))
+            elif action == "goto":
+                results.append(await self._session.goto(step["url"]))
+            elif action == "click":
+                results.append(await self._session.click(step["selector"]))
+            elif action == "type":
+                results.append(await self._session.type(step["selector"], step["text"]))
+        return results