Metadata-Version: 2.5
Name: humansand
Version: 0.1.0
Summary: The official Python SDK for the Persimmon user model by humans&
Project-URL: Documentation, https://persimmon.humansand.ai/docs
Project-URL: Homepage, https://persimmon.humansand.ai
Author: humans&
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# humansand

The official Python SDK for Persimmon, a user model by humans&.
Create a conversation, request a turn, and control the history sent with each request.

Requires Python 3.12 or later. The package name is `humansand`; the Python
import is `user_model`.

## Install

```sh
pip install humansand
```

Get an API key from the playground's API page. Store it in your secret manager
and load it into the `USER_MODEL_API_KEY` environment variable.

## Quickstart

```python
from user_model import Persimmon

with Persimmon() as client:
    conversation = client.conversations.create(
        model="persimmon-v0.1",
        participants=[
            {"name": "Maya", "description": "Product lead. Calm and direct."},
            {"name": "Theo", "description": "Engineer. Careful and practical."},
        ],
        setting="A team discusses a product launch.",
    )
    turn = conversation.get_turn(speaker="Maya")
    print(turn.content)
    conversation.append_turn(turn)
```

`get_turn()` returns a turn without saving it to the local history. Call
`append_turn()` to accept it. Each request sends the current conversation history.

Use `AsyncPersimmon` with `async with` and `await` in asynchronous applications.
Both clients close their HTTP connections when their context ends.

See the [Python SDK guide](https://persimmon.humansand.ai/docs#sdk/quickstart)
for asynchronous examples, error handling, pagination, and configuration.
