roosted 0.0.2

Python SDK for the Rooster multi-step agent API.

roosted

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

Install

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:

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

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

60-Second Start

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

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

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

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

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:

{
	"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:

{
	"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:

from roosted import RoosterClient

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