Metadata-Version: 2.4
Name: crewai-ceki
Version: 0.1.0
Summary: CrewAI toolkit for Ceki — real Chrome sessions for AI agents with persistent profiles across runs
Project-URL: homepage, https://ceki.me
Project-URL: repository, https://github.com/Ceki-me/crewai
Project-URL: issues, https://github.com/Ceki-me/crewai/issues
Author: iWedmak
License: MIT
License-File: LICENSE
Keywords: ai-agent,automation,browser,ceki,chrome,crewai,tool
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: ceki-sdk>=2.26.0
Requires-Dist: crewai-tools>=0.4
Requires-Dist: pydantic>=2
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# crewai-ceki

CrewAI toolkit for [Ceki](https://ceki.me) — drive a real Chrome session from your CrewAI agent.

> **Killer combo.** CrewAI's structured planning + Ceki's profile export = browser sessions that **remember themselves across runs.** Log in once, your crew walks straight into the dashboard on the next run — no cookies in your code, no second login.

## Install

```bash
pip install crewai-ceki
```

The squat alias [`ceki-crewai`](https://pypi.org/project/ceki-crewai/) is reserved by the same project and depends on `crewai-ceki` — both resolve to the same symbols.

## Architecture

Variant C — **structural toolkit**. Eleven `crewai.tools.BaseTool` subclasses that the CrewAI agent's own LLM plans across:

| Tool | What it does |
|---|---|
| `ceki_rent_browser` | Rent a real Chrome session and return its `session_id`. |
| `ceki_navigate` | Open a URL. |
| `ceki_click` | Click at viewport coordinates. Mouse jitter ON by default. |
| `ceki_type` | Type into the focused element. Cadence + jitter ON by default. |
| `ceki_scroll` | Scroll by `delta_y` pixels. |
| `ceki_screenshot` | PNG of the current viewport as base64. |
| `ceki_snapshot` | Screenshot + drained chat messages from the provider. |
| `ceki_chat_send` | Send a chat message to the human provider (captcha / OTP). |
| `ceki_stop` | End the session — always call this when done. |
| `ceki_export_profile` | **Killer:** export cookies/storage/fingerprint to disk. |
| `ceki_restore_profile` | **Killer:** restore a saved profile into a fresh rent. |

There is no server-side NL endpoint and no LLM lives inside this package — your CrewAI agent's own model does the planning.

## Quick start

```python
import os
os.environ["CEKI_API_KEY"] = "your_ceki_key"   # https://ceki.me dashboard

from crewai import Agent, Task, Crew
from crewai_ceki import CekiCrewaiToolkit

toolkit = CekiCrewaiToolkit(default_rent={"schedule_id": 4242})

browser_agent = Agent(
    role="Web Operator",
    goal="Drive the rented browser to complete the task.",
    backstory=(
        "You operate a real Chrome session via the ceki_* tools. After a "
        "successful login, ALWAYS call ceki_export_profile so future runs "
        "can skip the login. On a fresh rent for a site you previously "
        "logged into, ALWAYS try ceki_restore_profile BEFORE navigating."
    ),
    tools=toolkit.get_tools(),
)

task = Task(
    description="Open https://example.com and report the page title.",
    expected_output="The page title as a string.",
    agent=browser_agent,
)

try:
    Crew(agents=[browser_agent], tasks=[task]).kickoff()
finally:
    toolkit.close()
```

## The killer combo — persistent profiles

Tell your agent in its backstory:

```
After a successful login, always call ceki_export_profile.
On a fresh rent for a previously-logged-in site, always call
ceki_restore_profile before navigating.
```

That is the entire setup. Now every login the crew performs is durable:

```python
# Run A — crew logs into your.example.com, then:
ceki_export_profile(session_id, profile_name="your-example")
# → JSON written to ~/.cache/ceki-crewai/profiles/your-example.json

# Process restarts. The file survives.

# Run B — fresh rent on a new browser:
ceki_restore_profile(session_id, profile_name="your-example")
# → cookies, localStorage, sessionStorage, fingerprint all restored
ceki_navigate(session_id, "https://your.example.com/dashboard")
# → already authenticated
```

By default profiles live under `~/.cache/ceki-crewai/profiles/`. Override with:

```python
from pathlib import Path
toolkit = CekiCrewaiToolkit(
    default_rent={"schedule_id": 4242},
    profile_dir=Path("/var/lib/myapp/ceki-profiles"),
)
```

Or override via the `CEKI_PROFILE_DIR` environment variable. If you'd rather keep the JSON in your own store, pass it via the `payload` argument to either tool and the toolkit skips the disk read/write.

See [`examples/persistent_session.py`](examples/persistent_session.py) for an end-to-end runnable demo.

## Use responsibly

Use only on sites you own or have authorization to operate on (your own apps, your own dashboards, public data within site Terms of Service, accessibility audits you're responsible for).

## License

MIT.
