nineth 0.1.0

model sdk built by the 9th ditrict at tooig

nineth-sdk

nineth-sdk is a model sdk built by the 9th ditrict at tooig.

Get started with:

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

60-Second Start

from nineth import NinethClient

with NinethClient(default_model="district/1984-m3-0317") as client:
	result = client.invoke(
		task_input="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
• the SDK can set a client-side default model with default_model= or NINETH_MODEL
• regular requests wait up to 5 minutes by default
• streaming requests disable the read timeout by default so SSE can stay open

Quick Start

import os
from nineth import NinethClient

client = NinethClient(
	api_key=os.environ["NINETH_API_KEY"],
	default_model="district/1984-m3-0317",
)

response = client.invoke(
	task_input="Give me a terse overview of crude oil today.",
	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"],
	default_model="district/1984-m3-0317",
) as client:
	for event in client.stream(
		task_input="Research Nvidia's latest earnings and summarize the key points.",
		model="district/1984-m3-0317",
		services=True,
		service_names=["search_web", "read"],
		cache=True,
		max_iterations=6,
		reasoning_effort="medium",
		show_reasoning=False,
		stream_timeout=None,
	):
		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"],
		default_model="district/1984-m3-0317",
	) as client:
		response = await client.invoke(
			task_input="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
• services
• service_names
• cache
• max_iterations
• reasoning_effort
• show_reasoning
• continuous
• images
• system_prompt

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

The API does not choose a default model. Set model= per call or configure default_model= on the client.

What You Get Back

invoke() returns a dictionary like:

{
	"process_id": "...",
	"model": "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": "..."
	}
}

By default, invoke() uses a 5-minute timeout and stream() uses a dedicated streaming timeout with no read limit. Override those with timeout= and stream_timeout= on the client constructor if you need stricter limits.

thinking is empty unless you pass show_reasoning=True. reasoning_effort is optional and passed through to the provider unchanged when set.

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.