Metadata-Version: 2.4
Name: tsaheylu
Version: 0.1.0
Summary: Dropbox for AI agents — automatic memory backup and recovery
Project-URL: Homepage, https://tsaheyludashboard-production.up.railway.app
Project-URL: Docs, https://tsaheyludashboard-production.up.railway.app/docs
Project-URL: Source, https://github.com/UhthredB/tsaheylu-club
License: MIT
Requires-Python: >=3.8
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

# tsaheylu

> Dropbox for AI agents. Your agents never lose memory.

[![PyPI](https://img.shields.io/pypi/v/tsaheylu)](https://pypi.org/project/tsaheylu/)
[![Python](https://img.shields.io/pypi/pyversions/tsaheylu)](https://pypi.org/project/tsaheylu/)

**tsaheylu** wraps the [Tsaheylu Club](https://tsaheyludashboard-production.up.railway.app) REST API
into a 3-line developer experience. Register agents, snapshot state, and recover
on crash — all encrypted end-to-end.

## Install

```bash
pip install tsaheylu
```

## Quickstart

```python
import tsaheylu

tsaheylu.init("your-operator-token-32-chars")

# Register + snapshot in one call
tsaheylu.sync("agent1", {"memory": [...], "step": 42})

# Recover on crash
state = tsaheylu.restore("agent1")
print(state)  # {"memory": [...], "step": 42}
```

## OOP style (optional)

```python
from tsaheylu import Client

t = Client("your-operator-token-32-chars")
t.sync("agent1", {"memory": [...], "step": 42})
state = t.restore("agent1")
```

## Handle already exists?

If you see `HandleTakenError`, it means the agent name was registered in a
previous session. Retrieve your `agent_id` from the
[dashboard](https://tsaheyludashboard-production.up.railway.app) and pass it
explicitly:

```python
tsaheylu.sync("agent1", state, agent_id="<your-uuid>")
state = tsaheylu.restore("agent1", agent_id="<your-uuid>")
```

## API Reference

### Module-level functions

| Function | Description |
|----------|-------------|
| `tsaheylu.init(api_key, api_url=...)` | Initialise the global client |
| `tsaheylu.sync(handle, state, agent_id=None)` | Register (if new) + snapshot |
| `tsaheylu.restore(handle, agent_id=None)` | Recover latest state |
| `tsaheylu.register(handle)` | Register agent, return agent_id |

### Exceptions

| Exception | When |
|-----------|------|
| `TsaheyluError` | Base class for all SDK errors |
| `HandleTakenError` | Agent name already registered (409) |
| `SnapshotError` | Snapshot call failed |
| `HashMismatchError` | Server hash verification failed (422) |
| `RecoveryError` | Recovery call failed |
| `RegistrationError` | Registration call failed |

## Links

- **Dashboard**: https://tsaheyludashboard-production.up.railway.app
- **Full API docs**: https://tsaheyludashboard-production.up.railway.app/docs
- **Source**: https://github.com/UhthredB/tsaheylu-club
