nineth 0.1.2

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:
	try:
		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"])
	except Exception as exc:
		print("stream failed:", exc)

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 public event types are:

• accepted
• model_delta
• service_call
• service_response
• result

By default the stream is client-facing, not debug-facing:

• accepted is minimal and only echoes the requested public model.
• model_delta contains only visible response text. Hidden reasoning, raw service tags, and internal tool markup are stripped.
• result contains model, final_response, and iterations, plus thinking only when show_reasoning=True.
• Internal lifecycle events such as run_started, model_start, model_response, heartbeat, and idle are only included when debug=True.
• If the server emits an error frame, the SDK raises NinethAPIError instead of yielding that frame as a normal event.

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_delta",
	"timestamp": "2026-04-03T00:00:00+00:00",
	"process_id": "...",
	"iteration": 1,
	"data": {
		"text": "NVIDIA reported..."
	}
}

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.

If the server emits an error event, stream() raises NinethAPIError and closes the connection.

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.