Metadata-Version: 2.4
Name: roosted
Version: 0.0.2
Summary: Python SDK for the Rooster multi-step agent API.
Project-URL: Homepage, https://github.com/districtt/rooster
Project-URL: Bug Tracker, https://github.com/districtt/rooster/issues
Author-email: "Tooig, Inc" <tooighq@gmail.com>, Oyebamijo <boy@oyebamijo.com>
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27.2
Description-Content-Type: text/markdown

# roosted

`roosted` is the lightweight Python SDK for the Rooster agent API.

## Install

```bash
pip install roosted
export ROOSTER_API_KEY="your-shared-api-key"
```

If you are working from this repository directly, the packaged client dependencies are also listed in `rooster-sdk/requirements.txt`.

The SDK defaults to the provider-hosted endpoint:

```text
https://weirdpablo--rooster-api.modal.run
```

Override it with `base_url=...` or `ROOSTER_BASE_URL` if you are targeting another deployment.

## 60-Second Start

```python
from roosted import RoosterClient

with RoosterClient() as client:
	result = client.invoke(
		"Give me a tight market update on BTC.",
		services=False,
		cache=False,
	)
	print(result["final_response"])
```

That works because:

- the SDK defaults to `https://weirdpablo--rooster-api.modal.run`
- the SDK reads `ROOSTER_API_KEY` automatically

## Quick Start

```python
import os
from roosted import RoosterClient

client = RoosterClient(api_key=os.environ["ROOSTER_API_KEY"])

response = client.invoke(
	"Give me a terse overview of crude oil today.",
	model_name="district/1984-m3-0317",
	services=False,
	cache=False,
)

print(response["final_response"])
client.close()
```

## Streaming

```python
import os
from roosted import RoosterClient

with RoosterClient(api_key=os.environ["ROOSTER_API_KEY"]) as client:
	for event in client.stream(
		"Research Nvidia's latest earnings and summarize the key points.",
		services=True,
		service_names=["search_web", "read"],
		cache=True,
		max_iterations=6,
	):
		print(event["type"], event["data"])
```

## Health Check

```python
from roosted import RoosterClient

with RoosterClient() as client:
	print(client.health())
```

`health()` does not require authentication.

The SDK yields parsed SSE payloads as dictionaries. Typical event types are:

- `accepted`
- `run_started`
- `model_start`
- `model_delta`
- `model_response`
- `service_call`
- `service_response`
- `result`
- `completed`
- `error`

## Async Client

```python
import asyncio
import os
from roosted import AsyncRoosterClient


async def main():
	async with AsyncRoosterClient(api_key=os.environ["ROOSTER_API_KEY"]) as client:
		response = await client.invoke(
			"Tell me whether gold is trending or ranging.",
			services=False,
			cache=False,
		)
		print(response["final_response"])


asyncio.run(main())
```

## Payload Options

The SDK maps directly to the API request body. The most important options are:

- `task_input`
- `model_name`
- `services`
- `service_names`
- `cache`
- `max_iterations`
- `reasoning_effort`
- `continuous`
- `images`
- `system_prompt`

Unknown request keys can be passed through with `extra={...}` in `build_payload(...)`.

## What You Get Back

`invoke()` returns a dictionary like:

```python
{
	"process_id": "...",
	"model_name": "district/1984-m3-0317",
	"final_response": "...",
	"usage": {...},
	"thinking": [...],
	"service_calls": [...],
	"service_responses": [...],
	"iterations": 2,
	"events": [...],
}
```

`stream()` yields one dictionary per SSE event, for example:

```python
{
	"type": "model_response",
	"timestamp": "2026-04-03T00:00:00+00:00",
	"process_id": "...",
	"iteration": 1,
	"data": {
		"visible_response": "..."
	}
}
```

## Authentication

Execution requests send the shared key in the `X-API-Key` header. The SDK reads it from:

- the `api_key=` constructor argument
- or the `ROOSTER_API_KEY` environment variable

`health()` does not require authentication, but `invoke()` and `stream()` do.

## Overriding The Endpoint

Use a different deployment like this:

```python
from roosted import RoosterClient

client = RoosterClient(
	base_url="https://your-other-deployment.modal.run",
	api_key="your-shared-api-key",
)
```