nineth 0.0.4__py3-none-any.whl

nineth-0.0.4.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: nineth
+Version: 0.0.4
+Summary:  model sdk built by the 9th ditrict at tooig
+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
+
+# nineth-sdk
+
+`nineth-sdk` is the lightweight Python SDK for the Rooster agent API.
+
+## Install
+
+```bash
+pip install nineth
+export NINETH_API_KEY="your-shared-api-key"
+```
+
+## 60-Second Start
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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:
+
+```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 `NINETH_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 nineth import NinethClient
+
+client = NinethClient(
+	base_url="https://your-other-deployment.modal.run",
+	api_key="your-shared-api-key",
+)
+```

nineth-0.0.4.dist-info/RECORD

@@ -0,0 +1,5 @@
+roosted/__init__.py,sha256=GVhBHs49HB5By8DkQ5pNxvMD6JJ92IGdW5doTJc28EI,446
+roosted/client.py,sha256=b00G_ImL54jLbFTTokSjYEdN-xUQCbb9schPq2aXlJI,8080
+nineth-0.0.4.dist-info/METADATA,sha256=WTJqRuCv3qafTasxseeYocyL-thBDpFprIhny0j2OTg,3941
+nineth-0.0.4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+nineth-0.0.4.dist-info/RECORD,,

nineth-0.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

roosted/__init__.py

@@ -0,0 +1,18 @@
+from .client import AsyncRoosterClient, RoosterAPIError, RoosterClient, build_payload
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+except ImportError:
+    from importlib_metadata import PackageNotFoundError, version
+
+__all__ = [
+    "AsyncRoosterClient",
+    "RoosterAPIError",
+    "RoosterClient",
+    "build_payload",
+]
+
+try:
+    __version__ = version("roosted")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

roosted/client.py

@@ -0,0 +1,239 @@
+"""Python client for the Rooster agent API."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, AsyncIterator, Dict, Iterator, Optional
+
+import httpx
+
+
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_BASE_URL = "https://weirdpablo--rooster-api.modal.run"
+API_KEY_HEADER = "X-API-Key"
+
+
+class RoosterAPIError(RuntimeError):
+    """Raised when the Rooster API returns an unexpected response."""
+
+
+def build_payload(
+    task_input: str,
+    *,
+    model_name: Optional[str] = None,
+    services: bool = True,
+    service_names: Optional[list[str]] = None,
+    cache: bool = True,
+    max_iterations: int = 50,
+    reasoning_effort: str = "low",
+    process_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    debug: bool = False,
+    continuous: bool = False,
+    images: Optional[list[str]] = None,
+    system_prompt: Optional[str] = None,
+    extra: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {
+        "task_input": task_input,
+        "model_name": model_name,
+        "services": services,
+        "service_names": service_names,
+        "cache": cache,
+        "max_iterations": max_iterations,
+        "reasoning_effort": reasoning_effort,
+        "process_id": process_id,
+        "user_id": user_id,
+        "debug": debug,
+        "continuous": continuous,
+        "images": images,
+        "system_prompt": system_prompt,
+    }
+    if extra:
+        payload.update(extra)
+    return {key: value for key, value in payload.items() if value is not None}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    try:
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        message = response.text.strip() or str(exc)
+        raise RoosterAPIError(message) from exc
+
+
+def _parse_sse_lines(lines: Iterator[str]) -> Iterator[Dict[str, Any]]:
+    event_type = "message"
+    data_lines: list[str] = []
+
+    for raw_line in lines:
+        line = raw_line.rstrip("\r")
+        if not line:
+            if data_lines:
+                payload = json.loads("\n".join(data_lines))
+                payload.setdefault("type", event_type)
+                yield payload
+            event_type = "message"
+            data_lines = []
+            continue
+
+        if line.startswith(":"):
+            continue
+        if line.startswith("event:"):
+            event_type = line.split(":", 1)[1].strip()
+            continue
+        if line.startswith("data:"):
+            data_lines.append(line.split(":", 1)[1].strip())
+
+    if data_lines:
+        payload = json.loads("\n".join(data_lines))
+        payload.setdefault("type", event_type)
+        yield payload
+
+
+class NinethClient:
+    """Synchronous client for the Nineth API."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Optional[Dict[str, str]] = None,
+    ):
+        resolved_base_url = (base_url or os.getenv("ROOSTER_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        if not resolved_base_url:
+            raise ValueError("A base_url or ROOSTER_BASE_URL environment variable is required.")
+
+        resolved_api_key = api_key or os.getenv("ROOSTER_API_KEY")
+        request_headers = dict(headers or {})
+        if resolved_api_key:
+            request_headers.setdefault(API_KEY_HEADER, resolved_api_key)
+
+        self.base_url = resolved_base_url
+        self.api_key = resolved_api_key
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=request_headers or None,
+        )
+
+    def _ensure_api_key(self) -> None:
+        if not self.api_key and API_KEY_HEADER not in self._client.headers:
+            raise ValueError("An api_key or ROOSTER_API_KEY environment variable is required.")
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "NinethClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def health(self) -> Dict[str, Any]:
+        response = self._client.get("/health")
+        _raise_for_status(response)
+        return response.json()
+
+    def invoke(self, task_input: str, **kwargs: Any) -> Dict[str, Any]:
+        self._ensure_api_key()
+        payload = build_payload(task_input, **kwargs)
+        response = self._client.post("/agent", json=payload)
+        _raise_for_status(response)
+        return response.json()
+
+    def stream(self, task_input: str, **kwargs: Any) -> Iterator[Dict[str, Any]]:
+        self._ensure_api_key()
+        payload = build_payload(task_input, **kwargs)
+        with self._client.stream("POST", "/agent/stream", json=payload) as response:
+            _raise_for_status(response)
+            yield from _parse_sse_lines(response.iter_lines())
+
+
+class AsyncNinethClient:
+    """Asynchronous client for the Nineth API."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Optional[Dict[str, str]] = None,
+    ):
+        resolved_base_url = (base_url or os.getenv("ROOSTER_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        if not resolved_base_url:
+            raise ValueError("A base_url or ROOSTER_BASE_URL environment variable is required.")
+
+        resolved_api_key = api_key or os.getenv("ROOSTER_API_KEY")
+        request_headers = dict(headers or {})
+        if resolved_api_key:
+            request_headers.setdefault(API_KEY_HEADER, resolved_api_key)
+
+        self.base_url = resolved_base_url
+        self.api_key = resolved_api_key
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=request_headers or None,
+        )
+
+    def _ensure_api_key(self) -> None:
+        if not self.api_key and API_KEY_HEADER not in self._client.headers:
+            raise ValueError("An api_key or ROOSTER_API_KEY environment variable is required.")
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncNinethClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    async def health(self) -> Dict[str, Any]:
+        response = await self._client.get("/health")
+        _raise_for_status(response)
+        return response.json()
+
+    async def invoke(self, task_input: str, **kwargs: Any) -> Dict[str, Any]:
+        self._ensure_api_key()
+        payload = build_payload(task_input, **kwargs)
+        response = await self._client.post("/agent", json=payload)
+        _raise_for_status(response)
+        return response.json()
+
+    async def stream(self, task_input: str, **kwargs: Any) -> AsyncIterator[Dict[str, Any]]:
+        self._ensure_api_key()
+        payload = build_payload(task_input, **kwargs)
+        async with self._client.stream("POST", "/agent/stream", json=payload) as response:
+            _raise_for_status(response)
+            event_type = "message"
+            data_lines: list[str] = []
+
+            async for raw_line in response.aiter_lines():
+                line = raw_line.rstrip("\r")
+                if not line:
+                    if data_lines:
+                        payload = json.loads("\n".join(data_lines))
+                        payload.setdefault("type", event_type)
+                        yield payload
+                    event_type = "message"
+                    data_lines = []
+                    continue
+
+                if line.startswith(":"):
+                    continue
+                if line.startswith("event:"):
+                    event_type = line.split(":", 1)[1].strip()
+                    continue
+                if line.startswith("data:"):
+                    data_lines.append(line.split(":", 1)[1].strip())
+
+            if data_lines:
+                payload = json.loads("\n".join(data_lines))
+                payload.setdefault("type", event_type)
+                yield payload