Metadata-Version: 2.4
Name: tells-api
Version: 0.1.0
Summary: Browser sessions for AI agents. Connect Playwright/Puppeteer to stealth Chrome in one line.
Author-email: Tells <team@tells.dev>
License: MIT
Project-URL: Homepage, https://tells.dev
Project-URL: Documentation, https://docs.tells.dev
Project-URL: Repository, https://github.com/tellsdev/tells-python
Keywords: browser,automation,ai-agents,playwright,puppeteer,cdp,web-scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: playwright
Requires-Dist: playwright>=1.40.0; extra == "playwright"

# Tells Python SDK

Browser sessions for AI agents. Connect Playwright to managed Chrome with unique fingerprints, behavioral modeling, and CDP access.

## Install

```bash
pip install tells playwright
playwright install chromium
```

## Quick Start

```python
import tells

session = tells.session()
browser, ctx, page = session.connect_playwright()

page.goto("https://example.com")
print(page.title())

session.close()
```

That's it. The session has a unique fingerprint, behavioral engine, and ad blocking — all automatic.

## With Context Manager

```python
import tells

with tells.session() as session:
    browser, ctx, page = session.connect_playwright()
    page.goto("https://news.ycombinator.com")
    titles = page.eval_on_selector_all(".titleline a", "els => els.map(e => e.textContent)")
    print(titles[:5])
```

## Behavioral Engine

```python
session = tells.session()

# Human-like interactions
session.click(500, 300)
session.scroll(400)
session.type("search query", context="search")
```

## Session Profiles

```python
# First session — log in
s1 = tells.session(profile_name="my-account")
browser, ctx, page = s1.connect_playwright()
page.goto("https://example.com/login")
# ... log in ...
s1.close()

# Second session — cookies persist
s2 = tells.session(profile_name="my-account")
browser, ctx, page = s2.connect_playwright()
page.goto("https://example.com/dashboard")  # already logged in
```

## Client Instance

```python
from tells import Tells

client = Tells(api_key="sk_...")
session = client.session()
print(client.usage())
```

## Environment Variable

```bash
export TELLS_API_KEY=sk_your_key_here
```

## Links

- [Documentation](https://docs.tells.dev)
- [Dashboard](https://tells.dev/app)
- [Website](https://tells.dev)
