Metadata-Version: 2.4
Name: letta-ceki
Version: 0.1.0
Summary: Letta tool for Ceki — real Chrome sessions for AI agents with persistent memory across rentals
Project-URL: homepage, https://ceki.me
Project-URL: repository, https://github.com/Ceki-me/letta
Project-URL: issues, https://github.com/Ceki-me/letta/issues
Author: iWedmak
License: MIT
License-File: LICENSE
Keywords: ai-agent,automation,browser,ceki,chrome,letta,memgpt,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: letta-client>=0.1.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# letta-ceki

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

> **Killer combo.** Letta's archival memory + Ceki's profile export = browser sessions that **remember themselves across agent restarts.** Log in once on Monday, your agent walks straight into the dashboard on Friday — no cookies stored in your code, no second login.

## Install

```bash
pip install letta-ceki
```

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

## Architecture

Variant C — **structural toolkit**. Eleven self-contained Python functions that the Letta 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 Letta memory. |
| `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 Letta agent's own model does the planning.

## Register the tools in your Letta workspace

```python
import os
os.environ["CEKI_API_KEY"] = "your_ceki_key"     # https://ceki.me dashboard
os.environ["LETTA_TOKEN"] = "your_letta_token"   # https://app.letta.com/settings/api-keys

from letta_ceki import register_all
tool_ids = register_all()
print(f"Registered {len(tool_ids)} tools.")
```

Then attach the tools to your agent in the Letta UI, or programmatically:

```python
from letta_client import Letta
client = Letta(token=os.environ["LETTA_TOKEN"])
client.agents.update(agent_id="your_agent_id", tool_ids=list(tool_ids.values()))
```

## The killer combo — persistent sessions

Tell your agent in its persona prompt:

```
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 agent performs is durable:

```python
# Run A — agent logs into your.example.com, then:
ceki_export_profile(session_id, profile_name="your-example")

# Letta restarts. Memory 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
```

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.
