Metadata-Version: 2.4
Name: partython-brain
Version: 1.0.0
Summary: Python SDK for the Partython AI brain — embed conversational AI in your app or backend.
Author: Partython Inc
License: MIT
Project-URL: Homepage, https://partython.com
Project-URL: Repository, https://github.com/PARTYTHONPRIVATELIMITED/cortex
Keywords: partython,ai,chatbot,saas,conversational-ai,agent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0,>=2.28
Dynamic: license-file

# partython-brain

Python SDK for the [Partython AI](https://partython.com) brain — embed conversational, sales-aware AI in your app or backend.

```bash
pip install partython-brain
```

## Quick start

```python
from partython_brain import Brain
import os

brain = Brain(api_key=os.environ["PARTYTHON_API_KEY"])

result = brain.respond(
    channel="web",
    channel_user_id="user-abc",
    message_text="I'm planning a 5-year-old's birthday with 12 guests — any unicorn theme ideas?",
)
print(result["response"])
# → "A unicorn theme for a 5-year-old with 12 guests — fun! Let me show you our..."
```

## API

### `Brain(api_key, base_url=None, timeout=30, session=None)`

| Param     | Default                         | Description                                |
|-----------|---------------------------------|--------------------------------------------|
| api_key   | (required)                      | Your `pk_live_...` API key                 |
| base_url  | `https://brain.partython.com`   | Override for self-hosted                   |
| timeout   | `30.0`                          | Per-call timeout in seconds                |
| session   | new `requests.Session`          | Custom session for retries / connection pool |

### `brain.respond(...)`

Keyword args (all required unless noted):

- `channel: str` — `"web"` | `"whatsapp"` | `"sms"` | `"api"` ...
- `channel_user_id: str` — stable id for the conversation participant
- `message_text: str` — the customer's message
- `metadata: dict | None` — optional pass-through metadata
- `dedup_key: str | None` — idempotency key (webhook event id)
- `has_image: bool` — hint for the smart router

Returns `dict` with `response`, `assistant_name`, `request_id`, `metadata`.

## Errors

```python
from partython_brain import BrainAuthError, BrainRateLimitError

try:
    brain.respond(...)
except BrainRateLimitError as e:
    # back off — retry-after info is in e.body
    ...
except BrainAuthError as e:
    # key invalid or revoked
    ...
```

| Exception              | When it fires                                       |
|------------------------|-----------------------------------------------------|
| `BrainAuthError`       | 401 / 403 — key invalid, revoked, or no scope       |
| `BrainRateLimitError`  | 429 — per-key per-minute limit hit                  |
| `BrainNotFoundError`   | 404 — tenant misconfigured                          |
| `BrainServerError`     | 5xx upstream                                        |
| `BrainNetworkError`    | Network or timeout                                  |

## License

MIT
