nineth 0.0.4

model sdk built by the 9th ditrict at tooig

nineth-sdk

nineth-sdk is the lightweight Python SDK for the Rooster agent API.

Install

pip install nineth
export NINETH_API_KEY="your-shared-api-key"

60-Second Start

from nineth import NinethClient

with NinethClient() 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 NINETH_API_KEY automatically

Quick Start

import os
from nineth import NinethClient

client = NinethClient(api_key=os.environ["NINETH_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 nineth import NinethClient

with NinethClient(api_key=os.environ["NINETH_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 nineth import NinethClient

with NinethClient() 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 nineth import AsyncNinethClient


async def main():
	async with AsyncNinethClient(api_key=os.environ["NINETH_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 NINETH_API_KEY environment variable

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

Overriding The Endpoint

Use a different deployment like this:

from nineth import NinethClient

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