Metadata-Version: 2.4
Name: cykani-stealth
Version: 1.3.5
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
